feature #5917 [3.0][Cookbook] Use the 3.0 directory structure (WouterJ)

This PR was merged into the master branch.

Discussion
----------

[3.0][Cookbook] Use the 3.0 directory structure

| Q | A
| --- | ---
| Doc fix? | yes
| New docs? | yes
| Applies to | 3.0+
| Fixed tickets | part of #5898

Commits
-------

47e11f8 Applied comments
f2be12a Updated directory structures
df20095 Testing changes
ef613f6 app/SymfonyRequirements.php -> bin/SymfonyRequirements.php
af7052b app/bootstrap.php.cache -> var/bootstrap.php.cache
6614c0f app/logs -> var/logs
b3da3b7 app/cache -> var/cache
b6d93f0 app/phpunit.xml.dist -> phpunit.xml.dist
bea4a0c app/console -> bin/console

cookbook/assetic/asset_management.rst

@@ -500,7 +500,7 @@ each time you deploy), you should run the following command:
 
 .. code-block:: bash
 
-    $ php app/console assetic:dump --env=prod --no-debug
+    $ php bin/console assetic:dump --env=prod --no-debug
 
 This will physically generate and write each file that you need (e.g. ``/js/abcd123.js``).
 If you update any of your assets, you'll need to run this again to regenerate
@@ -542,7 +542,7 @@ need to dump them manually. To do so, run the following command:
 
 .. code-block:: bash
 
-    $ php app/console assetic:dump
+    $ php bin/console assetic:dump
 
 This physically writes all of the asset files you need for your ``dev``
 environment. The big disadvantage is that you need to run this each time
@@ -551,7 +551,7 @@ assets will be regenerated automatically *as they change*:
 
 .. code-block:: bash
 
-    $ php app/console assetic:watch
+    $ php bin/console assetic:watch
 
 The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior
 versions, you had to use the ``--watch`` option of the ``assetic:dump``

cookbook/bundles/installation.rst

@@ -108,14 +108,14 @@ via the ``config:dump-reference`` command:
 
 .. code-block:: bash
 
-    $ app/console config:dump-reference AsseticBundle
+    $ bin/console config:dump-reference AsseticBundle
 
 Instead of the full bundle name, you can also pass the short name used as the root
 of the bundle's configuration:
 
 .. code-block:: bash
 
-    $ app/console config:dump-reference assetic
+    $ bin/console config:dump-reference assetic
 
 The output will look like this:
 

cookbook/configuration/apache_router.rst

@@ -98,7 +98,7 @@ Now generate the mod_rewrite rules:
 
 .. code-block:: bash
 
-    $ php app/console router:dump-apache -e=prod --no-debug
+    $ php bin/console router:dump-apache -e=prod --no-debug
 
 Which should roughly output the following:
 
@@ -145,7 +145,7 @@ to ``ApacheRequest`` in ``web/app.php``::
 
     // web/app.php
 
-    require_once __DIR__.'/../app/bootstrap.php.cache';
+    require_once __DIR__.'/../var/bootstrap.php.cache';
     require_once __DIR__.'/../app/AppKernel.php';
     // require_once __DIR__.'/../app/AppCache.php';
 

cookbook/configuration/configuration_organization.rst

@@ -34,8 +34,9 @@ default Symfony Standard Edition follow this structure:
 
 .. code-block:: text
 
-    <your-project>/
+    your-project/
     ├─ app/
+    │  ├─ ...
     │  └─ config/
     │     ├─ config.yml
     │     ├─ config_dev.yml
@@ -46,9 +47,7 @@ default Symfony Standard Edition follow this structure:
     │     ├─ routing.yml
     │     ├─ routing_dev.yml
     │     └─ security.yml
-    ├─ src/
-    ├─ vendor/
-    └─ web/
+    ├─ ...
 
 This default structure was chosen for its simplicity — one file per environment.
 But as any other Symfony feature, you can customize it to better suit your needs.
@@ -65,8 +64,9 @@ name as the environment:
 
 .. code-block:: text
 
-    <your-project>/
+    your-project/
     ├─ app/
+    │  ├─ ...
     │  └─ config/
     │     ├─ common/
     │     │  ├─ config.yml
@@ -83,9 +83,7 @@ name as the environment:
     │        ├─ parameters.yml
     │        ├─ routing.yml
     │        └─ security.yml
