Merge branch '2.7' into 2.8

Author: wouterj

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/configuration.rst

@@ -52,8 +52,8 @@ Canonical Parameters
     Define all your application's parameters in the
     ``app/config/parameters.yml.dist`` file.
 
-Since version 2.3, Symfony includes a configuration file called ``parameters.yml.dist``,
-which stores the canonical list of configuration parameters for the application.
+Symfony includes a configuration file called ``parameters.yml.dist``, which
+stores the canonical list of configuration parameters for the application.
 
 Whenever a new configuration parameter is defined for the application, you
 should also add it to this file and submit the changes to your version control

best_practices/creating-the-project.rst

@@ -27,7 +27,6 @@ to create files and execute the following commands:
 
 .. code-block:: bash
 
-    # Linux, Mac OS X
     $ cd projects/
     $ symfony new blog
 
@@ -63,27 +62,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
@@ -107,8 +114,7 @@ ProductBundle, then there's no advantage to having two separate bundles.
     Create only one bundle called AppBundle for your application logic.
 
 Implementing a single AppBundle bundle in your projects will make your code
-more concise and easier to understand. Starting in Symfony 2.6, the official
-Symfony documentation uses the AppBundle name.
+more concise and easier to understand.
 
 .. note::
 
@@ -128,13 +134,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
@@ -147,7 +158,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
 ---------------------------------
@@ -157,27 +168,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/
 .. _`Phar extension`: http://php.net/manual/en/intro.phar.php
 .. _`public checksums repository`: https://github.com/sensiolabs/checksums

best_practices/forms.rst

@@ -85,9 +85,10 @@ makes them easier to re-use later.
 
     Add buttons in the templates, not in the form classes or the controllers.
 
-Since Symfony 2.3, you can add buttons as fields on your form. This is a nice
-way to simplify the template that renders your form. But if you add the buttons
-directly in your form class, this would effectively limit the scope of that form:
+The Symfony Form component allows you to add buttons as fields on your form.
+This is a nice way to simplify the template that renders your form. But if you
+add the buttons directly in your form class, this would effectively limit the
+scope of that form:
 
 .. code-block:: php
 

best_practices/i18n.rst

@@ -32,9 +32,9 @@ Of all the available translation formats, only XLIFF and gettext have broad
 support in the tools used by professional translators. And since it's based
 on XML, you can validate XLIFF file contents as you write them.
 
-Symfony 2.6 added support for notes inside XLIFF files, making them more
-user-friendly for translators. At the end, good translations are all about
-context, and these XLIFF notes allow you to define that context.
+Symfony supports notes in XLIFF files, making them more user-friendly for
+translators. At the end, good translations are all about context, and these
+XLIFF notes allow you to define that context.
 
 .. tip::
 

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/security.rst

@@ -270,7 +270,6 @@ the same ``getAuthorEmail`` logic you used above:
     use Symfony\Component\Security\Core\User\UserInterface;
     use AppBundle\Entity\Post;
 
-    // Voter class requires Symfony 2.8 or higher version
     class PostVoter extends Voter
     {
         const CREATE = 'create';

best_practices/tests.rst

@@ -28,8 +28,8 @@ functional tests, you can quickly spot any big errors before you deploy them:
 
 A functional test can be as easy as this::
 
-    // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php
-    namespace AppBundle\Tests;
+    // tests/AppBundle/ApplicationAvailabilityFunctionalTest.php
+    namespace Tests\AppBundle;
 
     use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
 

book/bundles.rst

@@ -107,6 +107,7 @@ Now that you've created the bundle, enable it via the ``AppKernel`` class::
     {
         $bundles = array(
             // ...
+
             // register your bundle
             new Acme\TestBundle\AcmeTestBundle(),
         );
@@ -122,7 +123,7 @@ generating a basic bundle skeleton:
 
 .. code-block:: bash
 
-    $ php app/console generate:bundle --namespace=Acme/TestBundle
+    $ php bin/console generate:bundle --namespace=Acme/TestBundle
 
 The bundle skeleton generates a basic controller, template and routing
 resource that can be customized. You'll learn more about Symfony's command-line

book/configuration.rst

@@ -122,13 +122,13 @@ FrameworkBundle configuration:
 
 .. code-block:: bash
 
-    $ php app/console config:dump-reference FrameworkBundle
+    $ php bin/console config:dump-reference FrameworkBundle
 
 The extension alias (configuration key) can also be used:
 
 .. code-block:: bash
 
-    $ php app/console config:dump-reference framework
+    $ php bin/console config:dump-reference framework
 
 .. note::
 
@@ -177,7 +177,7 @@ cached files and allow them to rebuild:
 
 .. code-block:: bash
 
-    $ php app/console cache:clear --env=prod --no-debug
+    $ php bin/console cache:clear --env=prod --no-debug
 
 .. note::
 

book/controller.rst

@@ -533,7 +533,7 @@ console command:
 
 .. code-block:: bash
 
-    $ php app/console debug:container
+    $ php bin/console debug:container
 
 For more information, see the :doc:`/book/service_container` chapter.