feature #5916 [3.0][Best Practices][Quick Tour] Use the 3.0 directory…

… structure (WouterJ)

This PR was merged into the master branch.

Discussion
----------

[3.0][Best Practices][Quick Tour] Use the 3.0 directory structure

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

Commits
-------

c6d436b [QuickTour] Use new directory structure
215c36d [BestPractices] Use new directory structure

best_practices/business-logic.rst

@@ -21,6 +21,8 @@ Inside here, you can create whatever directories you want to organize things:
     │  └─ AppBundle/
     │     └─ Utils/
     │        └─ MyClass.php
+    ├─ tests/
+    ├─ var/
     ├─ vendor/
     └─ web/
 
@@ -40,6 +42,8 @@ and put things there:
     │  │   └─ Utils/
     │  │      └─ MyClass.php
     │  └─ AppBundle/
+    ├─ tests/
+    ├─ var/
     ├─ vendor/
     └─ web/
 
@@ -318,7 +322,7 @@ command:
 
 .. code-block:: bash
 
-    $ php app/console doctrine:fixtures:load
+    $ php bin/console doctrine:fixtures:load
 
     Careful, database will be purged. Do you want to continue Y/N ? Y
       > purging database

best_practices/creating-the-project.rst

@@ -27,14 +27,9 @@ to create files and execute the following commands:
 
 .. code-block:: bash
 
-    # Linux, Mac OS X
     $ cd projects/
     $ symfony new blog
 
-    # Windows
-    c:\> cd projects/
-    c:\projects\> php symfony.phar new blog
-
 This command creates a new directory called ``blog`` that contains a fresh new
 project based on the most recent stable Symfony version available. In addition,
 the installer checks if your system meets the technical requirements to execute
@@ -58,27 +53,35 @@ number of files and directories generated automatically:
 
     blog/
     ├─ app/
-    │  ├─ console
-    │  ├─ cache/
     │  ├─ config/
-    │  ├─ logs/
     │  └─ Resources/
+    ├─ bin
+    │  └─ console
     ├─ src/
     │  └─ AppBundle/
+    ├─ var/
+    │  ├─ cache/
+    │  ├─ logs/
+    │  └─ sessions/
+    ├─ tests/
+    │  └─ AppBundle/
     ├─ vendor/
     └─ web/
 
 This file and directory hierarchy is the convention proposed by Symfony to
 structure your applications. The recommended purpose of each directory is the
 following:
 
-* ``app/cache/``, stores all the cache files generated by the application;
 * ``app/config/``, stores all the configuration defined for any environment;
-* ``app/logs/``, stores all the log files generated by the application;
 * ``app/Resources/``, stores all the templates and the translation files for the
   application;
 * ``src/AppBundle/``, stores the Symfony specific code (controllers and routes),
   your domain code (e.g. Doctrine classes) and all your business logic;
+* ``var/cache/``, stores all the cache files generated by the application;
+* ``var/logs/``, stores all the log files generated by the application;
+* ``var/sessions/``, stores all the session files generated by the application;
+* ``tests/AppBundle/``, stores the automatic tests (e.g. Unit tests) of the
+  application.
 * ``vendor/``, this is the directory where Composer installs the application's
   dependencies and you should never modify any of its contents;
 * ``web/``, stores all the front controller files and all the web assets, such
@@ -123,13 +126,18 @@ that follows these best practices:
 
     blog/
     ├─ app/
-    │  ├─ console
-    │  ├─ cache/
     │  ├─ config/
-    │  ├─ logs/
     │  └─ Resources/
+    ├─ bin/
+    │  └─ console
     ├─ src/
     │  └─ AppBundle/
+    ├─ tests/
+    │  └─ AppBundle/
+    ├─ var/
+    │  ├─ cache/
+    │  ├─ logs/
+       └─ sessions/
     ├─ vendor/
     └─ web/
        ├─ app.php
@@ -142,7 +150,7 @@ that follows these best practices:
 
     .. code-block:: bash
 
