May 16, 2019
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
 # Console
 /console* @chalasr
 /components/console* @chalasr

 # Form
 /forms.rst @xabbuh
 /components/form* @xabbuh
 /reference/forms* @xabbuh

 # PropertyInfo
 /components/property_info* @dunglas

 # Security
 /security* @chalasr
 /components/security* @chalasr

 # Validator
 /validation/*
 /components/validator* @xabbuh
 /reference/constraints* @xabbuh

 # Workflow
 /workflow* @lyrixx
 /components/workflow* @lyrixx

 # Yaml
 /components/yaml* @xabbuh
diff --git a/_build/_themes/_exts/symfonycom/sphinx/lexer.py b/_build/_themes/_exts/symfonycom/sphinx/lexer.py
    tokens = {
        'root': [
            ('^\$', Generic.Prompt, 'bash-prompt'),
            ('^[^\n>]+>', Generic.Prompt, 'dos-prompt'),
            ('^>', Generic.Prompt, 'dos-prompt'),
            ('^#.+$', Comment.Single),
            ('^.+$', Generic.Output),
        ],
diff --git a/_build/maintainer_guide.rst b/_build/maintainer_guide.rst
 Merging Process
 ~~~~~~~~~~~~~~~

 At first it's common to make mistakes and merge things badly. Don't worry. This
 At first, it's common to make mistakes and merge things badly. Don't worry. This
 has happened to all of us and we've always been able to recover from any mistake.

 Step 1: Select the right branch to merge
 Never use GitHub's web interface (or desktop clients) to merge PRs or to solve
 merge conflicts. Always use the ``gh`` tool for anything related to merges.

 We require2 approval votes from team members before merging a PR, except if
 it's a typo, a small change oran obvious error.
 We requiretwo approval votes from team members before merging a PR, except if
 it's a typo, a small change orclearly an error.

 If a PR contains lots of commits, there's no need to ask the contributor to
 squash them. The ``gh`` tool does that automatically. The only exceptions are
diff --git a/_build/redirection_map b/_build/redirection_map
 /workflow/state-machines /workflow/introduction
 /workflow/usage /workflow
 /introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony
 /configuration/environment_variables /configuration/env_var_processors
 /configuration/configuration_organization /configuration
 /configuration/environments /configuration
 /configuration/configuration_organization /configuration
 /email/dev_environment /mailer
 /email/spool /mailer
 /email/testing /mailer
 /contributing/community/other /contributing/community
 /profiler/storage /profiler
 /setup/composer /setup
 /security/security_checker /setup
 /service_container/parameters /configuration
diff --git a/_images/components/workflow/pull_request.png b/_images/components/workflow/pull_request.png
diff --git a/_images/components/workflow/pull_request_puml_styled.png b/_images/components/workflow/pull_request_puml_styled.png
diff --git a/_images/form/form-custom-type-postal-address-fragment-names.svg b/_images/form/form-custom-type-postal-address-fragment-names.svg
diff --git a/_images/form/form-custom-type-postal-address.svg b/_images/form/form-custom-type-postal-address.svg
diff --git a/_images/sources/README.md b/_images/sources/README.md
 How to Create Symfony Diagrams
 ==============================

 Creating the Diagram
 --------------------

 * Use [Dia][1] as the diagramming application;
 * Use [PT Sans Narrow][2] as the only font in all diagrams (if possible, use
  only the "normal" weight for all contents);
 * Use 36pt as the base font size;
 * Use 0.10 cm width for lines and shape borders;
 * Use the following color palette:
  * Text, lines and shape borders: black (#000000)
  * Shape backgrounds:
    * Grays: dark (#4d4d4d), medium (#b3b3b3), light (#f2f2f2)
    * Blue: #b2d4eb
    * Red: #ecbec0
    * Green: #b2dec7
    * Orange: #fddfbb

 In case of doubt, check the existing diagrams or ask to the
 [Symfony Documentation Team][3].

 Saving and Exporting the Diagram
 --------------------------------

 * Save the original diagram in `*.dia` format in `_images/sources/<folder-name>`;
 * Export the diagram to SVG format and save it in `_images/<folder-name>`.

 Including the Diagram in the Symfony Docs
 -----------------------------------------

 Use the following snippet to embed the diagram in the docs:

 ```
 .. raw:: html

    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
 ```

 Reasoning
 ---------

 * Dia was chosen because it's one of the few applications which are free, open
  source and compatible with Linux, macOS and Windows.
 * Font, colors and line widths were chosen to be similar to the diagrams used
  in the best tech books.

 Troubleshooting
 ---------------

 * On some macOS systems, Dia cannot be executed as a regular application and
  you must run the following console command instead:
  `export DISPLAY=:0 && /Applications/Dia.app/Contents/Resources/bin/dia`

 [1]: http://dia-installer.de/
 [2]: https://fonts.google.com/specimen/PT+Sans+Narrow
 [3]: https://symfony.com/doc/current/contributing/code/core_team.html
diff --git a/_images/sources/form/form-custom-type-postal-address-fragment-names.dia b/_images/sources/form/form-custom-type-postal-address-fragment-names.dia
diff --git a/_images/sources/form/form-custom-type-postal-address.dia b/_images/sources/form/form-custom-type-postal-address.dia
diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst
 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
 useany of the other formats ifyouprefer another format.
 We recommend YAML because it's friendly to newcomers and concise, but you can
 usewhatever formatyoulike.

 Using a Persistence Layer
 -------------------------

 .. code-block:: terminal

    $ composer require doctrine/doctrine-fixtures-bundle
    $ composer require--devdoctrine/doctrine-fixtures-bundle

 Then, this bundle is enabled automatically, but only for the ``dev`` and
 ``test`` environments::
diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst
 .. best-practice::

    Define the infrastructure-related configuration options as
    :doc:`environment variables </configuration/environment_variables>`. During
    development, use the ``.env`` and ``.env.local`` files at the root of your
    project to set these.
    :ref:`environment variables <config-env-vars>`. During development, use the
    ``.env`` and ``.env.local`` files at the root of your project to set these.

 By default, Symfony adds these types of options to the ``.env`` file when
 installing new dependencies in the app:
 configuration values to change on each server.

 The configuration options defined in the ``services.yaml`` may vary from one
 :doc:`environment </configuration/environments>` to another. That's why Symfony
 :ref:`environment <configuration-environments>` to another. That's why Symfony
 supports defining ``config/services_dev.yaml`` and ``config/services_prod.yaml``
 files so that you can override specific values for each environment.

        Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results.
    </p>

 And Doctrine entities and repositories cannow easilyaccess these values,
 whereas theycannot access the container parameters::
 And Doctrine entities and repositories can access these values too, whereas they
 cannot access the container parameters::

    namespace App\Repository;

    }

 The only notable disadvantage of using constants for this kind of configuration
 values is thatyou cannotredefinethem easily in your tests.
 values is thatit's complicated toredefinetheir values in your tests.

 Parameter Naming
 ----------------
diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst
 don't think its benefit is worth the magic, and so recommend against using
 it.

 Most of the time, ``@Template`` is used without any parameters, which makes
 itmore difficult to know which template is being rendered. It alsomakes
 it less obvious to beginnersthat a controller should always return a Response
 object (unless you're using aview layer).
 Most of the time, ``@Template`` is used without any parameters, which makes it
 more difficult to know which template is being rendered. It alsohides the fact
 that a controller should always return a Response object (unless you're using a
 view layer).

 What does the Controller look like
 ----------------------------------
diff --git a/best_practices/introduction.rst b/best_practices/introduction.rst

 .. note::

    **Best practice** is a noun that means *"a welldefined procedure that is
    **Best practice** is a noun that means *"a well-defined procedure that is
    known to produce near-optimum results"*. And that's exactly what this
    guide aims to provide. Even if you don't agree with every recommendation,
    we believe these will help you build great applications with less complexity.
diff --git a/best_practices/security.rst b/best_practices/security.rst
    API only), we recommend having only *one* firewall entry with the ``anonymous``
    key enabled.

 Most applications only have one authentication system and one set of users.
 Forthis reason, you only need *one* firewall entry.There are exceptions
 of course, especially ifyouhave separated web and API sections on your
 site. But the point isto keep things simple.
 Most applications only have one authentication system and one set of users. For
 this reason, you only need *one* firewall entry.If you have separated web and
 API sections on your site,youwill need more firewall entries. But the point is
 to keep things simple.

 Additionally, you should use the ``anonymous`` key under your firewall. If
 you need to require users to be logged in for different sections of your
diff --git a/best_practices/templates.rst b/best_practices/templates.rst
 Next: :doc:`/best_practices/forms`

 .. _`Twig`: https://twig.symfony.com/
 .. _`Parsedown`:http://parsedown.org/
 .. _`Parsedown`:https://parsedown.org/
diff --git a/best_practices/tests.rst b/best_practices/tests.rst
 test any JavaScript behavior on your pages. If you need to test this, consider
 using the `Mink`_ library from within PHPUnit.

 Of course, ifyou have a heavy JavaScriptfront-end, you should consider using
 pureJavaScript-based testing tools.
 Ifyou have a heavy JavaScriptfrontend, you should consider using pure
 JavaScript-based testing tools.

 Learn More about Functional Tests
 ---------------------------------
diff --git a/bundles.rst b/bundles.rst
 your application via `third-party bundles`_.

 Bundles used in your applications must be enabled per
 :doc:`environment </configuration/environments>` in the ``config/bundles.php``
 :ref:`environment <configuration-environments>` in the ``config/bundles.php``
 file::

    // config/bundles.php
diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst
        include:
              # Minimum supported dependencies with the latest and oldest PHP version
            - php: 7.2
              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[self]=0"
            - php: 7.0
              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[self]=0"

              # Test the latest stable release
            - php: 7.0
        ### Step 2: Enable the Bundle

        Then, enable the bundle by adding it to the list of registered bundles
        in the `app/AppKernel.php` file of your project:
        in the `config/bundles.php` file of your project:

        ```php
        // app/AppKernel.php

        // ...
        class AppKernel extends Kernel
        {
            public function registerBundles()
            {
                $bundles = [
                    // ...
                    new <vendor>\<bundle-name>\<bundle-long-name>(),
                ];

                // ...
            }
        // config/bundles.php

        return [
            // ...
        }
            <vendor>\<bundle-name>\<bundle-long-name>::class => ['all' => true],
        ];
        ```

    .. code-block:: rst
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        Then, enable the bundle by adding it to the list of registered bundles
        in the ``app/AppKernel.php`` file of your project::

            // app/AppKernel.php

            // ...
            class AppKernel extends Kernel
            {
                public function registerBundles()
                {
                    $bundles = [
                        // ...

                        new <vendor>\<bundle-name>\<bundle-long-name>(),
                    ];

                    // ...
                }
        in the ``config/bundles.php`` file of your project::

            // config/bundles.php
            return [
                // ...
            }
                <vendor>\<bundle-name>\<bundle-long-name>::class => ['all' => true],
            ];

        .. _`installation chapter`: https://getcomposer.org/doc/00-intro.md

diff --git a/bundles/configuration.rst b/bundles/configuration.rst

 XML has a very useful feature called `XML schema`_. This allows you to
 describe all possible elements and attributes and their values in an XML Schema
 Definition (anxsd file). This XSD file is used by IDEs for auto completion and
 Definition (anXSD file). This XSD file is used by IDEs for auto completion and
 it is used by the Config component to validate the elements.

 In order to use the schema, the XML configuration file must provide an
diff --git a/bundles/inheritance.rst b/bundles/inheritance.rst
 How to Use Bundle Inheritance to Override Parts of a Bundle
 ===========================================================

 ..caution::
 ..deprecated:: 3.4

    Bundle inheritance was removed in Symfony 4.0, but you can
    :doc:`override any part of a bundle </bundles/override>` without
diff --git a/bundles/override.rst b/bundles/override.rst

 For example, to override the translations defined in the
 ``Resources/translations/FOSUserBundle.es.yml`` file of the FOSUserBundle,
 create a``<your-project>/translations/FOSUserBundle.es.yml`` file.
 create a``<your-project>/translations/FOSUserBundle.es.yml`` file.

 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,27 @@
		# Console
		/console* @chalasr
		/components/console* @chalasr

		# Form
		/forms.rst @xabbuh
		/components/form* @xabbuh
		/reference/forms* @xabbuh

		# PropertyInfo
		/components/property_info* @dunglas

		# Security
		/security* @chalasr
		/components/security* @chalasr

		# Validator
		/validation/*
		/components/validator* @xabbuh
		/reference/constraints* @xabbuh

		# Workflow
		/workflow* @lyrixx
		/components/workflow* @lyrixx

		# Yaml
		/components/yaml* @xabbuh
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,7 +10,7 @@ class TerminalLexer(RegexLexer):
		tokens = {
		'root': [
		('^\$', Generic.Prompt, 'bash-prompt'),
		('^[^\n>]+>', Generic.Prompt, 'dos-prompt'),
		('^>', Generic.Prompt, 'dos-prompt'),
		('^#.+$', Comment.Single),
		('^.+$', Generic.Output),
		],
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -93,7 +93,7 @@ interface. Then:
		Merging Process
		~~~~~~~~~~~~~~~

		At first it's common to make mistakes and merge things badly. Don't worry. This
		At first, it's common to make mistakes and merge things badly. Don't worry. This
		has happened to all of us and we've always been able to recover from any mistake.

		Step 1: Select the right branch to merge
Expand All		@@ -120,8 +120,8 @@ Step 2: Merge the pull request
		Never use GitHub's web interface (or desktop clients) to merge PRs or to solve
		merge conflicts. Always use the ``gh`` tool for anything related to merges.

		We require2 approval votes from team members before merging a PR, except if
		it's a typo, a small change oran obvious error.
		We requiretwo approval votes from team members before merging a PR, except if
		it's a typo, a small change orclearly an error.

		If a PR contains lots of commits, there's no need to ask the contributor to
		squash them. The ``gh`` tool does that automatically. The only exceptions are
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -417,3 +417,15 @@
		/workflow/state-machines /workflow/introduction
		/workflow/usage /workflow
		/introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony
		/configuration/environment_variables /configuration/env_var_processors
		/configuration/configuration_organization /configuration
		/configuration/environments /configuration
		/configuration/configuration_organization /configuration
		/email/dev_environment /mailer
		/email/spool /mailer
		/email/testing /mailer
		/contributing/community/other /contributing/community
		/profiler/storage /profiler
		/setup/composer /setup
		/security/security_checker /setup
		/service_container/parameters /configuration
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,58 @@
		How to Create Symfony Diagrams
		==============================

		Creating the Diagram
		--------------------

		* Use [Dia][1] as the diagramming application;
		* Use [PT Sans Narrow][2] as the only font in all diagrams (if possible, use
		only the "normal" weight for all contents);
		* Use 36pt as the base font size;
		* Use 0.10 cm width for lines and shape borders;
		* Use the following color palette:
		* Text, lines and shape borders: black (#000000)
		* Shape backgrounds:
		* Grays: dark (#4d4d4d), medium (#b3b3b3), light (#f2f2f2)
		* Blue: #b2d4eb
		* Red: #ecbec0
		* Green: #b2dec7
		* Orange: #fddfbb

		In case of doubt, check the existing diagrams or ask to the
		[Symfony Documentation Team][3].

		Saving and Exporting the Diagram
		--------------------------------

		* Save the original diagram in `*.dia` format in `_images/sources/<folder-name>`;
		* Export the diagram to SVG format and save it in `_images/<folder-name>`.

		Including the Diagram in the Symfony Docs
		-----------------------------------------

		Use the following snippet to embed the diagram in the docs:

		```
		.. raw:: html

		<object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
		```

		Reasoning
		---------

		* Dia was chosen because it's one of the few applications which are free, open
		source and compatible with Linux, macOS and Windows.
		* Font, colors and line widths were chosen to be similar to the diagrams used
		in the best tech books.

		Troubleshooting
		---------------

		* On some macOS systems, Dia cannot be executed as a regular application and
		you must run the following console command instead:
		`export DISPLAY=:0 && /Applications/Dia.app/Contents/Resources/bin/dia`

		[1]: http://dia-installer.de/
		[2]: https://fonts.google.com/specimen/PT+Sans+Narrow
		[3]: https://symfony.com/doc/current/contributing/code/core_team.html
Original file line number	Diff line number	Diff line change
Expand Up		@@ -109,8 +109,8 @@ 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
		useany of the other formats ifyouprefer another format.
		We recommend YAML because it's friendly to newcomers and concise, but you can
		usewhatever formatyoulike.

		Using a Persistence Layer
		-------------------------
Expand DownExpand Up		@@ -235,7 +235,7 @@ the following command to install the Doctrine fixtures bundle:

		.. code-block:: terminal

		$ composer require doctrine/doctrine-fixtures-bundle
		$ composer require--devdoctrine/doctrine-fixtures-bundle

		Then, this bundle is enabled automatically, but only for the ``dev`` and
		``test`` environments::
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,9 +16,8 @@ application behavior.
		.. best-practice::

		Define the infrastructure-related configuration options as
		:doc:`environment variables </configuration/environment_variables>`. During
		development, use the ``.env`` and ``.env.local`` files at the root of your
		project to set these.
		:ref:`environment variables <config-env-vars>`. During development, use the
		``.env`` and ``.env.local`` files at the root of your project to set these.

		By default, Symfony adds these types of options to the ``.env`` file when
		installing new dependencies in the app:
Expand DownExpand Up		@@ -84,7 +83,7 @@ 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 ``services.yaml`` may vary from one
		:doc:`environment </configuration/environments>` to another. That's why Symfony
		:ref:`environment <configuration-environments>` to another. That's why Symfony
		supports defining ``config/services_dev.yaml`` and ``config/services_prod.yaml``
		files so that you can override specific values for each environment.

Expand DownExpand Up		@@ -138,8 +137,8 @@ Constants can be used for example in your Twig templates thanks to the
		Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results.
		</p>

		And Doctrine entities and repositories cannow easilyaccess these values,
		whereas theycannot access the container parameters::
		And Doctrine entities and repositories can access these values too, whereas they
		cannot access the container parameters::

		namespace App\Repository;

Expand All		@@ -155,7 +154,7 @@ whereas they cannot access the container parameters::
		}

		The only notable disadvantage of using constants for this kind of configuration
		values is thatyou cannotredefinethem easily in your tests.
		values is thatit's complicated toredefinetheir values in your tests.

		Parameter Naming
		----------------
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -89,10 +89,10 @@ The ``@Template`` annotation is useful, but also involves some magic. We
		don't think its benefit is worth the magic, and so recommend against using
		it.

		Most of the time, ``@Template`` is used without any parameters, which makes
		itmore difficult to know which template is being rendered. It alsomakes
		it less obvious to beginnersthat a controller should always return a Response
		object (unless you're using aview layer).
		Most of the time, ``@Template`` is used without any parameters, which makes it
		more difficult to know which template is being rendered. It alsohides the fact
		that a controller should always return a Response object (unless you're using a
		view layer).

		What does the Controller look like
		----------------------------------
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -25,7 +25,7 @@ that fit the philosophy of the framework as envisioned by its original creator

		.. note::

		Best practice is a noun that means *"a welldefined procedure that is
		Best practice is a noun that means *"a well-defined procedure that is
		known to produce near-optimum results"*. And that's exactly what this
		guide aims to provide. Even if you don't agree with every recommendation,
		we believe these will help you build great applications with less complexity.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -18,10 +18,10 @@ primarily under the ``firewalls`` key.
		API only), we recommend having only one firewall entry with the ``anonymous``
		key enabled.

		Most applications only have one authentication system and one set of users.
		Forthis reason, you only need one firewall entry.There are exceptions
		of course, especially ifyouhave separated web and API sections on your
		site. But the point isto keep things simple.
		Most applications only have one authentication system and one set of users. For
		this reason, you only need one firewall entry.If you have separated web and
		API sections on your site,youwill need more firewall entries. But the point is
		to keep things simple.

		Additionally, you should use the ``anonymous`` key under your firewall. If
		you need to require users to be logged in for different sections of your
Expand Down