Moved "Best Practices" to a dedicated article

Author: javiereguiluz

_build/redirection_map

@@ -460,3 +460,15 @@
 /testing/doctrine /testing/database
 /doctrine/lifecycle_callbacks /doctrine/events
 /doctrine/event_listeners_subscribers /doctrine/events
+/best_practices/index /best_practices
+/best_practices/introduction /best_practices
+/best_practices/creating-the-project /best_practices
+/best_practices/configuration /best_practices
+/best_practices/business-logic /best_practices
+/best_practices/controllers /best_practices
+/best_practices/templates /best_practices
+/best_practices/forms /best_practices
+/best_practices/i18n /best_practices
+/best_practices/security /best_practices
+/best_practices/web-assets /best_practices
+/best_practices/tests /best_practices

best_practices.rst

@@ -0,0 +1,307 @@
+The Symfony Framework Best Practices
+====================================
+
+The Symfony Framework is well-known for being *really* flexible and is used to
+build from micro-sites to enterprise applications. This guide describes the
+**best practices for developing web applications with Symfony** that fit the
+philosophy envisioned by the original Symfony creators. You should only read
+this guide if you already have experience developing Symfony applications.
+
+If you don't agree with some of these recommendations, this guide might be a good
+**starting point** that you can then **extend and fit to your specific needs**.
+You can even ignore this guide completely and continue using your own best
+practices and methodologies. Symfony is flexible enough to adapt to your needs.
+
+.. tip::
+
+    Symfony provides a sample application called `Symfony Demo`_ that follows
+    all these best practices, so you can experience them in practice.
+
+Creating the Project
+--------------------
+
+
+
+
+
+
+Configuration
+-------------
+
+Use Environment Variables for Infrastructure Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are the options that change from one machine to another (e.g. from your
+development machine to the production server) but which don't change the
+application behavior.
+
+:ref:`Use env vars in your project <config-env-vars>` to define these options
+and create multiple ``.env`` files to :ref:`configure env vars per environment <config-dot-env>`.
+
+Use Parameters for Application Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are the options used to modify the application behavior, such as the sender
+of email notifications, or the enabled `feature toggles`_. Their value doesn't
+change per machine, so it's not worth it to define them as environment variables.
+
+Define these options as :ref:`parameters <configuration-parameters>` in the
+``config/services.yaml`` file. You can override these options per
+:ref:`environment <configuration-environments>` in the ``config/services_dev.yaml``
+and ``config/services_prod.yaml`` files.
+
+Use Short and Prefixed Parameter Names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Consider using ``app.`` as the prefix of your :ref:`parameters <configuration-parameters>`
+to avoid collisions with Symfony and third-party bundles/libraries parameters.
+Then, use just one or two words to describe the purpose of the parameter:
+
+.. code-block:: yaml
+
+    # config/services.yaml
+    parameters:
+        # don't do this: 'dir' is too generic and it doesn't convey any meaning
+        app.dir: '...'
+        # do this: short but easy to understand names
+        app.contents_dir: '...'
+        # it's OK to use dots, underscores, dashes or nothing, but always
+        # be consistent and use the same format for all the parameters
+        app.dir.contents: '...'
+        app.contents-dir: '...'
+
+Use Constants to Define Options that Rarely Change
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Configuration options like the number of items to display in some listing rarely
+change. Instead of defining them as :ref:`service container parameters <configuration-parameters>`,
+define them as PHP constants in the related classes. Example::
+
+    // src/Entity/Post.php
+    namespace App\Entity;
+
+    class Post
+    {
+        public const NUMBER_OF_ITEMS = 10;
+
+        // ...
+    }
+
+The main advantage of constants is that you can use them everywhere, including
+Twig templates and Doctrine entities, whereas parameters are only available
+from places with access to the :doc:`service container </service_container>`.
+
+The only notable disadvantage of using constants for this kind of configuration
+values is that it's complicated to redefine their values in your tests.
+
+Business Logic
+--------------
+
+
+
+
+
+
+
+
+Controllers
+-----------
+
+Make your Controller Extend the ``AbstractController`` Base Controller
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony provides a :ref:`base controller <the-base-controller-classes-services>`
+which includes shortcuts for the most common needs such as rendering templates
+or checking security permissions.
+
+Extending your controllers from this base controller couples your application
+to Symfony. Coupling is generally wrong, but it may be OK in this case because
+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.
+
+Use Annotations to Configure Routing, Caching and Security
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+The only exception is when the annotations are too complex, such as when using
+long expressions in the ``@Security`` annotation or lots of variables and
+requirements in the ``@Route`` annotation.
+
+Don't Use Annotations to Configure the Controller Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``@Template`` annotation is useful, but also involves some *magic*.
+Moreover, most of the time ``@Template`` is used without any parameters, which
+makes it more difficult to know which template is being rendered. It also hides
+the fact that a controller should always return a ``Response`` object.
+
+Use Dependency Injection to Get Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you extend the base ``AbstractController``, you can't access services
+directly from the container via ``$this->container->get()`` or ``$this->get()``.
+Instead, you must use dependency injection to fetch services by
+:ref:`type-hinting action method arguments <controller-accessing-services>` or
+constructor arguments.
+
+Use ParamConverters If They Are Convenient
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using :doc:`Doctrine </doctrine>`, then you can *optionally* use the
+`ParamConverter`_ to automatically query for an entity and pass it as an argument
+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>`).
+
+Templates
+---------
+
+Use Twig to Create your Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`Twig <twig-language>` is more concise, readable and safe than PHP. Its
+performance is comparable because Symfony compiles Twig templates to PHP and
+caches the result.
+
+Use Snake Case for Template Names and Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use lowercased snake_case for template names, directories and variables (e.g.
+``user_profile`` instead of ``userProfile`` and ``product/edit_form.html.twig``
+instead of ``Product/EditForm.html.twig``).
+
+Prefix Template Fragments with an Underscore
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Template fragments, also called *"partial templates"*, allow to
+:ref:`reuse template contents <templates-reuse-contents>`. Prefix their names
+with an underscore to better differentiate them from complete templates (e.g.
+``_user_metadata.html.twig`` or ``_caution_message.html.twig``).
+
+Forms
+-----
+
+
+
+
+
+
+
+
+Internationalization
+--------------------
+
+Use the XLIFF Format for Your Translation Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Of all the translation formats supported by Symfony (PHP, Qt, ``.po``, ``.mo``,
+JSON, CSV, INI, etc.) XLIFF and gettext have the best support in the tools used
+by professional translators. And since it's based on XML, you can validate XLIFF
+file contents as you write them.
+
+Symfony also supports notes in XLIFF files, making them more user-friendly for
+translators. At the end, good translations are all about context, and these
+XLIFF notes allow you to define that context.
+
+Use Keys for Translations Instead of Content Strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using keys simplifies the management of the translation files because you can
+change the original contents in templates, controllers and services without
+having to update all of the translation files.
+
+Keys should always describe their *purpose* and *not* their location. For
+example, if a form has a field with the label "Username", then a nice key
+would be ``label.username``, *not* ``edit_form.label.username``.
+
+Security
+--------
+
+
+
+
+
+
+
+Web Assets
+----------
+
+Use Webpack Encore to Process Web Assets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Web assets are things like CSS, JavaScript and image files that make the
+frontend of your site look and work great. `Webpack`_ is the leading JavaScript
+module bundler that compiles, transforms and packages assets for usage in a browser.
+
+:doc:`Webpack Encore </frontend>` is a JavaScript library that gets rid of most
+of Webpack complexity without hiding any of its features or distorting its usage
+and philosophy. It was originally created for Symfony applications, but it works
+for any application using any technology.
+
+Tests
+-----
+
+Smoke Test your URLs
+~~~~~~~~~~~~~~~~~~~~
+
+In software engineering, `smoke testing`_ consists of *"preliminary testing to
+reveal simple failures severe enough to reject a prospective software release"*.
+Using :ref:`PHPUnit data providers <testing-data-providers>` you can define a
+functional test that checks that all application URLs load successfully::
+
+    // tests/ApplicationAvailabilityFunctionalTest.php
+    namespace App\Tests;
+
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+
+    class ApplicationAvailabilityFunctionalTest extends WebTestCase
+    {
+        /**
+         * @dataProvider urlProvider
+         */
+        public function testPageIsSuccessful($url)
+        {
+            $client = self::createClient();
+            $client->request('GET', $url);
+
+            $this->assertResponseIsSuccessful();
+        }
+
+        public function urlProvider()
+        {
+            yield ['/'];
+            yield ['/posts'];
+            yield ['/post/fixture-post-1'];
+            yield ['/blog/category/fixture-category'];
+            yield ['/archives'];
+            // ...
+        }
+    }
+
+Add this test while creating your application because it requires little effort
+and checks that none of your pages returns an error. Later you'll add more
+specific tests for each page.
+
+Hardcode URLs in a Functional Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Symfony applications it's recommended to :ref:`generate URLs <routing-generating-urls>`
+using routes to automatically update all links when a URL changes. However, if a
+URL changes, your public website will break unless you set up a redirection to
+the new URL.
+
+That's why it's recommended to use raw URLs in tests instead of generating them
+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
+.. _`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)
+.. _`Webpack`: https://webpack.js.org/