Jan 31, 2016 · Jan 31, 2016 · Jan 28, 2016 · Jan 31, 2016 · Dec 26, 2015 · Feb 1, 2016
diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst
    │  └─ AppBundle/
    │     └─ Utils/
    │        └─ MyClass.php
    ├─ tests/
    ├─ var/
    ├─ vendor/
    └─ web/

    │  │   └─ Utils/
    │  │      └─ MyClass.php
    │  └─ AppBundle/
    ├─ tests/
    ├─ var/
    ├─ vendor/
    └─ web/


 .. code-block:: bash

    $ phpapp/console doctrine:fixtures:load
    $ phpbin/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
    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``,
 whichstores 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
diff --git a/best_practices/creating-the-project.rst b/best_practices/creating-the-project.rst

 .. code-block:: bash

    # Linux, Mac OS X
    $ cd projects/
    $ symfony new blog


    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
    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::


    blog/
    ├─ app/
    │  ├─ console
    │  ├─ cache/
    │  ├─ config/
    │  ├─ logs/
    │  └─ Resources/
    ├─ bin/
    │  └─ console
    ├─ src/
    │  └─ AppBundle/
    ├─ tests/
    │  └─ AppBundle/
    ├─ var/
    │  ├─ cache/
    │  ├─ logs/
       └─ sessions/
    ├─ vendor/
    └─ web/
       ├─ app.php

    .. code-block:: bash

        $ phpapp/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
        $ phpbin/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction

 Extending the Directory Structure
 ---------------------------------
 :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

    use Symfony\Component\Form\AbstractType;
    use Symfony\Component\Form\FormBuilderInterface;
    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
    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','textarea')
                ->add('content','textarea')
                ->add('authorEmail','email')
                ->add('publishedAt','datetime')
                ->add('summary',TextareaType::class)
                ->add('content',TextareaType::class)
                ->add('authorEmail',EmailType::class)
                ->add('publishedAt',DateTimeType::class)
            ;
        }

        public functionsetDefaultOptions(OptionsResolverInterface $resolver)
        public functionconfigureOptions(OptionsResolver $resolver)
        {
            $resolver->setDefaults(array(
                '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()`` andinstantiate thenewclass::
 To use the class, use ``createForm()`` andpass thefully qualifiedclass name::

    // ...
    use AppBundle\Form\PostType;
    public function newAction(Request $request)
    {
        $post = new Post();
        $form = $this->createForm(newPostType(), $post);
        $form = $this->createForm(PostType::class, $post);

        // ...
    }

 You can also
 :ref:`register your form type as a service <form-cookbook-form-field-service>`.
 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.
 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.

 Form Button Configuration
 -------------------------

    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

        {
            $builder
                // ...
                ->add('save','submit', array('label' => 'Create Post'))
                ->add('save',SubmitType::class, array('label' => 'Create Post'))
            ;
        }


    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;

        public function newAction(Request $request)
        {
            $post = new Post();
            $form = $this->createForm(newPostType(), $post);
            $form->add('submit','submit', array(
            $form = $this->createForm(PostType::class, $post);
            $form->add('submit',SubmitType::class, array(
                'label' => 'Create',
                'attr'  => array('class' => 'btn btn-default pull-right')
            ));
 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
 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.

 Symfony2.6 added support fornotesinside XLIFF files, making them more
 user-friendly fortranslators. At the end, good translations are all about
 context, and theseXLIFF notes allow you to define that context.
 Symfonysupportsnotesin 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

 .. 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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -21,6 +21,8 @@ Inside here, you can create whatever directories you want to organize things:
		│ └─ AppBundle/
		│ └─ Utils/
		│ └─ MyClass.php
		├─ tests/
		├─ var/
		├─ vendor/
		└─ web/

Expand All		@@ -40,6 +42,8 @@ and put things there:
		│ │ └─ Utils/
		│ │ └─ MyClass.php
		│ └─ AppBundle/
		├─ tests/
		├─ var/
		├─ vendor/
		└─ web/

Expand DownExpand Up		@@ -318,7 +322,7 @@ command:

		.. code-block:: bash

		$ phpapp/console doctrine:fixtures:load
		$ phpbin/console doctrine:fixtures:load

		Careful, database will be purged. Do you want to continue Y/N ? Y
		> purging database
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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``,
		whichstores 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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -27,7 +27,6 @@ to create files and execute the following commands:

		.. code-block:: bash

		# Linux, Mac OS X
		$ cd projects/
		$ symfony new blog

Expand DownExpand Up		@@ -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
Expand All		@@ -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::

Expand All		@@ -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
Expand All		@@ -147,7 +158,7 @@ that follows these best practices:

		.. code-block:: bash

		$ phpapp/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
		$ phpbin/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction

		Extending the Directory Structure
		---------------------------------
Expand All		@@ -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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -21,40 +21,38 @@ form in its own PHP class::

		use Symfony\Component\Form\AbstractType;
		use Symfony\Component\Form\FormBuilderInterface;
		use Symfony\Component\OptionsResolver\OptionsResolverInterface;
		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','textarea')
		->add('content','textarea')
		->add('authorEmail','email')
		->add('publishedAt','datetime')
		->add('summary',TextareaType::class)
		->add('content',TextareaType::class)
		->add('authorEmail',EmailType::class)
		->add('publishedAt',DateTimeType::class)
		;
		}

		public functionsetDefaultOptions(OptionsResolverInterface $resolver)
		public functionconfigureOptions(OptionsResolver $resolver)
		{
		$resolver->setDefaults(array(
		'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()`` andinstantiate thenewclass::
		To use the class, use ``createForm()`` andpass thefully qualifiedclass name::

		// ...
		use AppBundle\Form\PostType;
Expand All		@@ -63,7 +61,7 @@ To use the class, use ``createForm()`` and instantiate the new class::
		public function newAction(Request $request)
		{
		$post = new Post();
		$form = $this->createForm(newPostType(), $post);
		$form = $this->createForm(PostType::class, $post);

		// ...
		}
Expand All		@@ -73,13 +71,9 @@ Registering Forms as Services

		You can also
		:ref:`register your form type as a service <form-cookbook-form-field-service>`.
		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.
		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.

		Form Button Configuration
		-------------------------
Expand All		@@ -91,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

Expand All		@@ -103,7 +98,7 @@ directly in your form class, this would effectively limit the scope of that form
		{
		$builder
		// ...
		->add('save','submit', array('label' => 'Create Post'))
		->add('save',SubmitType::class, array('label' => 'Create Post'))
		;
		}

Expand All		@@ -118,6 +113,7 @@ 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;

Expand All		@@ -128,8 +124,8 @@ some developers configure form buttons in the controller::
		public function newAction(Request $request)
		{
		$post = new Post();
		$form = $this->createForm(newPostType(), $post);
		$form->add('submit','submit', array(
		$form = $this->createForm(PostType::class, $post);
		$form->add('submit',SubmitType::class, array(
		'label' => 'Create',
		'attr' => array('class' => 'btn btn-default pull-right')
		));
Expand DownExpand Up		@@ -213,21 +209,3 @@ 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.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.

		Symfony2.6 added support fornotesinside XLIFF files, making them more
		user-friendly fortranslators. At the end, good translations are all about
		context, and theseXLIFF notes allow you to define that context.
		Symfonysupportsnotesin 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::

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down