Skip to content

Commit a64780f

Browse files
weaverryanweaverryan
committed
Merge pull request symfony#1678 from WouterJ/cookbook_config_new_article
[Cookbook] New article "How to Override Symfony's Default Directory Structure"
2 parents 4eb160b + 3d92644 commit a64780f

File tree

5 files changed

+123
-0
lines changed

5 files changed

+123
-0
lines changed

‎book/installation.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,12 @@ something like this:
7373
app.php
7474
...
7575
76+
.. note::
77+
78+
You can easily override the default directory structure. See
79+
:doc:`/cookbook/configuration/override_dir_structure` for more
80+
information.
81+
7682
Updating Vendors
7783
~~~~~~~~~~~~~~~~
7884

‎cookbook/configuration/environments.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,11 @@ includes the following:
338338

339339
* ``twig/`` - this directory contains all the cached Twig templates.
340340

341+
.. note::
342+
343+
You can easilly change the directory location and name, for more information
344+
read the article :doc:`/cookbook/configuration/override_dir_structure`.
345+
341346

342347
Going Further
343348
-------------

‎cookbook/configuration/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Configuration
55
:maxdepth: 2
66

77
environments
8+
override_dir_structure
89
external_parameters
910
pdo_session_storage
1011
apache_router

‎cookbook/configuration/override_dir_structure.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
.. index::
2+
single: Override Symfony
3+
4+
How to override Symfony's Default Directory Structure
5+
=====================================================
6+
7+
Symfony automatically ships with a default directory structure. You can
8+
easily override this directory structure to create your own. The default
9+
directory structure is:
10+
11+
.. code-block:: text
12+
13+
app/
14+
cache/
15+
config/
16+
logs/
17+
...
18+
src/
19+
...
20+
vendor/
21+
...
22+
web/
23+
app.php
24+
...
25+
26+
Override the ``cache`` directory
27+
--------------------------------
28+
29+
You can override the cache directory by overriding the ``getCacheDir`` method
30+
in the ``AppKernel`` class of you application::
31+
32+
// app/AppKernel.php
33+
34+
// ...
35+
class AppKernel extends Kernel
36+
{
37+
// ...
38+
39+
public function getCacheDir()
40+
{
41+
return $this->rootDir.'/'.$this->environment.'/cache/';
42+
}
43+
}
44+
45+
``$this->rootDir`` is the absolute path to the ``app`` directory and ``$this->environment``
46+
is the current environment (i.e. ``dev``). In this case we have changed
47+
the location of the cache directory to ``app/{environment}/cache``.
48+
49+
.. warning::
50+
51+
You should keep the ``cache`` directory different for each environment,
52+
otherwise some unexpected behaviour can happen as a different environment
53+
means different config files and those are cached, so the cached data
54+
is different.
55+
56+
Override the ``logs`` directory
57+
-------------------------------
58+
59+
Overriding the ``logs`` directory is the same as overriding the ``cache``
60+
directory, the only difference is that you need to override the ``getLogDir``
61+
method::
62+
63+
// app/AppKernel.php
64+
65+
// ...
66+
class AppKernel extends Kernel
67+
{
68+
// ...
69+
70+
public function getLogDir()
71+
{
72+
return $this->rootDir.'/'.$this->environment.'/logs/';
73+
}
74+
}
75+
76+
We have changed location of the directory to ``app/{environment}/logs``.
77+
78+
Override the ``web`` directory
79+
------------------------------
80+
81+
Some shared hosting require to rename the ``web`` directory to ``public_html``
82+
and move this directory to the apache root. You can simply rename the directory:
83+
The only thing you need to check is if the path to the ``app`` directory
84+
is still right in ``app.php`` or ``app_dev.php``. For instance: If we move
85+
the ``web`` directory one map up we need to add ``Symfony`` (the name of
86+
your Symfony installation directory) to the path::
87+
88+
require_once __DIR__.'/../Symfony/app/bootstrap.php.cache';
89+
require_once __DIR__.'/../Symfony/app/AppKernel.php';
90+
91+
.. note::
92+
93+
If you use the AsseticBundle you need to configure this, so it can use
94+
the correct ``web`` directory:
95+
96+
.. code-block:: yaml
97+
98+
# app/config/config.yml
99+
100+
# ...
101+
assetic:
102+
# ...
103+
read_from: %kernel.root_dir%/../../public_html
104+
105+
Now you just need to dump the assets again and your application should
106+
work:
107+
108+
.. code-block:: bash
109+
110+
$ php app/console assetic:dump --env=prod --no-debug

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
* :doc:`/cookbook/configuration/index`
2020

2121
* :doc:`/cookbook/configuration/environments`
22+
* :doc:`/cookbook/configuration/override_dir_structure`
2223
* :doc:`/cookbook/configuration/external_parameters`
2324
* :doc:`/cookbook/configuration/pdo_session_storage`
2425
* :doc:`/cookbook/configuration/apache_router`

0 commit comments

Comments
 (0)