-    ├─ src/
-    ├─ vendor/
-    └─ web/
+    ├─ ...
 
 To make this work, change the code of the
 :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`
@@ -161,8 +159,9 @@ and several files to define all application services:
 
 .. code-block:: text
 
-    <your-project>/
+    your-project/
     ├─ app/
+    │  ├─ ...
     │  └─ config/
     │     ├─ bundles/
     │     │  ├─ bundle1.yml
@@ -182,9 +181,7 @@ and several files to define all application services:
     │        ├─ backend.yml
     │        ├─ ...
     │        └─ security.yml
-    ├─ src/
-    ├─ vendor/
-    └─ web/
+    ├─ ...
 
 Again, change the code of the ``registerContainerConfiguration()`` method to
 make Symfony aware of the new file organization::

cookbook/configuration/environments.rst

@@ -221,13 +221,13 @@ behavior:
 .. code-block:: bash
 
     # 'dev' environment and debug enabled
-    $ php app/console command_name
+    $ php bin/console command_name
 
     # 'prod' environment (debug is always disabled for 'prod')
-    $ php app/console command_name --env=prod
+    $ php bin/console command_name --env=prod
 
     # 'test' environment and debug disabled
-    $ php app/console command_name --env=test --no-debug
+    $ php bin/console command_name --env=test --no-debug
 
 In addition to the ``--env`` and ``--debug`` options, the behavior of Symfony
 commands can also be controlled with environment variables. The Symfony console
@@ -342,13 +342,13 @@ Symfony takes advantage of caching in many ways: the application configuration,
 routing configuration, Twig templates and more are cached to PHP objects
 stored in files on the filesystem.
 
-By default, these cached files are largely stored in the ``app/cache`` directory.
+By default, these cached files are largely stored in the ``var/cache`` directory.
 However, each environment caches its own set of files:
 
 .. code-block:: text
 
-    <your-project>/
-    ├─ app/
+    your-project/
+    ├─ var/
     │  ├─ cache/
     │  │  ├─ dev/   # cache directory for the *dev* environment
     │  │  └─ prod/  # cache directory for the *prod* environment
@@ -357,7 +357,7 @@ However, each environment caches its own set of files:
 Sometimes, when debugging, it may be helpful to inspect a cached file to
 understand how something is working. When doing so, remember to look in
 the directory of the environment you're using (most commonly ``dev`` while
-developing and debugging). While it can vary, the ``app/cache/dev`` directory
+developing and debugging). While it can vary, the ``var/cache/dev`` directory
 includes the following:
 
 ``appDevDebugProjectContainer.php``

cookbook/configuration/front_controllers_and_kernel.rst

@@ -75,7 +75,7 @@ as the default one.
     access. For example, you don't want to make a debugging environment
     available to arbitrary users in your production environment.
 
-Technically, the `app/console`_ script used when running Symfony on the command
+Technically, the `bin/console`_ script used when running Symfony on the command
 line is also a front controller, only that is not used for web, but for command
 line requests.
 
@@ -162,7 +162,7 @@ way of loading your configuration.
 .. _Symfony Standard Edition: https://github.com/symfony/symfony-standard
 .. _app.php: https://github.com/symfony/symfony-standard/blob/master/web/app.php
 .. _app_dev.php: https://github.com/symfony/symfony-standard/blob/master/web/app_dev.php
-.. _app/console: https://github.com/symfony/symfony-standard/blob/master/app/console
+.. _bin/console: https://github.com/symfony/symfony-standard/blob/master/bin/console
 .. _AppKernel: https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php
 .. _decorate: https://en.wikipedia.org/wiki/Decorator_pattern
 .. _RewriteRule shipped with the Symfony Standard Edition: https://github.com/symfony/symfony-standard/blob/master/web/.htaccess

cookbook/configuration/override_dir_structure.rst

@@ -12,12 +12,16 @@ directory structure is:
 
     your-project/
     ├─ app/
-    │  ├─ cache/
     │  ├─ config/
-    │  ├─ logs/
     │  └─ ...
     ├─ src/
     │  └─ ...
+    ├─ tests/
+    │  └─ ...
+    ├─ var/
+    │  ├─ cache/
+    │  ├─ logs/
+    │  └─ ...
     ├─ vendor/
     │  └─ ...
     └─ web/
@@ -41,13 +45,13 @@ in the ``AppKernel`` class of you application::
 
         public function getCacheDir()
         {
-            return $this->rootDir.'/'.$this->environment.'/cache';
+            return dirname(__DIR__).'/var/'.$this->environment.'/cache';
         }
     }
 
-``$this->rootDir`` is the absolute path to the ``app`` directory and ``$this->environment``
-is the current environment (i.e. ``dev``). In this case you have changed
-the location of the cache directory to ``app/{environment}/cache``.
+In this code, ``$this->environment`` is the current environment (i.e. ``dev``).
+In this case you have changed the location of the cache directory to
+``var/{environment}/cache``.
 
 .. caution::
 
@@ -74,35 +78,34 @@ method::
 
         public function getLogDir()
         {
-            return $this->rootDir.'/'.$this->environment.'/logs';
+            return dirname(__DIR__).'/var/'.$this->environment.'/logs';
         }
     }
 
-Here you have changed the location of the directory to ``app/{environment}/logs``.
+Here you have changed the location of the directory to ``var/{environment}/logs``.
 
 .. _override-web-dir:
 
 Override the ``web`` Directory
 ------------------------------
 
 If you need to rename or move your ``web`` directory, the only thing you
-need to guarantee is that the path to the ``app`` directory is still correct
+need to guarantee is that the path to the ``var`` directory is still correct
 in your ``app.php`` and ``app_dev.php`` front controllers. If you simply
 renamed the directory, you're fine. But if you moved it in some way, you
 may need to modify these paths inside those files::
 
-    require_once __DIR__.'/../Symfony/app/bootstrap.php.cache';
-    require_once __DIR__.'/../Symfony/app/AppKernel.php';
+    require_once __DIR__.'/../path/to/var/bootstrap.php.cache';
 
-You also need to change the ``extra.symfony-web-dir`` option in the ``composer.json``
-file:
+You also need to change the ``extra.symfony-web-dir`` option in the
+``composer.json`` file:
 
-.. code-block:: javascript
+.. code-block:: json
 
     {
-        ...
+        "...": "...",
         "extra": {
-            ...
+            "...": "...",
             "symfony-web-dir": "my_new_web_dir"
         }
     }
@@ -154,8 +157,8 @@ file:
 
     .. code-block:: bash
 
-        $ php app/console cache:clear --env=prod
-        $ php app/console assetic:dump --env=prod --no-debug
+        $ php bin/console cache:clear --env=prod
+        $ php bin/console assetic:dump --env=prod --no-debug
 
 Override the ``vendor`` Directory
 ---------------------------------
@@ -179,6 +182,7 @@ The change in the ``composer.json`` will look like this:
 Then, update the path to the ``autoload.php`` file in ``app/autoload.php``::
 
     // app/autoload.php
+
     // ...
     $loader = require '/some/dir/vendor/autoload.php';
 

cookbook/console/console_command.rst

@@ -68,7 +68,7 @@ This command will now automatically be available to run:
 
 .. code-block:: bash
 
-    $ php app/console demo:greet Fabien
+    $ php bin/console demo:greet Fabien
 
 .. _cookbook-console-dic:
 

cookbook/console/logging.rst

@@ -65,7 +65,7 @@ container and use it to do the logging::
     }
 
 Depending on the environment in which you run your command (and your logging
-setup), you should see the logged entries in ``app/logs/dev.log`` or ``app/logs/prod.log``.
+setup), you should see the logged entries in ``var/logs/dev.log`` or ``var/logs/prod.log``.
 
 Enabling automatic Exceptions Logging
 -------------------------------------

cookbook/console/usage.rst

@@ -17,18 +17,18 @@ clear and warm the ``prod`` cache you need to run:
 
 .. code-block:: bash
 
-    $ php app/console cache:clear --env=prod
+    $ php bin/console cache:clear --env=prod
 
 or the equivalent:
 
 .. code-block:: bash
 
-    $ php app/console cache:clear -e prod
+    $ php bin/console cache:clear -e prod
 
 In addition to changing the environment, you can also choose to disable debug mode.
 This can be useful where you want to run commands in the ``dev`` environment
 but avoid the performance hit of collecting debug data:
 
 .. code-block:: bash
 
-    $ php app/console list --no-debug
+    $ php bin/console list --no-debug

cookbook/debugging.rst

@@ -30,22 +30,21 @@ The ``app_dev.php`` front controller reads as follows by default::
 
     // ...
 
-    $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
-    require_once __DIR__.'/../app/AppKernel.php';
+    $loader = require __DIR__.'/../app/autoload.php';
+    Debug::enable();
 
     $kernel = new AppKernel('dev', true);
     $kernel->loadClassCache();
     $request = Request::createFromGlobals();
+    // ...
 
-To make your debugger happier, disable all PHP class caches by removing the
-call to ``loadClassCache()`` and by replacing the require statements like
-below::
+To make your debugger happier, disable all PHP class caches by removing (or
+commenting) the call to ``loadClassCache()``::
 
     // ...
 
-    // $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
     $loader = require_once __DIR__.'/../app/autoload.php';
-    require_once __DIR__.'/../app/AppKernel.php';
+    Debug::enable();
 
     $kernel = new AppKernel('dev', true);
     // $kernel->loadClassCache();

cookbook/deployment/azure-website.rst

@@ -260,12 +260,12 @@ directory with at least the following contents:
 .. code-block:: text
 
     /app/bootstrap.php.cache
-    /app/cache/*
+    /var/cache/*
     /app/config/parameters.yml
-    /app/logs/*
-    !app/cache/.gitkeep
-    !app/logs/.gitkeep
-    /app/SymfonyRequirements.php
+    /var/logs/*
+    !var/cache/.gitkeep
+    !var/logs/.gitkeep
+    /var/SymfonyRequirements.php
     /build/
     /vendor/
     /bin/
@@ -388,7 +388,7 @@ MySQL database.
 
 .. code-block:: bash
 
-    $ php app/console doctrine:schema:update --force
+    $ php bin/console doctrine:schema:update --force
 
 This command builds the tables and indexes for your MySQL database. If your
 Symfony application is more complex than a basic Symfony Standard Edition, you

cookbook/deployment/heroku.rst

@@ -275,7 +275,7 @@ This is also very useful to build assets on the production system, e.g. with Ass
     {
         "scripts": {
             "compile": [
-                "app/console assetic:dump"
+                "bin/console assetic:dump"
             ]
         }
     }