-        $ php app/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
+        $ php bin/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
 
 Extending the Directory Structure
 ---------------------------------
@@ -152,27 +160,6 @@ structure of Symfony, you can
 :doc:`override the location of the main directories </cookbook/configuration/override_dir_structure>`:
 ``cache/``, ``logs/`` and ``web/``.
 
-In addition, Symfony3 will use a slightly different directory structure when
-it's released:
-
-.. code-block:: text
-
-    blog-symfony3/
-    ├─ app/
-    │  ├─ config/
-    │  └─ Resources/
-    ├─ bin/
-    │  └─ console
-    ├─ src/
-    ├─ var/
-    │  ├─ cache/
-    │  └─ logs/
-    ├─ vendor/
-    └─ web/
-
-The changes are pretty superficial, but for now, we recommend that you use
-the Symfony directory structure.
-
 .. _`Composer`: https://getcomposer.org/
 .. _`Get Started`: https://getcomposer.org/doc/00-intro.md
 .. _`Composer download page`: https://getcomposer.org/download/

best_practices/introduction.rst

@@ -76,12 +76,8 @@ installer and then execute this command to download the demo application:
 
 .. code-block:: bash
 
-    # Linux and Mac OS X
     $ symfony demo
 
-    # Windows
-    c:\> php symfony demo
-
 **The demo application is a simple blog engine**, because that will allow us to
 focus on the Symfony concepts and features without getting buried in difficult
 implementation details. Instead of developing the application step by step in

best_practices/tests.rst

@@ -30,8 +30,8 @@ A functional test can be as easy as this:
 
 .. code-block:: php
 
-    // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php
-    namespace AppBundle\Tests;
+    // tests/AppBundle/ApplicationAvailabilityFunctionalTest.php
+    namespace Tests\AppBundle;
 
     use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
 

quick_tour/the_architecture.rst

@@ -15,8 +15,14 @@ but the recommended structure is as follows:
 
 ``app/``
     The application configuration, templates and translations.
+``bin/``
+    Executable files (e.g. ``bin/console``).
 ``src/``
     The project's PHP code.
+``tests/``
+    Automatic tests (e.g. Unit tests).
+``var/``
+    Generated files (cache, logs, etc.).
 ``vendor/``
     The third-party dependencies.
 ``web/``
@@ -30,7 +36,7 @@ stylesheets and JavaScript files. It is also where each :term:`front controller`
 lives, such as the production controller shown here::
 
     // web/app.php
-    require_once __DIR__.'/../app/bootstrap.php.cache';
+    require_once __DIR__.'/../var/bootstrap.php.cache';
     require_once __DIR__.'/../app/AppKernel.php';
 
     use Symfony\Component\HttpFoundation\Request;
@@ -260,7 +266,7 @@ Symfony applications can contain several configuration files defined in
 several formats (YAML, XML, PHP, etc.) Instead of parsing and combining
 all those files for each request, Symfony uses its own cache system. In
 fact, the application configuration is only parsed for the very first request
-and then compiled down to plain PHP code stored in the ``app/cache/``
+and then compiled down to plain PHP code stored in the ``var/cache/``
 directory.
 
 In the development environment, Symfony is smart enough to update the cache
@@ -271,10 +277,10 @@ the ``prod`` environment:
 
 .. code-block:: bash
 
-    $ php app/console cache:clear --env=prod
+    $ php bin/console cache:clear --env=prod
 
 When developing a web application, things can go wrong in many ways. The
-log files in the ``app/logs/`` directory tell you everything about the requests
+log files in the ``var/logs/`` directory tell you everything about the requests
 and help you fix the problem quickly.
 
 Using the Command Line Interface
@@ -288,13 +294,13 @@ Run it without any arguments to learn more about its capabilities:
 
 .. code-block:: bash
 
-    $ php app/console
+    $ php bin/console
 
 The ``--help`` option helps you discover the usage of a command:
 
 .. code-block:: bash
 
-    $ php app/console debug:router --help
+    $ php bin/console debug:router --help
 
 Final Thoughts
 --------------