Finished moving the best practices

Author: javiereguiluz

best_practices.rst

@@ -20,10 +20,75 @@ practices and methodologies. Symfony is flexible enough to adapt to your needs.
 Creating the Project
 --------------------
 
+Use the Symfony Binary to Create Symfony Applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The Symfony binary is an executable command created in your machine when you
+`download Symfony`_. It provides multiple utilities, including the simplest way
+to create new Symfony applications:
 
+.. code-block:: terminal
 
+    $ symfony new my_project_name
 
+Under the hood, this Symfony binary command executes the needed `Composer`_
+command to create a new Symfony application based on the current stable version.
+
+Use the Symfony Skeleton to Create New Symfony-based Projects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony provides two "skeletons" (or "project templates") to
+:ref:`create new Symfony projects <creating-symfony-applications>`. Use the
+minimal "skeleton" to start small and get the best performance and grow your
+application later as needed.
+
+Use Composer and Symfony Flex to Manage Symfony Applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Composer`_ is the package manager used by modern PHP applications to manage
+their dependencies. :ref:`Symfony Flex <symfony-flex>` is a Composer plugin
+designed to automate some of the most common tasks performed in Symfony
+applications. Using Flex is optional but recommended because it improves your
+productivity significantly.
+
+Use the Directory Structure Proposed by Flex
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unless your project follows a development practice that imposes a certain
+directory structure, follow the structure proposed by Symfony Flex. It's flat,
+self-explanatory and not coupled to Symfony:
+
+.. code-block:: text
+
+    your_project/
+    ├─ assets/
+    ├─ bin/
+    │  └─ console
+    ├─ config/
+    │  ├─ packages/
+    │  └─ services.yaml
+    └─ public/
+    │  ├─ build/
+    │  └─ index.php
+    ├─ src/
+    │  ├─ Kernel.php
+    │  ├─ Command/
+    │  ├─ Controller/
+    │  ├─ DataFixtures/
+    │  ├─ Entity/
+    │  ├─ EventSubscriber/
+    │  ├─ Form/
+    │  ├─ Migrations/
+    │  ├─ Repository/
+    │  ├─ Security/
+    │  └─ Twig/
+    ├─ templates/
+    ├─ tests/
+    ├─ translations/
+    ├─ var/
+    │  ├─ cache/
+    │  └─ log/
+    └─ vendor/
 
 Configuration
 -------------
@@ -97,12 +162,61 @@ values is that it's complicated to redefine their values in your tests.
 Business Logic
 --------------
 
+Don't Create any Bundle to Organize your Application Logic
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When Symfony 2.0 was released, Symfony applications used bundles to divide their
+code into logical features: UserBundle, ProductBundle, InvoiceBundle, etc.
+
+However, 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
+applications, then it shouldn't be its own bundle. Moreover, if InvoiceBundle
+depends on ProductBundle, then there's no advantage to having two separate bundles.
 
+Symfony applications can still use third-party bundles (installed in ``vendor/``)
+to add features, but you should use PHP namespaces instead of bundles to organize
+your own code.
 
+Use Autowiring to Automate the Configuration of Application Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+:doc:`Service autowiring </service_container/autowiring>` is a feature that
+reads the type-hints on your constructor (or other methods) and automatically
+passes the correct services to each method, making unnecessary to configure
+services explicitly and simplifying the application maintenance.
 
+Use it in combination with :ref:`service autoconfiguration <services-autoconfigure>`
+to also add :doc:`service tags </service_container/tags>` to the services
+needing them, such as Twig extensions, event subscribers, etc.
 
+Services Should be Private Whenever Possible
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`Make services private <container-public>` to prevent you from accessing
+those services via ``$container->get()``. Instead, you will need to use proper
+dependency injection.
 
+Use the YAML Format to Configure your Own Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use the :ref:`default services.yaml configuration <service-container-services-load-example>`,
+most services will be configured automatically. However, in some edge cases
+you'll need to configure services (or parts of them) manually.
+
+YAML is the format recommended to configure services because it's friendly to
+newcomers and concise, but Symfony also supports XML and PHP configuration, so
+you can use whatever format you like.
+
+Use Annotations to Define the Doctrine Entity Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 several metadata formats, but it's recommended to use
+annotations because they are by far the most convenient and agile way of setting
+up and looking for mapping information.
 
 Controllers
 -----------
@@ -120,6 +234,8 @@ controllers shouldn't contain any business logic. Controllers should contain
 nothing more than a few lines of *glue-code*, so you are not coupling the
 important parts of your application.
 
+.. _best-practice-controller-annotations:
+
 Use Annotations to Configure Routing, Caching and Security
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -157,7 +273,7 @@ to your controller. It will also show a 404 page if no entity can be found.
 
 If the logic to get an entity from a route variable is more complex, instead of
 configuring the ParamConverter, it's better to make the Doctrine query inside
-the controller (e.g. by calling to a :ref:`Doctrine repository method </doctrine>`).
+the controller (e.g. by calling to a :doc:`Doctrine repository method </doctrine>`).
 
 Templates
 ---------
@@ -187,12 +303,41 @@ with an underscore to better differentiate them from complete templates (e.g.
 Forms
 -----
 
+Define your Forms as PHP Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Creating :ref:`forms in classes <creating-forms-in-classes>` allows to reuse
+them in different parts of the application. Besides, not creating forms in
+controllers simplify the code and maintenance of the controllers.
 
+Add Form Buttons in Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Form classes should be agnostic to where they will be used. For example, the
+button of a form used to both create and edit items should change from "Add new"
+to "Save changes" depending on where it's used.
 
+Instead of adding buttons in form classes or the controllers, it's recommended
+to add buttons in the templates. This also improves the separation of concerns,
+because the button styling (CSS class and other attributes) is defined in the
+template instead of in a PHP class.
 
+Define Validation Constraints on the Underlying Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Attaching :doc:`validation constraints </reference/constraints>` to form fields
+instead of to the mapped object prevents the validation from being reused in
+other forms or other places where the object is used.
+
+.. _best-practice-handle-form:
+
+Use a Single Action to Render and Process the Form
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`Rendering forms <rendering-forms>` and :ref:`processing forms <processing-forms>`
+are two of the main tasks when handling forms. Both are too similar (most of the
+times, almost identical), so it's much simpler to let a single controller action
+handle everything.
 
 Internationalization
 --------------------
@@ -223,11 +368,30 @@ would be ``label.username``, *not* ``edit_form.label.username``.
 Security
 --------
 
+Define a Single Firewall
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unless you have two legitimately different authentication systems and users
+(e.g. form login for the main site and a token system for your API only), it's
+recommended to have only one firewall to keep things simple.
 
+Additionally, you should use the ``anonymous`` key under your firewall. If you
+require users to be logged in for different sections of your site, use the
+:doc:`access_control </security/access_control>` option.
 
+Use the ``auto`` Password Hasher
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The :ref:`auto password hasher <reference-security-encoder-auto>` automatically
+selects the best possible encoder/hasher depending on your PHP installation.
+Currently, it tries to use ``sodium`` by default and falls back to ``bcrypt``.
 
+Use Voters to Implement Fine-grained Security Restrictions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+If your security logic is complex, you should create custom
+:doc:`security voters </security/voters>` instead of defining long expressions
+inside the ``@Security`` annotation.
 
 Web Assets
 ----------
@@ -301,6 +465,8 @@ from routes. Whenever a route changes, tests will break and you'll know that
 you must set up a redirection.
 
 .. _`Symfony Demo`: https://github.com/symfony/demo
+.. _`download Symfony`: https://symfony.com/download
+.. _`Composer`: https://getcomposer.org/
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
 .. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)