diff --git a/_exts b/_exts
index 03bc1c601..e58edd22d 160000
--- a/_exts
+++ b/_exts
@@ -1 +1 @@
-Subproject commit 03bc1c60172a280619e3476f22b111b4a187895d
+Subproject commit e58edd22d16cb247267025d557410dcbfa5fa959
diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst
new file mode 100644
index 000000000..fe7364ec2
--- /dev/null
+++ b/best_practices/business-logic.rst
@@ -0,0 +1,344 @@
+Organizing Your Business Logic
+==============================
+
+In computer software, **business logic** or domain logic is "the part of the
+program that encodes the real-world business rules that determine how data can
+be created, displayed, stored, and changed" (read `full definition`_).
+
+In Symfony applications, business logic is all the custom code you write for
+your app that's not specific to the framework (e.g. routing and controllers).
+Domain classes, Doctrine entities and regular PHP classes that are used as
+services are good examples of business logic.
+
+For most projects, you should store everything inside the ``AppBundle``.
+Inside here, you can create whatever directories you want to organize things:
+
+.. code-block:: text
+
+ symfoy2-project/
+ ├─ app/
+ ├─ src/
+ │ └─ AppBundle/
+ │ └─ Utils/
+ │ └─ MyClass.php
+ ├─ vendor/
+ └─ web/
+
+Storing Classes Outside of the Bundle?
+--------------------------------------
+
+But there's no technical reason for putting business logic inside of a bundle.
+If you like, you can create your own namespace inside the ``src/`` directory
+and put things there:
+
+.. code-block:: text
+
+ symfoy2-project/
+ ├─ app/
+ ├─ src/
+ │ ├─ Acme/
+ │ │ └─ Utils/
+ │ │ └─ MyClass.php
+ │ └─ AppBundle/
+ ├─ vendor/
+ └─ web/
+
+.. tip::
+
+ The recommended approach of using the ``AppBundle`` directory is for
+ simplicity. If you're advanced enough to know what needs to live in
+ a bundle and what can live outside of one, then feel free to do that.
+
+Services: Naming and Format
+---------------------------
+
+The blog application needs a utility that can transform a post title (e.g.
+"Hello World") into a slug (e.g. "hello-world"). The slug will be used as
+part of the post URL.
+
+Let's, create a new ``Slugger`` class inside ``src/AppBundle/Utils/`` and
+add the following ``slugify()`` method:
+
+.. code-block:: php
+
+ // src/AppBundle/Utils/Slugger.php
+ namespace AppBundle\Utils;
+
+ class Slugger
+ {
+ public function slugify($string)
+ {
+ return preg_replace(
+ '/[^a-z0-9]/', '-', strtolower(trim(strip_tags($string)))
+ );
+ }
+ }
+
+Next, define a new service for that class.
+
+.. code-block:: yaml
+
+ # app/config/services.yml
+ services:
+ # keep your service names short
+ slugger:
+ class: AppBundle\Utils\Slugger
+
+Traditionally, the naming convention for a service involved following the
+class name and location to avoid name collisions. Thus, the service
+*would have been* called ``app.utils.slugger``. But by using short service names,
+your code will be easier to read and use.
+
+.. best-practice::
+
+ The name of your application's services should be as short as possible,
+ ideally just one simple word.
+
+Now you can use the custom slugger in any controller class, such as the
+``AdminController``:
+
+.. code-block:: php
+
+ public function createAction(Request $request)
+ {
+ // ...
+
+ if ($form->isSubmitted() && $form->isValid()) {
+ $slug = $this->get('slugger')->slugify($post->getTitle()));
+ $post->setSlug($slug);
+
+ // ...
+ }
+ }
+
+Service Format: YAML
+--------------------
+
+In the previous section, YAML was used to define the service.
+
+.. best-practice::
+
+ Use the YAML format to define your own services.
+
+This is controversial, and in our experience, YAML and XML usage is evenly
+distributed among developers, with a slight preference towards YAML.
+Both formats have the same performance, so this is ultimately a matter of
+personal taste.
+
+We recommend YAML because it's friendly to newcomers and concise. You can
+of course use whatever format you like.
+
+Service: No Class Parameter
+---------------------------
+
+You may have noticed that the previous service definition doesn't configure
+the class namespace as a parameter:
+
+.. code-block:: yaml
+
+ # app/config/services.yml
+
+ # service definition with class namespace as parameter
+ parameters:
+ slugger.class: AppBundle\Utils\Slugger
+
+ services:
+ slugger:
+ class: "%slugger.class%"
+
+This practice is cumbersome and completely unnecessary for your own services:
+
+.. best-practice::
+
+ Don't define parameters for the classes of your services.
+
+This practice was wrongly adopted from third-party bundles. When Symfony
+introduced its service container, some developers used this technique to easily
+allow overriding services. However, overriding a service by just changing its
+class name is a very rare use case because, frequently, the new service has
+different constructor arguments.
+
+Using a Persistence Layer
+-------------------------
+
+Symfony is an HTTP framework that only cares about generating an HTTP response
+for each HTTP request. That's why Symfony doesn't provide a way to talk to
+a persistence layer (e.g. database, external API). You can choose whatever
+library of strategy you want for this.
+
+In practice, many Symfony applications rely on the independent
+`Doctrine project`_ to define their model using entities and repositories.
+Just like with business logic, we recommend storing Doctrine entities in
+the ``AppBundle``
+
+The three entities defined by our sample blog application are a good example:
+
+.. code-block:: text
+
+ symfony2-project/
+ ├─ ...
+ └─ src/
+ └─ AppBundle/
+ └─ Entity/
+ ├─ Comment.php
+ ├─ Post.php
+ └─ User.php
+
+.. tip::
+
+ If you're more advanced, you can of course store them under your own
+ namespace in ``src/``.
+
+Doctrine Mapping Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+.. best-practice::
+
+ Use annotations to define the mapping information of the Doctrine entities.
+
+Annotations are by far the most convenient and agile way of setting up and
+looking for mapping information:
+
+.. code-block:: php
+
+ namespace AppBundle\Entity;
+
+ use Doctrine\ORM\Mapping as ORM;
+ use Doctrine\Common\Collections\ArrayCollection;
+
+ /**
+ * @ORM\Entity
+ */
+ class Post
+ {
+ const NUM_ITEMS = 10;
+
+ /**
+ * @ORM\Id
+ * @ORM\GeneratedValue
+ * @ORM\Column(type="integer")
+ */
+ private $id;
+
+ /**
+ * @ORM\Column(type="string")
+ */
+ private $title;
+
+ /**
+ * @ORM\Column(type="string")
+ */
+ private $slug;
+
+ /**
+ * @ORM\Column(type="text")
+ */
+ private $content;
+
+ /**
+ * @ORM\Column(type="string")
+ */
+ private $authorEmail;
+
+ /**
+ * @ORM\Column(type="datetime")
+ */
+ private $publishedAt;
+
+ /**
+ * @ORM\OneToMany(
+ * targetEntity="Comment",
+ * mappedBy="post",
+ * orphanRemoval=true
+ * )
+ * @ORM\OrderBy({"publishedAt" = "ASC"})
+ */
+ private $comments;
+
+ public function __construct()
+ {
+ $this->publishedAt = new \DateTime();
+ $this->comments = new ArrayCollection();
+ }
+
+ // getters and setters ...
+ }
+
+All formats have the same performance, so this is once again ultimately a
+matter of taste.
+
+Data Fixtures
+~~~~~~~~~~~~~
+
+As fixtures support is not enabled by default in Symfony, you should execute
+the following command to install the Doctrine fixtures bundle:
+
+.. code-block:: bash
+
+ $ composer require "doctrine/doctrine-fixtures-bundle"
+
+Then, enable the bundle in ``AppKernel.php``, but only for the ``dev`` and
+``test`` environments:
+
+.. code-block:: php
+
+ use Symfony\Component\HttpKernel\Kernel;
+
+ class AppKernel extends Kernel
+ {
+ public function registerBundles()
+ {
+ $bundles = array(
+ // ...
+ );
+
+ if (in_array($this->getEnvironment(), array('dev', 'test'))) {
+ // ...
+ $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle(),
+ }
+
+ return $bundles;
+ }
+
+ // ...
+ }
+
+We recommend creating just *one* `fixture class`_ for simplicity, though
+you're welcome to have more if that class gets quite large.
+
+Assuming you have at least one fixtures class and that the database access
+is configured properly, you can load your fixtures by executing the following
+command:
+
+.. code-block:: bash
+
+ $ php app/console doctrine:fixtures:load
+
+ Careful, database will be purged. Do you want to continue Y/N ? Y
+ > purging database
+ > loading AppBundle\DataFixtures\ORM\LoadFixtures
+
+Coding Standards
+----------------
+
+The Symfony source code follows the `PSR-1`_ and `PSR-2`_ coding standards that
+were defined by the PHP community. You can learn more about
+`the Symfony Code Standards`_ and even use the `PHP-CS-Fixer`_, which is
+a command-line utility that can fix the coding standards of an entire codebase
+in a matter of seconds.
+
+.. _`full definition`: http://en.wikipedia.org/wiki/Business_logic
+.. _`Toran Proxy`: https://toranproxy.com/
+.. _`Composer`: https://getcomposer.org/
+.. _`MVC architecture`: http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
+.. _`Doctrine project`: http://www.doctrine-project.org/
+.. _`fixture class`: http://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures
+.. _`PSR-1`: http://www.php-fig.org/psr/psr-1/
+.. _`PSR-2`: http://www.php-fig.org/psr/psr-2/
+.. _`the Symfony Code Standards`: http://symfony.com/doc/current/contributing/code/standards.html
+.. _`PHP-CS-Fixer`: https://github.com/fabpot/PHP-CS-Fixer
diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst
new file mode 100644
index 000000000..ab340bbe7
--- /dev/null
+++ b/best_practices/configuration.rst
@@ -0,0 +1,187 @@
+Configuration
+=============
+
+La configuration implique généralement différentes parties de l'application (comme
+l'infrastructure et la sécurité) et différents environnements (développement, production).
+C'est pourquoi Symfony recommande de diviser la configuration de l'application en trois
+parties.
+
+Configuration liée à l'infrastructure
+-------------------------------------
+
+.. best-practice::
+
+ Définissez les options de configuration liée à l'infrastructure dans
+ le fichier ``app/config/parameters.yml``.
+
+Le fichier par défaut ``parameters.yml`` suit cette recommandation et défini les
+options relatives à la base de données et au serveur de mail :
+
+.. code-block:: yaml
+
+ # app/config/parameters.yml
+ parameters:
+ database_driver: pdo_mysql
+ database_host: 127.0.0.1
+ database_port: ~
+ database_name: symfony
+ database_user: root
+ database_password: ~
+
+ mailer_transport: smtp
+ mailer_host: 127.0.0.1
+ mailer_user: ~
+ mailer_password: ~
+
+ # ...
+
+Ces options ne sont pas définies dans le fichier ``app/config/config.yml`` car
+elles n'ont pas de rapport avec le comportement de l'application. En d'autres termes,
+votre application ne se soucie pas de l'emplacement de la base de données ou des
+droits permettant d'y avoir accès, tant que la base de données est bien configurée.
+
+Paramètres standards
+~~~~~~~~~~~~~~~~~~~~
+
+.. best-practice::
+
+ Définissez tous les paramètres de votre application dans le fichier
+ ``app/config/parameters.yml.dist``.
+
+Depuis la version 2.3, Symfony inclus un fichier de configuration appelé
+``parameters.yml.dist``, qui stocke la liste des paramètres de configuration
+standard de votre application.
+
+Chaque fois qu'un nouveau paramètre de configuration est défini pour votre application,
+vous devriez également l'ajouter à ce fichier et envoyer cette modification à votre
+gestionnaire de source. Ensuite, à chaque fois qu'un développeur met à jour le projet
+ou le déploie sur un serveur, Symfony vérifiera s'il y a des différences entre le fichier
+standard ``parameters.yml.dist`` et votre fichier local ``parameters.yml``. S'il existe
+une différence, Symfony vous demandera d'indiquer une valeur pour le nouveau paramètre
+et l'ajoutera à votre fichier local ``parameters.yml``.
+
+Configuration liée à l'application
+----------------------------------
+
+.. best-practice::
+
+ Définissez les options de configuration liées au comportement de
+ l'application dans le fichier ``app/config/config.yml``.
+
+Le fichier ``config.yml`` contient les options utilisées par l'application pour
+modifier son comportement, comme l'expéditeur des notifications par email ou
+l'activation de `fonctionnalitées conditionnelles`_. Définir ces valeurs
+dans le fichier ``parameters.yml`` serait ajouter une couche supplémentaire de
+configuration qui ne serait pas nécessaire car vous ne voulez pas ou n'avez pas
+besoin de modifier ces valeurs de configuration sur chaque serveur.
+
+Les options de configuration définies dans le fichier ``config.yml`` varient
+généralement d'un `environnement d'exécution`_ à l'autre. C'est pourquoi Symfony
+inclut déjà les fichiers ``app/config/config_dev.yml`` et ``app/config/config_prod.yml``
+de sorte que vous puissiez indiquer des valeurs spécifiques à chaque environnement.
+
+Constantes vs Options de Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+L'une des erreurs les plus commune lors de la définition de la configuration
+de l'application est de créer de nouvelles options pour les valeurs qui ne
+change jamais, comme le nombre d'éléments pour des résultats paginés.
+
+.. best-practice::
+
+ Utilisez des constantes pour définir les options de configuration ne changeant que rarement.
+
+L'approche traditionnelle pour définir les options de configuration a impliqué
+que beaucoup d'application Symfony ont inclut une option comme ce qui suit, qui
+serait utilisée pour gérer le nombre de messages à afficher sur la page d'accueil
+d'un blog :
+
+.. code-block:: yaml
+
+ # app/config/config.yml
+ parameters:
+ homepage.num_items: 10
+
+Si vous vous demandez quand est-ce la dernière fois que vous avez changé la valeur
+d'une option de ce type, il y a de fortes chances pour que ce soit *jamais*. Créer une
+option de configuration pour une valeur que vous ne configurerez jamais n'est pas
+nécessaire. Notre recommandation est de définir ces valeurs en tant que constantes
+dans votre application. Vous pourriez, par exemple, définir une constante ``NUM_ITEMS``
+dans l'entité ``Post`` :
+
+.. code-block:: php
+
+ // src/AppBundle/Entity/Post.php
+ namespace AppBundle\Entity;
+
+ class Post
+ {
+ const NUM_ITEMS = 10;
+
+ // ...
+ }
+
+Le principal avantage à définir des constantes est que vous pouvez utiliser leur
+valeur partout dans votre application. Lorsque vous utilisez des paramètres, ils
+ne sont disponibles que lorsque vous avez accès au container Symfony.
+
+Les constantes peuvent être utilisées par exemple dans vos templates Twig grâce
+à la fonction ``constant()`` :
+
+.. code-block:: html+jinja
+
+
+ Displaying the {{ constant('NUM_ITEMS', post) }} most recent results.
+
+
+Et les entités et repositories Doctrine peuvent accéder facilement à ces valeurs,
+alors qu'elles n'ont pas accès aux paramètres du container :
+
+.. code-block:: php
+
+ namespace AppBundle\Repository;
+
+ use Doctrine\ORM\EntityRepository;
+ use AppBundle\Entity\Post;
+
+ class PostRepository extends EntityRepository
+ {
+ public function findLatest($limit = Post::NUM_ITEMS)
+ {
+ // ...
+ }
+ }
+
+Le seul inconvénient notable de l'utilisation des constantes pour ce type de
+configuration est que vous ne pouvez pas les redéfinir facilement dans vos tests.
+
+Configuration Sémantique: Ne le faites pas
+------------------------------------------
+
+.. best-practice::
+
+ Ne définissez pas une configuration sémantique d'injection de dépendance pour vos bundle.
+
+Comme expliqué dans l'article `Comment exposer une configuration sémantique pour un Bundle`_,
+les bundles Symfony ont deux possibilités concernant la gestion de la configuration : la
+configuration normale des serveur via le fichier ``services.yml`` et la configuration
+sémantique via une classe spécifique ``*Extension``.
+
+Bien que la configuration sémantique soit beaucoup plus puissante et fournisse des
+fonctionnalités intéressante comme la validation, la charge de travail nécessaire
+pour définir cette configution n'est pas valable pour vos bundles qui ne sont pas
+destinés à être partagés en tant que bundle réutilisable.
+
+Déplacez les options sensibles entièrement en dehors de Symfony
+---------------------------------------------------------------
+
+Lorsque vous manipulez des options sensibles, comme des accès à une base de données, nous
+vous recommendons de les stocker en dehors du projet Symfony et de les rendre disponible
+au travers des variables d'environnement. Apprenez comme faire en suivant cet article :
+`Comment configurer les paramètres externes dans le conteneur de services`_
+
+.. _`fonctionnalitées conditionnelles`: http://en.wikipedia.org/wiki/Feature_toggle
+.. _`environnement d'exécution`: http://symfony.com/doc/current/cookbook/configuration/environments.html
+.. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html
+.. _`Comment exposer une configuration sémantique pour un Bundle`: http://symfony.com/fr/doc/current/cookbook/bundles/extension.html
+.. _`Comment configurer les paramètres externes dans le conteneur de services`: http://symfony.com/fr/doc/current/cookbook/configuration/external_parameters.html
diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst
new file mode 100644
index 000000000..05cd7a1af
--- /dev/null
+++ b/best_practices/controllers.rst
@@ -0,0 +1,212 @@
+Controllers
+===========
+
+Symfony follows the philosophy of *"thin controllers and fat models"*. This
+means that controllers should hold just the thin layer of *glue-code*
+needed to coordinate the different parts of the application.
+
+As a rule of thumb, you should follow the 5-10-20 rule, where controllers should
+only define 5 variables or less, contain 10 actions or less and include 20 lines
+of code or less in each action. This isn't an exact science, but it should
+help you realize when code should be refactored out of the controller and
+into a service.
+
+.. best-practice::
+
+ Make your controller extend the ``FrameworkBundle`` base Controller and
+ use annotations to configure routing, caching and security whenever possible.
+
+Coupling the controllers to the underlying framework allows you to leverage
+all of its features and increases your productivity.
+
+And since your controllers should be thin and contain nothing more than a
+few lines of *glue-code*, spending hours trying to decouple them from your
+framework doesn't benefit you in the long run. The amount of time *wasted*
+isn't worth the benefit.
+
+In addition, using annotations for routing, caching and security simplifies
+configuration. You don't need to browse tens of files created with different
+formats (YAML, XML, PHP): all the configuration is just where you need it
+and it only uses one format.
+
+Overall, this means you should aggressively decouple your business logic
+from the framework while, at the same time, aggressively coupling your controllers
+and routing *to* the framework in order to get the most out of it.
+
+Routing Configuration
+---------------------
+
+To load routes defined as annotations in your controllers, add the following
+configuration to the main routing configuration file:
+
+.. code-block:: yaml
+
+ # app/config/routing.yml
+ app:
+ resource: "@AppBundle/Controller/"
+ type: annotation
+
+This configuration will load annotations from any controller stored inside the
+``src/AppBundle/Controller/`` directory and even from its subdirectories.
+So if your application defines lots of controllers, it's perfectly ok to
+reorganize them into subdirectories:
+
+.. code-block:: text
+
+ /
+ ├─ ...
+ └─ src/
+ └─ AppBundle/
+ ├─ ...
+ └─ Controller/
+ ├─ DefaultController.php
+ ├─ ...
+ ├─ Api/
+ │ ├─ ...
+ │ └─ ...
+ └─ Backend/
+ ├─ ...
+ └─ ...
+
+Template Configuration
+----------------------
+
+.. best-practice::
+
+ Don't use the ``@Template()`` annotation to configure the template used by
+ the controller.
+
+The ``@Template`` annotation is useful, but also involves some magic. For
+that reason, we don't recommend using it.
+
+Most of the time, ``@Template`` is used without any parameters, which makes
+it more difficult to know which template is being rendered. It also makes
+it less obvious to beginners that a controller should always return a Response
+object (unless you're using a view layer).
+
+Lastly, the ``@Template`` annotation uses a ``TemplateListener`` class that hooks
+into the ``kernel.view`` event dispatched by the framework. This listener introduces
+a measurable performance impact. In the sample blog application, rendering the
+homepage took 5 milliseconds using the ``$this->render()`` method and 26 milliseconds
+using the ``@Template`` annotation.
+
+How the Controller Looks
+------------------------
+
+Considering all this, here is an example of how the controller should look
+for the homepage of our app:
+
+.. code-block:: php
+
+ namespace AppBundle\Controller;
+
+ use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+ use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+ class DefaultController extends Controller
+ {
+ /**
+ * @Route("/", name="homepage")
+ */
+ public function indexAction()
+ {
+ $em = $this->getDoctrine()->getManager();
+ $posts = $em->getRepository('App:Post')->findLatest();
+
+ return $this->render('default/index.html.twig', array(
+ 'posts' => $posts
+ ));
+ }
+ }
+
+.. _best-practices-paramconverter:
+
+Using the ParamConverter
+------------------------
+
+If you're using Doctrine, then you can *optionally* use the `ParamConverter`_
+to automatically query for an entity and pass it as an argument to your controller.
+
+.. best-practice::
+
+ Use the ParamConverter trick to automatically query for Doctrine entities
+ when it's simple and convenient.
+
+For example:
+
+.. code-block:: php
+
+ /**
+ * @Route("/{id}", name="admin_post_show")
+ */
+ public function showAction(Post $post)
+ {
+ $deleteForm = $this->createDeleteForm($post);
+
+ return $this->render('admin/post/show.html.twig', array(
+ 'post' => $post,
+ 'delete_form' => $deleteForm->createView(),
+ ));
+ }
+
+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
+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 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``:
+
+.. code-block:: php
+
+ /**
+ * @Route("/comment/{postSlug}/new", name = "comment_new")
+ */
+ public function newAction(Request $request, $postSlug)
+ {
+ $post = $this->getDoctrine()
+ ->getRepository('AppBundle:Post')
+ ->findOneBy(array('slug' => $postSlug));
+
+ if (!$post) {
+ throw $this->createNotFoundException();
+ }
+
+ // ...
+ }
+
+You can also use the ``@ParamConverter`` configuration, which is infinitely
+flexible:
+
+.. code-block:: php
+
+ use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+ use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
+
+ /**
+ * @Route("/comment/{postSlug}/new", name = "comment_new")
+ * @ParamConverter("post", options={"mapping": {"postSlug": "slug"}})
+ */
+ public function newAction(Request $request, Post $post)
+ {
+ // ...
+ }
+
+The point is this: the ParamConverter shortcut is great for simple situations.
+But you shouldn't forget that querying for entities directly is still very
+easy.
+
+Pre and Post Hooks
+------------------
+
+If you need to execute some code before or after the execution of your controllers,
+you can use the EventDispatcher component to `set up before/after filters`_.
+
+.. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`set up before/after filters`: http://symfony.com/doc/current/cookbook/event_dispatcher/before_after_filters.html
diff --git a/best_practices/creating-the-project.rst b/best_practices/creating-the-project.rst
new file mode 100644
index 000000000..f14190c2e
--- /dev/null
+++ b/best_practices/creating-the-project.rst
@@ -0,0 +1,255 @@
+Créer le projet
+===============
+
+Installer Symfony
+-----------------
+
+Il n'y a qu'une seule voie recommandée pour installer Symfony :
+
+.. best-practice::
+
+ Utilisez toujours `Composer`_ pour installer Symfony.
+
+Composer est le gestionnaire de dépendances utilisé par les applications PHP modernes.
+Ajoutez ou supprimez des prérequis à votre projet et mettez à jour les bibliothèques
+tierces utilisées par votre code est un vrai bonheur avec Composer.
+
+Gestion des dépendances avec Composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Avant d'installer Symfony, vous devez être sûr que vous avez Composer d'installé
+globalement. Ouvrez votre terminal (aussi appelé *console de commandes*) et exécutez
+la commande suivante :
+
+.. code-block:: bash
+
+ $ composer --version
+ Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48
+
+Vous verrez probablement un identifiant de version différent. Ce n'est pas grave
+car Composer est mis à jour de manière continuelle et sa version spécifique n'a
+pas d'importance.
+
+
+Installer Composer globalement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dans le cas où vous n'auriez pas Composer d'installer globalement, exécutez les
+deux commandes suivantes si vous utilisez Linux ou Max OS X (la seconde commande
+vous demandera votre mot de passe utilisateur) :
+
+.. code-block:: bash
+
+ $ curl -sS https://getcomposer.org/installer | php
+ $ sudo mv composer.phar /usr/local/bin/composer
+
+.. note::
+
+ En fonction de votre distribution Linux, vous devrez exécuter la commande ``su``
+ au lieu de ``sudo``.
+
+Si vous utilisez un système Windows, téléchargez l'installateur depuis la
+`page de téléchargement de Composer`_ et suivez les étapes pour l'installer.
+
+Créer l'application de blog
+---------------------------
+
+Maintenant que tout est correctement paramétré, vous pouvez créer un nouveau
+projet basé sur Symfony. Dans votre console, allez dans un répertoire où vous
+avez le droit de créer des fichiers et exécutez les commandes suivantes :
+
+.. code-block:: bash
+
+ $ cd projects/
+ $ composer create-project symfony/framework-standard-edition blog/
+
+Cette commande créera un nouveau répertoire appelé ``blog`` qui contiendra
+un nouveau projet basé sur la version stable la plus récente de Symfony disponible.
+
+Vérifier l'installation de Symfony
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Une fois l'installation terminée, allez dans le répertoire ``blog/`` et vérifiez
+que Symfony est correctement installé en exécutant la commande suivante :
+
+.. code-block:: bash
+
+ $ cd blog/
+ $ php app/console --version
+
+ Symfony version 2.6.* - app/dev/debug
+
+Si vous voyez la version de Symfony installée, tout fonctionne comme attendu. Sinon,
+vous pouvez exécuter le *script* suivant pour vérifier ce qui empêche votre système
+d'exécuter correctement des applications Symfony :
+
+.. code-block:: bash
+
+ $ php app/check.php
+
+En fonction de votre système, vous pouvez voir jusqu'à deux listes différentes
+lors de l'exécution du script `check.php`. La première montre les prérequis
+obligatoires que votre système doit avoir pour pouvoir exécuter des applications
+Symfony. La seconde liste montre les prérequis facultatifs suggérés pour une
+exécution optimal des applications Symfony :
+
+.. code-block:: bash
+
+ Symfony2 Requirements Checker
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ > PHP is using the following php.ini file:
+ /usr/local/zend/etc/php.ini
+
+ > Checking Symfony requirements:
+ .....E.........................W.....
+
+ [ERROR]
+ Your system is not ready to run Symfony2 projects
+
+ Fix the following mandatory requirements
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ * date.timezone setting must be set
+ > Set the "date.timezone" setting in php.ini* (like Europe/Paris).
+
+ Optional recommendations to improve your setup
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ * short_open_tag should be disabled in php.ini
+ > Set short_open_tag to off in php.ini*.
+
+
+.. tip::
+
+ Les distributions de Symfony sont signées numériquement pour des raisons de sécurité.
+ Si vous souhaitez vérifier l'intégrité de votre installation Symfony, regardez le
+ `dépôt public des sommes de contrôle`_ et suivez `ces étapes`_ pour vérifier les signatures.
+
+Structurer l'application
+------------------------
+
+Après avoir créé l'application, allez dans le répertoire ``blog/`` et vous verrez un
+certain nombre de fichiers et répertoires générés automatiquement :
+
+.. code-block:: text
+
+ blog/
+ ├─ app/
+ │ ├─ console
+ │ ├─ cache/
+ │ ├─ config/
+ │ ├─ logs/
+ │ └─ Resources/
+ ├─ src/
+ │ └─ AppBundle/
+ ├─ vendor/
+ └─ web/
+
+Cette architecture de fichers et de répertoires est une convention proposée par
+Symfony pour la structure de vos application. L'usage recommandé pour chaque
+répertoire est le suivant :
+
+* ``app/cache/``, stocke tous les fichiers de cache générés par l'application;
+* ``app/config/``, stocke toute la configuration définie pour chaque environnement;
+* ``app/logs/``, stocke tous les fichiers de journaux (logs) générés par l'application;
+* ``app/Resources/``, stocke tous les fichiers de templates et de traduction pour l'application;
+* ``src/AppBundle/``, stocke tout le code Symfony spécifique (contrôleurs et routes),
+ votre code métier (ex: classes Doctrine) et toute votre logique métier;
+* ``vendor/``, c'est le répertoire où Composer installe les dépendances de votre application
+ et vous ne devez jamais modifier son contenu;
+* ``web/``, stocke tous les fichiers des contrôleurs frontaux et toutes les ressources web, telles que
+ les feuilles de style, les fichiers JavaScript et les images.
+
+Application Bundles
+~~~~~~~~~~~~~~~~~~~
+
+Quand Symfony 2.0 est sorti, beaucoup de développeurs ont naturellement adopté
+la voie de symfony 1.x en divisant leurs applications en modules logiques. C'est
+pourquoi beaucoup d'applications Symfony utilisent les bundles pour diviser leur
+code en fonctionnalités logiques : ``UserBundle``, ``ProductBundle``, ``InvoiceBundle``,
+etc.
+
+Mais un bundle *entend* être quelque chose pouvant être réutilisé comme un élément
+de logiciel à part. Si ``UserBundle`` ne peut pas être réutilisé *"en l'état"* dans
+une autre application Symfony, alors il ne devrait pas être son propre bundle. Tout
+comme si ``InvoiceBundle`` dépend de ``ProductBundle``, alors il n'y a pas d'avantage
+à avoir deux bundles spérarés.
+
+.. best-practice::
+
+ Créez seulement un bundle appelé ``AppBundle`` pour votre application métier
+
+Implémenter un simple bundle ``AppBundle`` dans vos projet rendra votre code plus
+concis et plus simple à comprendre. À partir de Symfony 2.6, la documentation
+officielle de Symfony utilisera le nom ``AppBundle``.
+
+.. note::
+
+ Il n'est pas nécessaire de préfixer le ``AppBundle`` avec votre propre nom d'organisation
+ (ex: ``AcmeAppBundle``), car ce bundle applicatif n'a aucune vocation à être partagé.
+
+Au final, ceci est la structure typique d'une application Symfony suivant ces bonnes
+pratiques :
+
+.. code-block:: text
+
+ blog/
+ ├─ app/
+ │ ├─ console
+ │ ├─ cache/
+ │ ├─ config/
+ │ ├─ logs/
+ │ └─ Resources/
+ ├─ src/
+ │ └─ AppBundle/
+ ├─ vendor/
+ └─ web/
+ ├─ app.php
+ └─ app_dev.php
+
+.. tip::
+
+ Si vous utilisez Symfony 2.6 ou une version plus récente, le bundle ``AppBundle``
+ est déjà généré pour vous. Si vous utilisez une ancienne version de Symfony, vous
+ pouvez le générer à la main en exécutant cette commande :
+
+ .. code-block:: bash
+
+ $ php app/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
+
+Étendre la structure des répertoires
+------------------------------------
+
+Si vos projets ou votre infrastructure requiert quelques changement dans les
+répertoires par défaut de la structure de Symfony, vous pouvez
+`surcharger l'emplacement des répertoires principaux`_ :
+``cache/``, ``logs/`` and ``web/``.
+
+En plus, Symfony3 utilisera une structure de répertoire légèrement différentes
+lorsqu'il sortira :
+
+.. code-block:: text
+
+ blog-symfony3/
+ ├─ app/
+ │ ├─ config/
+ │ └─ Resources/
+ ├─ bin/
+ │ └─ console
+ ├─ src/
+ ├─ var/
+ │ ├─ cache/
+ │ └─ logs/
+ ├─ vendor/
+ └─ web/
+
+Les changements sont vraiment superficiels, mais pour le moment, nous vous
+recommandons d'utiliser la structure de répertoire de Symfony2.
+
+.. _`Composer`: https://getcomposer.org/
+.. _`Get Started`: https://getcomposer.org/doc/00-intro.md
+.. _`page de téléchargement de Composer`: https://getcomposer.org/download/
+.. _`surcharger l'emplacement des répertoires principaux`: http://symfony.com/doc/current/cookbook/configuration/override_dir_structure.html
+.. _`dépôt public des sommes de contrôle`: https://github.com/sensiolabs/checksums
+.. _`ces étapes`: http://fabien.potencier.org/article/73/signing-project-releases
diff --git a/best_practices/forms.rst b/best_practices/forms.rst
new file mode 100644
index 000000000..6d70561e9
--- /dev/null
+++ b/best_practices/forms.rst
@@ -0,0 +1,231 @@
+Forms
+=====
+
+Forms are one of the most misused Symfony components due to its vast scope and
+endless list of features. In this chapter we'll show you some of the best
+practices so you can leverage forms but get work done quickly.
+
+Building Forms
+--------------
+
+.. best-practice::
+
+ Define your forms as PHP classes.
+
+The Form component allows you to build forms right inside your controller
+code. Honestly, unless you need to reuse the form somewhere else, that's
+totally fine. But for organize and reuse, we recommend that you define each
+form in its own PHP class:
+
+.. code-block:: php
+
+ namespace AppBundle\Form;
+
+ use Symfony\Component\Form\AbstractType;
+ use Symfony\Component\Form\FormBuilderInterface;
+ use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+
+ 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')
+ ;
+ }
+
+ public function setDefaultOptions(OptionsResolverInterface $resolver)
+ {
+ $resolver->setDefaults(array(
+ 'data_class' => 'AppBundle\Entity\Post'
+ ));
+ }
+
+ public function getName()
+ {
+ return 'post';
+ }
+ }
+
+To use the class, use ``createForm`` and instantiate the new class:
+
+.. code-block:: php
+
+ use AppBundle\Form\PostType;
+ // ...
+
+ public function newAction(Request $request)
+ {
+ $post = new Post();
+ $form = $this->createForm(new PostType(), $post);
+
+ // ...
+ }
+
+Registering Forms as Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also `register your form type as a 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 `collection type`_.
+
+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
+-------------------------
+
+Form classes should try to be agnostic to *where* they will be used. This
+makes them easier to re-use later.
+
+.. best-practice::
+
+ Add buttons in the templates, not in the form classes or the controllers.
+
+Since Symfony 2.5, 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
+
+ class PostType extends AbstractType
+ {
+ public function buildForm(FormBuilderInterface $builder, array $options)
+ {
+ $builder
+ // ...
+ ->add('save', 'submit', array('label' => 'Create Post'))
+ ;
+ }
+
+ // ...
+ }
+
+This form *may* have been designed for creating posts, but if you wanted
+to reuse it for editing posts, the button label would be wrong. Instead,
+some developers configure form buttons in the controller:
+
+.. code-block:: php
+
+ namespace AppBundle\Controller\Admin;
+
+ use Symfony\Component\HttpFoundation\Request;
+ use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+ use AppBundle\Entity\Post;
+ use AppBundle\Form\PostType;
+
+ class PostController extends Controller
+ {
+ // ...
+
+ public function newAction(Request $request)
+ {
+ $post = new Post();
+ $form = $this->createForm(new PostType(), $post);
+ $form->add('submit', 'submit', array(
+ 'label' => 'Create',
+ 'attr' => array('class' => 'btn btn-default pull-right')
+ ));
+
+ // ...
+ }
+ }
+
+This is also an important error, because you are mixing presentation markup
+(labels, CSS classes, etc.) with pure PHP code. Separation of concerns is
+always a good practice to follow, so put all the view-related things in the
+view layer:
+
+.. code-block:: html+jinja
+
+
+
+Rendering the Form
+------------------
+
+There are a lot of ways to render your form, ranging from rendering the entire
+thing in one line to rendering each part of each field independently. The
+best way depends on how much customization you need.
+
+The simplest way - which is especially useful during development - is to render
+the form tags manually and then use ``form_widget()`` to render all of the fields:
+
+.. code-block:: html+jinja
+
+
+
+.. best-practice::
+
+ Don't use the ``form()`` or ``form_start()`` functions to render the
+ starting and ending form tags.
+
+Experienced Symfony developers will recognize that we're rendering the ``