Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

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/
 
@@ -145,7 +149,7 @@ the class namespace as a parameter:
 
     services:
         app.slugger:
-            class: "%slugger.class%"
+            class: '%slugger.class%'
 
 This practice is cumbersome and completely unnecessary for your own services:
 
@@ -193,7 +197,7 @@ The three entities defined by our sample blog application are a good example:
 Doctrine Mapping Information
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Doctrine Entities are plain PHP objects that you store in some "database".
+Doctrine entities are plain PHP objects that you store in some "database".
 Doctrine only knows about your entities through the mapping metadata configured
 for your model classes. Doctrine supports four metadata formats: YAML, XML,
 PHP and annotations.
@@ -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
@@ -107,9 +107,7 @@ If you've done something like this in the past, it's likely that you've in fact
 *never* actually needed to change that value. Creating a configuration
 option for a value that you are never going to configure just isn't necessary.
 Our recommendation is to define these values as constants in your application.
-You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity:
-
-.. code-block:: php
+You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity::
 
     // src/AppBundle/Entity/Post.php
     namespace AppBundle\Entity;
@@ -128,7 +126,7 @@ from places with access to the Symfony container.
 Constants can be used for example in your Twig templates thanks to the
 `constant() function`_:
 
-.. code-block:: html+jinja
+.. code-block:: html+twig
 
     <p>
         Displaying the {{ constant('NUM_ITEMS', post) }} most recent results.

best_practices/controllers.rst

@@ -43,7 +43,7 @@ configuration to the main routing configuration file:
 
     # app/config/routing.yml
     app:
-        resource: "@AppBundle/Controller/"
+        resource: '@AppBundle/Controller/'
         type:     annotation
 
 This configuration will load annotations from any controller stored inside the
@@ -73,7 +73,7 @@ Template Configuration
 
 .. best-practice::
 
-    Don't use the ``@Template()`` annotation to configure the template used by
+    Don't use the ``@Template`` annotation to configure the template used by
     the controller.
 
 The ``@Template`` annotation is useful, but also involves some magic. We
@@ -148,7 +148,7 @@ For example:
         ));
     }
 
-Normally, you'd expect a ``$id`` argument to ``showAction``. Instead, by
+Normally, you'd expect a ``$id`` argument to ``showAction()``. Instead, by
 creating a new argument (``$post``) and type-hinting it with the ``Post``
 class (which is a Doctrine entity), the ParamConverter automatically queries
 for an object whose ``$id`` property matches the ``{id}`` value. It will
@@ -157,7 +157,7 @@ also show a 404 page if no ``Post`` can be found.
 When Things Get More Advanced
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This works without any configuration because the wildcard name ``{id}`` matches
+The above example works without any configuration because the wildcard name ``{id}`` matches
 the name of the property on the entity. If this isn't true, or if you have
 even more complex logic, the easiest thing to do is just query for the entity
 manually. In our application, we have this situation in ``CommentController``:

best_practices/creating-the-project.rst

@@ -27,13 +27,17 @@ 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
+    c:\projects\> php symfony new blog
+
+.. note::
+
+    If the installer doesn't work for you or doesn't output anything, make sure
+    that the `Phar extension`_ is installed and enabled on your computer.
 
 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,
@@ -58,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
@@ -99,21 +111,20 @@ ProductBundle, then there's no advantage to having two separate bundles.
 
 .. best-practice::
 
-    Create only one bundle called AppBundle for your application logic
+    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::
 
     There is no need to prefix the AppBundle with your own vendor (e.g.
     AcmeAppBundle), because this application bundle is never going to be
     shared.
-    
+
 .. note::
-    
-    Another reason to create a new bundle is when you're overriding something 
+
+    Another reason to create a new bundle is when you're overriding something
     in a vendor's bundle (e.g. a controller). See :doc:`/cookbook/bundles/inheritance`.
 
 All in all, this is the typical directory structure of a Symfony application
@@ -123,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
@@ -142,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
 ---------------------------------
@@ -152,29 +168,7 @@ 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/
+.. _`Phar extension`: http://php.net/manual/en/intro.phar.php
 .. _`public checksums repository`: https://github.com/sensiolabs/checksums
-.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html
+.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html