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

diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst
@@ -52,8 +52,8 @@ Canonical Parameters
     Define all your application's parameters in the
     ``app/config/parameters.yml.dist`` file.
 
-Symfony includes a configuration file called ``parameters.yml.dist``, which
-stores the canonical list of configuration parameters for the application.
+Since version 2.3, 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

diff --git a/best_practices/creating-the-project.rst b/best_practices/creating-the-project.rst
@@ -27,6 +27,7 @@ to create files and execute the following commands:
 
 .. code-block:: bash
 
+    # Linux, Mac OS X
     $ cd projects/
     $ symfony new blog
 
@@ -62,35 +63,27 @@ 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
@@ -114,7 +107,8 @@ 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.
+more concise and easier to understand. Starting in Symfony 2.6, the official
+Symfony documentation uses the AppBundle name.
 
 .. note::
 
@@ -134,18 +128,13 @@ 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
@@ -158,7 +147,7 @@ that follows these best practices:
 
     .. code-block:: bash
 
-        $ php bin/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
+        $ php app/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
 
 Extending the Directory Structure
 ---------------------------------
@@ -168,6 +157,27 @@ 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

diff --git a/best_practices/forms.rst b/best_practices/forms.rst
@@ -22,20 +22,17 @@ form in its own PHP class::
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
-    use Symfony\Component\Form\Extension\Core\Type\EmailType;
-    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
 
     class PostType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
                 ->add('title')
-                ->add('summary', TextareaType::class)
-                ->add('content', TextareaType::class)
-                ->add('authorEmail', EmailType::class)
-                ->add('publishedAt', DateTimeType::class)
+                ->add('summary', 'textarea')
+                ->add('content', 'textarea')
+                ->add('authorEmail', 'email')
+                ->add('publishedAt', 'datetime')
             ;
         }
 
@@ -45,14 +42,19 @@ form in its own PHP class::
                 'data_class' => 'AppBundle\Entity\Post'
             ));
         }
+
+        public function getName()
+        {
+            return 'post';
+        }
     }
 
 .. best-practice::
 
     Put the form type classes in the ``AppBundle\Form`` namespace, unless you
     use other custom form classes like data transformers.
 
-To use the class, use ``createForm()`` and pass the fully qualified class name::
+To use the class, use ``createForm()`` and instantiate the new class::
 
     // ...
     use AppBundle\Form\PostType;
@@ -61,7 +63,7 @@ To use the class, use ``createForm()`` and pass the fully qualified class name::
     public function newAction(Request $request)
     {
         $post = new Post();
-        $form = $this->createForm(PostType::class, $post);
+        $form = $this->createForm(new PostType(), $post);
 
         // ...
     }
@@ -71,9 +73,13 @@ Registering Forms as Services
 
 You can also
 :ref:`register your form type as a service <form-cookbook-form-field-service>`.
-This is only needed if your form type requires some dependencies to be injected
-by the container, otherwise it is unnecessary overhead and therefore *not*
-recommended to do this for all form type classes.
+But this is *not* recommended unless you plan to reuse the new form type in many
+places or embed it in other forms directly or via the
+:doc:`collection type </reference/forms/types/collection>`.
+
+For most forms that are used only to edit or create something, registering
+the form as a service is over-kill, and makes it more difficult to figure
+out exactly which form class is being used in a controller.
 
 Form Button Configuration
 -------------------------
@@ -85,10 +91,9 @@ makes them easier to re-use later.
 
     Add buttons in the templates, not in the form classes or the controllers.
 
-The Symfony Form component allows you to add buttons a
F438
s 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:
+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:
 
 .. code-block:: php
 
@@ -98,7 +103,7 @@ scope of that form:
         {
             $builder
                 // ...
-                ->add('save', SubmitType::class, array('label' => 'Create Post'))
+                ->add('save', 'submit', array('label' => 'Create Post'))
             ;
         }
 
@@ -113,7 +118,6 @@ some developers configure form buttons in the controller::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
-    use Symfony\Component\Form\Extension\Core\Type\SubmitType;
     use AppBundle\Entity\Post;
     use AppBundle\Form\PostType;
 
@@ -124,8 +128,8 @@ some developers configure form buttons in the controller::
         public function newAction(Request $request)
         {
             $post = new Post();
-            $form = $this->createForm(PostType::class, $post);
-            $form->add('submit', SubmitType::class, array(
+            $form = $this->createForm(new PostType(), $post);
+            $form->add('submit', 'submit', array(
                 'label' => 'Create',
                 'attr'  => array('class' => 'btn btn-default pull-right')
             ));
@@ -209,3 +213,21 @@ Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement
 for clarity. This isn't technically needed, since ``isValid()`` first calls
 ``isSubmitted()``. But without this, the flow doesn't read well as it *looks*
 like the form is *always* processed (even on the GET request).
+
+Custom Form Field Types
+-----------------------
+
+.. best-practice::
+
+    Add the ``app_`` prefix to your custom form field types to avoid collisions.
+
+Custom form field types inherit from the ``AbstractType`` class, which defines the
+``getName()`` method to configure the name of that form type. These names must
+be unique in the application.
+
+If a custom form type uses the same name as any of the Symfony's built-in form
+types, it will override it. The same happens when the custom form type matches
+any of the types defined by the third-party bundles installed in your application.
+
+Add the ``app_`` prefix to your custom form field types to avoid name collisions
+that can lead to hard to debug errors.
diff --git a/best_practices/i18n.rst b/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 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.
+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.
 
 .. tip::
 

diff --git a/best_practices/introduction.rst b/best_practices/introduction.rst
@@ -76,8 +76,12 @@ 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