diff --git a/_exts b/_exts
index bb540b67288..e58edd22d16 160000
--- a/_exts
+++ b/_exts
@@ -1 +1 @@
-Subproject commit bb540b6728898b48d7ec61e52065a18c391951fe
+Subproject commit e58edd22d16cb247267025d557410dcbfa5fa959
diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst
new file mode 100644
index 00000000000..e844eaec2cc
--- /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 or 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 00000000000..0c463239784
--- /dev/null
+++ b/best_practices/configuration.rst
@@ -0,0 +1,183 @@
+Configuration
+=============
+
+Configuration usually involves different application parts (such as infrastructure
+and security credentials) and different environments (development, production).
+That's why Symfony recommends that you split the application configuration into
+three parts.
+
+Infrastructure-Related Configuration
+------------------------------------
+
+.. best-practice::
+
+ Define the infrastructure-related configuration options in the
+ ``app/config/parameters.yml`` file.
+
+The default ``parameters.yml`` file follows this recommendation and defines the
+options related to the database and mail server infrastructure:
+
+.. 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: ~
+
+ # ...
+
+These options aren't defined inside the ``app/config/config.yml`` file because
+they have nothing to do with the application's behavior. In other words, your
+application doesn't care about the location of your database or the credentials
+to access to it, as long as the database is correctly configured.
+
+Canonical Parameters
+~~~~~~~~~~~~~~~~~~~~
+
+.. best-practice::
+
+ 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.
+
+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
+system. Then, whenever a developer updates the project or deploys it to a server,
+Symfony will check if there is any difference between the canonical
+``parameters.yml.dist`` file and your local ``parameters.yml`` file. If there
+is a difference, Symfony will ask you to provide a value for the new parameter
+and it will add it to your local ``parameters.yml`` file.
+
+Application-Related Configuration
+---------------------------------
+
+.. best-practice::
+
+ Define the application behavior related configuration options in the
+ ``app/config/config.yml`` file.
+
+The ``config.yml`` file contains the options used by the application to modify
+its behavior, such as the sender of email notifications, or the enabled
+`feature toggles`_. Defining these values in ``parameters.yml`` file would
+add an extra layer of configuration that's not needed because you don't need
+or want these configuration values to change on each server.
+
+The configuration options defined in the ``config.yml`` file usually vary from
+one `execution environment`_ to another. That's why Symfony already includes
+``app/config/config_dev.yml`` and ``app/config/config_prod.yml`` files so
+that you can override specific values for each environment.
+
+Constants vs Configuration Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the most common errors when defining application configuration is to
+create new options for values that never change, such as the number of items for
+paginated results.
+
+.. best-practice::
+
+ Use constants to define configuration options that rarely change.
+
+The traditional approach for defining configuration options has caused many
+Symfony apps to include an option like the following, which would be used
+to control the number of posts to display on the blog homepage:
+
+.. code-block:: yaml
+
+ # app/config/config.yml
+ parameters:
+ homepage.num_items: 10
+
+If you ask yourself when the last time was that you changed the value of
+*any* option like this, odds are that you *never* have. 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
+
+ // src/AppBundle/Entity/Post.php
+ namespace AppBundle\Entity;
+
+ class Post
+ {
+ const NUM_ITEMS = 10;
+
+ // ...
+ }
+
+The main advantage of defining constants is that you can use their values
+everywhere in your application. When using parameters, they are only available
+from places wih access to the Symfony container.
+
+Constants can be used for example in your Twig templates thanks to the
+``constant()`` function:
+
+.. code-block:: html+jinja
+
+
+ Displaying the {{ constant('NUM_ITEMS', post) }} most recent results.
+
+
+And Doctrine entities and repositories can now easily access these values,
+whereas they cannot access the container parameters:
+
+.. 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)
+ {
+ // ...
+ }
+ }
+
+The only notable disadvantage of using constants for this kind of configuration
+values is that you cannot redefine them easily in your tests.
+
+Semantic Configuration: Don't Do It
+-----------------------------------
+
+.. best-practice::
+
+ Don't define a semantic dependency injection configuration for your bundles.
+
+As explained in `How to Expose a semantic Configuration for a Bundle`_ article,
+Symfony bundles have two choices on how to handle configuration: normal service
+configuration through the ``services.yml`` file and semantic configuration
+through a special ``*Extension`` class.
+
+Although semantic configuration is much more powerful and provides nice features
+such as configuration validation, the amount of work needed to define that
+configuration isn't worth it for bundles that aren't meant to be shared as
+third-party bundles.
+
+Moving Sensitive Options Outside of Symfony Entirely
+----------------------------------------------------
+
+When dealing with sensitive options, like database credentials, we also recommend
+that you store them outside the Symfony project and make them available
+through environment variables. Learn how to do it in the following article:
+`How to Set external Parameters in the Service Container`_
+
+.. _`feature toggles`: http://en.wikipedia.org/wiki/Feature_toggle
+.. _`execution environment`: http://symfony.com/doc/current/cookbook/configuration/environments.html
+.. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html
+.. _`How to Expose a semantic Configuration for a Bundle`: http://symfony.com/doc/current/cookbook/bundles/extension.html
+.. _`How to Set external Parameters in the Service Container`: http://symfony.com/doc/current/cookbook/configuration/external_parameters.html
diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst
new file mode 100644
index 00000000000..05cd7a1af9b
--- /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 00000000000..244cb6741b4
--- /dev/null
+++ b/best_practices/creating-the-project.rst
@@ -0,0 +1,252 @@
+Creating the Project
+====================
+
+Installing Symfony
+------------------
+
+There is only one recommended way to install Symfony:
+
+.. best-practice::
+
+ Always use `Composer`_ to install Symfony.
+
+Composer is the dependency manager used by modern PHP applications. Adding or
+removing requirements for your project and updating the third-party libraries
+used by your code is a breeze thanks to Composer.
+
+Dependency Management with Composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before installing Symfony, you need to make sure that you have Composer installed
+globally. Open your terminal (also called *command console*) and run the following
+command:
+
+.. code-block:: bash
+
+ $ composer --version
+ Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48
+
+You'll probably see a different version identifier. Never mind because Composer
+is updated on a continuous basis and its specific version doesn't matter.
+
+Installing Composer Globally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case you don't have Composer installed globally, execute the following two
+commands if you use Linux or Mac OS X (the second command will ask for your
+user password):
+
+.. code-block:: bash
+
+ $ curl -sS https://getcomposer.org/installer | php
+ $ sudo mv composer.phar /usr/local/bin/composer
+
+.. note::
+
+ Depending on your Linux distribution, you may need to execute ``su`` command
+ instead of ``sudo``.
+
+If you use a Windows system, download the executable installer from the
+`Composer download page`_ and follow the steps to install it.
+
+Creating the Blog Application
+-----------------------------
+
+Now that everything is correctly set up, you can create a new project based on
+Symfony. In your command console, browse to a directory where you have permission
+to create files and execute the following commands:
+
+.. code-block:: bash
+
+ $ cd projects/
+ $ composer create-project symfony/framework-standard-edition blog/
+
+This command will create a new directory called ``blog`` that will contain
+a fresh new project based on the most recent stable Symfony version available.
+
+Checking the Symfony Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the installation is finished, enter the ``blog/`` directory and check that
+Symfony is correctly installed by executing the following command:
+
+.. code-block:: bash
+
+ $ cd blog/
+ $ php app/console --version
+
+ Symfony version 2.6.* - app/dev/debug
+
+If you see the installed Symfony version, everything worked as expected. If not,
+you can execute the following *script* to check what does prevent your system
+from correctly executing Symfony applications:
+
+.. code-block:: bash
+
+ $ php app/check.php
+
+Depending on your system, you can see up to two different lists when executing the
+`check.php` script. The first one shows the mandatory requirements which your
+system must meet to execute Symfony applications. The second list shows the
+optional requirements suggested for an optimal execution of Symfony applications:
+
+.. 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::
+
+ Symfony releases are digitally signed for security reasons. If you want to
+ verify the integrity of your Symfony installation, take a look at the
+ `public checksums repository`_ and follow `these steps`_ to verify the
+ signatures.
+
+Structuring the Application
+---------------------------
+
+After creating the application, enter the ``blog/`` directory and you'll see a
+number of files and directories generated automatically:
+
+.. code-block:: text
+
+ blog/
+ ├─ app/
+ │ ├─ console
+ │ ├─ cache/
+ │ ├─ config/
+ │ ├─ logs/
+ │ └─ Resources/
+ ├─ src/
+ │ └─ 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;
+* ``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
+ as stylesheets, JavaScript files and images.
+
+Application Bundles
+~~~~~~~~~~~~~~~~~~~
+
+When Symfony 2.0 was released, most developers naturally adopted the symfony
+1.x way of dividing applications into logical modules. That's why many Symfony
+apps use bundles to divide their code into logical features: ``UserBundle``,
+``ProductBundle``, ``InvoiceBundle``, etc.
+
+But a bundle is *meant* to be something that can be reused as a stand-alone
+piece of software. If ``UserBundle`` cannot be used *"as is"* in other Symfony
+apps, then it shouldn't be its own bundle. Moreover ``InvoiceBundle`` depends
+on ``ProductBundle``, then there's no advantage to having two separate bundles.
+
+.. best-practice::
+
+ 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.
+
+.. 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.
+
+All in all, this is the typical directory structure of a Symfony application
+that follows these best practices:
+
+.. code-block:: text
+
+ blog/
+ ├─ app/
+ │ ├─ console
+ │ ├─ cache/
+ │ ├─ config/
+ │ ├─ logs/
+ │ └─ Resources/
+ ├─ src/
+ │ └─ AppBundle/
+ ├─ vendor/
+ └─ web/
+ ├─ app.php
+ └─ app_dev.php
+
+.. tip::
+
+ If you are using Symfony 2.6 or a newer version, the ``AppBundle`` bundle
+ is already generated for you. If you are using an older Symfony version,
+ you can generate it by hand executing this command:
+
+ .. code-block:: bash
+
+ $ php app/console generate:bundle --namespace=AppBundle --dir=src --format=annotation --no-interaction
+
+Extending the Directory Structure
+---------------------------------
+
+If your project or infrastructure requires some changes to the default directory
+structure of Symfony, you can `override the location of the main directories`_:
+``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 Symfony2 directory structure.
+
+.. _`Composer`: https://getcomposer.org/
+.. _`Get Started`: https://getcomposer.org/doc/00-intro.md
+.. _`Composer download page`: https://getcomposer.org/download/
+.. _`override the location of the main directories`: http://symfony.com/doc/current/cookbook/configuration/override_dir_structure.html
+.. _`public checksums repository`: https://github.com/sensiolabs/checksums
+.. _`these steps`: 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 00000000000..6d70561e914
--- /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 ``