diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml
new file mode 100644
index 00000000000..c4d6b09029a
--- /dev/null
+++ b/.doctor-rst.yaml
@@ -0,0 +1,82 @@
+rules:
+    no_inheritdoc: ~
+    avoid_repetetive_words: ~
+    blank_line_after_directive: ~
+    short_array_syntax: ~
+    no_app_console: ~
+    typo: ~
+    replacement: ~
+    composer_dev_option_not_at_the_end: ~
+    yarn_dev_option_at_the_end: ~
+    versionadded_directive_should_have_version: ~
+    deprecated_directive_should_have_version: ~
+    no_composer_req: ~
+    no_php_open_tag_in_code_block_php_directive: ~
+    no_blank_line_after_filepath_in_php_code_block: ~
+    no_blank_line_after_filepath_in_yaml_code_block: ~
+    no_blank_line_after_filepath_in_xml_code_block: ~
+    no_blank_line_after_filepath_in_twig_code_block: ~
+    php_prefix_before_bin_console: ~
+    use_deprecated_directive_instead_of_versionadded: ~
+    no_space_before_self_xml_closing_tag: ~
+    no_explicit_use_of_code_block_php: ~
+    ensure_order_of_code_blocks_in_configuration_block: ~
+    american_english: ~
+    valid_use_statements: ~
+    lowercase_as_in_use_statements: ~
+    ordered_use_statements: ~
+    no_namespace_after_use_statements: ~
+    correct_code_block_directive_based_on_the_content: ~
+    max_blank_lines:
+        max: 2
+    replace_code_block_types: ~
+    use_https_xsd_urls: ~
+    blank_line_before_directive: ~
+    extension_xlf_instead_of_xliff: ~
+    valid_inline_highlighted_namespaces: ~
+    indention: ~
+    unused_links: ~
+    yaml_instead_of_yml_suffix: ~
+    extend_abstract_controller: ~
+#    no_app_bundle: ~
+
+    #   4.x
+    versionadded_directive_major_version:
+        major_version: 4
+
+    versionadded_directive_min_version:
+        min_version: '4.0'
+
+    deprecated_directive_major_version:
+        major_version: 4
+
+    deprecated_directive_min_version:
+        min_version: '4.0'
+
+# do not report as violation
+whitelist:
+    regex:
+        - '/FOSUserBundle(.*)\.yml/'
+        - '/``.yml``/'
+        - '/(.*)\.orm\.yml/' # currently DoctrineBundle only supports .yml
+    lines:
+        - 'in config files, so the old ``app/config/config_dev.yml`` goes to'
+        - '#. The most important config file is ``app/config/services.yml``, which now is'
+        - 'code in production without a proxy, it becomes trivially easy to abuse your'
+        - '.. _`EasyDeployBundle`: https://github.com/EasyCorp/easy-deploy-bundle'
+        - 'The bin/console Command'
+        - '# username is your full Gmail or Google Apps email address'
+        - '.. _`LDAP injection`: http://projects.webappsec.org/w/page/13246947/LDAP%20Injection'
+        - '.. versionadded:: 0.21.0' # Encore
+        - '.. versionadded:: 2.4.0' # SwiftMailer
+        - '.. versionadded:: 1.26' # Twig
+        - '.. versionadded:: 1.30' # Twig
+        - '.. versionadded:: 1.2' # MakerBundle
+        - '.. versionadded:: 1.11' # MakerBundle
+        - '.. versionadded:: 1.3' # MakerBundle
+        - '.. versionadded:: 1.8' # MakerBundle
+        - '0 => 123' # assertion for var_dumper - components/var_dumper.rst
+        - '1 => "foo"' # assertion for var_dumper - components/var_dumper.rst
+        - '$var .= "Because of this `\xE9` octet (\\xE9),\n";'
+        - "`Deploying Symfony 4 Apps on Heroku`_."
+        - ".. _`Deploying Symfony 4 Apps on Heroku`: https://devcenter.heroku.com/articles/deploying-symfony4"
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 00000000000..d917bbee7ac
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -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
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
new file mode 100644
index 00000000000..ada570e342c
--- /dev/null
+++ b/.github/workflows/lint.yaml
@@ -0,0 +1,12 @@
+on: [push, pull_request]
+name: Lint
+jobs:
+    doctor-rst:
+        name: DOCtor-RST
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@master
+            - name: DOCtor-RST
+              uses: docker://oskarstark/doctor-rst
+              with:
+                  args: --short
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000000..d211dd419d0
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,83 @@
+Code of Conduct
+===============
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnic origin, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+religion, or sexual identity and orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Our Responsibilities
+--------------------
+
+[CoC Active Response Ensurers, or CARE][1], are responsible for clarifying the
+standards of acceptable behavior and are expected to take appropriate and fair
+corrective action in response to any instances of unacceptable behavior.
+
+CARE team members have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by CARE team members.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+[may be reported][2] by contacting the [CARE team members][1].
+All complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances. The CARE team is
+obligated to maintain confidentiality with regard to the reporter of an
+incident. Further details of specific enforcement policies may be posted
+separately.
+
+CARE team members who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by the
+[core team][3].
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the [Contributor Covenant version 1.4][4].
+
+[1]: https://symfony.com/doc/current/contributing/code_of_conduct/care_team.html
+[2]: https://symfony.com/doc/current/contributing/code_of_conduct/reporting_guidelines.html
+[3]: https://symfony.com/doc/current/contributing/code/core_team.html
+[4]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 00000000000..01524e6ec84
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,340 @@
+LICENSE
+=======
+
+**Creative Commons Attribution-ShareAlike 3.0 Unported**
+https://creativecommons.org/licenses/by-sa/3.0/
+
+-----
+
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS
+PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR
+OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS
+LICENSE OR COPYRIGHT LAW IS PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE
+BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED
+TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN
+CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.
+
+1. Definitions
+--------------
+
+a. **"Adaptation"** means a work based upon the Work, or upon the Work and other
+pre-existing works, such as a translation, adaptation, derivative work,
+arrangement of music or other alterations of a literary or artistic work, or
+phonogram or performance and includes cinematographic adaptations or any other
+form in which the Work may be recast, transformed, or adapted including in any
+form recognizably derived from the original, except that a work that constitutes
+a Collection will not be considered an Adaptation for the purpose of this
+License. For the avoidance of doubt, where the Work is a musical work,
+performance or phonogram, the synchronization of the Work in timed-relation with
+a moving image ("synching") will be considered an Adaptation for the purpose of
+this License.
+
+b. **"Collection"** means a collection of literary or artistic works, such as
+encyclopedias and anthologies, or performances, phonograms or broadcasts, or
+other works or subject matter other than works listed in Section 1(f) below,
+which, by reason of the selection and arrangement of their contents, constitute
+intellectual creations, in which the Work is included in its entirety in
+unmodified form along with one or more other contributions, each constituting
+separate and independent works in themselves, which together are assembled into
+a collective whole. A work that constitutes a Collection will not be considered
+an Adaptation (as defined below) for the purposes of this License.
+
+c. **"Creative Commons Compatible License"** means a license that is listed at
+https://creativecommons.org/compatiblelicenses that has been approved by
+Creative Commons as being essentially equivalent to this License, including, at
+a minimum, because that license: (i) contains terms that have the same purpose,
+meaning and effect as the License Elements of this License; and, (ii) explicitly
+permits the relicensing of adaptations of works made available under that
+license under this License or a Creative Commons jurisdiction license with the
+same License Elements as this License.
+
+d. **"Distribute"** means to make available to the public the original and
+copies of the Work or Adaptation, as appropriate, through sale or other transfer
+of ownership.
+
+e. **"License Elements"** means the following high-level license attributes as
+selected by Licensor and indicated in the title of this License: Attribution,
+ShareAlike.
+
+f. **"Licensor"** means the individual, individuals, entity or entities that
+offer(s) the Work under the terms of this License.
+
+g. **"Original Author""** means, in the case of a literary or artistic work, the
+individual, individuals, entity or entities who created the Work or if no
+individual or entity can be identified, the publisher; and in addition (i) in
+the case of a performance the actors, singers, musicians, dancers, and other
+persons who act, sing, deliver, declaim, play in, interpret or otherwise perform
+literary or artistic works or expressions of folklore; (ii) in the case of a
+phonogram the producer being the person or legal entity who first fixes the
+sounds of a performance or other sounds; and, (iii) in the case of broadcasts,
+the organization that transmits the broadcast.
+
+h. **"Work"** means the literary and/or artistic work offered under the terms of
+this License including without limitation any production in the literary,
+scientific and artistic domain, whatever may be the mode or form of its
+expression including digital form, such as a book, pamphlet and other writing; a
+lecture, address, sermon or other work of the same nature; a dramatic or
+dramatico-musical work; a choreographic work or entertainment in dumb show; a
+musical composition with or without words; a cinematographic work to which are
+assimilated works expressed by a process analogous to cinematography; a work of
+drawing, painting, architecture, sculpture, engraving or lithography; a
+photographic work to which are assimilated works expressed by a process
+analogous to photography; a work of applied art; an illustration, map, plan,
+sketch or three-dimensional work relative to geography, topography, architecture
+or science; a performance; a broadcast; a phonogram; a compilation of data to
+the extent it is protected as a copyrightable work; or a work performed by a
+variety or circus performer to the extent it is not otherwise considered a
+literary or artistic work.
+
+i. **"You"** means an individual or entity exercising rights under this License
+who has not previously violated the terms of this License with respect to the
+Work, or who has received express permission from the Licensor to exercise
+rights under this License despite a previous violation.
+
+j. **"Publicly Perform"** means to perform public recitations of the Work and to
+communicate to the public those public recitations, by any means or process,
+including by wire or wireless means or public digital performances; to make
+available to the public Works in such a way that members of the public may
+access these Works from a place and at a place individually chosen by them; to
+perform the Work to the public by any means or process and the communication to
+the public of the performances of the Work, including by public digital
+performance; to broadcast and rebroadcast the Work by any means including signs,
+sounds or images.
+
+k. **"Reproduce"** means to make copies of the Work by any means including
+without limitation by sound or visual recordings and the right of fixation and
+reproducing fixations of the Work, including storage of a protected performance
+or phonogram in digital form or other electronic medium.
+
+2. Fair Dealing Rights
+----------------------
+
+Nothing in this License is intended to reduce, limit, or restrict any uses free
+from copyright or rights arising from limitations or exceptions that are
+provided for in connection with the copyright protection under copyright law or
+other applicable laws.
+
+3. License Grant
+----------------
+
+Subject to the terms and conditions of this License, Licensor hereby grants You
+a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the
+applicable copyright) license to exercise the rights in the Work as stated
+below:
+
+a. to Reproduce the Work, to incorporate the Work into one or more Collections,
+and to Reproduce the Work as incorporated in the Collections;
+
+b. to create and Reproduce Adaptations provided that any such Adaptation,
+including any translation in any medium, takes reasonable steps to clearly
+label, demarcate or otherwise identify that changes were made to the original
+Work. For example, a translation could be marked "The original work was
+translated from English to Spanish," or a modification could indicate "The
+original work has been modified.";
+
+c. to Distribute and Publicly Perform the Work including as incorporated in
+Collections; and,
+
+d. to Distribute and Publicly Perform Adaptations.
+
+e. For the avoidance of doubt:
+
+   1. **Non-waivable Compulsory License Schemes.** In those jurisdictions in
+      which the right to collect royalties through any statutory or compulsory
+      licensing scheme cannot be waived, the Licensor reserves the exclusive
+      right to collect such royalties for any exercise by You of the rights
+      granted under this License;
+
+   2. **Waivable Compulsory License Schemes.** In those jurisdictions in which
+      the right to collect royalties through any statutory or compulsory
+      licensing scheme can be waived, the Licensor waives the exclusive right to
+      collect such royalties for any exercise by You of the rights granted under
+      this License; and,
+
+   3. **Voluntary License Schemes.** The Licensor waives the right to collect
+      royalties, whether individually or, in the event that the Licensor is a
+      member of a collecting society that administers voluntary licensing
+      schemes, via that society, from any exercise by You of the rights granted
+      under this License.
+
+The above rights may be exercised in all media and formats whether now known or
+hereafter devised. The above rights include the right to make such modifications
+as are technically necessary to exercise the rights in other media and formats.
+Subject to Section 8(f), all rights not expressly granted by Licensor are hereby
+reserved.
+
+4. Restrictions
+---------------
+
+The license granted in Section 3 above is expressly made subject to and limited
+by the following restrictions:
+
+a. You may Distribute or Publicly Perform the Work only under the terms of this
+License. You must include a copy of, or the Uniform Resource Identifier (URI)
+for, this License with every copy of the Work You Distribute or Publicly
+Perform. You may not offer or impose any terms on the Work that restrict the
+terms of this License or the ability of the recipient of the Work to exercise
+the rights granted to that recipient under the terms of the License. You may not
+sublicense the Work. You must keep intact all notices that refer to this License
+and to the disclaimer of warranties with every copy of the Work You Distribute
+or Publicly Perform. When You Distribute or Publicly Perform the Work, You may
+not impose any effective technological measures on the Work that restrict the
+ability of a recipient of the Work from You to exercise the rights granted to
+that recipient under the terms of the License. This Section 4(a) applies to the
+Work as incorporated in a Collection, but this does not require the Collection
+apart from the Work itself to be made subject to the terms of this License. If
+You create a Collection, upon notice from any Licensor You must, to the extent
+practicable, remove from the Collection any credit as required by Section 4(c),
+as requested. If You create an Adaptation, upon notice from any Licensor You
+must, to the extent practicable, remove from the Adaptation any credit as
+required by Section 4(c), as requested.
+
+b. You may Distribute or Publicly Perform an Adaptation only under the terms of:
+(i) this License; (ii) a later version of this License with the same License
+Elements as this License; (iii) a Creative Commons jurisdiction license (either
+this or a later license version) that contains the same License Elements as this
+License (e.g., Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons
+Compatible License. If you license the Adaptation under one of the licenses
+mentioned in (iv), you must comply with the terms of that license. If you
+license the Adaptation under the terms of any of the licenses mentioned in (i),
+(ii) or (iii) (the "Applicable License"), you must comply with the terms of the
+Applicable License generally and the following provisions: (I) You must include
+a copy of, or the URI for, the Applicable License with every copy of each
+Adaptation You Distribute or Publicly Perform; (II) You may not offer or impose
+any terms on the Adaptation that restrict the terms of the Applicable License or
+the ability of the recipient of the Adaptation to exercise the rights granted to
+that recipient under the terms of the Applicable License; (III) You must keep
+intact all notices that refer to the Applicable License and to the disclaimer of
+warranties with every copy of the Work as included in the Adaptation You
+Distribute or Publicly Perform; (IV) when You Distribute or Publicly Perform the
+Adaptation, You may not impose any effective technological measures on the
+Adaptation that restrict the ability of a recipient of the Adaptation from You
+to exercise the rights granted to that recipient under the terms of the
+Applicable License. This Section 4(b) applies to the Adaptation as incorporated
+in a Collection, but this does not require the Collection apart from the
+Adaptation itself to be made subject to the terms of the Applicable License.
+
+c. If You Distribute, or Publicly Perform the Work or any Adaptations or
+Collections, You must, unless a request has been made pursuant to Section 4(a),
+keep intact all copyright notices for the Work and provide, reasonable to the
+medium or means You are utilizing: (i) the name of the Original Author (or
+pseudonym, if applicable) if supplied, and/or if the Original Author and/or
+Licensor designate another party or parties (e.g., a sponsor institute,
+publishing entity, journal) for attribution ("Attribution Parties") in
+Licensor's copyright notice, terms of service or by other reasonable means, the
+name of such party or parties; (ii) the title of the Work if supplied; (iii) to
+the extent reasonably practicable, the URI, if any, that Licensor specifies to
+be associated with the Work, unless such URI does not refer to the copyright
+notice or licensing information for the Work; and (iv) , consistent with Section
+3(b), in the case of an Adaptation, a credit identifying the use of the Work in
+the Adaptation (e.g., "French translation of the Work by Original Author," or
+"Screenplay based on original Work by Original Author"). The credit required by
+this Section 4(c) may be implemented in any reasonable manner; provided,
+however, that in the case of a Adaptation or Collection, at a minimum such
+credit will appear, if a credit for all contributing authors of the Adaptation
+or Collection appears, then as part of these credits and in a manner at least as
+prominent as the credits for the other contributing authors. For the avoidance
+of doubt, You may only use the credit required by this Section for the purpose
+of attribution in the manner set out above and, by exercising Your rights under
+this License, You may not implicitly or explicitly assert or imply any
+connection with, sponsorship or endorsement by the Original Author, Licensor
+and/or Attribution Parties, as appropriate, of You or Your use of the Work,
+without the separate, express prior written permission of the Original Author,
+Licensor and/or Attribution Parties.
+
+d. Except as otherwise agreed in writing by the Licensor or as may be otherwise
+permitted by applicable law, if You Reproduce, Distribute or Publicly Perform
+the Work either by itself or as part of any Adaptations or Collections, You must
+not distort, mutilate, modify or take other derogatory action in relation to the
+Work which would be prejudicial to the Original Author's honor or reputation.
+Licensor agrees that in those jurisdictions (e.g. Japan), in which any exercise
+of the right granted in Section 3(b) of this License (the right to make
+Adaptations) would be deemed to be a distortion, mutilation, modification or
+other derogatory action prejudicial to the Original Author's honor and
+reputation, the Licensor will waive or not assert, as appropriate, this Section,
+to the fullest extent permitted by the applicable national law, to enable You to
+reasonably exercise Your right under Section 3(b) of this License (right to make
+Adaptations) but not otherwise.
+
+5. Representations, Warranties and Disclaimer
+---------------------------------------------
+
+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS
+THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING
+THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT
+LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY,
+OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME
+JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH
+EXCLUSION MAY NOT APPLY TO YOU.
+
+6. Limitation on Liability
+--------------------------
+
+EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE
+LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL,
+PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE
+WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Termination
+--------------
+
+a. This License and the rights granted hereunder will terminate automatically
+upon any breach by You of the terms of this License. Individuals or entities who
+have received Adaptations or Collections from You under this License, however,
+will not have their licenses terminated provided such individuals or entities
+remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8
+will survive any termination of this License.
+
+b. Subject to the above terms and conditions, the license granted here is
+perpetual (for the duration of the applicable copyright in the Work).
+Notwithstanding the above, Licensor reserves the right to release the Work under
+different license terms or to stop distributing the Work at any time; provided,
+however that any such election will not serve to withdraw this License (or any
+other license that has been, or is required to be, granted under the terms of
+this License), and this License will continue in full force and effect unless
+terminated as stated above.
+
+8. Miscellaneous
+----------------
+
+a. Each time You Distribute or Publicly Perform the Work or a Collection, the
+Licensor offers to the recipient a license to the Work on the same terms and
+conditions as the license granted to You under this License.
+
+b. Each time You Distribute or Publicly Perform an Adaptation, Licensor offers
+to the recipient a license to the original Work on the same terms and conditions
+as the license granted to You under this License.
+
+c. If any provision of this License is invalid or unenforceable under applicable
+law, it shall not affect the validity or enforceability of the remainder of the
+terms of this License, and without further action by the parties to this
+agreement, such provision shall be reformed to the minimum extent necessary to
+make such provision valid and enforceable.
+
+d. No term or provision of this License shall be deemed waived and no breach
+consented to unless such waiver or consent shall be in writing and signed by the
+party to be charged with such waiver or consent.
+
+e. This License constitutes the entire agreement between the parties with
+respect to the Work licensed here. There are no understandings, agreements or
+representations with respect to the Work not specified here. Licensor shall not
+be bound by any additional provisions that may appear in any communication from
+You. This License may not be modified without the mutual written agreement of
+the Licensor and You.
+
+f. The rights granted under, and the subject matter referenced, in this License
+were drafted utilizing the terminology of the Berne Convention for the
+Protection of Literary and Artistic Works (as amended on September 28, 1979),
+the Rome Convention of 1961, the WIPO Copyright Treaty of 1996, the WIPO
+Performances and Phonograms Treaty of 1996 and the Universal Copyright
+Convention (as revised on July 24, 1971). These rights and subject matter take
+effect in the relevant jurisdiction in which the License terms are sought to be
+enforced according to the corresponding provisions of the implementation of
+those treaty provisions in the applicable national law. If the standard suite of
+rights granted under applicable copyright law includes additional rights not
+granted under this License, such additional rights are deemed to be included in
+the License; this License is not intended to restrict the license of any rights
+under applicable law.
diff --git a/README.markdown b/README.markdown
index 218c3354128..c1c1000be1a 100644
--- a/README.markdown
+++ b/README.markdown
@@ -6,15 +6,15 @@ This documentation is rendered online at https://symfony.com/doc/current/
 Contributing
 ------------
 
->**Note**
->Unless you're documenting a feature that was introduced *after* Symfony 3.4
->(e.g. in Symfony 4.2), all pull requests must be based off of the **3.4** branch,
->**not** the master or older branches.
-
 We love contributors! For more information on how you can contribute to the
 Symfony documentation, please read
 [Contributing to the Documentation](https://symfony.com/doc/current/contributing/documentation/overview.html)
 
+> **Note**
+> Unless you're documenting a feature that was introduced *after* Symfony 3.4
+> (e.g. in Symfony 4.2), all pull requests must be based off of the **3.4** branch,
+> **not** the master or older branches.
+
 SymfonyCloud
 ------------
 
@@ -29,7 +29,10 @@ You can build the doc locally with these commands:
 # build the image...
 $ docker build . -t symfony-docs
 
-# ...and serve it locally on http//:127.0.0.1:8080
+# ...and start the local web server
 # (if it's already in use, change the '8080' port by any other port)
 $ docker run --rm -p 8080:80 symfony-docs
 ```
+
+You can now read the docs at http://127.0.0.1:8080 (if you use a virtual
+machine, browse its IP instead of localhost; e.g. `http://192.168.99.100:8080`).
diff --git a/_build/.requirements.txt b/_build/.requirements.txt
index 430bce090b0..53c6c3ddff0 100644
--- a/_build/.requirements.txt
+++ b/_build/.requirements.txt
@@ -2,7 +2,7 @@ alabaster==0.7.10
 Babel==2.4.0
 docutils==0.13.1
 imagesize==0.7.1
-Jinja2==2.9.6
+Jinja2==2.10.1
 MarkupSafe==1.0
 Pygments==2.2.0
 pytz==2017.2
diff --git a/_build/_themes/_exts/symfonycom/sphinx/lexer.py b/_build/_themes/_exts/symfonycom/sphinx/lexer.py
index 4100b66d283..f1e87066236 100644
--- a/_build/_themes/_exts/symfonycom/sphinx/lexer.py
+++ b/_build/_themes/_exts/symfonycom/sphinx/lexer.py
@@ -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),
         ],
diff --git a/_build/maintainer_guide.rst b/_build/maintainer_guide.rst
new file mode 100644
index 00000000000..fd3de4f3f3b
--- /dev/null
+++ b/_build/maintainer_guide.rst
@@ -0,0 +1,341 @@
+Symfony Docs Maintainer Guide
+=============================
+
+The `symfony/symfony-docs`_ repository stores the Symfony project documentation
+and is managed by the `Symfony Docs team`_. This article explains in detail some
+of those management tasks, so it's only useful for maintainers and not regular
+readers or Symfony developers.
+
+Reviewing Pull Requests
+-----------------------
+
+All the recommendations of the `Symfony's respectful review comments`_ apply,
+but there are extra things to keep in mind for maintainers:
+
+* Always be nice in all interactions with all contributors.
+* Be extra-patient with new contributors (GitHub shows a special badge for them).
+* Don't assume that contributors know what you think is obvious (e.g. lots of
+  them don't know what to "squash commits" means).
+* Don't use acronyms like IMO, IIRC, etc. or complex English words (most
+  contributors are not native in English and it's intimidating for them).
+* Never engage in a heated discussion. Lock it right away using GitHub.
+* Never discuss non-tech issues. Some PRs are related to our Diversity initiative
+  and some people always try to drag you into politics. Never engage in that and
+  lock the issue/PR as off-topic on GitHub.
+
+Fixing Minor Issues Yourself
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's common for new contributors to make lots of minor mistakes in the syntax
+of the RST format used in the docs. It's also common for non English speakers to
+make minor typos.
+
+Even if your intention is good, if you add lots of comments when reviewing a
+first contribution, that person will probably not contribute again. It's better
+to fix the minor errors and typos yourself while merging. If that person
+contributes again, it's OK to mention some of the minor issues to educate them.
+
+.. code-block:: terminal
+
+    $ gh merge 11059
+
+      Working on symfony/symfony-docs (branch master)
+      Merging Pull Request 11059: dmaicher/patch-3
+
+      ...
+
+      # This is important!! Say NO to push the changes now
+      Push the changes now? (Y/n) n
+      Now, push with: git push gh "master" refs/notes/github-comments
+
+      # Now, open your editor and make the needed changes ...
+
+      $ git commit -a
+      # Use "Minor reword", "Minor tweak", etc. as the commit message
+
+      # now run the 'push' command shown above by 'gh' (it's different each time)
+      $ git push gh "master" refs/notes/github-comments
+
+Merging Pull Requests
+---------------------
+
+Technical Requirements
+~~~~~~~~~~~~~~~~~~~~~~
+
+* `Git`_ installed and properly configured.
+* ``gh`` tool fully installed according to its installation instructions
+  (GitHub token configured, Git remote configured, etc.)
+  This is a proprietary CLI tool which only Symfony team members have access to.
+* Some previous Git experience, specially merging pull requests.
+
+First Setup
+~~~~~~~~~~~
+
+First, fork the <https://github.com/symfony/symfony-docs> using the GitHub web
+interface. Then:
+
+.. code-block:: terminal
+
+    # Clone your fork
+    $ git clone https://github.com/<YOUR-NAME>/symfony-docs.git
+
+    $ cd symfony-docs/
+
+    # Add the original repo as 'upstream' remote
+    $ git remote add upstream https://github.com/symfony/symfony-docs
+
+    # Add the original repo as 'gh' remote (needed for the 'gh' tool)
+    $ git remote add gh https://github.com/symfony/symfony-docs
+
+    # Configure 'gh' in Git as the remote used by the 'gh' tool
+    $ git config gh.remote gh
+
+Merging Process
+~~~~~~~~~~~~~~~
+
+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
+........................................
+
+PRs must be merged in the oldest maintained branch where they are applicable:
+
+* Here you can find the currently maintained branches: https://symfony.com/roadmap.
+* Typos and old undocumented features are merged into the oldest maintained branch.
+* New features are merged into the branch where they were introduced. This
+  usually means ``master``. And don't forget to check that new feature includes
+  the ``versionadded`` directive.
+
+It's very common for contributors (specially newcomers) to select the wrong
+branch for their PRs, so we must always check if the change should go to the
+proposed branch or not.
+
+If the branch is wrong, there's no need to ask the contributor to rebase. The
+``gh`` tool can do that for us.
+
+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 require two approval votes from team members before merging a PR, except if
+it's a typo, a small change or clearly 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
+when commits are made by more than one person and when there's a merge commit.
+``gh`` can't squash commits in those cases, so it's better to ask to the
+original contributor.
+
+.. code-block:: terminal
+
+    $ cd symfony-docs/
+
+    # make sure that your local branch is updated
+    $ git checkout 3.4
+    $ git fetch upstream
+    $ git merge upstream/3.4
+
+    # merge any PR passing its GitHub number as argument
+    $ gh merge 11159
+
+    # the gh tool will ask you some questions...
+
+    # push your changes (you can merge several PRs and push once at the end)
+    $ git push origin
+    $ git push upstream
+
+It's common to have to change the branch where a PR is merged. Instead of asking
+the contributors to rebase their PRs, the "gh" tool can change the branch with
+the ``-s`` option:
+
+.. code-block:: terminal
+
+    # e.g. this PR was sent against 'master', but it's merged in '3.4'
+    $ gh merge 11160 -s 3.4
+
+Sometimes, when changing the branch, you may face rebase issues, but they are
+usually simple to fix:
+
+.. code-block:: terminal
+
+    $ gh merge 11160 -s 3.4
+
+      ...
+
+      Unable to rebase the patch for <comment>pull/11183</comment>
+      The command "'git' 'rebase' '--onto' '3.4' '4.2' 'pull/11160'" failed.
+      Exit Code: 128(Invalid exit argument)
+
+      [...]
+      Auto-merging reference/forms/types/entity.rst
+      CONFLICT (content): Merge conflict in reference/forms/types/entity.rst
+      Patch failed at 0001 Update entity.rst
+      The copy of the patch that failed is found in: .git/rebase-apply/patch
+
+    # Now, fix all the conflicts using your editor
+
+    # Add the modified files and continue the rebase
+    $ git add reference/forms/types/entity.rst ...
+    $ git rebase --continue
+
+    # Lastly, re-run the exact same original command that resulted in a conflict
+    # There's no need to change the branch or do anything else.
+    $ gh merge 11160 -s 3.4
+
+      The previous run had some conflicts. Do you want to resume the merge? (Y/n)
+
+Later in this article you can find a troubleshooting section for the errors that
+you will usually face while merging.
+
+Step 3: Merge it into the other branches
+........................................
+
+If a PR has not been merged in ``master``, you must merge it up into all the
+maintained branches until ``master``. Imagine that you are merging a PR against
+``3.4`` and the maintained branches are ``3.4``, ``4.2`` and ``master``:
+
+.. code-block:: terminal
+
+    $ git fetch upstream
+
+    $ git checkout 3.4
+    $ git merge upstream/3.4
+
+    $ gh merge 11159
+    $ git push origin
+    $ git push upstream
+
+    $ git checkout 4.2
+    $ git merge upstream/4.2
+    $ git merge --log 3.4
+    # here you can face several errors explained later
+    $ git push origin
+    $ git push upstream
+
+    $ git checkout master
+    $ git merge upstream/master
+    $ git merge --log 4.2
+    $ git push origin
+    $ git push upstream
+
+.. tip::
+
+    If you followed the full ``gh`` installation instructions you can remove the
+    ``--log`` option in the above commands.
+
+.. tip::
+
+    When the support of a Symfony branch ends, it's recommended to delete your
+    local branch to avoid merging in it unawarely:
+
+    .. code-block:: terminal
+
+        # if Symfony 3.3 goes out of maintenance today, delete your local branch
+        $ git branch -D 3.3
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+Wrong merge of your local branch
+................................
+
+When updating your local branches before merging:
+
+.. code-block:: terminal
+
+    $ git fetch upstream
+    $ git checkout 3.4
+    $ git merge upstream/3.4
+
+It's possible that you merge a wrong upstream branch unawarely. It's usually
+easy to spot because you'll see lots of conflicts:
+
+.. code-block:: terminal
+
+    # DON'T DO THIS! It's a wrong branch merge
+    $ git checkout 3.4
+    $ git merge upstream/4.2
+
+As long as you don't push this wrong merge, there's no problem. Delete your
+local branch and check it out again:
+
+.. code-block:: terminal
+
+    $ git checkout master
+    $ git branch -D 3.4
+    $ git checkout 3.4 upstream/3.4
+
+If you did push the wrong branch merge, ask for help in the documentation
+mergers chat and we'll help solve the problem.
+
+Solving merge conflicts
+.......................
+
+When merging things to upper branches, most of the times you'll see conflicts:
+
+.. code-block:: terminal
+
+    $ git checkout 4.2
+    $ git merge upstream/4.2
+    $ git merge --log 3.4
+
+      Auto-merging security/entity_provider.rst
+      Auto-merging logging/monolog_console.rst
+      Auto-merging form/dynamic_form_modification.rst
+      Auto-merging components/phpunit_bridge.rst
+      CONFLICT (content): Merge conflict in components/phpunit_bridge.rst
+      Automatic merge failed; fix conflicts and then commit the result.
+
+Solve the conflicts with your editor (look for occurrences of ``<<<<``, which is
+the marker used by Git for conflicts) and then do this:
+
+.. code-block:: terminal
+
+    # add all the conflicting files that you fixed
+    $ git add components/phpunit_bridge.rst
+    $ git commit -a
+    $ git push origin
+    $ git push upstream
+
+.. tip::
+
+    When there are lots of conflicts, look for ``<<<<<`` with your editor in all
+    docs before committing the changes. It's common to forget about some of them.
+    If you prefer, you can run this too: ``git grep --cached "<<<<<"``.
+
+Merging deleted files
+.....................
+
+A common cause of conflict when merging PRs into upper branches are files which
+were modified by the PR but no longer exist in newer branches:
+
+.. code-block:: terminal
+
+    $ git checkout 4.2
+    $ git merge upstream/4.2
+    $ git merge --log 3.4
+
+      Auto-merging translation/debug.rst
+      CONFLICT (modify/delete): service_container/scopes.rst deleted in HEAD and
+      modified in 3.4. Version 3.4 of service_container/scopes.rst left in tree.
+      Auto-merging service_container.rst
+
+If the contents of the deleted file were moved to a different file in newer
+branches, redo the changes in the new file. Then, delete the file that Git left
+in the tree as follows:
+
+.. code-block:: terminal
+
+    # delete all the conflicting files that no longer exist in this branch
+    $ git rm service_container/scopes.rst
+    $ git commit -a
+    $ git push origin
+    $ git push upstream
+
+.. _`symfony/symfony-docs`: https://github.com/symfony/symfony-docs
+.. _`Symfony Docs team`: https://github.com/orgs/symfony/teams/team-symfony-docs
+.. _`Symfony's respectful review comments`: https://symfony.com/doc/current/contributing/community/review-comments.html
+.. _`Git`: https://git-scm.com/
diff --git a/_build/redirection_map b/_build/redirection_map
index 5bc5ef3a0df..f9ec4237331 100644
--- a/_build/redirection_map
+++ b/_build/redirection_map
@@ -405,3 +405,44 @@
 /console/logging /console
 /reference/forms/twig_reference /form/form_customization
 /form/rendering /form/form_customization
+/profiler/matchers /profiler
+/profiler/profiling_data /profiler
+/profiler/wdt_follow_ajax /profiler
+/security/entity_provider /security/user_provider
+/session/avoid_session_start /session
+/session/sessions_directory /session
+/frontend/encore/legacy-apps /frontend/encore/legacy-applications
+/configuration/external_parameters /configuration/environment_variables
+/contributing/code/patches /contributing/code/pull_requests
+/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
+/routing/generate_url_javascript /routing
+/routing/slash_in_parameter /routing
+/routing/scheme /routing
+/routing/optional_placeholders /routing
+/routing/conditions /routing
+/routing/requirements /routing
+/routing/redirect_trailing_slash /routing
+/routing/debug /routing
+/routing/service_container_parameters /routing
+/routing/redirect_in_config /routing
+/routing/external_resources /routing
+/routing/hostname_pattern /routing
+/routing/extra_information /routing
+/console/request_context /routing
+/form/action_method /forms
+/reference/requirements /setup
+ /bundles/inheritance /bundles/override
diff --git a/_images/components/workflow/pull_request.png b/_images/components/workflow/pull_request.png
index 1aa8886728c..692a95345ae 100644
Binary files a/_images/components/workflow/pull_request.png and b/_images/components/workflow/pull_request.png differ
diff --git a/_images/components/workflow/pull_request_puml_styled.png b/_images/components/workflow/pull_request_puml_styled.png
new file mode 100644
index 00000000000..cda9233d731
Binary files /dev/null and b/_images/components/workflow/pull_request_puml_styled.png differ
diff --git a/_images/form/form-custom-type-postal-address-fragment-names.svg b/_images/form/form-custom-type-postal-address-fragment-names.svg
new file mode 100644
index 00000000000..9b6092c9808
--- /dev/null
+++ b/_images/form/form-custom-type-postal-address-fragment-names.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="650" viewBox="0 0 722 514"><defs><symbol overflow="visible" id="a"><path d="M 6.5625 -3.15625 L 3.265625 -3.15625 L 2.4375 0 L -0.0625 0 L 4 -14.09375 L 5.984375 -14.09375 L 10.0625 0 L 7.421875 0 Z M 3.796875 -5.234375 L 6.125 -5.234375 L 5.3125 -8.5 L 5 -10.703125 L 4.921875 -10.703125 L 4.578125 -8.484375 Z M 3.796875 -5.234375"/></symbol><symbol overflow="visible" id="b"><path d="M 8.046875 -3.515625 C 8.046875 -2.960938 8.050781 -2.40625 8.0625 -1.84375 C 8.070312 -1.28125 8.125 -0.660156 8.21875 0.015625 L 6.546875 0.015625 L 6.21875 -1.140625 L 6.140625 -1.140625 C 5.679688 -0.203125 4.890625 0.265625 3.765625 0.265625 C 2.742188 0.265625 1.941406 -0.132812 1.359375 -0.9375 C 0.785156 -1.738281 0.5 -3.039062 0.5 -4.84375 C 0.5 -6.601562 0.8125 -7.9375 1.4375 -8.84375 C 2.0625 -9.757812 2.992188 -10.21875 4.234375 -10.21875 C 4.554688 -10.21875 4.820312 -10.195312 5.03125 -10.15625 C 5.25 -10.113281 5.457031 -10.046875 5.65625 -9.953125 L 5.65625 -14 L 8.046875 -14 Z M 4.3125 -1.921875 C 4.675781 -1.921875 4.960938 -2.007812 5.171875 -2.1875 C 5.390625 -2.363281 5.550781 -2.628906 5.65625 -2.984375 L 5.65625 -7.703125 C 5.519531 -7.816406 5.367188 -7.898438 5.203125 -7.953125 C 5.035156 -8.015625 4.820312 -8.046875 4.5625 -8.046875 C 4.03125 -8.046875 3.628906 -7.800781 3.359375 -7.3125 C 3.085938 -6.832031 2.953125 -5.984375 2.953125 -4.765625 C 2.953125 -3.835938 3.0625 -3.128906 3.28125 -2.640625 C 3.507812 -2.160156 3.851562 -1.921875 4.3125 -1.921875 Z M 4.3125 -1.921875"/></symbol><symbol overflow="visible" id="c"><path d="M 5.578125 -7.640625 C 5.253906 -7.753906 4.960938 -7.8125 4.703125 -7.8125 C 4.335938 -7.8125 4.023438 -7.710938 3.765625 -7.515625 C 3.503906 -7.316406 3.328125 -7.039062 3.234375 -6.6875 L 3.234375 0 L 0.859375 0 L 0.859375 -10 L 2.6875 -10 L 2.953125 -8.796875 L 3.046875 -8.796875 C 3.210938 -9.234375 3.457031 -9.578125 3.78125 -9.828125 C 4.113281 -10.078125 4.492188 -10.203125 4.921875 -10.203125 C 5.242188 -10.203125 5.554688 -10.132812 5.859375 -10 Z M 5.578125 -7.640625"/></symbol><symbol overflow="visible" id="d"><path d="M 7.625 -0.734375 C 7.289062 -0.441406 6.835938 -0.203125 6.265625 -0.015625 C 5.691406 0.171875 5.085938 0.265625 4.453125 0.265625 C 3.765625 0.265625 3.171875 0.144531 2.671875 -0.09375 C 2.171875 -0.332031 1.757812 -0.675781 1.4375 -1.125 C 1.113281 -1.582031 0.875 -2.132812 0.71875 -2.78125 C 0.570312 -3.4375 0.5 -4.175781 0.5 -5 C 0.5 -6.800781 0.851562 -8.128906 1.5625 -8.984375 C 2.28125 -9.847656 3.273438 -10.28125 4.546875 -10.28125 C 4.972656 -10.28125 5.382812 -10.21875 5.78125 -10.09375 C 6.175781 -9.96875 6.53125 -9.753906 6.84375 -9.453125 C 7.15625 -9.148438 7.410156 -8.75 7.609375 -8.25 C 7.804688 -7.75 7.90625 -7.117188 7.90625 -6.359375 C 7.90625 -6.066406 7.882812 -5.753906 7.84375 -5.421875 C 7.8125 -5.085938 7.765625 -4.726562 7.703125 -4.34375 L 2.84375 -4.34375 C 2.863281 -3.507812 3.035156 -2.875 3.359375 -2.4375 C 3.679688 -2 4.195312 -1.78125 4.90625 -1.78125 C 5.332031 -1.78125 5.71875 -1.847656 6.0625 -1.984375 C 6.414062 -2.117188 6.6875 -2.257812 6.875 -2.40625 Z M 4.5 -8.234375 C 3.988281 -8.234375 3.609375 -8.03125 3.359375 -7.625 C 3.109375 -7.21875 2.960938 -6.648438 2.921875 -5.921875 L 5.6875 -5.921875 C 5.71875 -6.679688 5.632812 -7.253906 5.4375 -7.640625 C 5.238281 -8.035156 4.925781 -8.234375 4.5 -8.234375 Z M 4.5 -8.234375"/></symbol><symbol overflow="visible" id="e"><path d="M 4.21875 -2.65625 C 4.21875 -2.9375 4.128906 -3.171875 3.953125 -3.359375 C 3.773438 -3.554688 3.546875 -3.738281 3.265625 -3.90625 C 2.984375 -4.070312 2.6875 -4.242188 2.375 -4.421875 C 2.0625 -4.597656 1.765625 -4.8125 1.484375 -5.0625 C 1.203125 -5.3125 0.96875 -5.613281 0.78125 -5.96875 C 0.601562 -6.332031 0.515625 -6.789062 0.515625 -7.34375 C 0.515625 -8.269531 0.769531 -8.988281 1.28125 -9.5 C 1.789062 -10.007812 2.535156 -10.265625 3.515625 -10.265625 C 4.109375 -10.265625 4.660156 -10.195312 5.171875 -10.0625 C 5.691406 -9.9375 6.109375 -9.78125 6.421875 -9.59375 L 5.859375 -7.765625 C 5.609375 -7.867188 5.300781 -7.96875 4.9375 -8.0625 C 4.582031 -8.164062 4.226562 -8.21875 3.875 -8.21875 C 3.226562 -8.21875 2.90625 -7.945312 2.90625 -7.40625 C 2.90625 -7.144531 2.992188 -6.929688 3.171875 -6.765625 C 3.347656 -6.597656 3.578125 -6.4375 3.859375 -6.28125 C 4.140625 -6.125 4.4375 -5.957031 4.75 -5.78125 C 5.0625 -5.601562 5.359375 -5.382812 5.640625 -5.125 C 5.921875 -4.863281 6.148438 -4.546875 6.328125 -4.171875 C 6.503906 -3.804688 6.59375 -3.347656 6.59375 -2.796875 C 6.59375 -1.878906 6.3125 -1.140625 5.75 -0.578125 C 5.195312 -0.015625 4.367188 0.265625 3.265625 0.265625 C 2.710938 0.265625 2.171875 0.195312 1.640625 0.0625 C 1.117188 -0.0703125 0.695312 -0.242188 0.375 -0.453125 L 1.046875 -2.375 C 1.316406 -2.21875 1.632812 -2.078125 2 -1.953125 C 2.375 -1.835938 2.757812 -1.78125 3.15625 -1.78125 C 3.46875 -1.78125 3.722656 -1.847656 3.921875 -1.984375 C 4.117188 -2.128906 4.21875 -2.351562 4.21875 -2.65625 Z M 4.21875 -2.65625"/></symbol><symbol overflow="visible" id="g"><path d="M 3.28125 -3.234375 C 3.28125 -2.773438 3.328125 -2.441406 3.421875 -2.234375 C 3.515625 -2.035156 3.664062 -1.9375 3.875 -1.9375 C 4 -1.9375 4.125 -1.945312 4.25 -1.96875 C 4.375 -2 4.519531 -2.050781 4.6875 -2.125 L 4.90625 -0.203125 C 4.738281 -0.0976562 4.460938 0 4.078125 0.09375 C 3.691406 0.1875 3.300781 0.234375 2.90625 0.234375 C 2.238281 0.234375 1.738281 0.0664062 1.40625 -0.265625 C 1.070312 -0.597656 0.90625 -1.160156 0.90625 -1.953125 L 0.90625 -14 L 3.28125 -14 Z M 3.28125 -3.234375"/></symbol><symbol overflow="visible" id="h"><path d="M 1.0625 -10 L 3.4375 -10 L 3.4375 0 L 1.0625 0 Z M 1.203125 -12.8125 C 1.203125 -13.21875 1.328125 -13.550781 1.578125 -13.8125 C 1.828125 -14.070312 2.1875 -14.203125 2.65625 -14.203125 C 3.125 -14.203125 3.5 -14.070312 3.78125 -13.8125 C 4.0625 -13.5625 4.203125 -13.226562 4.203125 -12.8125 C 4.203125 -12.40625 4.0625 -12.082031 3.78125 -11.84375 C 3.5 -11.601562 3.125 -11.484375 2.65625 -11.484375 C 2.1875 -11.484375 1.828125 -11.601562 1.578125 -11.84375 C 1.328125 -12.09375 1.203125 -12.414062 1.203125 -12.8125 Z M 1.203125 -12.8125"/></symbol><symbol overflow="visible" id="i"><path d="M 5.8125 0 L 5.8125 -6.078125 C 5.8125 -6.816406 5.722656 -7.332031 5.546875 -7.625 C 5.378906 -7.914062 5.09375 -8.0625 4.6875 -8.0625 C 4.332031 -8.0625 4.03125 -7.953125 3.78125 -7.734375 C 3.53125 -7.523438 3.347656 -7.257812 3.234375 -6.9375 L 3.234375 0 L 0.859375 0 L 0.859375 -10 L 2.765625 -10 L 3.046875 -8.84375 L 3.09375 -8.84375 C 3.332031 -9.226562 3.660156 -9.554688 4.078125 -9.828125 C 4.492188 -10.097656 5.035156 -10.234375 5.703125 -10.234375 C 6.097656 -10.234375 6.453125 -10.171875 6.765625 -10.046875 C 7.078125 -9.929688 7.335938 -9.738281 7.546875 -9.46875 C 7.765625 -9.195312 7.925781 -8.832031 8.03125 -8.375 C 8.144531 -7.914062 8.203125 -7.34375 8.203125 -6.65625 L 8.203125 0 Z M 5.8125 0"/></symbol><symbol overflow="visible" id="j"><path d="M 1.734375 -2.125 L 4.015625 -2.125 L 4.015625 -9.984375 L 4.28125 -11.34375 L 3.453125 -10.15625 L 2.140625 -9.140625 L 1.046875 -10.484375 L 4.90625 -14.234375 L 6.296875 -14.234375 L 6.296875 -2.125 L 8.546875 -2.125 L 8.546875 0 L 1.734375 0 Z M 1.734375 -2.125"/></symbol><symbol overflow="visible" id="E"><path d="M 8.046875 -10.640625 C 8.046875 -9.941406 7.941406 -9.226562 7.734375 -8.5 C 7.535156 -7.78125 7.28125 -7.070312 6.96875 -6.375 C 6.65625 -5.6875 6.3125 -5.023438 5.9375 -4.390625 C 5.5625 -3.765625 5.195312 -3.210938 4.84375 -2.734375 L 3.953125 -1.921875 L 3.953125 -1.8125 L 5.15625 -2.125 L 8.265625 -2.125 L 8.265625 0 L 1.234375 0 L 1.234375 -1.375 C 1.515625 -1.726562 1.816406 -2.125 2.140625 -2.5625 C 2.472656 -3.007812 2.800781 -3.484375 3.125 -3.984375 C 3.457031 -4.484375 3.773438 -5.003906 4.078125 -5.546875 C 4.390625 -6.085938 4.660156 -6.628906 4.890625 -7.171875 C 5.117188 -7.710938 5.300781 -8.242188 5.4375 -8.765625 C 5.582031 -9.285156 5.644531 -9.769531 5.625 -10.21875 C 5.644531 -10.78125 5.519531 -11.234375 5.25 -11.578125 C 4.988281 -11.921875 4.570312 -12.09375 4 -12.09375 C 3.664062 -12.09375 3.320312 -12.015625 2.96875 -11.859375 C 2.625 -11.710938 2.332031 -11.53125 2.09375 -11.3125 L 1.1875 -13.0625 C 1.625 -13.4375 2.117188 -13.734375 2.671875 -13.953125 C 3.234375 -14.171875 3.894531 -14.28125 4.65625 -14.28125 C 5.132812 -14.28125 5.582031 -14.203125 6 -14.046875 C 6.414062 -13.890625 6.769531 -13.660156 7.0625 -13.359375 C 7.363281 -13.054688 7.601562 -12.675781 7.78125 -12.21875 C 7.957031 -11.769531 8.046875 -11.242188 8.046875 -10.640625 Z M 8.046875 -10.640625"/></symbol><symbol overflow="visible" id="L"><path d="M 8.84375 -0.5625 C 8.488281 -0.269531 8.019531 -0.0546875 7.4375 0.078125 C 6.863281 0.210938 6.289062 0.28125 5.71875 0.28125 C 5 0.28125 4.328125 0.160156 3.703125 -0.078125 C 3.085938 -0.328125 2.546875 -0.738281 2.078125 -1.3125 C 1.609375 -1.894531 1.238281 -2.648438 0.96875 -3.578125 C 0.707031 -4.515625 0.578125 -5.660156 0.578125 -7.015625 C 0.578125 -8.429688 0.726562 -9.601562 1.03125 -10.53125 C 1.332031 -11.46875 1.722656 -12.210938 2.203125 -12.765625 C 2.691406 -13.316406 3.25 -13.707031 3.875 -13.9375 C 4.5 -14.164062 5.132812 -14.28125 5.78125 -14.28125 C 6.4375 -14.28125 7.003906 -14.222656 7.484375 -14.109375 C 7.972656 -14.003906 8.375 -13.890625 8.6875 -13.765625 L 8.1875 -11.546875 C 7.925781 -11.671875 7.625 -11.769531 7.28125 -11.84375 C 6.945312 -11.914062 6.546875 -11.953125 6.078125 -11.953125 C 5.160156 -11.953125 4.453125 -11.550781 3.953125 -10.75 C 3.460938 -9.957031 3.21875 -8.707031 3.21875 -7 C 3.21875 -6.269531 3.273438 -5.597656 3.390625 -4.984375 C 3.503906 -4.378906 3.679688 -3.859375 3.921875 -3.421875 C 4.171875 -2.984375 4.484375 -2.644531 4.859375 -2.40625 C 5.242188 -2.164062 5.703125 -2.046875 6.234375 -2.046875 C 6.703125 -2.046875 7.101562 -2.109375 7.4375 -2.234375 C 7.769531 -2.359375 8.070312 -2.507812 8.34375 -2.6875 Z M 8.84375 -0.5625"/></symbol><symbol overflow="visible" id="M"><path d="M 0.078125 -10 L 1.1875 -10 L 1.1875 -11.875 L 3.5625 -12.625 L 3.5625 -10 L 5.5 -10 L 5.5 -7.875 L 3.5625 -7.875 L 3.5625 -3.515625 C 3.5625 -2.941406 3.617188 -2.535156 3.734375 -2.296875 C 3.847656 -2.054688 4.050781 -1.9375 4.34375 -1.9375 C 4.539062 -1.9375 4.71875 -1.957031 4.875 -2 C 5.039062 -2.039062 5.21875 -2.101562 5.40625 -2.1875 L 5.703125 -0.28125 C 5.410156 -0.132812 5.066406 -0.015625 4.671875 0.078125 C 4.285156 0.179688 3.878906 0.234375 3.453125 0.234375 C 2.691406 0.234375 2.125 0.015625 1.75 -0.421875 C 1.375 -0.859375 1.1875 -1.597656 1.1875 -2.640625 L 1.1875 -7.875 L 0.078125 -7.875 Z M 0.078125 -10"/></symbol><symbol overflow="visible" id="N"><path d="M 4.0625 -4.375 L 4.3125 -2.8125 L 4.421875 -2.8125 L 4.59375 -4.40625 L 5.765625 -10 L 8.203125 -10 L 5.703125 -0.984375 C 5.472656 -0.191406 5.257812 0.515625 5.0625 1.140625 C 4.863281 1.765625 4.648438 2.296875 4.421875 2.734375 C 4.191406 3.179688 3.929688 3.519531 3.640625 3.75 C 3.359375 3.976562 3.019531 4.09375 2.625 4.09375 C 2.34375 4.09375 2.070312 4.066406 1.8125 4.015625 C 1.550781 3.972656 1.328125 3.898438 1.140625 3.796875 L 1.546875 1.765625 C 1.710938 1.828125 1.882812 1.851562 2.0625 1.84375 C 2.25 1.84375 2.414062 1.773438 2.5625 1.640625 C 2.71875 1.515625 2.851562 1.316406 2.96875 1.046875 C 3.09375 0.785156 3.195312 0.4375 3.28125 0 L -0.203125 -10 L 2.65625 -10 Z M 4.0625 -4.375"/></symbol><symbol overflow="visible" id="O"><path d="M 0.421875 -2.3125 L 5.09375 -10.859375 L 5.9375 -11.6875 L 0.421875 -11.6875 L 0.421875 -14 L 8.484375 -14 L 8.484375 -11.6875 L 3.78125 -3.078125 L 2.953125 -2.3125 L 8.484375 -2.3125 L 8.484375 0 L 0.421875 0 Z M 0.421875 -2.3125"/></symbol><symbol overflow="visible" id="P"><path d="M 1.125 -14 L 3.640625 -14 L 3.640625 0 L 1.125 0 Z M 1.125 -14"/></symbol><symbol overflow="visible" id="Q"><path d="M 0.90625 -13.859375 C 1.382812 -13.960938 1.910156 -14.046875 2.484375 -14.109375 C 3.054688 -14.171875 3.628906 -14.203125 4.203125 -14.203125 C 4.816406 -14.203125 5.421875 -14.144531 6.015625 -14.03125 C 6.609375 -13.914062 7.132812 -13.691406 7.59375 -13.359375 C 8.0625 -13.023438 8.441406 -12.554688 8.734375 -11.953125 C 9.035156 -11.347656 9.1875 -10.554688 9.1875 -9.578125 C 9.1875 -8.703125 9.0625 -7.957031 8.8125 -7.34375 C 8.5625 -6.726562 8.226562 -6.226562 7.8125 -5.84375 C 7.40625 -5.457031 6.929688 -5.175781 6.390625 -5 C 5.847656 -4.820312 5.289062 -4.734375 4.71875 -4.734375 C 4.664062 -4.734375 4.578125 -4.734375 4.453125 -4.734375 C 4.335938 -4.734375 4.210938 -4.738281 4.078125 -4.75 C 3.941406 -4.757812 3.8125 -4.769531 3.6875 -4.78125 C 3.5625 -4.789062 3.472656 -4.800781 3.421875 -4.8125 L 3.421875 0 L 0.90625 0 Z M 3.421875 -7.078125 C 3.503906 -7.054688 3.65625 -7.035156 3.875 -7.015625 C 4.09375 -6.992188 4.238281 -6.984375 4.3125 -6.984375 C 4.613281 -6.984375 4.894531 -7.019531 5.15625 -7.09375 C 5.425781 -7.175781 5.664062 -7.3125 5.875 -7.5 C 6.082031 -7.695312 6.242188 -7.960938 6.359375 -8.296875 C 6.484375 -8.640625 6.546875 -9.070312 6.546875 -9.59375 C 6.546875 -10.039062 6.488281 -10.414062 6.375 -10.71875 C 6.257812 -11.03125 6.101562 -11.273438 5.90625 -11.453125 C 5.71875 -11.628906 5.492188 -11.753906 5.234375 -11.828125 C 4.984375 -11.910156 4.71875 -11.953125 4.4375 -11.953125 C 4.019531 -11.953125 3.679688 -11.921875 3.421875 -11.859375 Z M 3.421875 -7.078125"/></symbol><symbol overflow="visible" id="R"><path d="M 0.5 -5 C 0.5 -6.769531 0.84375 -8.085938 1.53125 -8.953125 C 2.226562 -9.828125 3.195312 -10.265625 4.4375 -10.265625 C 5.769531 -10.265625 6.765625 -9.820312 7.421875 -8.9375 C 8.078125 -8.0625 8.40625 -6.75 8.40625 -5 C 8.40625 -3.207031 8.054688 -1.878906 7.359375 -1.015625 C 6.660156 -0.160156 5.6875 0.265625 4.4375 0.265625 C 1.8125 0.265625 0.5 -1.488281 0.5 -5 Z M 2.953125 -5 C 2.953125 -4 3.066406 -3.222656 3.296875 -2.671875 C 3.523438 -2.128906 3.90625 -1.859375 4.4375 -1.859375 C 4.945312 -1.859375 5.320312 -2.09375 5.5625 -2.5625 C 5.8125 -3.039062 5.9375 -3.851562 5.9375 -5 C 5.9375 -6.03125 5.820312 -6.8125 5.59375 -7.34375 C 5.375 -7.875 4.988281 -8.140625 4.4375 -8.140625 C 3.96875 -8.140625 3.601562 -7.898438 3.34375 -7.421875 C 3.082031 -6.953125 2.953125 -6.144531 2.953125 -5 Z M 2.953125 -5"/></symbol><symbol overflow="visible" id="S"><path d="M 5.796875 -3.59375 C 5.796875 -4.019531 5.671875 -4.382812 5.421875 -4.6875 C 5.171875 -4.988281 4.851562 -5.269531 4.46875 -5.53125 C 4.09375 -5.800781 3.679688 -6.078125 3.234375 -6.359375 C 2.785156 -6.640625 2.367188 -6.96875 1.984375 -7.34375 C 1.609375 -7.71875 1.289062 -8.15625 1.03125 -8.65625 C 0.78125 -9.164062 0.65625 -9.785156 0.65625 -10.515625 C 0.65625 -11.203125 0.757812 -11.78125 0.96875 -12.25 C 1.175781 -12.71875 1.457031 -13.101562 1.8125 -13.40625 C 2.175781 -13.707031 2.601562 -13.925781 3.09375 -14.0625 C 3.59375 -14.207031 4.125 -14.28125 4.6875 -14.28125 C 5.363281 -14.28125 5.992188 -14.210938 6.578125 -14.078125 C 7.160156 -13.941406 7.648438 -13.765625 8.046875 -13.546875 L 7.265625 -11.3125 C 7.035156 -11.476562 6.695312 -11.625 6.25 -11.75 C 5.800781 -11.882812 5.316406 -11.953125 4.796875 -11.953125 C 4.273438 -11.953125 3.875 -11.84375 3.59375 -11.625 C 3.320312 -11.414062 3.1875 -11.109375 3.1875 -10.703125 C 3.1875 -10.328125 3.3125 -9.992188 3.5625 -9.703125 C 3.8125 -9.421875 4.125 -9.144531 4.5 -8.875 C 4.882812 -8.613281 5.300781 -8.335938 5.75 -8.046875 C 6.195312 -7.765625 6.609375 -7.429688 6.984375 -7.046875 C 7.367188 -6.671875 7.6875 -6.222656 7.9375 -5.703125 C 8.1875 -5.191406 8.3125 -4.582031 8.3125 -3.875 C 8.3125 -3.164062 8.207031 -2.550781 8 -2.03125 C 7.800781 -1.519531 7.507812 -1.09375 7.125 -0.75 C 6.75 -0.40625 6.289062 -0.148438 5.75 0.015625 C 5.21875 0.191406 4.628906 0.28125 3.984375 0.28125 C 3.148438 0.28125 2.421875 0.195312 1.796875 0.03125 C 1.179688 -0.125 0.707031 -0.300781 0.375 -0.5 L 1.203125 -2.765625 C 1.460938 -2.597656 1.828125 -2.4375 2.296875 -2.28125 C 2.765625 -2.125 3.265625 -2.046875 3.796875 -2.046875 C 5.128906 -2.046875 5.796875 -2.5625 5.796875 -3.59375 Z M 5.796875 -3.59375"/></symbol><symbol overflow="visible" id="T"><path d="M 0.875 -9.40625 C 1.28125 -9.644531 1.78125 -9.835938 2.375 -9.984375 C 2.976562 -10.128906 3.660156 -10.203125 4.421875 -10.203125 C 5.554688 -10.203125 6.34375 -9.90625 6.78125 -9.3125 C 7.226562 -8.726562 7.453125 -7.894531 7.453125 -6.8125 C 7.453125 -6.1875 7.4375 -5.570312 7.40625 -4.96875 C 7.375 -4.363281 7.347656 -3.769531 7.328125 -3.1875 C 7.316406 -2.601562 7.328125 -2.039062 7.359375 -1.5 C 7.398438 -0.96875 7.492188 -0.460938 7.640625 0.015625 L 5.703125 0.015625 L 5.3125 -1.203125 L 5.234375 -1.203125 C 5.023438 -0.816406 4.726562 -0.492188 4.34375 -0.234375 C 3.957031 0.015625 3.46875 0.140625 2.875 0.140625 C 2.09375 0.140625 1.472656 -0.117188 1.015625 -0.640625 C 0.566406 -1.171875 0.34375 -1.878906 0.34375 -2.765625 C 0.34375 -3.960938 0.769531 -4.8125 1.625 -5.3125 C 2.476562 -5.820312 3.628906 -6.035156 5.078125 -5.953125 C 5.148438 -6.734375 5.101562 -7.296875 4.9375 -7.640625 C 4.769531 -7.984375 4.410156 -8.15625 3.859375 -8.15625 C 3.460938 -8.15625 3.050781 -8.109375 2.625 -8.015625 C 2.195312 -7.921875 1.816406 -7.789062 1.484375 -7.625 Z M 3.734375 -1.90625 C 4.097656 -1.90625 4.390625 -1.992188 4.609375 -2.171875 C 4.835938 -2.347656 5.007812 -2.546875 5.125 -2.765625 L 5.125 -4.421875 C 4.8125 -4.460938 4.515625 -4.46875 4.234375 -4.4375 C 3.953125 -4.414062 3.707031 -4.359375 3.5 -4.265625 C 3.289062 -4.171875 3.117188 -4.03125 2.984375 -3.84375 C 2.859375 -3.664062 2.796875 -3.4375 2.796875 -3.15625 C 2.796875 -2.75 2.878906 -2.4375 3.046875 -2.21875 C 3.210938 -2.007812 3.441406 -1.90625 3.734375 -1.90625 Z M 3.734375 -1.90625"/></symbol><symbol overflow="visible" id="k"><path d="M 1.0625 -1.671875 C 1.289062 -1.515625 1.609375 -1.367188 2.015625 -1.234375 C 2.429688 -1.097656 2.90625 -1.03125 3.4375 -1.03125 C 4.113281 -1.03125 4.660156 -1.191406 5.078125 -1.515625 C 5.492188 -1.847656 5.703125 -2.367188 5.703125 -3.078125 C 5.703125 -3.546875 5.582031 -3.953125 5.34375 -4.296875 C 5.101562 -4.648438 4.800781 -4.972656 4.4375 -5.265625 C 4.082031 -5.554688 3.695312 -5.84375 3.28125 -6.125 C 2.863281 -6.40625 2.472656 -6.71875 2.109375 -7.0625 C 1.753906 -7.40625 1.457031 -7.796875 1.21875 -8.234375 C 0.976562 -8.679688 0.859375 -9.21875 0.859375 -9.84375 C 0.859375 -10.851562 1.160156 -11.597656 1.765625 -12.078125 C 2.378906 -12.566406 3.171875 -12.8125 4.140625 -12.8125 C 4.742188 -12.8125 5.273438 -12.753906 5.734375 -12.640625 C 6.203125 -12.535156 6.582031 -12.398438 6.875 -12.234375 L 6.4375 -11.046875 C 6.226562 -11.179688 5.921875 -11.300781 5.515625 -11.40625 C 5.109375 -11.519531 4.644531 -11.578125 4.125 -11.578125 C 3.476562 -11.578125 3 -11.414062 2.6875 -11.09375 C 2.375 -10.78125 2.21875 -10.382812 2.21875 -9.90625 C 2.21875 -9.476562 2.335938 -9.101562 2.578125 -8.78125 C 2.816406 -8.457031 3.113281 -8.148438 3.46875 -7.859375 C 3.832031 -7.578125 4.21875 -7.285156 4.625 -6.984375 C 5.039062 -6.691406 5.429688 -6.363281 5.796875 -6 C 6.160156 -5.644531 6.460938 -5.238281 6.703125 -4.78125 C 6.941406 -4.332031 7.0625 -3.796875 7.0625 -3.171875 C 7.0625 -2.109375 6.75 -1.273438 6.125 -0.671875 C 5.5 -0.078125 4.613281 0.21875 3.46875 0.21875 C 2.75 0.21875 2.160156 0.148438 1.703125 0.015625 C 1.242188 -0.117188 0.875 -0.269531 0.59375 -0.4375 Z M 1.0625 -1.671875"/></symbol><symbol overflow="visible" id="l"><path d="M 0.15625 -9 L 1.265625 -9 L 1.265625 -10.78125 L 2.5625 -11.203125 L 2.5625 -9 L 4.5 -9 L 4.5 -7.828125 L 2.5625 -7.828125 L 2.5625 -2.46875 C 2.5625 -1.9375 2.625 -1.550781 2.75 -1.3125 C 2.875 -1.082031 3.078125 -0.96875 3.359375 -0.96875 C 3.597656 -0.96875 3.804688 -0.992188 3.984375 -1.046875 C 4.160156 -1.109375 4.347656 -1.179688 4.546875 -1.265625 L 4.8125 -0.234375 C 4.539062 -0.0976562 4.242188 0.00390625 3.921875 0.078125 C 3.609375 0.160156 3.28125 0.203125 2.9375 0.203125 C 2.332031 0.203125 1.898438 0.0078125 1.640625 -0.375 C 1.390625 -0.769531 1.265625 -1.40625 1.265625 -2.28125 L 1.265625 -7.828125 L 0.15625 -7.828125 Z M 0.15625 -9"/></symbol><symbol overflow="visible" id="m"><path d="M 1.0625 -9 L 1.984375 -9 L 2.21875 -8.046875 L 2.265625 -8.046875 C 2.429688 -8.390625 2.648438 -8.660156 2.921875 -8.859375 C 3.191406 -9.054688 3.519531 -9.15625 3.90625 -9.15625 C 4.175781 -9.15625 4.488281 -9.101562 4.84375 -9 L 4.59375 -7.6875 C 4.28125 -7.789062 4.003906 -7.84375 3.765625 -7.84375 C 3.378906 -7.84375 3.066406 -7.734375 2.828125 -7.515625 C 2.585938 -7.296875 2.429688 -7 2.359375 -6.625 L 2.359375 0 L 1.0625 0 Z M 1.0625 -9"/></symbol><symbol overflow="visible" id="n"><path d="M 6.4375 -0.609375 C 6.15625 -0.347656 5.789062 -0.144531 5.34375 0 C 4.90625 0.144531 4.4375 0.21875 3.9375 0.21875 C 3.375 0.21875 2.882812 0.109375 2.46875 -0.109375 C 2.0625 -0.335938 1.722656 -0.65625 1.453125 -1.0625 C 1.179688 -1.476562 0.984375 -1.972656 0.859375 -2.546875 C 0.734375 -3.128906 0.671875 -3.78125 0.671875 -4.5 C 0.671875 -6.03125 0.953125 -7.195312 1.515625 -8 C 2.078125 -8.8125 2.875 -9.21875 3.90625 -9.21875 C 4.238281 -9.21875 4.570312 -9.175781 4.90625 -9.09375 C 5.238281 -9.007812 5.535156 -8.835938 5.796875 -8.578125 C 6.054688 -8.328125 6.265625 -7.972656 6.421875 -7.515625 C 6.585938 -7.066406 6.671875 -6.472656 6.671875 -5.734375 C 6.671875 -5.535156 6.660156 -5.316406 6.640625 -5.078125 C 6.628906 -4.847656 6.613281 -4.609375 6.59375 -4.359375 L 2.015625 -4.359375 C 2.015625 -3.835938 2.054688 -3.367188 2.140625 -2.953125 C 2.222656 -2.535156 2.351562 -2.175781 2.53125 -1.875 C 2.71875 -1.582031 2.953125 -1.351562 3.234375 -1.1875 C 3.515625 -1.03125 3.863281 -0.953125 4.28125 -0.953125 C 4.601562 -0.953125 4.921875 -1.007812 5.234375 -1.125 C 5.554688 -1.25 5.800781 -1.394531 5.96875 -1.5625 Z M 5.4375 -5.4375 C 5.457031 -6.332031 5.328125 -6.988281 5.046875 -7.40625 C 4.773438 -7.832031 4.398438 -8.046875 3.921875 -8.046875 C 3.367188 -8.046875 2.929688 -7.832031 2.609375 -7.40625 C 2.285156 -6.988281 2.09375 -6.332031 2.03125 -5.4375 Z M 5.4375 -5.4375"/></symbol><symbol overflow="visible" id="p"><path d="M 0.96875 -8.453125 C 1.320312 -8.671875 1.742188 -8.835938 2.234375 -8.953125 C 2.734375 -9.078125 3.257812 -9.140625 3.8125 -9.140625 C 4.320312 -9.140625 4.726562 -9.0625 5.03125 -8.90625 C 5.332031 -8.757812 5.570312 -8.554688 5.75 -8.296875 C 5.925781 -8.046875 6.039062 -7.753906 6.09375 -7.421875 C 6.144531 -7.097656 6.171875 -6.753906 6.171875 -6.390625 C 6.171875 -5.671875 6.15625 -4.96875 6.125 -4.28125 C 6.09375 -3.601562 6.078125 -2.957031 6.078125 -2.34375 C 6.078125 -1.882812 6.09375 -1.457031 6.125 -1.0625 C 6.15625 -0.675781 6.210938 -0.3125 6.296875 0.03125 L 5.3125 0.03125 L 5 -1.03125 L 4.9375 -1.03125 C 4.75 -0.71875 4.484375 -0.445312 4.140625 -0.21875 C 3.796875 0.0078125 3.328125 0.125 2.734375 0.125 C 2.085938 0.125 1.554688 -0.0976562 1.140625 -0.546875 C 0.722656 -0.992188 0.515625 -1.613281 0.515625 -2.40625 C 0.515625 -2.925781 0.601562 -3.359375 0.78125 -3.703125 C 0.957031 -4.054688 1.203125 -4.335938 1.515625 -4.546875 C 1.835938 -4.765625 2.21875 -4.914062 2.65625 -5 C 3.09375 -5.09375 3.582031 -5.140625 4.125 -5.140625 C 4.238281 -5.140625 4.351562 -5.140625 4.46875 -5.140625 C 4.59375 -5.140625 4.722656 -5.132812 4.859375 -5.125 C 4.890625 -5.5 4.90625 -5.832031 4.90625 -6.125 C 4.90625 -6.800781 4.800781 -7.273438 4.59375 -7.546875 C 4.394531 -7.828125 4.023438 -7.96875 3.484375 -7.96875 C 3.148438 -7.96875 2.785156 -7.914062 2.390625 -7.8125 C 1.992188 -7.71875 1.664062 -7.59375 1.40625 -7.4375 Z M 4.875 -4.109375 C 4.757812 -4.117188 4.640625 -4.125 4.515625 -4.125 C 4.398438 -4.132812 4.28125 -4.140625 4.15625 -4.140625 C 3.863281 -4.140625 3.578125 -4.113281 3.296875 -4.0625 C 3.023438 -4.019531 2.78125 -3.9375 2.5625 -3.8125 C 2.351562 -3.695312 2.1875 -3.535156 2.0625 -3.328125 C 1.9375 -3.128906 1.875 -2.875 1.875 -2.5625 C 1.875 -2.082031 1.988281 -1.707031 2.21875 -1.4375 C 2.457031 -1.175781 2.757812 -1.046875 3.125 -1.046875 C 3.632812 -1.046875 4.023438 -1.164062 4.296875 -1.40625 C 4.578125 -1.644531 4.769531 -1.910156 4.875 -2.203125 Z M 4.875 -4.109375"/></symbol><symbol overflow="visible" id="q"><path d="M 6.734375 -3.09375 C 6.734375 -2.476562 6.738281 -1.921875 6.75 -1.421875 C 6.757812 -0.929688 6.800781 -0.445312 6.875 0.03125 L 6 0.03125 L 5.703125 -1.046875 L 5.640625 -1.046875 C 5.460938 -0.679688 5.191406 -0.378906 4.828125 -0.140625 C 4.472656 0.0976562 4.046875 0.21875 3.546875 0.21875 C 2.578125 0.21875 1.851562 -0.15625 1.375 -0.90625 C 0.90625 -1.664062 0.671875 -2.859375 0.671875 -4.484375 C 0.671875 -6.015625 0.957031 -7.175781 1.53125 -7.96875 C 2.113281 -8.757812 2.914062 -9.15625 3.9375 -9.15625 C 4.289062 -9.15625 4.566406 -9.132812 4.765625 -9.09375 C 4.972656 -9.050781 5.195312 -8.984375 5.4375 -8.890625 L 5.4375 -12.59375 L 6.734375 -12.59375 Z M 5.4375 -7.578125 C 5.269531 -7.722656 5.078125 -7.828125 4.859375 -7.890625 C 4.648438 -7.953125 4.375 -7.984375 4.03125 -7.984375 C 3.394531 -7.984375 2.898438 -7.695312 2.546875 -7.125 C 2.191406 -6.550781 2.015625 -5.664062 2.015625 -4.46875 C 2.015625 -3.9375 2.046875 -3.457031 2.109375 -3.03125 C 2.179688 -2.601562 2.285156 -2.234375 2.421875 -1.921875 C 2.554688 -1.609375 2.734375 -1.367188 2.953125 -1.203125 C 3.179688 -1.035156 3.457031 -0.953125 3.78125 -0.953125 C 4.644531 -0.953125 5.195312 -1.460938 5.4375 -2.484375 Z M 5.4375 -7.578125"/></symbol><symbol overflow="visible" id="r"><path d="M 0.921875 -1.46875 C 1.160156 -1.332031 1.441406 -1.210938 1.765625 -1.109375 C 2.097656 -1.003906 2.441406 -0.953125 2.796875 -0.953125 C 3.191406 -0.953125 3.523438 -1.050781 3.796875 -1.25 C 4.078125 -1.445312 4.21875 -1.769531 4.21875 -2.21875 C 4.21875 -2.582031 4.128906 -2.882812 3.953125 -3.125 C 3.785156 -3.363281 3.570312 -3.578125 3.3125 -3.765625 C 3.0625 -3.960938 2.785156 -4.140625 2.484375 -4.296875 C 2.179688 -4.460938 1.898438 -4.660156 1.640625 -4.890625 C 1.390625 -5.117188 1.175781 -5.390625 1 -5.703125 C 0.832031 -6.015625 0.75 -6.410156 0.75 -6.890625 C 0.75 -7.660156 0.957031 -8.238281 1.375 -8.625 C 1.789062 -9.019531 2.375 -9.21875 3.125 -9.21875 C 3.625 -9.21875 4.050781 -9.171875 4.40625 -9.078125 C 4.769531 -8.992188 5.082031 -8.875 5.34375 -8.71875 L 5 -7.625 C 4.769531 -7.75 4.503906 -7.847656 4.203125 -7.921875 C 3.910156 -8.003906 3.609375 -8.046875 3.296875 -8.046875 C 2.859375 -8.046875 2.539062 -7.953125 2.34375 -7.765625 C 2.144531 -7.585938 2.046875 -7.3125 2.046875 -6.9375 C 2.046875 -6.632812 2.128906 -6.375 2.296875 -6.15625 C 2.472656 -5.945312 2.6875 -5.753906 2.9375 -5.578125 C 3.195312 -5.410156 3.476562 -5.234375 3.78125 -5.046875 C 4.082031 -4.867188 4.359375 -4.65625 4.609375 -4.40625 C 4.867188 -4.164062 5.082031 -3.875 5.25 -3.53125 C 5.425781 -3.195312 5.515625 -2.769531 5.515625 -2.25 C 5.515625 -1.914062 5.457031 -1.597656 5.34375 -1.296875 C 5.238281 -0.992188 5.070312 -0.734375 4.84375 -0.515625 C 4.625 -0.296875 4.347656 -0.117188 4.015625 0.015625 C 3.691406 0.148438 3.304688 0.21875 2.859375 0.21875 C 2.328125 0.21875 1.867188 0.164062 1.484375 0.0625 C 1.109375 -0.0390625 0.785156 -0.175781 0.515625 -0.34375 Z M 0.921875 -1.46875"/></symbol><symbol overflow="visible" id="s"><path d="M 0.640625 -0.78125 C 0.640625 -1.070312 0.726562 -1.304688 0.90625 -1.484375 C 1.082031 -1.671875 1.304688 -1.765625 1.578125 -1.765625 C 1.890625 -1.765625 2.144531 -1.640625 2.34375 -1.390625 C 2.539062 -1.140625 2.640625 -0.742188 2.640625 -0.203125 C 2.640625 0.191406 2.585938 0.546875 2.484375 0.859375 C 2.390625 1.179688 2.257812 1.460938 2.09375 1.703125 C 1.9375 1.941406 1.757812 2.140625 1.5625 2.296875 C 1.375 2.453125 1.191406 2.566406 1.015625 2.640625 L 0.5625 2.03125 C 0.71875 1.945312 0.863281 1.835938 1 1.703125 C 1.132812 1.566406 1.242188 1.410156 1.328125 1.234375 C 1.421875 1.066406 1.492188 0.890625 1.546875 0.703125 C 1.597656 0.523438 1.625 0.34375 1.625 0.15625 C 1.382812 0.226562 1.160156 0.179688 0.953125 0.015625 C 0.742188 -0.148438 0.640625 -0.414062 0.640625 -0.78125 Z M 0.640625 -0.78125"/></symbol><symbol overflow="visible" id="t"><path d="M 1.15625 -12.46875 C 1.539062 -12.582031 1.945312 -12.65625 2.375 -12.6875 C 2.8125 -12.726562 3.238281 -12.75 3.65625 -12.75 C 4.132812 -12.75 4.609375 -12.691406 5.078125 -12.578125 C 5.546875 -12.472656 5.96875 -12.273438 6.34375 -11.984375 C 6.71875 -11.703125 7.019531 -11.304688 7.25 -10.796875 C 7.488281 -10.296875 7.609375 -9.65625 7.609375 -8.875 C 7.609375 -8.113281 7.5 -7.46875 7.28125 -6.9375 C 7.0625 -6.414062 6.765625 -5.988281 6.390625 -5.65625 C 6.023438 -5.332031 5.601562 -5.09375 5.125 -4.9375 C 4.65625 -4.789062 4.171875 -4.71875 3.671875 -4.71875 C 3.617188 -4.71875 3.539062 -4.71875 3.4375 -4.71875 C 3.332031 -4.71875 3.21875 -4.71875 3.09375 -4.71875 C 2.976562 -4.726562 2.863281 -4.738281 2.75 -4.75 C 2.632812 -4.757812 2.550781 -4.769531 2.5 -4.78125 L 2.5 0 L 1.15625 0 Z M 3.71875 -11.5 C 3.476562 -11.5 3.25 -11.488281 3.03125 -11.46875 C 2.8125 -11.457031 2.632812 -11.429688 2.5 -11.390625 L 2.5 -6.03125 C 2.550781 -6.007812 2.625 -5.992188 2.71875 -5.984375 C 2.820312 -5.972656 2.925781 -5.960938 3.03125 -5.953125 C 3.144531 -5.953125 3.253906 -5.953125 3.359375 -5.953125 C 3.460938 -5.953125 3.535156 -5.953125 3.578125 -5.953125 C 3.921875 -5.953125 4.242188 -5.992188 4.546875 -6.078125 C 4.859375 -6.160156 5.132812 -6.3125 5.375 -6.53125 C 5.613281 -6.757812 5.804688 -7.0625 5.953125 -7.4375 C 6.109375 -7.820312 6.1875 -8.300781 6.1875 -8.875 C 6.1875 -9.375 6.117188 -9.789062 5.984375 -10.125 C 5.847656 -10.46875 5.664062 -10.738281 5.4375 -10.9375 C 5.21875 -11.144531 4.957031 -11.289062 4.65625 -11.375 C 4.363281 -11.457031 4.050781 -11.5 3.71875 -11.5 Z M 3.71875 -11.5"/></symbol><symbol overflow="visible" id="u"><path d="M 0.703125 -0.8125 C 0.703125 -1.144531 0.78125 -1.394531 0.9375 -1.5625 C 1.101562 -1.726562 1.328125 -1.8125 1.609375 -1.8125 C 1.878906 -1.8125 2.09375 -1.726562 2.25 -1.5625 C 2.414062 -1.394531 2.5 -1.144531 2.5 -0.8125 C 2.5 -0.457031 2.414062 -0.195312 2.25 -0.03125 C 2.09375 0.132812 1.878906 0.21875 1.609375 0.21875 C 1.328125 0.21875 1.101562 0.132812 0.9375 -0.03125 C 0.78125 -0.195312 0.703125 -0.457031 0.703125 -0.8125 Z M 0.703125 -0.8125"/></symbol><symbol overflow="visible" id="v"><path d="M 0.78125 -6.296875 C 0.78125 -8.429688 1.117188 -10.050781 1.796875 -11.15625 C 2.484375 -12.257812 3.53125 -12.8125 4.9375 -12.8125 C 5.6875 -12.8125 6.328125 -12.65625 6.859375 -12.34375 C 7.390625 -12.039062 7.816406 -11.609375 8.140625 -11.046875 C 8.472656 -10.484375 8.71875 -9.800781 8.875 -9 C 9.03125 -8.195312 9.109375 -7.296875 9.109375 -6.296875 C 9.109375 -4.160156 8.757812 -2.539062 8.0625 -1.4375 C 7.375 -0.332031 6.332031 0.21875 4.9375 0.21875 C 4.1875 0.21875 3.546875 0.0664062 3.015625 -0.234375 C 2.492188 -0.546875 2.0625 -0.984375 1.71875 -1.546875 C 1.382812 -2.109375 1.144531 -2.789062 1 -3.59375 C 0.851562 -4.40625 0.78125 -5.304688 0.78125 -6.296875 Z M 2.203125 -6.296875 C 2.203125 -5.585938 2.25 -4.914062 2.34375 -4.28125 C 2.445312 -3.644531 2.609375 -3.085938 2.828125 -2.609375 C 3.046875 -2.128906 3.328125 -1.742188 3.671875 -1.453125 C 4.015625 -1.171875 4.4375 -1.03125 4.9375 -1.03125 C 5.832031 -1.03125 6.515625 -1.460938 6.984375 -2.328125 C 7.453125 -3.191406 7.6875 -4.515625 7.6875 -6.296875 C 7.6875 -6.992188 7.632812 -7.660156 7.53125 -8.296875 C 7.425781 -8.929688 7.265625 -9.488281 7.046875 -9.96875 C 6.835938 -10.457031 6.554688 -10.847656 6.203125 -11.140625 C 5.859375 -11.429688 5.4375 -11.578125 4.9375 -11.578125 C 4.039062 -11.578125 3.359375 -11.144531 2.890625 -10.28125 C 2.429688 -9.414062 2.203125 -8.085938 2.203125 -6.296875 Z M 2.203125 -6.296875"/></symbol><symbol overflow="visible" id="w"><path d="M 1.0625 -12.59375 L 2.359375 -12.59375 L 2.359375 -8.3125 L 2.40625 -8.3125 C 2.90625 -8.914062 3.5625 -9.21875 4.375 -9.21875 C 5.300781 -9.21875 5.992188 -8.847656 6.453125 -8.109375 C 6.910156 -7.378906 7.140625 -6.222656 7.140625 -4.640625 C 7.140625 -3.023438 6.832031 -1.820312 6.21875 -1.03125 C 5.601562 -0.238281 4.726562 0.15625 3.59375 0.15625 C 3.039062 0.15625 2.535156 0.09375 2.078125 -0.03125 C 1.628906 -0.15625 1.289062 -0.300781 1.0625 -0.46875 Z M 2.359375 -1.3125 C 2.523438 -1.21875 2.726562 -1.144531 2.96875 -1.09375 C 3.21875 -1.039062 3.484375 -1.015625 3.765625 -1.015625 C 4.390625 -1.015625 4.882812 -1.3125 5.25 -1.90625 C 5.613281 -2.5 5.796875 -3.410156 5.796875 -4.640625 C 5.796875 -5.160156 5.757812 -5.625 5.6875 -6.03125 C 5.625 -6.445312 5.523438 -6.804688 5.390625 -7.109375 C 5.253906 -7.410156 5.070312 -7.640625 4.84375 -7.796875 C 4.625 -7.960938 4.359375 -8.046875 4.046875 -8.046875 C 3.617188 -8.046875 3.265625 -7.914062 2.984375 -7.65625 C 2.703125 -7.394531 2.492188 -7.046875 2.359375 -6.609375 Z M 2.359375 -1.3125"/></symbol><symbol overflow="visible" id="x"><path d="M 0.671875 -4.5 C 0.671875 -6.125 0.945312 -7.316406 1.5 -8.078125 C 2.0625 -8.835938 2.859375 -9.21875 3.890625 -9.21875 C 4.992188 -9.21875 5.804688 -8.828125 6.328125 -8.046875 C 6.847656 -7.265625 7.109375 -6.082031 7.109375 -4.5 C 7.109375 -2.863281 6.828125 -1.664062 6.265625 -0.90625 C 5.703125 -0.15625 4.910156 0.21875 3.890625 0.21875 C 2.785156 0.21875 1.972656 -0.171875 1.453125 -0.953125 C 0.929688 -1.734375 0.671875 -2.914062 0.671875 -4.5 Z M 2.015625 -4.5 C 2.015625 -3.96875 2.046875 -3.484375 2.109375 -3.046875 C 2.179688 -2.617188 2.289062 -2.25 2.4375 -1.9375 C 2.582031 -1.625 2.773438 -1.378906 3.015625 -1.203125 C 3.265625 -1.035156 3.554688 -0.953125 3.890625 -0.953125 C 4.515625 -0.953125 4.984375 -1.226562 5.296875 -1.78125 C 5.609375 -2.34375 5.765625 -3.25 5.765625 -4.5 C 5.765625 -5.019531 5.726562 -5.5 5.65625 -5.9375 C 5.59375 -6.375 5.484375 -6.75 5.328125 -7.0625 C 5.179688 -7.375 4.988281 -7.613281 4.75 -7.78125 C 4.507812 -7.957031 4.222656 -8.046875 3.890625 -8.046875 C 3.273438 -8.046875 2.804688 -7.765625 2.484375 -7.203125 C 2.171875 -6.640625 2.015625 -5.738281 2.015625 -4.5 Z M 2.015625 -4.5"/></symbol><symbol overflow="visible" id="y"><path d="M 2.890625 -4.609375 L 0.515625 -9 L 2.0625 -9 L 3.40625 -6.421875 L 3.765625 -5.421875 L 4.140625 -6.421875 L 5.515625 -9 L 6.9375 -9 L 4.53125 -4.6875 L 7.078125 0 L 5.59375 0 L 4.09375 -2.828125 L 3.6875 -3.90625 L 3.28125 -2.828125 L 1.765625 0 L 0.34375 0 Z M 2.890625 -4.609375"/></symbol><symbol overflow="visible" id="z"><path d="M 6.03125 -0.453125 C 5.726562 -0.222656 5.382812 -0.0546875 5 0.046875 C 4.613281 0.160156 4.210938 0.21875 3.796875 0.21875 C 3.222656 0.21875 2.738281 0.109375 2.34375 -0.109375 C 1.945312 -0.335938 1.625 -0.65625 1.375 -1.0625 C 1.132812 -1.476562 0.957031 -1.976562 0.84375 -2.5625 C 0.726562 -3.144531 0.671875 -3.789062 0.671875 -4.5 C 0.671875 -6.03125 0.941406 -7.195312 1.484375 -8 C 2.023438 -8.8125 2.804688 -9.21875 3.828125 -9.21875 C 4.296875 -9.21875 4.695312 -9.175781 5.03125 -9.09375 C 5.375 -9.007812 5.664062 -8.898438 5.90625 -8.765625 L 5.546875 -7.625 C 5.066406 -7.90625 4.546875 -8.046875 3.984375 -8.046875 C 3.328125 -8.046875 2.832031 -7.757812 2.5 -7.1875 C 2.175781 -6.625 2.015625 -5.726562 2.015625 -4.5 C 2.015625 -4.007812 2.050781 -3.546875 2.125 -3.109375 C 2.195312 -2.679688 2.316406 -2.304688 2.484375 -1.984375 C 2.648438 -1.671875 2.863281 -1.421875 3.125 -1.234375 C 3.394531 -1.046875 3.726562 -0.953125 4.125 -0.953125 C 4.4375 -0.953125 4.726562 -1.003906 5 -1.109375 C 5.269531 -1.222656 5.488281 -1.351562 5.65625 -1.5 Z M 6.03125 -0.453125"/></symbol><symbol overflow="visible" id="A"><path d="M 5.28125 0 L 5.28125 -5.34375 C 5.28125 -5.820312 5.265625 -6.234375 5.234375 -6.578125 C 5.203125 -6.921875 5.132812 -7.195312 5.03125 -7.40625 C 4.9375 -7.625 4.804688 -7.785156 4.640625 -7.890625 C 4.472656 -7.992188 4.253906 -8.046875 3.984375 -8.046875 C 3.566406 -8.046875 3.21875 -7.882812 2.9375 -7.5625 C 2.65625 -7.25 2.460938 -6.890625 2.359375 -6.484375 L 2.359375 0 L 1.0625 0 L 1.0625 -9 L 1.984375 -9 L 2.21875 -8.046875 L 2.265625 -8.046875 C 2.515625 -8.390625 2.8125 -8.671875 3.15625 -8.890625 C 3.507812 -9.109375 3.957031 -9.21875 4.5 -9.21875 C 4.957031 -9.21875 5.332031 -9.117188 5.625 -8.921875 C 5.914062 -8.722656 6.144531 -8.367188 6.3125 -7.859375 C 6.53125 -8.285156 6.835938 -8.617188 7.234375 -8.859375 C 7.640625 -9.097656 8.082031 -9.21875 8.5625 -9.21875 C 8.957031 -9.21875 9.296875 -9.164062 9.578125 -9.0625 C 9.867188 -8.957031 10.097656 -8.773438 10.265625 -8.515625 C 10.441406 -8.265625 10.570312 -7.925781 10.65625 -7.5 C 10.738281 -7.070312 10.78125 -6.535156 10.78125 -5.890625 L 10.78125 0 L 9.484375 0 L 9.484375 -5.71875 C 9.484375 -6.5 9.40625 -7.082031 9.25 -7.46875 C 9.101562 -7.851562 8.757812 -8.046875 8.21875 -8.046875 C 7.769531 -8.046875 7.410156 -7.90625 7.140625 -7.625 C 6.867188 -7.34375 6.675781 -6.960938 6.5625 -6.484375 L 6.5625 0 Z M 5.28125 0"/></symbol><symbol overflow="visible" id="B"><path d="M 1.0625 -9 L 1.984375 -9 L 2.171875 -8.03125 L 2.25 -8.03125 C 2.695312 -8.820312 3.394531 -9.21875 4.34375 -9.21875 C 5.289062 -9.21875 6 -8.863281 6.46875 -8.15625 C 6.945312 -7.445312 7.1875 -6.289062 7.1875 -4.6875 C 7.1875 -3.925781 7.109375 -3.242188 6.953125 -2.640625 C 6.796875 -2.035156 6.570312 -1.519531 6.28125 -1.09375 C 5.988281 -0.664062 5.632812 -0.335938 5.21875 -0.109375 C 4.8125 0.109375 4.359375 0.21875 3.859375 0.21875 C 3.503906 0.21875 3.222656 0.195312 3.015625 0.15625 C 2.816406 0.113281 2.597656 0.0234375 2.359375 -0.109375 L 2.359375 3.59375 L 1.0625 3.59375 Z M 2.359375 -1.421875 C 2.523438 -1.273438 2.710938 -1.160156 2.921875 -1.078125 C 3.128906 -0.992188 3.410156 -0.953125 3.765625 -0.953125 C 4.398438 -0.953125 4.898438 -1.273438 5.265625 -1.921875 C 5.640625 -2.566406 5.828125 -3.492188 5.828125 -4.703125 C 5.828125 -5.203125 5.796875 -5.65625 5.734375 -6.0625 C 5.671875 -6.46875 5.566406 -6.816406 5.421875 -7.109375 C 5.273438 -7.410156 5.085938 -7.640625 4.859375 -7.796875 C 4.640625 -7.960938 4.367188 -8.046875 4.046875 -8.046875 C 3.171875 -8.046875 2.609375 -7.507812 2.359375 -6.4375 Z M 2.359375 -1.421875"/></symbol><symbol overflow="visible" id="C"><path d="M 5.671875 0 L 5.671875 -5.484375 C 5.671875 -6.390625 5.566406 -7.039062 5.359375 -7.4375 C 5.148438 -7.84375 4.773438 -8.046875 4.234375 -8.046875 C 3.753906 -8.046875 3.359375 -7.898438 3.046875 -7.609375 C 2.734375 -7.328125 2.503906 -6.972656 2.359375 -6.546875 L 2.359375 0 L 1.0625 0 L 1.0625 -9 L 2 -9 L 2.234375 -8.046875 L 2.28125 -8.046875 C 2.507812 -8.367188 2.816406 -8.644531 3.203125 -8.875 C 3.597656 -9.101562 4.066406 -9.21875 4.609375 -9.21875 C 4.992188 -9.21875 5.332031 -9.160156 5.625 -9.046875 C 5.914062 -8.941406 6.160156 -8.757812 6.359375 -8.5 C 6.554688 -8.25 6.707031 -7.90625 6.8125 -7.46875 C 6.914062 -7.039062 6.96875 -6.492188 6.96875 -5.828125 L 6.96875 0 Z M 5.671875 0"/></symbol><symbol overflow="visible" id="D"><path d="M 3.296875 -3.1875 L 3.671875 -1.4375 L 3.765625 -1.4375 L 4.03125 -3.1875 L 5.40625 -9 L 6.71875 -9 L 4.578125 -0.921875 C 4.398438 -0.273438 4.226562 0.328125 4.0625 0.890625 C 3.894531 1.460938 3.710938 1.953125 3.515625 2.359375 C 3.316406 2.773438 3.09375 3.097656 2.84375 3.328125 C 2.601562 3.566406 2.316406 3.6875 1.984375 3.6875 C 1.640625 3.6875 1.34375 3.632812 1.09375 3.53125 L 1.3125 2.296875 C 1.476562 2.359375 1.644531 2.367188 1.8125 2.328125 C 1.976562 2.296875 2.132812 2.195312 2.28125 2.03125 C 2.4375 1.863281 2.578125 1.613281 2.703125 1.28125 C 2.828125 0.957031 2.941406 0.53125 3.046875 0 L 0.125 -9 L 1.609375 -9 Z M 3.296875 -3.1875"/></symbol><symbol overflow="visible" id="F"><path d="M 6 -3.53125 L 2.4375 -3.53125 L 1.421875 0 L 0.09375 0 L 3.890625 -12.796875 L 4.625 -12.796875 L 8.421875 0 L 7.015625 0 Z M 2.796875 -4.734375 L 5.671875 -4.734375 L 4.578125 -8.625 L 4.234375 -10.515625 L 4.1875 -10.515625 L 3.859375 -8.59375 Z M 2.796875 -4.734375"/></symbol><symbol overflow="visible" id="G"><path d="M 2.234375 -9 L 2.234375 -3.484375 C 2.234375 -2.578125 2.328125 -1.925781 2.515625 -1.53125 C 2.703125 -1.144531 3.039062 -0.953125 3.53125 -0.953125 C 3.78125 -0.953125 4.003906 -1.003906 4.203125 -1.109375 C 4.398438 -1.210938 4.578125 -1.347656 4.734375 -1.515625 C 4.890625 -1.679688 5.023438 -1.867188 5.140625 -2.078125 C 5.265625 -2.296875 5.363281 -2.519531 5.4375 -2.75 L 5.4375 -9 L 6.734375 -9 L 6.734375 -2.5625 C 6.734375 -2.125 6.75 -1.671875 6.78125 -1.203125 C 6.8125 -0.742188 6.851562 -0.34375 6.90625 0 L 6 0 L 5.671875 -1.265625 L 5.609375 -1.265625 C 5.410156 -0.867188 5.117188 -0.519531 4.734375 -0.21875 C 4.347656 0.0703125 3.867188 0.21875 3.296875 0.21875 C 2.910156 0.21875 2.570312 0.164062 2.28125 0.0625 C 2 -0.03125 1.753906 -0.203125 1.546875 -0.453125 C 1.335938 -0.703125 1.179688 -1.046875 1.078125 -1.484375 C 0.984375 -1.921875 0.9375 -2.484375 0.9375 -3.171875 L 0.9375 -9 Z M 2.234375 -9"/></symbol><symbol overflow="visible" id="H"><path d="M 1.28125 -9 L 2.578125 -9 L 2.578125 0 L 1.28125 0 Z M 1.046875 -11.734375 C 1.046875 -12.023438 1.125 -12.257812 1.28125 -12.4375 C 1.445312 -12.613281 1.660156 -12.703125 1.921875 -12.703125 C 2.191406 -12.703125 2.410156 -12.613281 2.578125 -12.4375 C 2.753906 -12.269531 2.84375 -12.035156 2.84375 -11.734375 C 2.84375 -11.441406 2.753906 -11.210938 2.578125 -11.046875 C 2.410156 -10.890625 2.191406 -10.8125 1.921875 -10.8125 C 1.660156 -10.8125 1.445312 -10.894531 1.28125 -11.0625 C 1.125 -11.238281 1.046875 -11.460938 1.046875 -11.734375 Z M 1.046875 -11.734375"/></symbol><symbol overflow="visible" id="I"><path d="M 2.453125 -2.140625 C 2.453125 -1.722656 2.507812 -1.421875 2.625 -1.234375 C 2.738281 -1.054688 2.894531 -0.96875 3.09375 -0.96875 C 3.34375 -0.96875 3.640625 -1.035156 3.984375 -1.171875 L 4.109375 -0.125 C 3.953125 -0.03125 3.734375 0.046875 3.453125 0.109375 C 3.171875 0.171875 2.914062 0.203125 2.6875 0.203125 C 2.226562 0.203125 1.859375 0.0625 1.578125 -0.21875 C 1.296875 -0.5 1.15625 -0.992188 1.15625 -1.703125 L 1.15625 -12.59375 L 2.453125 -12.59375 Z M 2.453125 -2.140625"/></symbol><symbol overflow="visible" id="J"><path d="M 6.734375 0.40625 C 6.734375 1.570312 6.472656 2.429688 5.953125 2.984375 C 5.441406 3.535156 4.691406 3.8125 3.703125 3.8125 C 3.109375 3.8125 2.617188 3.757812 2.234375 3.65625 C 1.847656 3.5625 1.535156 3.445312 1.296875 3.3125 L 1.671875 2.203125 C 1.910156 2.304688 2.171875 2.40625 2.453125 2.5 C 2.742188 2.59375 3.101562 2.640625 3.53125 2.640625 C 4.257812 2.640625 4.757812 2.4375 5.03125 2.03125 C 5.300781 1.625 5.4375 0.941406 5.4375 -0.015625 L 5.4375 -0.6875 L 5.375 -0.6875 C 5.1875 -0.40625 4.941406 -0.1875 4.640625 -0.03125 C 4.335938 0.125 3.953125 0.203125 3.484375 0.203125 C 2.515625 0.203125 1.800781 -0.171875 1.34375 -0.921875 C 0.894531 -1.671875 0.671875 -2.851562 0.671875 -4.46875 C 0.671875 -6.007812 0.96875 -7.175781 1.5625 -7.96875 C 2.15625 -8.757812 3.03125 -9.15625 4.1875 -9.15625 C 4.757812 -9.15625 5.25 -9.101562 5.65625 -9 C 6.0625 -8.894531 6.421875 -8.769531 6.734375 -8.625 Z M 5.4375 -7.703125 C 5.070312 -7.890625 4.609375 -7.984375 4.046875 -7.984375 C 3.429688 -7.984375 2.9375 -7.703125 2.5625 -7.140625 C 2.195312 -6.585938 2.015625 -5.703125 2.015625 -4.484375 C 2.015625 -3.972656 2.046875 -3.503906 2.109375 -3.078125 C 2.171875 -2.660156 2.269531 -2.289062 2.40625 -1.96875 C 2.550781 -1.65625 2.734375 -1.410156 2.953125 -1.234375 C 3.179688 -1.054688 3.457031 -0.96875 3.78125 -0.96875 C 4.238281 -0.96875 4.597656 -1.085938 4.859375 -1.328125 C 5.117188 -1.566406 5.3125 -1.925781 5.4375 -2.40625 Z M 5.4375 -7.703125"/></symbol><symbol overflow="visible" id="K"><path d="M 5.40625 -11.5 C 5.269531 -11.519531 5.070312 -11.546875 4.8125 -11.578125 C 4.550781 -11.617188 4.296875 -11.640625 4.046875 -11.640625 C 3.734375 -11.640625 3.488281 -11.578125 3.3125 -11.453125 C 3.132812 -11.335938 2.992188 -11.171875 2.890625 -10.953125 C 2.796875 -10.734375 2.738281 -10.457031 2.71875 -10.125 C 2.695312 -9.789062 2.6875 -9.414062 2.6875 -9 L 4.109375 -9 L 4.109375 -7.828125 L 2.6875 -7.828125 L 2.6875 0 L 1.390625 0 L 1.390625 -7.828125 L 0.28125 -7.828125 L 0.28125 -9 L 1.390625 -9 L 1.390625 -9.5 C 1.390625 -10.632812 1.585938 -11.46875 1.984375 -12 C 2.390625 -12.539062 3.066406 -12.8125 4.015625 -12.8125 C 4.203125 -12.8125 4.425781 -12.800781 4.6875 -12.78125 C 4.945312 -12.769531 5.203125 -12.75 5.453125 -12.71875 C 5.703125 -12.6875 5.9375 -12.648438 6.15625 -12.609375 C 6.382812 -12.578125 6.566406 -12.535156 6.703125 -12.484375 L 6.703125 -2.046875 C 6.703125 -1.648438 6.753906 -1.367188 6.859375 -1.203125 C 6.972656 -1.035156 7.132812 -0.953125 7.34375 -0.953125 C 7.601562 -0.953125 7.90625 -1.019531 8.25 -1.15625 L 8.328125 -0.109375 C 8.171875 -0.015625 7.957031 0.0625 7.6875 0.125 C 7.425781 0.1875 7.164062 0.21875 6.90625 0.21875 C 6.457031 0.21875 6.09375 0.078125 5.8125 -0.203125 C 5.539062 -0.492188 5.40625 -0.988281 5.40625 -1.6875 Z M 5.40625 -11.5"/></symbol><symbol overflow="visible" id="U"><path d="M 0 2.515625 L 6.015625 2.515625 L 6.015625 3.6875 L 0 3.6875 Z M 0 2.515625"/></symbol><symbol overflow="visible" id="V"><path d="M 5.875 -9 L 7.46875 -3.75 L 7.796875 -2.015625 L 7.828125 -2.015625 L 8.09375 -3.78125 L 9.328125 -9 L 10.546875 -9 L 8.15625 0.203125 L 7.421875 0.203125 L 5.59375 -5.703125 L 5.34375 -7.21875 L 5.3125 -7.21875 L 5.0625 -5.6875 L 3.296875 0.203125 L 2.5625 0.203125 L 0.09375 -9 L 1.46875 -9 L 2.859375 -3.765625 L 3.078125 -2.015625 L 3.109375 -2.015625 L 3.4375 -3.796875 L 4.90625 -9 Z M 5.875 -9"/></symbol><symbol overflow="visible" id="W"><path d="M 7.21875 0 L 1.15625 0 L 1.15625 -12.59375 L 2.5 -12.59375 L 2.5 -1.234375 L 7.21875 -1.234375 Z M 7.21875 0"/></symbol><symbol overflow="visible" id="X"><path d="M 1.6875 -1.203125 L 3.71875 -1.203125 L 3.71875 -9.96875 L 3.890625 -11.03125 L 3.28125 -10.171875 L 1.765625 -8.953125 L 1.078125 -9.75 L 4.359375 -12.8125 L 5.015625 -12.8125 L 5.015625 -1.203125 L 6.984375 -1.203125 L 6.984375 0 L 1.6875 0 Z M 1.6875 -1.203125"/></symbol><symbol overflow="visible" id="Y"><path d="M 5.671875 0 L 5.671875 -5.46875 C 5.671875 -6.3125 5.570312 -6.953125 5.375 -7.390625 C 5.175781 -7.828125 4.78125 -8.046875 4.1875 -8.046875 C 3.769531 -8.046875 3.390625 -7.894531 3.046875 -7.59375 C 2.703125 -7.289062 2.472656 -6.914062 2.359375 -6.46875 L 2.359375 0 L 1.0625 0 L 1.0625 -12.59375 L 2.359375 -12.59375 L 2.359375 -8.15625 L 2.40625 -8.15625 C 2.644531 -8.46875 2.941406 -8.722656 3.296875 -8.921875 C 3.648438 -9.117188 4.09375 -9.21875 4.625 -9.21875 C 5.019531 -9.21875 5.363281 -9.160156 5.65625 -9.046875 C 5.957031 -8.941406 6.203125 -8.753906 6.390625 -8.484375 C 6.578125 -8.222656 6.71875 -7.875 6.8125 -7.4375 C 6.914062 -7 6.96875 -6.457031 6.96875 -5.8125 L 6.96875 0 Z M 5.671875 0"/></symbol><symbol overflow="visible" id="Z"><path d="M 0.578125 -1.171875 L 3.921875 -7.0625 L 4.546875 -7.828125 L 0.578125 -7.828125 L 0.578125 -9 L 5.828125 -9 L 5.828125 -7.828125 L 2.46875 -1.890625 L 1.859375 -1.171875 L 5.828125 -1.171875 L 5.828125 0 L 0.578125 0 Z M 0.578125 -1.171875"/></symbol><symbol overflow="visible" id="aa"><path d="M 7.734375 -0.484375 C 7.441406 -0.234375 7.066406 -0.0546875 6.609375 0.046875 C 6.148438 0.160156 5.671875 0.21875 5.171875 0.21875 C 4.535156 0.21875 3.945312 0.0976562 3.40625 -0.140625 C 2.863281 -0.378906 2.394531 -0.757812 2 -1.28125 C 1.613281 -1.800781 1.3125 -2.472656 1.09375 -3.296875 C 0.882812 -4.128906 0.78125 -5.128906 0.78125 -6.296875 C 0.78125 -7.492188 0.898438 -8.503906 1.140625 -9.328125 C 1.390625 -10.160156 1.71875 -10.832031 2.125 -11.34375 C 2.53125 -11.863281 3 -12.238281 3.53125 -12.46875 C 4.070312 -12.695312 4.625 -12.8125 5.1875 -12.8125 C 5.757812 -12.8125 6.234375 -12.769531 6.609375 -12.6875 C 6.992188 -12.601562 7.320312 -12.503906 7.59375 -12.390625 L 7.265625 -11.15625 C 7.023438 -11.289062 6.742188 -11.394531 6.421875 -11.46875 C 6.097656 -11.539062 5.726562 -11.578125 5.3125 -11.578125 C 4.894531 -11.578125 4.5 -11.484375 4.125 -11.296875 C 3.75 -11.109375 3.414062 -10.804688 3.125 -10.390625 C 2.84375 -9.984375 2.617188 -9.441406 2.453125 -8.765625 C 2.285156 -8.097656 2.203125 -7.273438 2.203125 -6.296875 C 2.203125 -4.546875 2.5 -3.226562 3.09375 -2.34375 C 3.695312 -1.46875 4.492188 -1.03125 5.484375 -1.03125 C 5.898438 -1.03125 6.269531 -1.085938 6.59375 -1.203125 C 6.914062 -1.316406 7.191406 -1.453125 7.421875 -1.609375 Z M 7.734375 -0.484375"/></symbol></defs><path fill="#fff" d="M0 0H722V514H0z"/><path d="M 24.2362 40.852794 L 60.101239 40.852794 L 60.101239 66.190294 L 24.2362 66.190294 Z M 24.2362 40.852794" transform="matrix(20 0 0 20 -483.724 -810.384)" fill-rule="evenodd" fill="#fff" stroke-width=".1" stroke="#fff" stroke-miterlimit="10"/><path d="M 26.643622 44.584239 L 57.100262 44.584239" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.643622 62.446153 L 57.100262 62.446153" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.643622 44.584239 L 26.643622 44.584239 C 26.477997 44.584239 26.343622 44.718419 26.343622 44.884239" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 57.400262 44.884239 L 57.400262 44.884239 C 57.400262 44.718419 57.266083 44.584239 57.100262 44.584239" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.343622 44.884239 L 26.343622 62.146153" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 57.400262 44.884239 L 57.400262 62.146153" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.343622 62.146153 L 26.343622 62.146153 C 26.343622 62.311778 26.477997 62.446153 26.643622 62.446153" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 57.100262 62.446153 L 57.100262 62.446153 C 57.266083 62.446153 57.400262 62.311778 57.400262 62.146153" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 81.667969 125.710938 L 176.96875 125.710938 L 176.96875 151.960938 L 81.667969 151.960938 Z M 81.667969 125.710938" fill-rule="evenodd" fill="#fff"/><use xlink:href="#a" x="83.082" y="146.359"/><use xlink:href="#b" x="93.102" y="146.359"/><use xlink:href="#b" x="102.008" y="146.359"/><use xlink:href="#c" x="110.914" y="146.359"/><use xlink:href="#d" x="116.773" y="146.359"/><use xlink:href="#e" x="125.328" y="146.359"/><use xlink:href="#f" x="132.32" y="146.359"/><use xlink:href="#g" x="136.422" y="146.359"/><use xlink:href="#h" x="141.285" y="146.359"/><use xlink:href="#i" x="145.777" y="146.359"/><use xlink:href="#d" x="154.762" y="146.359"/><use xlink:href="#f" x="163.316" y="146.359"/><use xlink:href="#j" x="167.418" y="146.359"/><path d="M 197.3125 118.835938 L 605.3125 118.835938 L 605.3125 158.835938 L 197.3125 158.835938 Z M 197.3125 118.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 124.835938 L 197.3125 118.835938 C 194 118.835938 191.3125 121.519531 191.3125 124.835938 Z M 197.3125 124.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.3125 124.835938 L 611.3125 124.835938 C 611.3125 121.519531 608.625 118.835938 605.3125 118.835938 Z M 605.3125 124.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.3125 124.835938 L 611.3125 124.835938 L 611.3125 152.835938 L 191.3125 152.835938 Z M 191.3125 124.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 152.835938 L 191.3125 152.835938 C 191.3125 156.148438 194 158.835938 197.3125 158.835938 Z M 197.3125 152.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.3125 152.835938 L 605.3125 158.835938 C 608.625 158.835938 611.3125 156.148438 611.3125 152.835938 Z M 605.3125 152.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.051825 46.460997 L 54.451825 46.460997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 48.460997 L 54.451825 48.460997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 46.460997 L 34.051825 46.460997 C 33.8862 46.460997 33.751825 46.595177 33.751825 46.760997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.751825 46.760997 L 54.751825 46.760997 C 54.751825 46.595177 54.61745 46.460997 54.451825 46.460997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 46.760997 L 33.751825 48.160997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.751825 46.760997 L 54.751825 48.160997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 48.160997 L 33.751825 48.160997 C 33.751825 48.326622 33.8862 48.460997 34.051825 48.460997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.451825 48.460997 L 54.451825 48.460997 C 54.61745 48.460997 54.751825 48.326622 54.751825 48.160997" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 191.3125 161.433594 L 432.511719 161.433594 L 432.511719 184.832031 L 191.3125 184.832031 Z M 191.3125 161.433594" fill-rule="evenodd" fill="#fff"/><g fill="#4d4d4d"><use xlink:href="#k" x="191.313" y="179.836"/><use xlink:href="#l" x="199.008" y="179.836"/><use xlink:href="#m" x="203.949" y="179.836"/><use xlink:href="#n" x="208.891" y="179.836"/><use xlink:href="#n" x="216.215" y="179.836"/><use xlink:href="#l" x="223.656" y="179.836"/><use xlink:href="#o" x="228.598" y="179.836"/><use xlink:href="#p" x="232.406" y="179.836"/><use xlink:href="#q" x="239.613" y="179.836"/><use xlink:href="#q" x="247.406" y="179.836"/><use xlink:href="#m" x="255.199" y="179.836"/><use xlink:href="#n" x="260.141" y="179.836"/><use xlink:href="#r" x="267.582" y="179.836"/><use xlink:href="#r" x="273.656" y="179.836"/><use xlink:href="#s" x="279.73" y="179.836"/><use xlink:href="#o" x="281.898" y="179.836"/><use xlink:href="#t" x="285.707" y="179.836"/><use xlink:href="#u" x="291.957" y="179.836"/><use xlink:href="#v" x="295.16" y="179.836"/><use xlink:href="#u" x="304.633" y="179.836"/><use xlink:href="#o" x="306.664" y="179.836"/><use xlink:href="#w" x="310.473" y="179.836"/><use xlink:href="#x" x="318.285" y="179.836"/><use xlink:href="#y" x="325.746" y="179.836"/><use xlink:href="#s" x="333.168" y="179.836"/><use xlink:href="#o" x="335.336" y="179.836"/><use xlink:href="#z" x="339.145" y="179.836"/><use xlink:href="#x" x="345.258" y="179.836"/><use xlink:href="#A" x="353.031" y="179.836"/><use xlink:href="#B" x="364.75" y="179.836"/><use xlink:href="#p" x="372.582" y="179.836"/><use xlink:href="#C" x="379.789" y="179.836"/><use xlink:href="#D" x="387.699" y="179.836"/><use xlink:href="#o" x="393.988" y="179.836"/><use xlink:href="#C" x="397.797" y="179.836"/><use xlink:href="#p" x="405.707" y="179.836"/><use xlink:href="#A" x="412.914" y="179.836"/><use xlink:href="#n" x="424.633" y="179.836"/></g><path d="M 48.157489 51.129552 L 44.694989 51.12545" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 44.694989 51.12545 C 44.695184 51.00045 44.82038 50.875645 44.94538 50.875645 C 45.07038 50.875841 45.195184 51.001036 45.194989 51.126036 C 45.194794 51.251036 45.069794 51.375841 44.944794 51.375645 C 44.819794 51.375645 44.694794 51.25045 44.694989 51.12545" transform="matrix(20 0 0 20 -483.724 -810.384)" fill-rule="evenodd" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 81.667969 207.042969 L 176.96875 207.042969 L 176.96875 233.292969 L 81.667969 233.292969 Z M 81.667969 207.042969" fill-rule="evenodd" fill="#fff"/><use xlink:href="#a" x="83.082" y="227.695"/><use xlink:href="#b" x="93.102" y="227.695"/><use xlink:href="#b" x="102.008" y="227.695"/><use xlink:href="#c" x="110.914" y="227.695"/><use xlink:href="#d" x="116.773" y="227.695"/><use xlink:href="#e" x="125.328" y="227.695"/><use xlink:href="#f" x="132.32" y="227.695"/><use xlink:href="#g" x="136.422" y="227.695"/><use xlink:href="#h" x="141.285" y="227.695"/><use xlink:href="#i" x="145.777" y="227.695"/><use xlink:href="#d" x="154.762" y="227.695"/><use xlink:href="#f" x="163.316" y="227.695"/><use xlink:href="#E" x="167.418" y="227.695"/><path d="M 197.3125 200.167969 L 605.3125 200.167969 L 605.3125 240.167969 L 197.3125 240.167969 Z M 197.3125 200.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 206.167969 L 197.3125 200.167969 C 194 200.167969 191.3125 202.855469 191.3125 206.167969 Z M 197.3125 206.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.3125 206.167969 L 611.3125 206.167969 C 611.3125 202.855469 608.625 200.167969 605.3125 200.167969 Z M 605.3125 206.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.3125 206.167969 L 611.3125 206.167969 L 611.3125 234.167969 L 191.3125 234.167969 Z M 191.3125 206.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 234.167969 L 191.3125 234.167969 C 191.3125 237.480469 194 240.167969 197.3125 240.167969 Z M 197.3125 234.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.3125 234.167969 L 605.3125 240.167969 C 608.625 240.167969 611.3125 237.480469 611.3125 234.167969 Z M 605.3125 234.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.051825 50.527598 L 54.451825 50.527598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 52.527598 L 54.451825 52.527598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 50.527598 L 34.051825 50.527598 C 33.8862 50.527598 33.751825 50.661973 33.751825 50.827598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.751825 50.827598 L 54.751825 50.827598 C 54.751825 50.661973 54.61745 50.527598 54.451825 50.527598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 50.827598 L 33.751825 52.227598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.751825 50.827598 L 54.751825 52.227598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 52.227598 L 33.751825 52.227598 C 33.751825 52.393223 33.8862 52.527598 34.051825 52.527598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.451825 52.527598 L 54.451825 52.527598 C 54.61745 52.527598 54.751825 52.393223 54.751825 52.227598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 190.8125 242.433594 L 415.710938 242.433594 L 415.710938 265.832031 L 190.8125 265.832031 Z M 190.8125 242.433594" fill-rule="evenodd" fill="#fff"/><g fill="#4d4d4d"><use xlink:href="#F" x="190.813" y="260.836"/><use xlink:href="#B" x="199.328" y="260.836"/><use xlink:href="#p" x="207.16" y="260.836"/><use xlink:href="#m" x="214.367" y="260.836"/><use xlink:href="#l" x="219.738" y="260.836"/><use xlink:href="#A" x="224.68" y="260.836"/><use xlink:href="#n" x="236.398" y="260.836"/><use xlink:href="#C" x="243.84" y="260.836"/><use xlink:href="#l" x="251.75" y="260.836"/><use xlink:href="#s" x="256.691" y="260.836"/><use xlink:href="#o" x="258.859" y="260.836"/><use xlink:href="#r" x="262.668" y="260.836"/><use xlink:href="#G" x="268.742" y="260.836"/><use xlink:href="#H" x="276.555" y="260.836"/><use xlink:href="#l" x="280.461" y="260.836"/><use xlink:href="#n" x="285.285" y="260.836"/><use xlink:href="#s" x="292.727" y="260.836"/><use xlink:href="#o" x="294.895" y="260.836"/><use xlink:href="#G" x="298.703" y="260.836"/><use xlink:href="#C" x="306.516" y="260.836"/><use xlink:href="#H" x="314.426" y="260.836"/><use xlink:href="#l" x="318.332" y="260.836"/><use xlink:href="#s" x="323.273" y="260.836"/><use xlink:href="#o" x="325.441" y="260.836"/><use xlink:href="#w" x="329.25" y="260.836"/><use xlink:href="#G" x="337.063" y="260.836"/><use xlink:href="#H" x="344.875" y="260.836"/><use xlink:href="#I" x="348.781" y="260.836"/><use xlink:href="#q" x="352.98" y="260.836"/><use xlink:href="#H" x="360.773" y="260.836"/><use xlink:href="#C" x="364.68" y="260.836"/><use xlink:href="#J" x="372.59" y="260.836"/><use xlink:href="#s" x="380.363" y="260.836"/><use xlink:href="#o" x="382.531" y="260.836"/><use xlink:href="#K" x="386.34" y="260.836"/><use xlink:href="#x" x="394.777" y="260.836"/><use xlink:href="#x" x="402.551" y="260.836"/><use xlink:href="#m" x="410.324" y="260.836"/></g><path d="M 148.910156 290.542969 L 176.308594 290.542969 L 176.308594 316.792969 L 148.910156 316.792969 Z M 148.910156 290.542969" fill-rule="evenodd" fill="#fff"/><use xlink:href="#L" x="149.242" y="311.195"/><use xlink:href="#h" x="158.383" y="311.195"/><use xlink:href="#M" x="162.875" y="311.195"/><use xlink:href="#N" x="168.305" y="311.195"/><path d="M 197.3125 283.667969 L 385.3125 283.667969 L 385.3125 323.667969 L 197.3125 323.667969 Z M 197.3125 283.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 289.667969 L 197.3125 283.667969 C 194 283.667969 191.3125 286.355469 191.3125 289.667969 Z M 197.3125 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 385.3125 289.667969 L 391.3125 289.667969 C 391.3125 286.355469 388.625 283.667969 385.3125 283.667969 Z M 385.3125 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.3125 289.667969 L 391.3125 289.667969 L 391.3125 317.667969 L 191.3125 317.667969 Z M 191.3125 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 317.667969 L 191.3125 317.667969 C 191.3125 320.980469 194 323.667969 197.3125 323.667969 Z M 197.3125 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 385.3125 317.667969 L 385.3125 323.667969 C 388.625 323.667969 391.3125 320.980469 391.3125 317.667969 Z M 385.3125 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.051825 54.702598 L 43.451825 54.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 56.702598 L 43.451825 56.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 54.702598 L 34.051825 54.702598 C 33.8862 54.702598 33.751825 54.836973 33.751825 55.002598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 43.751825 55.002598 L 43.751825 55.002598 C 43.751825 54.836973 43.61745 54.702598 43.451825 54.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 55.002598 L 33.751825 56.402598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 43.751825 55.002598 L 43.751825 56.402598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 56.402598 L 33.751825 56.402598 C 33.751825 56.568223 33.8862 56.702598 34.051825 56.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 43.451825 56.702598 L 43.451825 56.702598 C 43.61745 56.702598 43.751825 56.568223 43.751825 56.402598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 113.960938 361.773438 L 176.3125 361.773438 L 176.3125 388.023438 L 113.960938 388.023438 Z M 113.960938 361.773438" fill-rule="evenodd" fill="#fff"/><use xlink:href="#O" x="114.887" y="382.422"/><use xlink:href="#P" x="123.793" y="382.422"/><use xlink:href="#Q" x="128.559" y="382.422"/><use xlink:href="#f" x="137.465" y="382.422"/><use xlink:href="#L" x="141.352" y="382.422"/><use xlink:href="#R" x="149.945" y="382.422"/><use xlink:href="#b" x="158.852" y="382.422"/><use xlink:href="#d" x="167.758" y="382.422"/><path d="M 197.3125 354.898438 L 305.3125 354.898438 L 305.3125 394.898438 L 197.3125 394.898438 Z M 197.3125 354.898438" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 360.898438 L 197.3125 354.898438 C 194 354.898438 191.3125 357.585938 191.3125 360.898438 Z M 197.3125 360.898438" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 305.3125 360.898438 L 311.3125 360.898438 C 311.3125 357.585938 308.625 354.898438 305.3125 354.898438 Z M 305.3125 360.898438" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.3125 360.898438 L 311.3125 360.898438 L 311.3125 388.898438 L 191.3125 388.898438 Z M 191.3125 360.898438" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.3125 388.898438 L 191.3125 388.898438 C 191.3125 392.210938 194 394.898438 197.3125 394.898438 Z M 197.3125 388.898438" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 305.3125 388.898438 L 305.3125 394.898438 C 308.625 394.898438 311.3125 392.210938 311.3125 388.898438 Z M 305.3125 388.898438" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.051825 58.264122 L 39.451825 58.264122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 60.264122 L 39.451825 60.264122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.051825 58.264122 L 34.051825 58.264122 C 33.8862 58.264122 33.751825 58.398497 33.751825 58.564122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 39.751825 58.564122 L 39.751825 58.564122 C 39.751825 58.398497 39.61745 58.264122 39.451825 58.264122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 58.564122 L 33.751825 59.964122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 39.751825 58.564122 L 39.751825 59.964122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.751825 59.964122 L 33.751825 59.964122 C 33.751825 60.129747 33.8862 60.264122 34.051825 60.264122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 39.451825 60.264122 L 39.451825 60.264122 C 39.61745 60.264122 39.751825 60.129747 39.751825 59.964122" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 477.3125 283.667969 L 605.3125 283.667969 L 605.3125 323.667969 L 477.3125 323.667969 Z M 477.3125 283.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 477.3125 289.667969 L 477.3125 283.667969 C 474 283.667969 471.3125 286.355469 471.3125 289.667969 Z M 477.3125 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.3125 289.667969 L 611.3125 289.667969 C 611.3125 286.355469 608.625 283.667969 605.3125 283.667969 Z M 605.3125 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 471.3125 289.667969 L 611.3125 289.667969 L 611.3125 317.667969 L 471.3125 317.667969 Z M 471.3125 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 477.3125 317.667969 L 471.3125 317.667969 C 471.3125 320.980469 474 323.667969 477.3125 323.667969 Z M 477.3125 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.3125 317.667969 L 605.3125 323.667969 C 608.625 323.667969 611.3125 320.980469 611.3125 317.667969 Z M 605.3125 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 48.051825 54.702598 L 54.451825 54.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 48.051825 56.702598 L 54.451825 56.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 48.051825 54.702598 L 48.051825 54.702598 C 47.8862 54.702598 47.751825 54.836973 47.751825 55.002598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.751825 55.002598 L 54.751825 55.002598 C 54.751825 54.836973 54.61745 54.702598 54.451825 54.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 47.751825 55.002598 L 47.751825 56.402598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.751825 55.002598 L 54.751825 56.402598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 47.751825 56.402598 L 47.751825 56.402598 C 47.751825 56.568223 47.8862 56.702598 48.051825 56.702598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.451825 56.702598 L 54.451825 56.702598 C 54.61745 56.702598 54.751825 56.568223 54.751825 56.402598" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 422.511719 290.542969 L 460.3125 290.542969 L 460.3125 316.792969 L 422.511719 316.792969 Z M 422.511719 290.542969" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#S" x="423.066" y="311.195"/><use xlink:href="#M" x="431.855" y="311.195"/><use xlink:href="#T" x="437.676" y="311.195"/><use xlink:href="#M" x="445.938" y="311.195"/><use xlink:href="#d" x="451.758" y="311.195"/></g><path d="M 27.900653 42.973497 L 27.905536 44.871934" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 27.905536 44.871934 C 27.780536 44.87213 27.655145 44.74752 27.65495 44.62252 C 27.654559 44.49752 27.779169 44.37213 27.904169 44.371934 C 28.029169 44.371544 28.154559 44.496348 28.15495 44.621348 C 28.155145 44.746348 28.030536 44.871544 27.905536 44.871934" transform="matrix(20 0 0 20 -483.724 -810.384)" fill-rule="evenodd" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 46.275067 43.802208 L 46.249091 49.473887" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 46.249091 49.473887 C 46.124091 49.473302 45.999481 49.347716 46.000067 49.222716 C 46.000653 49.097716 46.126239 48.973302 46.251239 48.973887 C 46.376239 48.974473 46.500653 49.100059 46.500067 49.225059 C 46.499481 49.350059 46.374091 49.474473 46.249091 49.473887" transform="matrix(20 0 0 20 -483.724 -810.384)" fill-rule="evenodd" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 519.304688 458.691406 L 696.003906 458.691406 L 696.003906 482.089844 L 519.304688 482.089844 Z M 519.304688 458.691406" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#B" x="519.305" y="477.09"/><use xlink:href="#x" x="527.137" y="477.09"/><use xlink:href="#r" x="534.91" y="477.09"/><use xlink:href="#l" x="540.984" y="477.09"/><use xlink:href="#p" x="545.926" y="477.09"/><use xlink:href="#I" x="553.133" y="477.09"/><use xlink:href="#U" x="557.332" y="477.09"/><use xlink:href="#p" x="563.348" y="477.09"/><use xlink:href="#q" x="570.555" y="477.09"/><use xlink:href="#q" x="578.348" y="477.09"/><use xlink:href="#m" x="586.141" y="477.09"/><use xlink:href="#n" x="591.082" y="477.09"/><use xlink:href="#r" x="598.523" y="477.09"/><use xlink:href="#r" x="604.598" y="477.09"/><use xlink:href="#U" x="610.672" y="477.09"/><use xlink:href="#r" x="616.688" y="477.09"/><use xlink:href="#l" x="622.762" y="477.09"/><use xlink:href="#p" x="627.703" y="477.09"/><use xlink:href="#l" x="634.91" y="477.09"/><use xlink:href="#n" x="639.734" y="477.09"/><use xlink:href="#U" x="647.176" y="477.09"/><use xlink:href="#V" x="653.191" y="477.09"/><use xlink:href="#H" x="663.816" y="477.09"/><use xlink:href="#q" x="667.723" y="477.09"/><use xlink:href="#J" x="675.516" y="477.09"/><use xlink:href="#n" x="683.289" y="477.09"/><use xlink:href="#l" x="690.73" y="477.09"/></g><path d="M 44.988281 24.355469 L 165.839844 24.355469 L 165.839844 47.753906 L 44.988281 47.753906 Z M 44.988281 24.355469" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#B" x="44.988" y="42.754"/><use xlink:href="#x" x="52.82" y="42.754"/><use xlink:href="#r" x="60.594" y="42.754"/><use xlink:href="#l" x="66.668" y="42.754"/><use xlink:href="#p" x="71.609" y="42.754"/><use xlink:href="#I" x="78.816" y="42.754"/><use xlink:href="#U" x="83.016" y="42.754"/><use xlink:href="#p" x="89.031" y="42.754"/><use xlink:href="#q" x="96.238" y="42.754"/><use xlink:href="#q" x="104.031" y="42.754"/><use xlink:href="#m" x="111.824" y="42.754"/><use xlink:href="#n" x="116.766" y="42.754"/><use xlink:href="#r" x="124.207" y="42.754"/><use xlink:href="#r" x="130.281" y="42.754"/><use xlink:href="#U" x="136.355" y="42.754"/><use xlink:href="#m" x="142.371" y="42.754"/><use xlink:href="#x" x="147.313" y="42.754"/><use xlink:href="#V" x="154.949" y="42.754"/></g><path d="M 311.148438 41.605469 L 524.5 41.605469 L 524.5 65.003906 L 311.148438 65.003906 Z M 311.148438 41.605469" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#B" x="311.148" y="60.008"/><use xlink:href="#x" x="318.98" y="60.008"/><use xlink:href="#r" x="326.754" y="60.008"/><use xlink:href="#l" x="332.828" y="60.008"/><use xlink:href="#p" x="337.77" y="60.008"/><use xlink:href="#I" x="344.977" y="60.008"/><use xlink:href="#U" x="349.176" y="60.008"/><use xlink:href="#p" x="355.191" y="60.008"/><use xlink:href="#q" x="362.398" y="60.008"/><use xlink:href="#q" x="370.191" y="60.008"/><use xlink:href="#m" x="377.984" y="60.008"/><use xlink:href="#n" x="382.926" y="60.008"/><use xlink:href="#r" x="390.367" y="60.008"/><use xlink:href="#r" x="396.441" y="60.008"/><use xlink:href="#U" x="402.516" y="60.008"/><use xlink:href="#p" x="408.531" y="60.008"/><use xlink:href="#q" x="415.738" y="60.008"/><use xlink:href="#q" x="423.531" y="60.008"/><use xlink:href="#m" x="431.324" y="60.008"/><use xlink:href="#n" x="436.266" y="60.008"/><use xlink:href="#r" x="443.707" y="60.008"/><use xlink:href="#r" x="449.781" y="60.008"/><use xlink:href="#W" x="455.855" y="60.008"/><use xlink:href="#H" x="463.316" y="60.008"/><use xlink:href="#C" x="467.223" y="60.008"/><use xlink:href="#n" x="475.133" y="60.008"/><use xlink:href="#X" x="482.574" y="60.008"/><use xlink:href="#U" x="490.68" y="60.008"/><use xlink:href="#Y" x="496.695" y="60.008"/><use xlink:href="#n" x="504.625" y="60.008"/><use xlink:href="#I" x="512.066" y="60.008"/><use xlink:href="#B" x="516.266" y="60.008"/></g><path d="M 54.402344 467.421875 L 238.003906 467.421875 L 238.003906 490.820312 L 54.402344 490.820312 Z M 54.402344 467.421875" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#B" x="54.402" y="485.82"/><use xlink:href="#x" x="62.234" y="485.82"/><use xlink:href="#r" x="70.008" y="485.82"/><use xlink:href="#l" x="76.082" y="485.82"/><use xlink:href="#p" x="81.023" y="485.82"/><use xlink:href="#I" x="88.23" y="485.82"/><use xlink:href="#U" x="92.43" y="485.82"/><use xlink:href="#p" x="98.445" y="485.82"/><use xlink:href="#q" x="105.652" y="485.82"/><use xlink:href="#q" x="113.445" y="485.82"/><use xlink:href="#m" x="121.238" y="485.82"/><use xlink:href="#n" x="126.18" y="485.82"/><use xlink:href="#r" x="133.621" y="485.82"/><use xlink:href="#r" x="139.695" y="485.82"/><use xlink:href="#U" x="145.77" y="485.82"/><use xlink:href="#Z" x="151.785" y="485.82"/><use xlink:href="#H" x="158.27" y="485.82"/><use xlink:href="#B" x="162.176" y="485.82"/><use xlink:href="#aa" x="170.008" y="485.82"/><use xlink:href="#x" x="177.781" y="485.82"/><use xlink:href="#q" x="185.555" y="485.82"/><use xlink:href="#n" x="193.348" y="485.82"/><use xlink:href="#U" x="200.789" y="485.82"/><use xlink:href="#I" x="206.805" y="485.82"/><use xlink:href="#p" x="211.004" y="485.82"/><use xlink:href="#w" x="218.211" y="485.82"/><use xlink:href="#n" x="226.023" y="485.82"/><use xlink:href="#I" x="233.465" y="485.82"/></g><path d="M 53.802606 63.60045 L 53.829364 56.467247" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 53.829364 56.467247 C 53.954364 56.467637 54.078778 56.593223 54.078387 56.718223 C 54.077997 56.843223 53.952411 56.967637 53.827411 56.967247 C 53.702411 56.966661 53.577997 56.84127 53.578387 56.71627 C 53.578778 56.59127 53.704364 56.466661 53.829364 56.467247" transform="matrix(20 0 0 20 -483.724 -810.384)" fill-rule="evenodd" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 29.356122 63.967833 L 29.382684 59.091075" transform="matrix(20 0 0 20 -483.724 -810.384)" fill="none" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 29.382684 59.091075 C 29.507684 59.091856 29.632098 59.217442 29.631317 59.342442 C 29.630731 59.467442 29.50495 59.591856 29.37995 59.591075 C 29.25495 59.590489 29.130731 59.464708 29.131317 59.339708 C 29.132098 59.214708 29.257684 59.090489 29.382684 59.091075" transform="matrix(20 0 0 20 -483.724 -810.384)" fill-rule="evenodd" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/></svg>
diff --git a/_images/form/form-custom-type-postal-address.svg b/_images/form/form-custom-type-postal-address.svg
new file mode 100644
index 00000000000..ab0fde8af3a
--- /dev/null
+++ b/_images/form/form-custom-type-postal-address.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="650" viewBox="0 0 707 478"><defs><symbol overflow="visible" id="a"><path d="M 1.28125 -13.859375 C 1.707031 -13.984375 2.160156 -14.0625 2.640625 -14.09375 C 3.117188 -14.132812 3.59375 -14.15625 4.0625 -14.15625 C 4.59375 -14.15625 5.117188 -14.09375 5.640625 -13.96875 C 6.160156 -13.851562 6.628906 -13.632812 7.046875 -13.3125 C 7.472656 -13 7.8125 -12.5625 8.0625 -12 C 8.320312 -11.4375 8.453125 -10.722656 8.453125 -9.859375 C 8.453125 -9.015625 8.328125 -8.300781 8.078125 -7.71875 C 7.835938 -7.132812 7.515625 -6.65625 7.109375 -6.28125 C 6.703125 -5.914062 6.234375 -5.648438 5.703125 -5.484375 C 5.179688 -5.316406 4.640625 -5.234375 4.078125 -5.234375 C 4.023438 -5.234375 3.9375 -5.234375 3.8125 -5.234375 C 3.695312 -5.234375 3.570312 -5.238281 3.4375 -5.25 C 3.300781 -5.257812 3.171875 -5.269531 3.046875 -5.28125 C 2.921875 -5.289062 2.832031 -5.300781 2.78125 -5.3125 L 2.78125 0 L 1.28125 0 Z M 4.140625 -12.78125 C 3.867188 -12.78125 3.609375 -12.769531 3.359375 -12.75 C 3.117188 -12.726562 2.925781 -12.695312 2.78125 -12.65625 L 2.78125 -6.703125 C 2.832031 -6.671875 2.914062 -6.648438 3.03125 -6.640625 C 3.144531 -6.640625 3.257812 -6.632812 3.375 -6.625 C 3.5 -6.625 3.617188 -6.625 3.734375 -6.625 C 3.847656 -6.625 3.929688 -6.625 3.984375 -6.625 C 4.359375 -6.625 4.71875 -6.671875 5.0625 -6.765625 C 5.40625 -6.859375 5.707031 -7.023438 5.96875 -7.265625 C 6.238281 -7.515625 6.457031 -7.847656 6.625 -8.265625 C 6.789062 -8.691406 6.875 -9.222656 6.875 -9.859375 C 6.875 -10.421875 6.796875 -10.882812 6.640625 -11.25 C 6.492188 -11.625 6.296875 -11.925781 6.046875 -12.15625 C 5.804688 -12.382812 5.519531 -12.546875 5.1875 -12.640625 C 4.851562 -12.734375 4.503906 -12.78125 4.140625 -12.78125 Z M 4.140625 -12.78125"/></symbol><symbol overflow="visible" id="b"><path d="M 0.734375 -5 C 0.734375 -6.800781 1.039062 -8.125 1.65625 -8.96875 C 2.28125 -9.8125 3.164062 -10.234375 4.3125 -10.234375 C 5.539062 -10.234375 6.445312 -9.800781 7.03125 -8.9375 C 7.613281 -8.070312 7.90625 -6.757812 7.90625 -5 C 7.90625 -3.1875 7.585938 -1.859375 6.953125 -1.015625 C 6.328125 -0.179688 5.445312 0.234375 4.3125 0.234375 C 3.09375 0.234375 2.191406 -0.195312 1.609375 -1.0625 C 1.023438 -1.925781 0.734375 -3.238281 0.734375 -5 Z M 2.234375 -5 C 2.234375 -4.414062 2.269531 -3.882812 2.34375 -3.40625 C 2.414062 -2.925781 2.535156 -2.507812 2.703125 -2.15625 C 2.867188 -1.8125 3.085938 -1.539062 3.359375 -1.34375 C 3.628906 -1.15625 3.945312 -1.0625 4.3125 -1.0625 C 5.007812 -1.0625 5.53125 -1.367188 5.875 -1.984375 C 6.226562 -2.609375 6.40625 -3.613281 6.40625 -5 C 6.40625 -5.570312 6.367188 -6.097656 6.296875 -6.578125 C 6.222656 -7.066406 6.101562 -7.484375 5.9375 -7.828125 C 5.769531 -8.179688 5.550781 -8.453125 5.28125 -8.640625 C 5.007812 -8.835938 4.6875 -8.9375 4.3125 -8.9375 C 3.632812 -8.9375 3.117188 -8.625 2.765625 -8 C 2.410156 -7.375 2.234375 -6.375 2.234375 -5 Z M 2.234375 -5"/></symbol><symbol overflow="visible" id="c"><path d="M 1.015625 -1.640625 C 1.285156 -1.484375 1.601562 -1.347656 1.96875 -1.234375 C 2.332031 -1.117188 2.707031 -1.0625 3.09375 -1.0625 C 3.539062 -1.0625 3.914062 -1.171875 4.21875 -1.390625 C 4.53125 -1.609375 4.6875 -1.960938 4.6875 -2.453125 C 4.6875 -2.867188 4.59375 -3.207031 4.40625 -3.46875 C 4.21875 -3.738281 3.976562 -3.976562 3.6875 -4.1875 C 3.40625 -4.40625 3.097656 -4.601562 2.765625 -4.78125 C 2.429688 -4.96875 2.117188 -5.1875 1.828125 -5.4375 C 1.546875 -5.6875 1.3125 -5.984375 1.125 -6.328125 C 0.9375 -6.679688 0.84375 -7.125 0.84375 -7.65625 C 0.84375 -8.507812 1.070312 -9.148438 1.53125 -9.578125 C 1.988281 -10.015625 2.640625 -10.234375 3.484375 -10.234375 C 4.023438 -10.234375 4.492188 -10.179688 4.890625 -10.078125 C 5.296875 -9.984375 5.644531 -9.851562 5.9375 -9.6875 L 5.5625 -8.484375 C 5.3125 -8.617188 5.019531 -8.726562 4.6875 -8.8125 C 4.351562 -8.894531 4.007812 -8.9375 3.65625 -8.9375 C 3.175781 -8.9375 2.828125 -8.835938 2.609375 -8.640625 C 2.390625 -8.441406 2.28125 -8.128906 2.28125 -7.703125 C 2.28125 -7.367188 2.375 -7.082031 2.5625 -6.84375 C 2.75 -6.613281 2.984375 -6.398438 3.265625 -6.203125 C 3.554688 -6.015625 3.867188 -5.816406 4.203125 -5.609375 C 4.535156 -5.410156 4.84375 -5.175781 5.125 -4.90625 C 5.414062 -4.632812 5.65625 -4.304688 5.84375 -3.921875 C 6.03125 -3.546875 6.125 -3.070312 6.125 -2.5 C 6.125 -2.125 6.0625 -1.769531 5.9375 -1.4375 C 5.820312 -1.101562 5.640625 -0.8125 5.390625 -0.5625 C 5.140625 -0.320312 4.832031 -0.128906 4.46875 0.015625 C 4.101562 0.160156 3.675781 0.234375 3.1875 0.234375 C 2.59375 0.234375 2.082031 0.175781 1.65625 0.0625 C 1.226562 -0.0390625 0.867188 -0.1875 0.578125 -0.375 Z M 1.015625 -1.640625"/></symbol><symbol overflow="visible" id="d"><path d="M 0.1875 -10 L 1.40625 -10 L 1.40625 -11.984375 L 2.84375 -12.4375 L 2.84375 -10 L 5 -10 L 5 -8.703125 L 2.84375 -8.703125 L 2.84375 -2.734375 C 2.84375 -2.148438 2.910156 -1.726562 3.046875 -1.46875 C 3.191406 -1.207031 3.421875 -1.078125 3.734375 -1.078125 C 4.003906 -1.078125 4.234375 -1.109375 4.421875 -1.171875 C 4.617188 -1.234375 4.832031 -1.3125 5.0625 -1.40625 L 5.34375 -0.265625 C 5.050781 -0.117188 4.726562 -0.00390625 4.375 0.078125 C 4.019531 0.171875 3.648438 0.21875 3.265625 0.21875 C 2.597656 0.21875 2.117188 0.00390625 1.828125 -0.421875 C 1.546875 -0.859375 1.40625 -1.566406 1.40625 -2.546875 L 1.40625 -8.703125 L 0.1875 -8.703125 Z M 0.1875 -10"/></symbol><symbol overflow="visible" id="e"><path d="M 1.078125 -9.40625 C 1.460938 -9.644531 1.929688 -9.828125 2.484375 -9.953125 C 3.035156 -10.085938 3.617188 -10.15625 4.234375 -10.15625 C 4.796875 -10.15625 5.242188 -10.070312 5.578125 -9.90625 C 5.921875 -9.738281 6.191406 -9.507812 6.390625 -9.21875 C 6.585938 -8.9375 6.710938 -8.613281 6.765625 -8.25 C 6.828125 -7.882812 6.859375 -7.5 6.859375 -7.09375 C 6.859375 -6.300781 6.84375 -5.523438 6.8125 -4.765625 C 6.78125 -4.003906 6.765625 -3.28125 6.765625 -2.59375 C 6.765625 -2.09375 6.78125 -1.625 6.8125 -1.1875 C 6.84375 -0.757812 6.90625 -0.347656 7 0.046875 L 5.90625 0.046875 L 5.5625 -1.140625 L 5.484375 -1.140625 C 5.285156 -0.796875 4.988281 -0.492188 4.59375 -0.234375 C 4.207031 0.015625 3.691406 0.140625 3.046875 0.140625 C 2.316406 0.140625 1.722656 -0.109375 1.265625 -0.609375 C 0.804688 -1.109375 0.578125 -1.800781 0.578125 -2.6875 C 0.578125 -3.257812 0.671875 -3.738281 0.859375 -4.125 C 1.054688 -4.507812 1.332031 -4.820312 1.6875 -5.0625 C 2.039062 -5.300781 2.460938 -5.46875 2.953125 -5.5625 C 3.441406 -5.664062 3.984375 -5.71875 4.578125 -5.71875 C 4.710938 -5.71875 4.847656 -5.71875 4.984375 -5.71875 C 5.117188 -5.71875 5.257812 -5.710938 5.40625 -5.703125 C 5.4375 -6.109375 5.453125 -6.472656 5.453125 -6.796875 C 5.453125 -7.554688 5.335938 -8.085938 5.109375 -8.390625 C 4.890625 -8.703125 4.476562 -8.859375 3.875 -8.859375 C 3.5 -8.859375 3.09375 -8.800781 2.65625 -8.6875 C 2.21875 -8.570312 1.851562 -8.429688 1.5625 -8.265625 Z M 5.421875 -4.5625 C 5.285156 -4.570312 5.148438 -4.578125 5.015625 -4.578125 C 4.878906 -4.585938 4.75 -4.59375 4.625 -4.59375 C 4.300781 -4.59375 3.984375 -4.566406 3.671875 -4.515625 C 3.367188 -4.460938 3.097656 -4.367188 2.859375 -4.234375 C 2.617188 -4.109375 2.425781 -3.929688 2.28125 -3.703125 C 2.144531 -3.472656 2.078125 -3.1875 2.078125 -2.84375 C 2.078125 -2.3125 2.207031 -1.894531 2.46875 -1.59375 C 2.726562 -1.300781 3.066406 -1.15625 3.484375 -1.15625 C 4.035156 -1.15625 4.460938 -1.285156 4.765625 -1.546875 C 5.078125 -1.816406 5.296875 -2.113281 5.421875 -2.4375 Z M 5.421875 -4.5625"/></symbol><symbol overflow="visible" id="f"><path d="M 2.71875 -2.375 C 2.71875 -1.914062 2.78125 -1.582031 2.90625 -1.375 C 3.03125 -1.175781 3.207031 -1.078125 3.4375 -1.078125 C 3.71875 -1.078125 4.046875 -1.148438 4.421875 -1.296875 L 4.5625 -0.140625 C 4.382812 -0.0351562 4.140625 0.046875 3.828125 0.109375 C 3.515625 0.179688 3.234375 0.21875 2.984375 0.21875 C 2.472656 0.21875 2.0625 0.0625 1.75 -0.25 C 1.4375 -0.5625 1.28125 -1.113281 1.28125 -1.90625 L 1.28125 -14 L 2.71875 -14 Z M 2.71875 -2.375"/></symbol><symbol overflow="visible" id="g"><path d="M 6.65625 -3.921875 L 2.703125 -3.921875 L 1.578125 0 L 0.09375 0 L 4.3125 -14.21875 L 5.140625 -14.21875 L 9.359375 0 L 7.796875 0 Z M 3.09375 -5.265625 L 6.296875 -5.265625 L 5.078125 -9.578125 L 4.703125 -11.6875 L 4.65625 -11.6875 L 4.28125 -9.546875 Z M 3.09375 -5.265625"/></symbol><symbol overflow="visible" id="h"><path d="M 7.484375 -3.4375 C 7.484375 -2.757812 7.488281 -2.144531 7.5 -1.59375 C 7.507812 -1.039062 7.554688 -0.492188 7.640625 0.046875 L 6.65625 0.046875 L 6.34375 -1.15625 L 6.265625 -1.15625 C 6.078125 -0.757812 5.78125 -0.425781 5.375 -0.15625 C 4.976562 0.101562 4.5 0.234375 3.9375 0.234375 C 2.851562 0.234375 2.046875 -0.179688 1.515625 -1.015625 C 0.992188 -1.859375 0.734375 -3.179688 0.734375 -4.984375 C 0.734375 -6.691406 1.054688 -7.984375 1.703125 -8.859375 C 2.359375 -9.742188 3.25 -10.1875 4.375 -10.1875 C 4.757812 -10.1875 5.066406 -10.160156 5.296875 -10.109375 C 5.523438 -10.066406 5.773438 -9.988281 6.046875 -9.875 L 6.046875 -14 L 7.484375 -14 Z M 6.046875 -8.421875 C 5.859375 -8.578125 5.644531 -8.691406 5.40625 -8.765625 C 5.175781 -8.835938 4.867188 -8.875 4.484375 -8.875 C 3.773438 -8.875 3.222656 -8.550781 2.828125 -7.90625 C 2.429688 -7.269531 2.234375 -6.285156 2.234375 -4.953125 C 2.234375 -4.367188 2.269531 -3.835938 2.34375 -3.359375 C 2.414062 -2.890625 2.53125 -2.484375 2.6875 -2.140625 C 2.84375 -1.796875 3.039062 -1.53125 3.28125 -1.34375 C 3.53125 -1.15625 3.835938 -1.0625 4.203125 -1.0625 C 5.160156 -1.0625 5.773438 -1.628906 6.046875 -2.765625 Z M 6.046875 -8.421875"/></symbol><symbol overflow="visible" id="i"><path d="M 1.1875 -10 L 2.203125 -10 L 2.453125 -8.9375 L 2.515625 -8.9375 C 2.703125 -9.320312 2.945312 -9.625 3.25 -9.84375 C 3.550781 -10.070312 3.914062 -10.1875 4.34375 -10.1875 C 4.644531 -10.1875 4.988281 -10.125 5.375 -10 L 5.09375 -8.546875 C 4.75 -8.660156 4.445312 -8.71875 4.1875 -8.71875 C 3.757812 -8.71875 3.410156 -8.59375 3.140625 -8.34375 C 2.867188 -8.101562 2.695312 -7.773438 2.625 -7.359375 L 2.625 0 L 1.1875 0 Z M 1.1875 -10"/></symbol><symbol overflow="visible" id="j"><path d="M 7.15625 -0.6875 C 6.84375 -0.382812 6.4375 -0.15625 5.9375 0 C 5.445312 0.15625 4.925781 0.234375 4.375 0.234375 C 3.75 0.234375 3.207031 0.113281 2.75 -0.125 C 2.289062 -0.375 1.910156 -0.726562 1.609375 -1.1875 C 1.304688 -1.644531 1.082031 -2.191406 0.9375 -2.828125 C 0.800781 -3.472656 0.734375 -4.195312 0.734375 -5 C 0.734375 -6.707031 1.046875 -8.003906 1.671875 -8.890625 C 2.304688 -9.785156 3.195312 -10.234375 4.34375 -10.234375 C 4.71875 -10.234375 5.085938 -10.1875 5.453125 -10.09375 C 5.816406 -10 6.144531 -9.8125 6.4375 -9.53125 C 6.726562 -9.257812 6.960938 -8.867188 7.140625 -8.359375 C 7.328125 -7.847656 7.421875 -7.1875 7.421875 -6.375 C 7.421875 -6.15625 7.410156 -5.914062 7.390625 -5.65625 C 7.367188 -5.394531 7.34375 -5.125 7.3125 -4.84375 L 2.234375 -4.84375 C 2.234375 -4.269531 2.28125 -3.75 2.375 -3.28125 C 2.46875 -2.8125 2.613281 -2.410156 2.8125 -2.078125 C 3.019531 -1.753906 3.28125 -1.503906 3.59375 -1.328125 C 3.90625 -1.148438 4.296875 -1.0625 4.765625 -1.0625 C 5.117188 -1.0625 5.472656 -1.125 5.828125 -1.25 C 6.179688 -1.382812 6.453125 -1.546875 6.640625 -1.734375 Z M 6.046875 -6.046875 C 6.066406 -7.046875 5.921875 -7.773438 5.609375 -8.234375 C 5.304688 -8.703125 4.890625 -8.9375 4.359375 -8.9375 C 3.742188 -8.9375 3.253906 -8.703125 2.890625 -8.234375 C 2.535156 -7.773438 2.328125 -7.046875 2.265625 -6.046875 Z M 6.046875 -6.046875"/></symbol><symbol overflow="visible" id="k"><path d="M 8.65625 -12.625 L 5.21875 -12.625 L 5.21875 0 L 3.71875 0 L 3.71875 -12.625 L 0.28125 -12.625 L 0.28125 -14 L 8.65625 -14 Z M 8.65625 -12.625"/></symbol><symbol overflow="visible" id="l"><path d="M 3.65625 -3.546875 L 4.078125 -1.59375 L 4.1875 -1.59375 L 4.484375 -3.546875 L 6 -10 L 7.453125 -10 L 5.078125 -1.015625 C 4.890625 -0.296875 4.703125 0.375 4.515625 1 C 4.328125 1.625 4.125 2.164062 3.90625 2.625 C 3.6875 3.082031 3.441406 3.441406 3.171875 3.703125 C 2.898438 3.960938 2.578125 4.09375 2.203125 4.09375 C 1.828125 4.09375 1.5 4.035156 1.21875 3.921875 L 1.453125 2.5625 C 1.640625 2.625 1.828125 2.632812 2.015625 2.59375 C 2.203125 2.5625 2.378906 2.453125 2.546875 2.265625 C 2.710938 2.078125 2.863281 1.796875 3 1.421875 C 3.144531 1.054688 3.269531 0.582031 3.375 0 L 0.140625 -10 L 1.78125 -10 Z M 3.65625 -3.546875"/></symbol><symbol overflow="visible" id="m"><path d="M 1.1875 -10 L 2.203125 -10 L 2.421875 -8.921875 L 2.5 -8.921875 C 2.988281 -9.796875 3.757812 -10.234375 4.8125 -10.234375 C 5.875 -10.234375 6.664062 -9.835938 7.1875 -9.046875 C 7.71875 -8.265625 7.984375 -6.984375 7.984375 -5.203125 C 7.984375 -4.359375 7.894531 -3.597656 7.71875 -2.921875 C 7.539062 -2.253906 7.289062 -1.679688 6.96875 -1.203125 C 6.65625 -0.734375 6.269531 -0.375 5.8125 -0.125 C 5.351562 0.113281 4.84375 0.234375 4.28125 0.234375 C 3.894531 0.234375 3.585938 0.207031 3.359375 0.15625 C 3.128906 0.113281 2.882812 0.0195312 2.625 -0.125 L 2.625 4 L 1.1875 4 Z M 2.625 -1.578125 C 2.8125 -1.421875 3.019531 -1.296875 3.25 -1.203125 C 3.476562 -1.109375 3.789062 -1.0625 4.1875 -1.0625 C 4.882812 -1.0625 5.441406 -1.421875 5.859375 -2.140625 C 6.273438 -2.859375 6.484375 -3.882812 6.484375 -5.21875 C 6.484375 -5.78125 6.445312 -6.285156 6.375 -6.734375 C 6.300781 -7.191406 6.179688 -7.582031 6.015625 -7.90625 C 5.859375 -8.238281 5.65625 -8.492188 5.40625 -8.671875 C 5.164062 -8.847656 4.863281 -8.9375 4.5 -8.9375 C 3.53125 -8.9375 2.90625 -8.34375 2.625 -7.15625 Z M 2.625 -1.578125"/></symbol><symbol overflow="visible" id="n"><path d="M 6.5625 -3.15625 L 3.265625 -3.15625 L 2.4375 0 L -0.0625 0 L 4 -14.09375 L 5.984375 -14.09375 L 10.0625 0 L 7.421875 0 Z M 3.796875 -5.234375 L 6.125 -5.234375 L 5.3125 -8.5 L 5 -10.703125 L 4.921875 -10.703125 L 4.578125 -8.484375 Z M 3.796875 -5.234375"/></symbol><symbol overflow="visible" id="o"><path d="M 8.046875 -3.515625 C 8.046875 -2.960938 8.050781 -2.40625 8.0625 -1.84375 C 8.070312 -1.28125 8.125 -0.660156 8.21875 0.015625 L 6.546875 0.015625 L 6.21875 -1.140625 L 6.140625 -1.140625 C 5.679688 -0.203125 4.890625 0.265625 3.765625 0.265625 C 2.742188 0.265625 1.941406 -0.132812 1.359375 -0.9375 C 0.785156 -1.738281 0.5 -3.039062 0.5 -4.84375 C 0.5 -6.601562 0.8125 -7.9375 1.4375 -8.84375 C 2.0625 -9.757812 2.992188 -10.21875 4.234375 -10.21875 C 4.554688 -10.21875 4.820312 -10.195312 5.03125 -10.15625 C 5.25 -10.113281 5.457031 -10.046875 5.65625 -9.953125 L 5.65625 -14 L 8.046875 -14 Z M 4.3125 -1.921875 C 4.675781 -1.921875 4.960938 -2.007812 5.171875 -2.1875 C 5.390625 -2.363281 5.550781 -2.628906 5.65625 -2.984375 L 5.65625 -7.703125 C 5.519531 -7.816406 5.367188 -7.898438 5.203125 -7.953125 C 5.035156 -8.015625 4.820312 -8.046875 4.5625 -8.046875 C 4.03125 -8.046875 3.628906 -7.800781 3.359375 -7.3125 C 3.085938 -6.832031 2.953125 -5.984375 2.953125 -4.765625 C 2.953125 -3.835938 3.0625 -3.128906 3.28125 -2.640625 C 3.507812 -2.160156 3.851562 -1.921875 4.3125 -1.921875 Z M 4.3125 -1.921875"/></symbol><symbol overflow="visible" id="p"><path d="M 5.578125 -7.640625 C 5.253906 -7.753906 4.960938 -7.8125 4.703125 -7.8125 C 4.335938 -7.8125 4.023438 -7.710938 3.765625 -7.515625 C 3.503906 -7.316406 3.328125 -7.039062 3.234375 -6.6875 L 3.234375 0 L 0.859375 0 L 0.859375 -10 L 2.6875 -10 L 2.953125 -8.796875 L 3.046875 -8.796875 C 3.210938 -9.234375 3.457031 -9.578125 3.78125 -9.828125 C 4.113281 -10.078125 4.492188 -10.203125 4.921875 -10.203125 C 5.242188 -10.203125 5.554688 -10.132812 5.859375 -10 Z M 5.578125 -7.640625"/></symbol><symbol overflow="visible" id="q"><path d="M 7.625 -0.734375 C 7.289062 -0.441406 6.835938 -0.203125 6.265625 -0.015625 C 5.691406 0.171875 5.085938 0.265625 4.453125 0.265625 C 3.765625 0.265625 3.171875 0.144531 2.671875 -0.09375 C 2.171875 -0.332031 1.757812 -0.675781 1.4375 -1.125 C 1.113281 -1.582031 0.875 -2.132812 0.71875 -2.78125 C 0.570312 -3.4375 0.5 -4.175781 0.5 -5 C 0.5 -6.800781 0.851562 -8.128906 1.5625 -8.984375 C 2.28125 -9.847656 3.273438 -10.28125 4.546875 -10.28125 C 4.972656 -10.28125 5.382812 -10.21875 5.78125 -10.09375 C 6.175781 -9.96875 6.53125 -9.753906 6.84375 -9.453125 C 7.15625 -9.148438 7.410156 -8.75 7.609375 -8.25 C 7.804688 -7.75 7.90625 -7.117188 7.90625 -6.359375 C 7.90625 -6.066406 7.882812 -5.753906 7.84375 -5.421875 C 7.8125 -5.085938 7.765625 -4.726562 7.703125 -4.34375 L 2.84375 -4.34375 C 2.863281 -3.507812 3.035156 -2.875 3.359375 -2.4375 C 3.679688 -2 4.195312 -1.78125 4.90625 -1.78125 C 5.332031 -1.78125 5.71875 -1.847656 6.0625 -1.984375 C 6.414062 -2.117188 6.6875 -2.257812 6.875 -2.40625 Z M 4.5 -8.234375 C 3.988281 -8.234375 3.609375 -8.03125 3.359375 -7.625 C 3.109375 -7.21875 2.960938 -6.648438 2.921875 -5.921875 L 5.6875 -5.921875 C 5.71875 -6.679688 5.632812 -7.253906 5.4375 -7.640625 C 5.238281 -8.035156 4.925781 -8.234375 4.5 -8.234375 Z M 4.5 -8.234375"/></symbol><symbol overflow="visible" id="r"><path d="M 4.21875 -2.65625 C 4.21875 -2.9375 4.128906 -3.171875 3.953125 -3.359375 C 3.773438 -3.554688 3.546875 -3.738281 3.265625 -3.90625 C 2.984375 -4.070312 2.6875 -4.242188 2.375 -4.421875 C 2.0625 -4.597656 1.765625 -4.8125 1.484375 -5.0625 C 1.203125 -5.3125 0.96875 -5.613281 0.78125 -5.96875 C 0.601562 -6.332031 0.515625 -6.789062 0.515625 -7.34375 C 0.515625 -8.269531 0.769531 -8.988281 1.28125 -9.5 C 1.789062 -10.007812 2.535156 -10.265625 3.515625 -10.265625 C 4.109375 -10.265625 4.660156 -10.195312 5.171875 -10.0625 C 5.691406 -9.9375 6.109375 -9.78125 6.421875 -9.59375 L 5.859375 -7.765625 C 5.609375 -7.867188 5.300781 -7.96875 4.9375 -8.0625 C 4.582031 -8.164062 4.226562 -8.21875 3.875 -8.21875 C 3.226562 -8.21875 2.90625 -7.945312 2.90625 -7.40625 C 2.90625 -7.144531 2.992188 -6.929688 3.171875 -6.765625 C 3.347656 -6.597656 3.578125 -6.4375 3.859375 -6.28125 C 4.140625 -6.125 4.4375 -5.957031 4.75 -5.78125 C 5.0625 -5.601562 5.359375 -5.382812 5.640625 -5.125 C 5.921875 -4.863281 6.148438 -4.546875 6.328125 -4.171875 C 6.503906 -3.804688 6.59375 -3.347656 6.59375 -2.796875 C 6.59375 -1.878906 6.3125 -1.140625 5.75 -0.578125 C 5.195312 -0.015625 4.367188 0.265625 3.265625 0.265625 C 2.710938 0.265625 2.171875 0.195312 1.640625 0.0625 C 1.117188 -0.0703125 0.695312 -0.242188 0.375 -0.453125 L 1.046875 -2.375 C 1.316406 -2.21875 1.632812 -2.078125 2 -1.953125 C 2.375 -1.835938 2.757812 -1.78125 3.15625 -1.78125 C 3.46875 -1.78125 3.722656 -1.847656 3.921875 -1.984375 C 4.117188 -2.128906 4.21875 -2.351562 4.21875 -2.65625 Z M 4.21875 -2.65625"/></symbol><symbol overflow="visible" id="t"><path d="M 3.28125 -3.234375 C 3.28125 -2.773438 3.328125 -2.441406 3.421875 -2.234375 C 3.515625 -2.035156 3.664062 -1.9375 3.875 -1.9375 C 4 -1.9375 4.125 -1.945312 4.25 -1.96875 C 4.375 -2 4.519531 -2.050781 4.6875 -2.125 L 4.90625 -0.203125 C 4.738281 -0.0976562 4.460938 0 4.078125 0.09375 C 3.691406 0.1875 3.300781 0.234375 2.90625 0.234375 C 2.238281 0.234375 1.738281 0.0664062 1.40625 -0.265625 C 1.070312 -0.597656 0.90625 -1.160156 0.90625 -1.953125 L 0.90625 -14 L 3.28125 -14 Z M 3.28125 -3.234375"/></symbol><symbol overflow="visible" id="u"><path d="M 1.0625 -10 L 3.4375 -10 L 3.4375 0 L 1.0625 0 Z M 1.203125 -12.8125 C 1.203125 -13.21875 1.328125 -13.550781 1.578125 -13.8125 C 1.828125 -14.070312 2.1875 -14.203125 2.65625 -14.203125 C 3.125 -14.203125 3.5 -14.070312 3.78125 -13.8125 C 4.0625 -13.5625 4.203125 -13.226562 4.203125 -12.8125 C 4.203125 -12.40625 4.0625 -12.082031 3.78125 -11.84375 C 3.5 -11.601562 3.125 -11.484375 2.65625 -11.484375 C 2.1875 -11.484375 1.828125 -11.601562 1.578125 -11.84375 C 1.328125 -12.09375 1.203125 -12.414062 1.203125 -12.8125 Z M 1.203125 -12.8125"/></symbol><symbol overflow="visible" id="v"><path d="M 5.8125 0 L 5.8125 -6.078125 C 5.8125 -6.816406 5.722656 -7.332031 5.546875 -7.625 C 5.378906 -7.914062 5.09375 -8.0625 4.6875 -8.0625 C 4.332031 -8.0625 4.03125 -7.953125 3.78125 -7.734375 C 3.53125 -7.523438 3.347656 -7.257812 3.234375 -6.9375 L 3.234375 0 L 0.859375 0 L 0.859375 -10 L 2.765625 -10 L 3.046875 -8.84375 L 3.09375 -8.84375 C 3.332031 -9.226562 3.660156 -9.554688 4.078125 -9.828125 C 4.492188 -10.097656 5.035156 -10.234375 5.703125 -10.234375 C 6.097656 -10.234375 6.453125 -10.171875 6.765625 -10.046875 C 7.078125 -9.929688 7.335938 -9.738281 7.546875 -9.46875 C 7.765625 -9.195312 7.925781 -8.832031 8.03125 -8.375 C 8.144531 -7.914062 8.203125 -7.34375 8.203125 -6.65625 L 8.203125 0 Z M 5.8125 0"/></symbol><symbol overflow="visible" id="w"><path d="M 1.734375 -2.125 L 4.015625 -2.125 L 4.015625 -9.984375 L 4.28125 -11.34375 L 3.453125 -10.15625 L 2.140625 -9.140625 L 1.046875 -10.484375 L 4.90625 -14.234375 L 6.296875 -14.234375 L 6.296875 -2.125 L 8.546875 -2.125 L 8.546875 0 L 1.734375 0 Z M 1.734375 -2.125"/></symbol><symbol overflow="visible" id="R"><path d="M 8.046875 -10.640625 C 8.046875 -9.941406 7.941406 -9.226562 7.734375 -8.5 C 7.535156 -7.78125 7.28125 -7.070312 6.96875 -6.375 C 6.65625 -5.6875 6.3125 -5.023438 5.9375 -4.390625 C 5.5625 -3.765625 5.195312 -3.210938 4.84375 -2.734375 L 3.953125 -1.921875 L 3.953125 -1.8125 L 5.15625 -2.125 L 8.265625 -2.125 L 8.265625 0 L 1.234375 0 L 1.234375 -1.375 C 1.515625 -1.726562 1.816406 -2.125 2.140625 -2.5625 C 2.472656 -3.007812 2.800781 -3.484375 3.125 -3.984375 C 3.457031 -4.484375 3.773438 -5.003906 4.078125 -5.546875 C 4.390625 -6.085938 4.660156 -6.628906 4.890625 -7.171875 C 5.117188 -7.710938 5.300781 -8.242188 5.4375 -8.765625 C 5.582031 -9.285156 5.644531 -9.769531 5.625 -10.21875 C 5.644531 -10.78125 5.519531 -11.234375 5.25 -11.578125 C 4.988281 -11.921875 4.570312 -12.09375 4 -12.09375 C 3.664062 -12.09375 3.320312 -12.015625 2.96875 -11.859375 C 2.625 -11.710938 2.332031 -11.53125 2.09375 -11.3125 L 1.1875 -13.0625 C 1.625 -13.4375 2.117188 -13.734375 2.671875 -13.953125 C 3.234375 -14.171875 3.894531 -14.28125 4.65625 -14.28125 C 5.132812 -14.28125 5.582031 -14.203125 6 -14.046875 C 6.414062 -13.890625 6.769531 -13.660156 7.0625 -13.359375 C 7.363281 -13.054688 7.601562 -12.675781 7.78125 -12.21875 C 7.957031 -11.769531 8.046875 -11.242188 8.046875 -10.640625 Z M 8.046875 -10.640625"/></symbol><symbol overflow="visible" id="Y"><path d="M 8.84375 -0.5625 C 8.488281 -0.269531 8.019531 -0.0546875 7.4375 0.078125 C 6.863281 0.210938 6.289062 0.28125 5.71875 0.28125 C 5 0.28125 4.328125 0.160156 3.703125 -0.078125 C 3.085938 -0.328125 2.546875 -0.738281 2.078125 -1.3125 C 1.609375 -1.894531 1.238281 -2.648438 0.96875 -3.578125 C 0.707031 -4.515625 0.578125 -5.660156 0.578125 -7.015625 C 0.578125 -8.429688 0.726562 -9.601562 1.03125 -10.53125 C 1.332031 -11.46875 1.722656 -12.210938 2.203125 -12.765625 C 2.691406 -13.316406 3.25 -13.707031 3.875 -13.9375 C 4.5 -14.164062 5.132812 -14.28125 5.78125 -14.28125 C 6.4375 -14.28125 7.003906 -14.222656 7.484375 -14.109375 C 7.972656 -14.003906 8.375 -13.890625 8.6875 -13.765625 L 8.1875 -11.546875 C 7.925781 -11.671875 7.625 -11.769531 7.28125 -11.84375 C 6.945312 -11.914062 6.546875 -11.953125 6.078125 -11.953125 C 5.160156 -11.953125 4.453125 -11.550781 3.953125 -10.75 C 3.460938 -9.957031 3.21875 -8.707031 3.21875 -7 C 3.21875 -6.269531 3.273438 -5.597656 3.390625 -4.984375 C 3.503906 -4.378906 3.679688 -3.859375 3.921875 -3.421875 C 4.171875 -2.984375 4.484375 -2.644531 4.859375 -2.40625 C 5.242188 -2.164062 5.703125 -2.046875 6.234375 -2.046875 C 6.703125 -2.046875 7.101562 -2.109375 7.4375 -2.234375 C 7.769531 -2.359375 8.070312 -2.507812 8.34375 -2.6875 Z M 8.84375 -0.5625"/></symbol><symbol overflow="visible" id="Z"><path d="M 0.078125 -10 L 1.1875 -10 L 1.1875 -11.875 L 3.5625 -12.625 L 3.5625 -10 L 5.5 -10 L 5.5 -7.875 L 3.5625 -7.875 L 3.5625 -3.515625 C 3.5625 -2.941406 3.617188 -2.535156 3.734375 -2.296875 C 3.847656 -2.054688 4.050781 -1.9375 4.34375 -1.9375 C 4.539062 -1.9375 4.71875 -1.957031 4.875 -2 C 5.039062 -2.039062 5.21875 -2.101562 5.40625 -2.1875 L 5.703125 -0.28125 C 5.410156 -0.132812 5.066406 -0.015625 4.671875 0.078125 C 4.285156 0.179688 3.878906 0.234375 3.453125 0.234375 C 2.691406 0.234375 2.125 0.015625 1.75 -0.421875 C 1.375 -0.859375 1.1875 -1.597656 1.1875 -2.640625 L 1.1875 -7.875 L 0.078125 -7.875 Z M 0.078125 -10"/></symbol><symbol overflow="visible" id="aa"><path d="M 4.0625 -4.375 L 4.3125 -2.8125 L 4.421875 -2.8125 L 4.59375 -4.40625 L 5.765625 -10 L 8.203125 -10 L 5.703125 -0.984375 C 5.472656 -0.191406 5.257812 0.515625 5.0625 1.140625 C 4.863281 1.765625 4.648438 2.296875 4.421875 2.734375 C 4.191406 3.179688 3.929688 3.519531 3.640625 3.75 C 3.359375 3.976562 3.019531 4.09375 2.625 4.09375 C 2.34375 4.09375 2.070312 4.066406 1.8125 4.015625 C 1.550781 3.972656 1.328125 3.898438 1.140625 3.796875 L 1.546875 1.765625 C 1.710938 1.828125 1.882812 1.851562 2.0625 1.84375 C 2.25 1.84375 2.414062 1.773438 2.5625 1.640625 C 2.71875 1.515625 2.851562 1.316406 2.96875 1.046875 C 3.09375 0.785156 3.195312 0.4375 3.28125 0 L -0.203125 -10 L 2.65625 -10 Z M 4.0625 -4.375"/></symbol><symbol overflow="visible" id="ab"><path d="M 0.421875 -2.3125 L 5.09375 -10.859375 L 5.9375 -11.6875 L 0.421875 -11.6875 L 0.421875 -14 L 8.484375 -14 L 8.484375 -11.6875 L 3.78125 -3.078125 L 2.953125 -2.3125 L 8.484375 -2.3125 L 8.484375 0 L 0.421875 0 Z M 0.421875 -2.3125"/></symbol><symbol overflow="visible" id="ac"><path d="M 1.125 -14 L 3.640625 -14 L 3.640625 0 L 1.125 0 Z M 1.125 -14"/></symbol><symbol overflow="visible" id="ad"><path d="M 0.90625 -13.859375 C 1.382812 -13.960938 1.910156 -14.046875 2.484375 -14.109375 C 3.054688 -14.171875 3.628906 -14.203125 4.203125 -14.203125 C 4.816406 -14.203125 5.421875 -14.144531 6.015625 -14.03125 C 6.609375 -13.914062 7.132812 -13.691406 7.59375 -13.359375 C 8.0625 -13.023438 8.441406 -12.554688 8.734375 -11.953125 C 9.035156 -11.347656 9.1875 -10.554688 9.1875 -9.578125 C 9.1875 -8.703125 9.0625 -7.957031 8.8125 -7.34375 C 8.5625 -6.726562 8.226562 -6.226562 7.8125 -5.84375 C 7.40625 -5.457031 6.929688 -5.175781 6.390625 -5 C 5.847656 -4.820312 5.289062 -4.734375 4.71875 -4.734375 C 4.664062 -4.734375 4.578125 -4.734375 4.453125 -4.734375 C 4.335938 -4.734375 4.210938 -4.738281 4.078125 -4.75 C 3.941406 -4.757812 3.8125 -4.769531 3.6875 -4.78125 C 3.5625 -4.789062 3.472656 -4.800781 3.421875 -4.8125 L 3.421875 0 L 0.90625 0 Z M 3.421875 -7.078125 C 3.503906 -7.054688 3.65625 -7.035156 3.875 -7.015625 C 4.09375 -6.992188 4.238281 -6.984375 4.3125 -6.984375 C 4.613281 -6.984375 4.894531 -7.019531 5.15625 -7.09375 C 5.425781 -7.175781 5.664062 -7.3125 5.875 -7.5 C 6.082031 -7.695312 6.242188 -7.960938 6.359375 -8.296875 C 6.484375 -8.640625 6.546875 -9.070312 6.546875 -9.59375 C 6.546875 -10.039062 6.488281 -10.414062 6.375 -10.71875 C 6.257812 -11.03125 6.101562 -11.273438 5.90625 -11.453125 C 5.71875 -11.628906 5.492188 -11.753906 5.234375 -11.828125 C 4.984375 -11.910156 4.71875 -11.953125 4.4375 -11.953125 C 4.019531 -11.953125 3.679688 -11.921875 3.421875 -11.859375 Z M 3.421875 -7.078125"/></symbol><symbol overflow="visible" id="ae"><path d="M 0.5 -5 C 0.5 -6.769531 0.84375 -8.085938 1.53125 -8.953125 C 2.226562 -9.828125 3.195312 -10.265625 4.4375 -10.265625 C 5.769531 -10.265625 6.765625 -9.820312 7.421875 -8.9375 C 8.078125 -8.0625 8.40625 -6.75 8.40625 -5 C 8.40625 -3.207031 8.054688 -1.878906 7.359375 -1.015625 C 6.660156 -0.160156 5.6875 0.265625 4.4375 0.265625 C 1.8125 0.265625 0.5 -1.488281 0.5 -5 Z M 2.953125 -5 C 2.953125 -4 3.066406 -3.222656 3.296875 -2.671875 C 3.523438 -2.128906 3.90625 -1.859375 4.4375 -1.859375 C 4.945312 -1.859375 5.320312 -2.09375 5.5625 -2.5625 C 5.8125 -3.039062 5.9375 -3.851562 5.9375 -5 C 5.9375 -6.03125 5.820312 -6.8125 5.59375 -7.34375 C 5.375 -7.875 4.988281 -8.140625 4.4375 -8.140625 C 3.96875 -8.140625 3.601562 -7.898438 3.34375 -7.421875 C 3.082031 -6.953125 2.953125 -6.144531 2.953125 -5 Z M 2.953125 -5"/></symbol><symbol overflow="visible" id="af"><path d="M 5.796875 -3.59375 C 5.796875 -4.019531 5.671875 -4.382812 5.421875 -4.6875 C 5.171875 -4.988281 4.851562 -5.269531 4.46875 -5.53125 C 4.09375 -5.800781 3.679688 -6.078125 3.234375 -6.359375 C 2.785156 -6.640625 2.367188 -6.96875 1.984375 -7.34375 C 1.609375 -7.71875 1.289062 -8.15625 1.03125 -8.65625 C 0.78125 -9.164062 0.65625 -9.785156 0.65625 -10.515625 C 0.65625 -11.203125 0.757812 -11.78125 0.96875 -12.25 C 1.175781 -12.71875 1.457031 -13.101562 1.8125 -13.40625 C 2.175781 -13.707031 2.601562 -13.925781 3.09375 -14.0625 C 3.59375 -14.207031 4.125 -14.28125 4.6875 -14.28125 C 5.363281 -14.28125 5.992188 -14.210938 6.578125 -14.078125 C 7.160156 -13.941406 7.648438 -13.765625 8.046875 -13.546875 L 7.265625 -11.3125 C 7.035156 -11.476562 6.695312 -11.625 6.25 -11.75 C 5.800781 -11.882812 5.316406 -11.953125 4.796875 -11.953125 C 4.273438 -11.953125 3.875 -11.84375 3.59375 -11.625 C 3.320312 -11.414062 3.1875 -11.109375 3.1875 -10.703125 C 3.1875 -10.328125 3.3125 -9.992188 3.5625 -9.703125 C 3.8125 -9.421875 4.125 -9.144531 4.5 -8.875 C 4.882812 -8.613281 5.300781 -8.335938 5.75 -8.046875 C 6.195312 -7.765625 6.609375 -7.429688 6.984375 -7.046875 C 7.367188 -6.671875 7.6875 -6.222656 7.9375 -5.703125 C 8.1875 -5.191406 8.3125 -4.582031 8.3125 -3.875 C 8.3125 -3.164062 8.207031 -2.550781 8 -2.03125 C 7.800781 -1.519531 7.507812 -1.09375 7.125 -0.75 C 6.75 -0.40625 6.289062 -0.148438 5.75 0.015625 C 5.21875 0.191406 4.628906 0.28125 3.984375 0.28125 C 3.148438 0.28125 2.421875 0.195312 1.796875 0.03125 C 1.179688 -0.125 0.707031 -0.300781 0.375 -0.5 L 1.203125 -2.765625 C 1.460938 -2.597656 1.828125 -2.4375 2.296875 -2.28125 C 2.765625 -2.125 3.265625 -2.046875 3.796875 -2.046875 C 5.128906 -2.046875 5.796875 -2.5625 5.796875 -3.59375 Z M 5.796875 -3.59375"/></symbol><symbol overflow="visible" id="ag"><path d="M 0.875 -9.40625 C 1.28125 -9.644531 1.78125 -9.835938 2.375 -9.984375 C 2.976562 -10.128906 3.660156 -10.203125 4.421875 -10.203125 C 5.554688 -10.203125 6.34375 -9.90625 6.78125 -9.3125 C 7.226562 -8.726562 7.453125 -7.894531 7.453125 -6.8125 C 7.453125 -6.1875 7.4375 -5.570312 7.40625 -4.96875 C 7.375 -4.363281 7.347656 -3.769531 7.328125 -3.1875 C 7.316406 -2.601562 7.328125 -2.039062 7.359375 -1.5 C 7.398438 -0.96875 7.492188 -0.460938 7.640625 0.015625 L 5.703125 0.015625 L 5.3125 -1.203125 L 5.234375 -1.203125 C 5.023438 -0.816406 4.726562 -0.492188 4.34375 -0.234375 C 3.957031 0.015625 3.46875 0.140625 2.875 0.140625 C 2.09375 0.140625 1.472656 -0.117188 1.015625 -0.640625 C 0.566406 -1.171875 0.34375 -1.878906 0.34375 -2.765625 C 0.34375 -3.960938 0.769531 -4.8125 1.625 -5.3125 C 2.476562 -5.820312 3.628906 -6.035156 5.078125 -5.953125 C 5.148438 -6.734375 5.101562 -7.296875 4.9375 -7.640625 C 4.769531 -7.984375 4.410156 -8.15625 3.859375 -8.15625 C 3.460938 -8.15625 3.050781 -8.109375 2.625 -8.015625 C 2.195312 -7.921875 1.816406 -7.789062 1.484375 -7.625 Z M 3.734375 -1.90625 C 4.097656 -1.90625 4.390625 -1.992188 4.609375 -2.171875 C 4.835938 -2.347656 5.007812 -2.546875 5.125 -2.765625 L 5.125 -4.421875 C 4.8125 -4.460938 4.515625 -4.46875 4.234375 -4.4375 C 3.953125 -4.414062 3.707031 -4.359375 3.5 -4.265625 C 3.289062 -4.171875 3.117188 -4.03125 2.984375 -3.84375 C 2.859375 -3.664062 2.796875 -3.4375 2.796875 -3.15625 C 2.796875 -2.75 2.878906 -2.4375 3.046875 -2.21875 C 3.210938 -2.007812 3.441406 -1.90625 3.734375 -1.90625 Z M 3.734375 -1.90625"/></symbol><symbol overflow="visible" id="x"><path d="M 1.0625 -1.671875 C 1.289062 -1.515625 1.609375 -1.367188 2.015625 -1.234375 C 2.429688 -1.097656 2.90625 -1.03125 3.4375 -1.03125 C 4.113281 -1.03125 4.660156 -1.191406 5.078125 -1.515625 C 5.492188 -1.847656 5.703125 -2.367188 5.703125 -3.078125 C 5.703125 -3.546875 5.582031 -3.953125 5.34375 -4.296875 C 5.101562 -4.648438 4.800781 -4.972656 4.4375 -5.265625 C 4.082031 -5.554688 3.695312 -5.84375 3.28125 -6.125 C 2.863281 -6.40625 2.472656 -6.71875 2.109375 -7.0625 C 1.753906 -7.40625 1.457031 -7.796875 1.21875 -8.234375 C 0.976562 -8.679688 0.859375 -9.21875 0.859375 -9.84375 C 0.859375 -10.851562 1.160156 -11.597656 1.765625 -12.078125 C 2.378906 -12.566406 3.171875 -12.8125 4.140625 -12.8125 C 4.742188 -12.8125 5.273438 -12.753906 5.734375 -12.640625 C 6.203125 -12.535156 6.582031 -12.398438 6.875 -12.234375 L 6.4375 -11.046875 C 6.226562 -11.179688 5.921875 -11.300781 5.515625 -11.40625 C 5.109375 -11.519531 4.644531 -11.578125 4.125 -11.578125 C 3.476562 -11.578125 3 -11.414062 2.6875 -11.09375 C 2.375 -10.78125 2.21875 -10.382812 2.21875 -9.90625 C 2.21875 -9.476562 2.335938 -9.101562 2.578125 -8.78125 C 2.816406 -8.457031 3.113281 -8.148438 3.46875 -7.859375 C 3.832031 -7.578125 4.21875 -7.285156 4.625 -6.984375 C 5.039062 -6.691406 5.429688 -6.363281 5.796875 -6 C 6.160156 -5.644531 6.460938 -5.238281 6.703125 -4.78125 C 6.941406 -4.332031 7.0625 -3.796875 7.0625 -3.171875 C 7.0625 -2.109375 6.75 -1.273438 6.125 -0.671875 C 5.5 -0.078125 4.613281 0.21875 3.46875 0.21875 C 2.75 0.21875 2.160156 0.148438 1.703125 0.015625 C 1.242188 -0.117188 0.875 -0.269531 0.59375 -0.4375 Z M 1.0625 -1.671875"/></symbol><symbol overflow="visible" id="y"><path d="M 0.15625 -9 L 1.265625 -9 L 1.265625 -10.78125 L 2.5625 -11.203125 L 2.5625 -9 L 4.5 -9 L 4.5 -7.828125 L 2.5625 -7.828125 L 2.5625 -2.46875 C 2.5625 -1.9375 2.625 -1.550781 2.75 -1.3125 C 2.875 -1.082031 3.078125 -0.96875 3.359375 -0.96875 C 3.597656 -0.96875 3.804688 -0.992188 3.984375 -1.046875 C 4.160156 -1.109375 4.347656 -1.179688 4.546875 -1.265625 L 4.8125 -0.234375 C 4.539062 -0.0976562 4.242188 0.00390625 3.921875 0.078125 C 3.609375 0.160156 3.28125 0.203125 2.9375 0.203125 C 2.332031 0.203125 1.898438 0.0078125 1.640625 -0.375 C 1.390625 -0.769531 1.265625 -1.40625 1.265625 -2.28125 L 1.265625 -7.828125 L 0.15625 -7.828125 Z M 0.15625 -9"/></symbol><symbol overflow="visible" id="z"><path d="M 1.0625 -9 L 1.984375 -9 L 2.21875 -8.046875 L 2.265625 -8.046875 C 2.429688 -8.390625 2.648438 -8.660156 2.921875 -8.859375 C 3.191406 -9.054688 3.519531 -9.15625 3.90625 -9.15625 C 4.175781 -9.15625 4.488281 -9.101562 4.84375 -9 L 4.59375 -7.6875 C 4.28125 -7.789062 4.003906 -7.84375 3.765625 -7.84375 C 3.378906 -7.84375 3.066406 -7.734375 2.828125 -7.515625 C 2.585938 -7.296875 2.429688 -7 2.359375 -6.625 L 2.359375 0 L 1.0625 0 Z M 1.0625 -9"/></symbol><symbol overflow="visible" id="A"><path d="M 6.4375 -0.609375 C 6.15625 -0.347656 5.789062 -0.144531 5.34375 0 C 4.90625 0.144531 4.4375 0.21875 3.9375 0.21875 C 3.375 0.21875 2.882812 0.109375 2.46875 -0.109375 C 2.0625 -0.335938 1.722656 -0.65625 1.453125 -1.0625 C 1.179688 -1.476562 0.984375 -1.972656 0.859375 -2.546875 C 0.734375 -3.128906 0.671875 -3.78125 0.671875 -4.5 C 0.671875 -6.03125 0.953125 -7.195312 1.515625 -8 C 2.078125 -8.8125 2.875 -9.21875 3.90625 -9.21875 C 4.238281 -9.21875 4.570312 -9.175781 4.90625 -9.09375 C 5.238281 -9.007812 5.535156 -8.835938 5.796875 -8.578125 C 6.054688 -8.328125 6.265625 -7.972656 6.421875 -7.515625 C 6.585938 -7.066406 6.671875 -6.472656 6.671875 -5.734375 C 6.671875 -5.535156 6.660156 -5.316406 6.640625 -5.078125 C 6.628906 -4.847656 6.613281 -4.609375 6.59375 -4.359375 L 2.015625 -4.359375 C 2.015625 -3.835938 2.054688 -3.367188 2.140625 -2.953125 C 2.222656 -2.535156 2.351562 -2.175781 2.53125 -1.875 C 2.71875 -1.582031 2.953125 -1.351562 3.234375 -1.1875 C 3.515625 -1.03125 3.863281 -0.953125 4.28125 -0.953125 C 4.601562 -0.953125 4.921875 -1.007812 5.234375 -1.125 C 5.554688 -1.25 5.800781 -1.394531 5.96875 -1.5625 Z M 5.4375 -5.4375 C 5.457031 -6.332031 5.328125 -6.988281 5.046875 -7.40625 C 4.773438 -7.832031 4.398438 -8.046875 3.921875 -8.046875 C 3.367188 -8.046875 2.929688 -7.832031 2.609375 -7.40625 C 2.285156 -6.988281 2.09375 -6.332031 2.03125 -5.4375 Z M 5.4375 -5.4375"/></symbol><symbol overflow="visible" id="C"><path d="M 0.96875 -8.453125 C 1.320312 -8.671875 1.742188 -8.835938 2.234375 -8.953125 C 2.734375 -9.078125 3.257812 -9.140625 3.8125 -9.140625 C 4.320312 -9.140625 4.726562 -9.0625 5.03125 -8.90625 C 5.332031 -8.757812 5.570312 -8.554688 5.75 -8.296875 C 5.925781 -8.046875 6.039062 -7.753906 6.09375 -7.421875 C 6.144531 -7.097656 6.171875 -6.753906 6.171875 -6.390625 C 6.171875 -5.671875 6.15625 -4.96875 6.125 -4.28125 C 6.09375 -3.601562 6.078125 -2.957031 6.078125 -2.34375 C 6.078125 -1.882812 6.09375 -1.457031 6.125 -1.0625 C 6.15625 -0.675781 6.210938 -0.3125 6.296875 0.03125 L 5.3125 0.03125 L 5 -1.03125 L 4.9375 -1.03125 C 4.75 -0.71875 4.484375 -0.445312 4.140625 -0.21875 C 3.796875 0.0078125 3.328125 0.125 2.734375 0.125 C 2.085938 0.125 1.554688 -0.0976562 1.140625 -0.546875 C 0.722656 -0.992188 0.515625 -1.613281 0.515625 -2.40625 C 0.515625 -2.925781 0.601562 -3.359375 0.78125 -3.703125 C 0.957031 -4.054688 1.203125 -4.335938 1.515625 -4.546875 C 1.835938 -4.765625 2.21875 -4.914062 2.65625 -5 C 3.09375 -5.09375 3.582031 -5.140625 4.125 -5.140625 C 4.238281 -5.140625 4.351562 -5.140625 4.46875 -5.140625 C 4.59375 -5.140625 4.722656 -5.132812 4.859375 -5.125 C 4.890625 -5.5 4.90625 -5.832031 4.90625 -6.125 C 4.90625 -6.800781 4.800781 -7.273438 4.59375 -7.546875 C 4.394531 -7.828125 4.023438 -7.96875 3.484375 -7.96875 C 3.148438 -7.96875 2.785156 -7.914062 2.390625 -7.8125 C 1.992188 -7.71875 1.664062 -7.59375 1.40625 -7.4375 Z M 4.875 -4.109375 C 4.757812 -4.117188 4.640625 -4.125 4.515625 -4.125 C 4.398438 -4.132812 4.28125 -4.140625 4.15625 -4.140625 C 3.863281 -4.140625 3.578125 -4.113281 3.296875 -4.0625 C 3.023438 -4.019531 2.78125 -3.9375 2.5625 -3.8125 C 2.351562 -3.695312 2.1875 -3.535156 2.0625 -3.328125 C 1.9375 -3.128906 1.875 -2.875 1.875 -2.5625 C 1.875 -2.082031 1.988281 -1.707031 2.21875 -1.4375 C 2.457031 -1.175781 2.757812 -1.046875 3.125 -1.046875 C 3.632812 -1.046875 4.023438 -1.164062 4.296875 -1.40625 C 4.578125 -1.644531 4.769531 -1.910156 4.875 -2.203125 Z M 4.875 -4.109375"/></symbol><symbol overflow="visible" id="D"><path d="M 6.734375 -3.09375 C 6.734375 -2.476562 6.738281 -1.921875 6.75 -1.421875 C 6.757812 -0.929688 6.800781 -0.445312 6.875 0.03125 L 6 0.03125 L 5.703125 -1.046875 L 5.640625 -1.046875 C 5.460938 -0.679688 5.191406 -0.378906 4.828125 -0.140625 C 4.472656 0.0976562 4.046875 0.21875 3.546875 0.21875 C 2.578125 0.21875 1.851562 -0.15625 1.375 -0.90625 C 0.90625 -1.664062 0.671875 -2.859375 0.671875 -4.484375 C 0.671875 -6.015625 0.957031 -7.175781 1.53125 -7.96875 C 2.113281 -8.757812 2.914062 -9.15625 3.9375 -9.15625 C 4.289062 -9.15625 4.566406 -9.132812 4.765625 -9.09375 C 4.972656 -9.050781 5.195312 -8.984375 5.4375 -8.890625 L 5.4375 -12.59375 L 6.734375 -12.59375 Z M 5.4375 -7.578125 C 5.269531 -7.722656 5.078125 -7.828125 4.859375 -7.890625 C 4.648438 -7.953125 4.375 -7.984375 4.03125 -7.984375 C 3.394531 -7.984375 2.898438 -7.695312 2.546875 -7.125 C 2.191406 -6.550781 2.015625 -5.664062 2.015625 -4.46875 C 2.015625 -3.9375 2.046875 -3.457031 2.109375 -3.03125 C 2.179688 -2.601562 2.285156 -2.234375 2.421875 -1.921875 C 2.554688 -1.609375 2.734375 -1.367188 2.953125 -1.203125 C 3.179688 -1.035156 3.457031 -0.953125 3.78125 -0.953125 C 4.644531 -0.953125 5.195312 -1.460938 5.4375 -2.484375 Z M 5.4375 -7.578125"/></symbol><symbol overflow="visible" id="E"><path d="M 0.921875 -1.46875 C 1.160156 -1.332031 1.441406 -1.210938 1.765625 -1.109375 C 2.097656 -1.003906 2.441406 -0.953125 2.796875 -0.953125 C 3.191406 -0.953125 3.523438 -1.050781 3.796875 -1.25 C 4.078125 -1.445312 4.21875 -1.769531 4.21875 -2.21875 C 4.21875 -2.582031 4.128906 -2.882812 3.953125 -3.125 C 3.785156 -3.363281 3.570312 -3.578125 3.3125 -3.765625 C 3.0625 -3.960938 2.785156 -4.140625 2.484375 -4.296875 C 2.179688 -4.460938 1.898438 -4.660156 1.640625 -4.890625 C 1.390625 -5.117188 1.175781 -5.390625 1 -5.703125 C 0.832031 -6.015625 0.75 -6.410156 0.75 -6.890625 C 0.75 -7.660156 0.957031 -8.238281 1.375 -8.625 C 1.789062 -9.019531 2.375 -9.21875 3.125 -9.21875 C 3.625 -9.21875 4.050781 -9.171875 4.40625 -9.078125 C 4.769531 -8.992188 5.082031 -8.875 5.34375 -8.71875 L 5 -7.625 C 4.769531 -7.75 4.503906 -7.847656 4.203125 -7.921875 C 3.910156 -8.003906 3.609375 -8.046875 3.296875 -8.046875 C 2.859375 -8.046875 2.539062 -7.953125 2.34375 -7.765625 C 2.144531 -7.585938 2.046875 -7.3125 2.046875 -6.9375 C 2.046875 -6.632812 2.128906 -6.375 2.296875 -6.15625 C 2.472656 -5.945312 2.6875 -5.753906 2.9375 -5.578125 C 3.195312 -5.410156 3.476562 -5.234375 3.78125 -5.046875 C 4.082031 -4.867188 4.359375 -4.65625 4.609375 -4.40625 C 4.867188 -4.164062 5.082031 -3.875 5.25 -3.53125 C 5.425781 -3.195312 5.515625 -2.769531 5.515625 -2.25 C 5.515625 -1.914062 5.457031 -1.597656 5.34375 -1.296875 C 5.238281 -0.992188 5.070312 -0.734375 4.84375 -0.515625 C 4.625 -0.296875 4.347656 -0.117188 4.015625 0.015625 C 3.691406 0.148438 3.304688 0.21875 2.859375 0.21875 C 2.328125 0.21875 1.867188 0.164062 1.484375 0.0625 C 1.109375 -0.0390625 0.785156 -0.175781 0.515625 -0.34375 Z M 0.921875 -1.46875"/></symbol><symbol overflow="visible" id="F"><path d="M 0.640625 -0.78125 C 0.640625 -1.070312 0.726562 -1.304688 0.90625 -1.484375 C 1.082031 -1.671875 1.304688 -1.765625 1.578125 -1.765625 C 1.890625 -1.765625 2.144531 -1.640625 2.34375 -1.390625 C 2.539062 -1.140625 2.640625 -0.742188 2.640625 -0.203125 C 2.640625 0.191406 2.585938 0.546875 2.484375 0.859375 C 2.390625 1.179688 2.257812 1.460938 2.09375 1.703125 C 1.9375 1.941406 1.757812 2.140625 1.5625 2.296875 C 1.375 2.453125 1.191406 2.566406 1.015625 2.640625 L 0.5625 2.03125 C 0.71875 1.945312 0.863281 1.835938 1 1.703125 C 1.132812 1.566406 1.242188 1.410156 1.328125 1.234375 C 1.421875 1.066406 1.492188 0.890625 1.546875 0.703125 C 1.597656 0.523438 1.625 0.34375 1.625 0.15625 C 1.382812 0.226562 1.160156 0.179688 0.953125 0.015625 C 0.742188 -0.148438 0.640625 -0.414062 0.640625 -0.78125 Z M 0.640625 -0.78125"/></symbol><symbol overflow="visible" id="G"><path d="M 1.15625 -12.46875 C 1.539062 -12.582031 1.945312 -12.65625 2.375 -12.6875 C 2.8125 -12.726562 3.238281 -12.75 3.65625 -12.75 C 4.132812 -12.75 4.609375 -12.691406 5.078125 -12.578125 C 5.546875 -12.472656 5.96875 -12.273438 6.34375 -11.984375 C 6.71875 -11.703125 7.019531 -11.304688 7.25 -10.796875 C 7.488281 -10.296875 7.609375 -9.65625 7.609375 -8.875 C 7.609375 -8.113281 7.5 -7.46875 7.28125 -6.9375 C 7.0625 -6.414062 6.765625 -5.988281 6.390625 -5.65625 C 6.023438 -5.332031 5.601562 -5.09375 5.125 -4.9375 C 4.65625 -4.789062 4.171875 -4.71875 3.671875 -4.71875 C 3.617188 -4.71875 3.539062 -4.71875 3.4375 -4.71875 C 3.332031 -4.71875 3.21875 -4.71875 3.09375 -4.71875 C 2.976562 -4.726562 2.863281 -4.738281 2.75 -4.75 C 2.632812 -4.757812 2.550781 -4.769531 2.5 -4.78125 L 2.5 0 L 1.15625 0 Z M 3.71875 -11.5 C 3.476562 -11.5 3.25 -11.488281 3.03125 -11.46875 C 2.8125 -11.457031 2.632812 -11.429688 2.5 -11.390625 L 2.5 -6.03125 C 2.550781 -6.007812 2.625 -5.992188 2.71875 -5.984375 C 2.820312 -5.972656 2.925781 -5.960938 3.03125 -5.953125 C 3.144531 -5.953125 3.253906 -5.953125 3.359375 -5.953125 C 3.460938 -5.953125 3.535156 -5.953125 3.578125 -5.953125 C 3.921875 -5.953125 4.242188 -5.992188 4.546875 -6.078125 C 4.859375 -6.160156 5.132812 -6.3125 5.375 -6.53125 C 5.613281 -6.757812 5.804688 -7.0625 5.953125 -7.4375 C 6.109375 -7.820312 6.1875 -8.300781 6.1875 -8.875 C 6.1875 -9.375 6.117188 -9.789062 5.984375 -10.125 C 5.847656 -10.46875 5.664062 -10.738281 5.4375 -10.9375 C 5.21875 -11.144531 4.957031 -11.289062 4.65625 -11.375 C 4.363281 -11.457031 4.050781 -11.5 3.71875 -11.5 Z M 3.71875 -11.5"/></symbol><symbol overflow="visible" id="H"><path d="M 0.703125 -0.8125 C 0.703125 -1.144531 0.78125 -1.394531 0.9375 -1.5625 C 1.101562 -1.726562 1.328125 -1.8125 1.609375 -1.8125 C 1.878906 -1.8125 2.09375 -1.726562 2.25 -1.5625 C 2.414062 -1.394531 2.5 -1.144531 2.5 -0.8125 C 2.5 -0.457031 2.414062 -0.195312 2.25 -0.03125 C 2.09375 0.132812 1.878906 0.21875 1.609375 0.21875 C 1.328125 0.21875 1.101562 0.132812 0.9375 -0.03125 C 0.78125 -0.195312 0.703125 -0.457031 0.703125 -0.8125 Z M 0.703125 -0.8125"/></symbol><symbol overflow="visible" id="I"><path d="M 0.78125 -6.296875 C 0.78125 -8.429688 1.117188 -10.050781 1.796875 -11.15625 C 2.484375 -12.257812 3.53125 -12.8125 4.9375 -12.8125 C 5.6875 -12.8125 6.328125 -12.65625 6.859375 -12.34375 C 7.390625 -12.039062 7.816406 -11.609375 8.140625 -11.046875 C 8.472656 -10.484375 8.71875 -9.800781 8.875 -9 C 9.03125 -8.195312 9.109375 -7.296875 9.109375 -6.296875 C 9.109375 -4.160156 8.757812 -2.539062 8.0625 -1.4375 C 7.375 -0.332031 6.332031 0.21875 4.9375 0.21875 C 4.1875 0.21875 3.546875 0.0664062 3.015625 -0.234375 C 2.492188 -0.546875 2.0625 -0.984375 1.71875 -1.546875 C 1.382812 -2.109375 1.144531 -2.789062 1 -3.59375 C 0.851562 -4.40625 0.78125 -5.304688 0.78125 -6.296875 Z M 2.203125 -6.296875 C 2.203125 -5.585938 2.25 -4.914062 2.34375 -4.28125 C 2.445312 -3.644531 2.609375 -3.085938 2.828125 -2.609375 C 3.046875 -2.128906 3.328125 -1.742188 3.671875 -1.453125 C 4.015625 -1.171875 4.4375 -1.03125 4.9375 -1.03125 C 5.832031 -1.03125 6.515625 -1.460938 6.984375 -2.328125 C 7.453125 -3.191406 7.6875 -4.515625 7.6875 -6.296875 C 7.6875 -6.992188 7.632812 -7.660156 7.53125 -8.296875 C 7.425781 -8.929688 7.265625 -9.488281 7.046875 -9.96875 C 6.835938 -10.457031 6.554688 -10.847656 6.203125 -11.140625 C 5.859375 -11.429688 5.4375 -11.578125 4.9375 -11.578125 C 4.039062 -11.578125 3.359375 -11.144531 2.890625 -10.28125 C 2.429688 -9.414062 2.203125 -8.085938 2.203125 -6.296875 Z M 2.203125 -6.296875"/></symbol><symbol overflow="visible" id="J"><path d="M 1.0625 -12.59375 L 2.359375 -12.59375 L 2.359375 -8.3125 L 2.40625 -8.3125 C 2.90625 -8.914062 3.5625 -9.21875 4.375 -9.21875 C 5.300781 -9.21875 5.992188 -8.847656 6.453125 -8.109375 C 6.910156 -7.378906 7.140625 -6.222656 7.140625 -4.640625 C 7.140625 -3.023438 6.832031 -1.820312 6.21875 -1.03125 C 5.601562 -0.238281 4.726562 0.15625 3.59375 0.15625 C 3.039062 0.15625 2.535156 0.09375 2.078125 -0.03125 C 1.628906 -0.15625 1.289062 -0.300781 1.0625 -0.46875 Z M 2.359375 -1.3125 C 2.523438 -1.21875 2.726562 -1.144531 2.96875 -1.09375 C 3.21875 -1.039062 3.484375 -1.015625 3.765625 -1.015625 C 4.390625 -1.015625 4.882812 -1.3125 5.25 -1.90625 C 5.613281 -2.5 5.796875 -3.410156 5.796875 -4.640625 C 5.796875 -5.160156 5.757812 -5.625 5.6875 -6.03125 C 5.625 -6.445312 5.523438 -6.804688 5.390625 -7.109375 C 5.253906 -7.410156 5.070312 -7.640625 4.84375 -7.796875 C 4.625 -7.960938 4.359375 -8.046875 4.046875 -8.046875 C 3.617188 -8.046875 3.265625 -7.914062 2.984375 -7.65625 C 2.703125 -7.394531 2.492188 -7.046875 2.359375 -6.609375 Z M 2.359375 -1.3125"/></symbol><symbol overflow="visible" id="K"><path d="M 0.671875 -4.5 C 0.671875 -6.125 0.945312 -7.316406 1.5 -8.078125 C 2.0625 -8.835938 2.859375 -9.21875 3.890625 -9.21875 C 4.992188 -9.21875 5.804688 -8.828125 6.328125 -8.046875 C 6.847656 -7.265625 7.109375 -6.082031 7.109375 -4.5 C 7.109375 -2.863281 6.828125 -1.664062 6.265625 -0.90625 C 5.703125 -0.15625 4.910156 0.21875 3.890625 0.21875 C 2.785156 0.21875 1.972656 -0.171875 1.453125 -0.953125 C 0.929688 -1.734375 0.671875 -2.914062 0.671875 -4.5 Z M 2.015625 -4.5 C 2.015625 -3.96875 2.046875 -3.484375 2.109375 -3.046875 C 2.179688 -2.617188 2.289062 -2.25 2.4375 -1.9375 C 2.582031 -1.625 2.773438 -1.378906 3.015625 -1.203125 C 3.265625 -1.035156 3.554688 -0.953125 3.890625 -0.953125 C 4.515625 -0.953125 4.984375 -1.226562 5.296875 -1.78125 C 5.609375 -2.34375 5.765625 -3.25 5.765625 -4.5 C 5.765625 -5.019531 5.726562 -5.5 5.65625 -5.9375 C 5.59375 -6.375 5.484375 -6.75 5.328125 -7.0625 C 5.179688 -7.375 4.988281 -7.613281 4.75 -7.78125 C 4.507812 -7.957031 4.222656 -8.046875 3.890625 -8.046875 C 3.273438 -8.046875 2.804688 -7.765625 2.484375 -7.203125 C 2.171875 -6.640625 2.015625 -5.738281 2.015625 -4.5 Z M 2.015625 -4.5"/></symbol><symbol overflow="visible" id="L"><path d="M 2.890625 -4.609375 L 0.515625 -9 L 2.0625 -9 L 3.40625 -6.421875 L 3.765625 -5.421875 L 4.140625 -6.421875 L 5.515625 -9 L 6.9375 -9 L 4.53125 -4.6875 L 7.078125 0 L 5.59375 0 L 4.09375 -2.828125 L 3.6875 -3.90625 L 3.28125 -2.828125 L 1.765625 0 L 0.34375 0 Z M 2.890625 -4.609375"/></symbol><symbol overflow="visible" id="M"><path d="M 6.03125 -0.453125 C 5.726562 -0.222656 5.382812 -0.0546875 5 0.046875 C 4.613281 0.160156 4.210938 0.21875 3.796875 0.21875 C 3.222656 0.21875 2.738281 0.109375 2.34375 -0.109375 C 1.945312 -0.335938 1.625 -0.65625 1.375 -1.0625 C 1.132812 -1.476562 0.957031 -1.976562 0.84375 -2.5625 C 0.726562 -3.144531 0.671875 -3.789062 0.671875 -4.5 C 0.671875 -6.03125 0.941406 -7.195312 1.484375 -8 C 2.023438 -8.8125 2.804688 -9.21875 3.828125 -9.21875 C 4.296875 -9.21875 4.695312 -9.175781 5.03125 -9.09375 C 5.375 -9.007812 5.664062 -8.898438 5.90625 -8.765625 L 5.546875 -7.625 C 5.066406 -7.90625 4.546875 -8.046875 3.984375 -8.046875 C 3.328125 -8.046875 2.832031 -7.757812 2.5 -7.1875 C 2.175781 -6.625 2.015625 -5.726562 2.015625 -4.5 C 2.015625 -4.007812 2.050781 -3.546875 2.125 -3.109375 C 2.195312 -2.679688 2.316406 -2.304688 2.484375 -1.984375 C 2.648438 -1.671875 2.863281 -1.421875 3.125 -1.234375 C 3.394531 -1.046875 3.726562 -0.953125 4.125 -0.953125 C 4.4375 -0.953125 4.726562 -1.003906 5 -1.109375 C 5.269531 -1.222656 5.488281 -1.351562 5.65625 -1.5 Z M 6.03125 -0.453125"/></symbol><symbol overflow="visible" id="N"><path d="M 5.28125 0 L 5.28125 -5.34375 C 5.28125 -5.820312 5.265625 -6.234375 5.234375 -6.578125 C 5.203125 -6.921875 5.132812 -7.195312 5.03125 -7.40625 C 4.9375 -7.625 4.804688 -7.785156 4.640625 -7.890625 C 4.472656 -7.992188 4.253906 -8.046875 3.984375 -8.046875 C 3.566406 -8.046875 3.21875 -7.882812 2.9375 -7.5625 C 2.65625 -7.25 2.460938 -6.890625 2.359375 -6.484375 L 2.359375 0 L 1.0625 0 L 1.0625 -9 L 1.984375 -9 L 2.21875 -8.046875 L 2.265625 -8.046875 C 2.515625 -8.390625 2.8125 -8.671875 3.15625 -8.890625 C 3.507812 -9.109375 3.957031 -9.21875 4.5 -9.21875 C 4.957031 -9.21875 5.332031 -9.117188 5.625 -8.921875 C 5.914062 -8.722656 6.144531 -8.367188 6.3125 -7.859375 C 6.53125 -8.285156 6.835938 -8.617188 7.234375 -8.859375 C 7.640625 -9.097656 8.082031 -9.21875 8.5625 -9.21875 C 8.957031 -9.21875 9.296875 -9.164062 9.578125 -9.0625 C 9.867188 -8.957031 10.097656 -8.773438 10.265625 -8.515625 C 10.441406 -8.265625 10.570312 -7.925781 10.65625 -7.5 C 10.738281 -7.070312 10.78125 -6.535156 10.78125 -5.890625 L 10.78125 0 L 9.484375 0 L 9.484375 -5.71875 C 9.484375 -6.5 9.40625 -7.082031 9.25 -7.46875 C 9.101562 -7.851562 8.757812 -8.046875 8.21875 -8.046875 C 7.769531 -8.046875 7.410156 -7.90625 7.140625 -7.625 C 6.867188 -7.34375 6.675781 -6.960938 6.5625 -6.484375 L 6.5625 0 Z M 5.28125 0"/></symbol><symbol overflow="visible" id="O"><path d="M 1.0625 -9 L 1.984375 -9 L 2.171875 -8.03125 L 2.25 -8.03125 C 2.695312 -8.820312 3.394531 -9.21875 4.34375 -9.21875 C 5.289062 -9.21875 6 -8.863281 6.46875 -8.15625 C 6.945312 -7.445312 7.1875 -6.289062 7.1875 -4.6875 C 7.1875 -3.925781 7.109375 -3.242188 6.953125 -2.640625 C 6.796875 -2.035156 6.570312 -1.519531 6.28125 -1.09375 C 5.988281 -0.664062 5.632812 -0.335938 5.21875 -0.109375 C 4.8125 0.109375 4.359375 0.21875 3.859375 0.21875 C 3.503906 0.21875 3.222656 0.195312 3.015625 0.15625 C 2.816406 0.113281 2.597656 0.0234375 2.359375 -0.109375 L 2.359375 3.59375 L 1.0625 3.59375 Z M 2.359375 -1.421875 C 2.523438 -1.273438 2.710938 -1.160156 2.921875 -1.078125 C 3.128906 -0.992188 3.410156 -0.953125 3.765625 -0.953125 C 4.398438 -0.953125 4.898438 -1.273438 5.265625 -1.921875 C 5.640625 -2.566406 5.828125 -3.492188 5.828125 -4.703125 C 5.828125 -5.203125 5.796875 -5.65625 5.734375 -6.0625 C 5.671875 -6.46875 5.566406 -6.816406 5.421875 -7.109375 C 5.273438 -7.410156 5.085938 -7.640625 4.859375 -7.796875 C 4.640625 -7.960938 4.367188 -8.046875 4.046875 -8.046875 C 3.171875 -8.046875 2.609375 -7.507812 2.359375 -6.4375 Z M 2.359375 -1.421875"/></symbol><symbol overflow="visible" id="P"><path d="M 5.671875 0 L 5.671875 -5.484375 C 5.671875 -6.390625 5.566406 -7.039062 5.359375 -7.4375 C 5.148438 -7.84375 4.773438 -8.046875 4.234375 -8.046875 C 3.753906 -8.046875 3.359375 -7.898438 3.046875 -7.609375 C 2.734375 -7.328125 2.503906 -6.972656 2.359375 -6.546875 L 2.359375 0 L 1.0625 0 L 1.0625 -9 L 2 -9 L 2.234375 -8.046875 L 2.28125 -8.046875 C 2.507812 -8.367188 2.816406 -8.644531 3.203125 -8.875 C 3.597656 -9.101562 4.066406 -9.21875 4.609375 -9.21875 C 4.992188 -9.21875 5.332031 -9.160156 5.625 -9.046875 C 5.914062 -8.941406 6.160156 -8.757812 6.359375 -8.5 C 6.554688 -8.25 6.707031 -7.90625 6.8125 -7.46875 C 6.914062 -7.039062 6.96875 -6.492188 6.96875 -5.828125 L 6.96875 0 Z M 5.671875 0"/></symbol><symbol overflow="visible" id="Q"><path d="M 3.296875 -3.1875 L 3.671875 -1.4375 L 3.765625 -1.4375 L 4.03125 -3.1875 L 5.40625 -9 L 6.71875 -9 L 4.578125 -0.921875 C 4.398438 -0.273438 4.226562 0.328125 4.0625 0.890625 C 3.894531 1.460938 3.710938 1.953125 3.515625 2.359375 C 3.316406 2.773438 3.09375 3.097656 2.84375 3.328125 C 2.601562 3.566406 2.316406 3.6875 1.984375 3.6875 C 1.640625 3.6875 1.34375 3.632812 1.09375 3.53125 L 1.3125 2.296875 C 1.476562 2.359375 1.644531 2.367188 1.8125 2.328125 C 1.976562 2.296875 2.132812 2.195312 2.28125 2.03125 C 2.4375 1.863281 2.578125 1.613281 2.703125 1.28125 C 2.828125 0.957031 2.941406 0.53125 3.046875 0 L 0.125 -9 L 1.609375 -9 Z M 3.296875 -3.1875"/></symbol><symbol overflow="visible" id="S"><path d="M 6 -3.53125 L 2.4375 -3.53125 L 1.421875 0 L 0.09375 0 L 3.890625 -12.796875 L 4.625 -12.796875 L 8.421875 0 L 7.015625 0 Z M 2.796875 -4.734375 L 5.671875 -4.734375 L 4.578125 -8.625 L 4.234375 -10.515625 L 4.1875 -10.515625 L 3.859375 -8.59375 Z M 2.796875 -4.734375"/></symbol><symbol overflow="visible" id="T"><path d="M 2.234375 -9 L 2.234375 -3.484375 C 2.234375 -2.578125 2.328125 -1.925781 2.515625 -1.53125 C 2.703125 -1.144531 3.039062 -0.953125 3.53125 -0.953125 C 3.78125 -0.953125 4.003906 -1.003906 4.203125 -1.109375 C 4.398438 -1.210938 4.578125 -1.347656 4.734375 -1.515625 C 4.890625 -1.679688 5.023438 -1.867188 5.140625 -2.078125 C 5.265625 -2.296875 5.363281 -2.519531 5.4375 -2.75 L 5.4375 -9 L 6.734375 -9 L 6.734375 -2.5625 C 6.734375 -2.125 6.75 -1.671875 6.78125 -1.203125 C 6.8125 -0.742188 6.851562 -0.34375 6.90625 0 L 6 0 L 5.671875 -1.265625 L 5.609375 -1.265625 C 5.410156 -0.867188 5.117188 -0.519531 4.734375 -0.21875 C 4.347656 0.0703125 3.867188 0.21875 3.296875 0.21875 C 2.910156 0.21875 2.570312 0.164062 2.28125 0.0625 C 2 -0.03125 1.753906 -0.203125 1.546875 -0.453125 C 1.335938 -0.703125 1.179688 -1.046875 1.078125 -1.484375 C 0.984375 -1.921875 0.9375 -2.484375 0.9375 -3.171875 L 0.9375 -9 Z M 2.234375 -9"/></symbol><symbol overflow="visible" id="U"><path d="M 1.28125 -9 L 2.578125 -9 L 2.578125 0 L 1.28125 0 Z M 1.046875 -11.734375 C 1.046875 -12.023438 1.125 -12.257812 1.28125 -12.4375 C 1.445312 -12.613281 1.660156 -12.703125 1.921875 -12.703125 C 2.191406 -12.703125 2.410156 -12.613281 2.578125 -12.4375 C 2.753906 -12.269531 2.84375 -12.035156 2.84375 -11.734375 C 2.84375 -11.441406 2.753906 -11.210938 2.578125 -11.046875 C 2.410156 -10.890625 2.191406 -10.8125 1.921875 -10.8125 C 1.660156 -10.8125 1.445312 -10.894531 1.28125 -11.0625 C 1.125 -11.238281 1.046875 -11.460938 1.046875 -11.734375 Z M 1.046875 -11.734375"/></symbol><symbol overflow="visible" id="V"><path d="M 2.453125 -2.140625 C 2.453125 -1.722656 2.507812 -1.421875 2.625 -1.234375 C 2.738281 -1.054688 2.894531 -0.96875 3.09375 -0.96875 C 3.34375 -0.96875 3.640625 -1.035156 3.984375 -1.171875 L 4.109375 -0.125 C 3.953125 -0.03125 3.734375 0.046875 3.453125 0.109375 C 3.171875 0.171875 2.914062 0.203125 2.6875 0.203125 C 2.226562 0.203125 1.859375 0.0625 1.578125 -0.21875 C 1.296875 -0.5 1.15625 -0.992188 1.15625 -1.703125 L 1.15625 -12.59375 L 2.453125 -12.59375 Z M 2.453125 -2.140625"/></symbol><symbol overflow="visible" id="W"><path d="M 6.734375 0.40625 C 6.734375 1.570312 6.472656 2.429688 5.953125 2.984375 C 5.441406 3.535156 4.691406 3.8125 3.703125 3.8125 C 3.109375 3.8125 2.617188 3.757812 2.234375 3.65625 C 1.847656 3.5625 1.535156 3.445312 1.296875 3.3125 L 1.671875 2.203125 C 1.910156 2.304688 2.171875 2.40625 2.453125 2.5 C 2.742188 2.59375 3.101562 2.640625 3.53125 2.640625 C 4.257812 2.640625 4.757812 2.4375 5.03125 2.03125 C 5.300781 1.625 5.4375 0.941406 5.4375 -0.015625 L 5.4375 -0.6875 L 5.375 -0.6875 C 5.1875 -0.40625 4.941406 -0.1875 4.640625 -0.03125 C 4.335938 0.125 3.953125 0.203125 3.484375 0.203125 C 2.515625 0.203125 1.800781 -0.171875 1.34375 -0.921875 C 0.894531 -1.671875 0.671875 -2.851562 0.671875 -4.46875 C 0.671875 -6.007812 0.96875 -7.175781 1.5625 -7.96875 C 2.15625 -8.757812 3.03125 -9.15625 4.1875 -9.15625 C 4.757812 -9.15625 5.25 -9.101562 5.65625 -9 C 6.0625 -8.894531 6.421875 -8.769531 6.734375 -8.625 Z M 5.4375 -7.703125 C 5.070312 -7.890625 4.609375 -7.984375 4.046875 -7.984375 C 3.429688 -7.984375 2.9375 -7.703125 2.5625 -7.140625 C 2.195312 -6.585938 2.015625 -5.703125 2.015625 -4.484375 C 2.015625 -3.972656 2.046875 -3.503906 2.109375 -3.078125 C 2.171875 -2.660156 2.269531 -2.289062 2.40625 -1.96875 C 2.550781 -1.65625 2.734375 -1.410156 2.953125 -1.234375 C 3.179688 -1.054688 3.457031 -0.96875 3.78125 -0.96875 C 4.238281 -0.96875 4.597656 -1.085938 4.859375 -1.328125 C 5.117188 -1.566406 5.3125 -1.925781 5.4375 -2.40625 Z M 5.4375 -7.703125"/></symbol><symbol overflow="visible" id="X"><path d="M 5.40625 -11.5 C 5.269531 -11.519531 5.070312 -11.546875 4.8125 -11.578125 C 4.550781 -11.617188 4.296875 -11.640625 4.046875 -11.640625 C 3.734375 -11.640625 3.488281 -11.578125 3.3125 -11.453125 C 3.132812 -11.335938 2.992188 -11.171875 2.890625 -10.953125 C 2.796875 -10.734375 2.738281 -10.457031 2.71875 -10.125 C 2.695312 -9.789062 2.6875 -9.414062 2.6875 -9 L 4.109375 -9 L 4.109375 -7.828125 L 2.6875 -7.828125 L 2.6875 0 L 1.390625 0 L 1.390625 -7.828125 L 0.28125 -7.828125 L 0.28125 -9 L 1.390625 -9 L 1.390625 -9.5 C 1.390625 -10.632812 1.585938 -11.46875 1.984375 -12 C 2.390625 -12.539062 3.066406 -12.8125 4.015625 -12.8125 C 4.203125 -12.8125 4.425781 -12.800781 4.6875 -12.78125 C 4.945312 -12.769531 5.203125 -12.75 5.453125 -12.71875 C 5.703125 -12.6875 5.9375 -12.648438 6.15625 -12.609375 C 6.382812 -12.578125 6.566406 -12.535156 6.703125 -12.484375 L 6.703125 -2.046875 C 6.703125 -1.648438 6.753906 -1.367188 6.859375 -1.203125 C 6.972656 -1.035156 7.132812 -0.953125 7.34375 -0.953125 C 7.601562 -0.953125 7.90625 -1.019531 8.25 -1.15625 L 8.328125 -0.109375 C 8.171875 -0.015625 7.957031 0.0625 7.6875 0.125 C 7.425781 0.1875 7.164062 0.21875 6.90625 0.21875 C 6.457031 0.21875 6.09375 0.078125 5.8125 -0.203125 C 5.539062 -0.492188 5.40625 -0.988281 5.40625 -1.6875 Z M 5.40625 -11.5"/></symbol></defs><path fill="#fff" d="M0 0H707V478H0z"/><path d="M 24.194 15.513817 L 59.46568 15.513817 L 59.46568 38.091747 L 24.194 38.091747 Z M 24.194 15.513817" transform="matrix(20 0 0 20 -482.88 -284.624)" fill-rule="evenodd" fill="#fff" stroke-width=".1" stroke="#fff" stroke-miterlimit="10"/><path d="M 57.890625 44.359375 L 187.191406 44.359375 L 187.191406 70.609375 L 57.890625 70.609375 Z M 57.890625 44.359375" fill-rule="evenodd" fill="#fff"/><use xlink:href="#a" x="57.891" y="65.012"/><use xlink:href="#b" x="66.367" y="65.012"/><use xlink:href="#c" x="75" y="65.012"/><use xlink:href="#d" x="81.758" y="65.012"/><use xlink:href="#e" x="87.266" y="65.012"/><use xlink:href="#f" x="95.273" y="65.012"/><use xlink:href="#g" x="99.941" y="65.012"/><use xlink:href="#h" x="109.395" y="65.012"/><use xlink:href="#h" x="118.047" y="65.012"/><use xlink:href="#i" x="126.699" y="65.012"/><use xlink:href="#j" x="132.188" y="65.012"/><use xlink:href="#c" x="140.449" y="65.012"/><use xlink:href="#c" x="147.207" y="65.012"/><use xlink:href="#k" x="153.965" y="65.012"/><use xlink:href="#l" x="160.879" y="65.012"/><use xlink:href="#m" x="168.398" y="65.012"/><use xlink:href="#j" x="177.09" y="65.012"/><path d="M 26.601422 18.296239 L 57.058062 18.296239" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.601422 36.158153 L 57.058062 36.158153" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.601422 18.296239 L 26.601422 18.296239 C 26.435797 18.296239 26.301422 18.430419 26.301422 18.596239" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 57.358062 18.596239 L 57.358062 18.596239 C 57.358062 18.430419 57.223883 18.296239 57.058062 18.296239" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.301422 18.596239 L 26.301422 35.858153" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 57.358062 18.596239 L 57.358062 35.858153" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 26.301422 35.858153 L 26.301422 35.858153 C 26.301422 36.023778 26.435797 36.158153 26.601422 36.158153" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 57.058062 36.158153 L 57.058062 36.158153 C 57.223883 36.158153 57.358062 36.023778 57.358062 35.858153" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#b3b3b3" stroke-miterlimit="10"/><path d="M 81.667969 125.710938 L 176.96875 125.710938 L 176.96875 151.960938 L 81.667969 151.960938 Z M 81.667969 125.710938" fill-rule="evenodd" fill="#fff"/><use xlink:href="#n" x="83.082" y="146.359"/><use xlink:href="#o" x="93.102" y="146.359"/><use xlink:href="#o" x="102.008" y="146.359"/><use xlink:href="#p" x="110.914" y="146.359"/><use xlink:href="#q" x="116.773" y="146.359"/><use xlink:href="#r" x="125.328" y="146.359"/><use xlink:href="#s" x="132.32" y="146.359"/><use xlink:href="#t" x="136.422" y="146.359"/><use xlink:href="#u" x="141.285" y="146.359"/><use xlink:href="#v" x="145.777" y="146.359"/><use xlink:href="#q" x="154.762" y="146.359"/><use xlink:href="#s" x="163.316" y="146.359"/><use xlink:href="#w" x="167.418" y="146.359"/><path d="M 197.308594 118.835938 L 605.308594 118.835938 L 605.308594 158.835938 L 197.308594 158.835938 Z M 197.308594 118.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 124.835938 L 197.308594 118.835938 C 193.996094 118.835938 191.308594 121.519531 191.308594 124.835938 Z M 197.308594 124.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.308594 124.835938 L 611.308594 124.835938 C 611.308594 121.519531 608.625 118.835938 605.308594 118.835938 Z M 605.308594 124.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.308594 124.835938 L 611.308594 124.835938 L 611.308594 152.835938 L 191.308594 152.835938 Z M 191.308594 124.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 152.835938 L 191.308594 152.835938 C 191.308594 156.148438 193.996094 158.835938 197.308594 158.835938 Z M 197.308594 152.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.308594 152.835938 L 605.308594 158.835938 C 608.625 158.835938 611.308594 156.148438 611.308594 152.835938 Z M 605.308594 152.835938" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.00943 20.172997 L 54.40943 20.172997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 22.172997 L 54.40943 22.172997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 20.172997 L 34.00943 20.172997 C 33.843805 20.172997 33.70943 20.307177 33.70943 20.472997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.70943 20.472997 L 54.70943 20.472997 C 54.70943 20.307177 54.57525 20.172997 54.40943 20.172997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 20.472997 L 33.70943 21.872997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.70943 20.472997 L 54.70943 21.872997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 21.872997 L 33.70943 21.872997 C 33.70943 22.038622 33.843805 22.172997 34.00943 22.172997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.40943 22.172997 L 54.40943 22.172997 C 54.57525 22.172997 54.70943 22.038622 54.70943 21.872997" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 191.308594 161.433594 L 432.507812 161.433594 L 432.507812 184.832031 L 191.308594 184.832031 Z M 191.308594 161.433594" fill-rule="evenodd" fill="#fff"/><g fill="#4d4d4d"><use xlink:href="#x" x="191.309" y="179.836"/><use xlink:href="#y" x="199.004" y="179.836"/><use xlink:href="#z" x="203.945" y="179.836"/><use xlink:href="#A" x="208.887" y="179.836"/><use xlink:href="#A" x="216.211" y="179.836"/><use xlink:href="#y" x="223.652" y="179.836"/><use xlink:href="#B" x="228.594" y="179.836"/><use xlink:href="#C" x="232.402" y="179.836"/><use xlink:href="#D" x="239.609" y="179.836"/><use xlink:href="#D" x="247.402" y="179.836"/><use xlink:href="#z" x="255.195" y="179.836"/><use xlink:href="#A" x="260.137" y="179.836"/><use xlink:href="#E" x="267.578" y="179.836"/><use xlink:href="#E" x="273.652" y="179.836"/><use xlink:href="#F" x="279.727" y="179.836"/><use xlink:href="#B" x="281.895" y="179.836"/><use xlink:href="#G" x="285.703" y="179.836"/><use xlink:href="#H" x="291.953" y="179.836"/><use xlink:href="#I" x="295.156" y="179.836"/><use xlink:href="#H" x="304.629" y="179.836"/><use xlink:href="#B" x="306.66" y="179.836"/><use xlink:href="#J" x="310.469" y="179.836"/><use xlink:href="#K" x="318.281" y="179.836"/><use xlink:href="#L" x="325.742" y="179.836"/><use xlink:href="#F" x="333.164" y="179.836"/><use xlink:href="#B" x="335.332" y="179.836"/><use xlink:href="#M" x="339.141" y="179.836"/><use xlink:href="#K" x="345.254" y="179.836"/><use xlink:href="#N" x="353.027" y="179.836"/><use xlink:href="#O" x="364.746" y="179.836"/><use xlink:href="#C" x="372.578" y="179.836"/><use xlink:href="#P" x="379.785" y="179.836"/><use xlink:href="#Q" x="387.695" y="179.836"/><use xlink:href="#B" x="393.984" y="179.836"/><use xlink:href="#P" x="397.793" y="179.836"/><use xlink:href="#C" x="405.703" y="179.836"/><use xlink:href="#N" x="412.91" y="179.836"/><use xlink:href="#A" x="424.629" y="179.836"/></g><path d="M 48.115289 24.841552 L 44.652789 24.83745" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 44.652789 24.83745 C 44.652789 24.71245 44.777984 24.587645 44.902984 24.587645 C 45.027984 24.587841 45.152789 24.713036 45.152789 24.838036 C 45.152594 24.963036 45.027398 25.087841 44.902398 25.087645 C 44.777398 25.087645 44.652594 24.96245 44.652789 24.83745" transform="matrix(20 0 0 20 -482.88 -284.624)" fill-rule="evenodd" stroke-width=".1" stroke="#000" stroke-miterlimit="10"/><path d="M 81.667969 207.042969 L 176.96875 207.042969 L 176.96875 233.292969 L 81.667969 233.292969 Z M 81.667969 207.042969" fill-rule="evenodd" fill="#fff"/><use xlink:href="#n" x="83.082" y="227.691"/><use xlink:href="#o" x="93.102" y="227.691"/><use xlink:href="#o" x="102.008" y="227.691"/><use xlink:href="#p" x="110.914" y="227.691"/><use xlink:href="#q" x="116.773" y="227.691"/><use xlink:href="#r" x="125.328" y="227.691"/><use xlink:href="#s" x="132.32" y="227.691"/><use xlink:href="#t" x="136.422" y="227.691"/><use xlink:href="#u" x="141.285" y="227.691"/><use xlink:href="#v" x="145.777" y="227.691"/><use xlink:href="#q" x="154.762" y="227.691"/><use xlink:href="#s" x="163.316" y="227.691"/><use xlink:href="#R" x="167.418" y="227.691"/><path d="M 197.308594 200.167969 L 605.308594 200.167969 L 605.308594 240.167969 L 197.308594 240.167969 Z M 197.308594 200.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 206.167969 L 197.308594 200.167969 C 193.996094 200.167969 191.308594 202.855469 191.308594 206.167969 Z M 197.308594 206.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.308594 206.167969 L 611.308594 206.167969 C 611.308594 202.855469 608.625 200.167969 605.308594 200.167969 Z M 605.308594 206.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.308594 206.167969 L 611.308594 206.167969 L 611.308594 234.167969 L 191.308594 234.167969 Z M 191.308594 206.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 234.167969 L 191.308594 234.167969 C 191.308594 237.480469 193.996094 240.167969 197.308594 240.167969 Z M 197.308594 234.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.308594 234.167969 L 605.308594 240.167969 C 608.625 240.167969 611.308594 237.480469 611.308594 234.167969 Z M 605.308594 234.167969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.00943 24.239598 L 54.40943 24.239598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 26.239598 L 54.40943 26.239598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 24.239598 L 34.00943 24.239598 C 33.843805 24.239598 33.70943 24.373973 33.70943 24.539598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.70943 24.539598 L 54.70943 24.539598 C 54.70943 24.373973 54.57525 24.239598 54.40943 24.239598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 24.539598 L 33.70943 25.939598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.70943 24.539598 L 54.70943 25.939598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 25.939598 L 33.70943 25.939598 C 33.70943 26.105223 33.843805 26.239598 34.00943 26.239598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.40943 26.239598 L 54.40943 26.239598 C 54.57525 26.239598 54.70943 26.105223 54.70943 25.939598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 190.808594 242.433594 L 415.707031 242.433594 L 415.707031 265.832031 L 190.808594 265.832031 Z M 190.808594 242.433594" fill-rule="evenodd" fill="#fff"/><g fill="#4d4d4d"><use xlink:href="#S" x="190.809" y="260.836"/><use xlink:href="#O" x="199.324" y="260.836"/><use xlink:href="#C" x="207.156" y="260.836"/><use xlink:href="#z" x="214.363" y="260.836"/><use xlink:href="#y" x="219.734" y="260.836"/><use xlink:href="#N" x="224.676" y="260.836"/><use xlink:href="#A" x="236.395" y="260.836"/><use xlink:href="#P" x="243.836" y="260.836"/><use xlink:href="#y" x="251.746" y="260.836"/><use xlink:href="#F" x="256.688" y="260.836"/><use xlink:href="#B" x="258.855" y="260.836"/><use xlink:href="#E" x="262.664" y="260.836"/><use xlink:href="#T" x="268.738" y="260.836"/><use xlink:href="#U" x="276.551" y="260.836"/><use xlink:href="#y" x="280.457" y="260.836"/><use xlink:href="#A" x="285.281" y="260.836"/><use xlink:href="#F" x="292.723" y="260.836"/><use xlink:href="#B" x="294.891" y="260.836"/><use xlink:href="#T" x="298.699" y="260.836"/><use xlink:href="#P" x="306.512" y="260.836"/><use xlink:href="#U" x="314.422" y="260.836"/><use xlink:href="#y" x="318.328" y="260.836"/><use xlink:href="#F" x="323.27" y="260.836"/><use xlink:href="#B" x="325.438" y="260.836"/><use xlink:href="#J" x="329.246" y="260.836"/><use xlink:href="#T" x="337.059" y="260.836"/><use xlink:href="#U" x="344.871" y="260.836"/><use xlink:href="#V" x="348.777" y="260.836"/><use xlink:href="#D" x="352.977" y="260.836"/><use xlink:href="#U" x="360.77" y="260.836"/><use xlink:href="#P" x="364.676" y="260.836"/><use xlink:href="#W" x="372.586" y="260.836"/><use xlink:href="#F" x="380.359" y="260.836"/><use xlink:href="#B" x="382.527" y="260.836"/><use xlink:href="#X" x="386.336" y="260.836"/><use xlink:href="#K" x="394.773" y="260.836"/><use xlink:href="#K" x="402.547" y="260.836"/><use xlink:href="#z" x="410.32" y="260.836"/></g><path d="M 148.910156 290.542969 L 176.308594 290.542969 L 176.308594 316.792969 L 148.910156 316.792969 Z M 148.910156 290.542969" fill-rule="evenodd" fill="#fff"/><use xlink:href="#Y" x="149.238" y="311.191"/><use xlink:href="#u" x="158.379" y="311.191"/><use xlink:href="#Z" x="162.871" y="311.191"/><use xlink:href="#aa" x="168.301" y="311.191"/><path d="M 197.308594 283.667969 L 385.308594 283.667969 L 385.308594 323.667969 L 197.308594 323.667969 Z M 197.308594 283.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 289.667969 L 197.308594 283.667969 C 193.996094 283.667969 191.308594 286.355469 191.308594 289.667969 Z M 197.308594 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 385.308594 289.667969 L 391.308594 289.667969 C 391.308594 286.355469 388.625 283.667969 385.308594 283.667969 Z M 385.308594 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.308594 289.667969 L 391.308594 289.667969 L 391.308594 317.667969 L 191.308594 317.667969 Z M 191.308594 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 317.667969 L 191.308594 317.667969 C 191.308594 320.980469 193.996094 323.667969 197.308594 323.667969 Z M 197.308594 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 385.308594 317.667969 L 385.308594 323.667969 C 388.625 323.667969 391.308594 320.980469 391.308594 317.667969 Z M 385.308594 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.00943 28.414598 L 43.40943 28.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 30.414598 L 43.40943 30.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 28.414598 L 34.00943 28.414598 C 33.843805 28.414598 33.70943 28.548973 33.70943 28.714598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 43.70943 28.714598 L 43.70943 28.714598 C 43.70943 28.548973 43.57525 28.414598 43.40943 28.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 28.714598 L 33.70943 30.114598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 43.70943 28.714598 L 43.70943 30.114598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 30.114598 L 33.70943 30.114598 C 33.70943 30.280223 33.843805 30.414598 34.00943 30.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 43.40943 30.414598 L 43.40943 30.414598 C 43.57525 30.414598 43.70943 30.280223 43.70943 30.114598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 113.960938 361.773438 L 176.3125 361.773438 L 176.3125 388.023438 L 113.960938 388.023438 Z M 113.960938 361.773438" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#ab" x="114.883" y="382.422"/><use xlink:href="#ac" x="123.789" y="382.422"/><use xlink:href="#ad" x="128.555" y="382.422"/><use xlink:href="#s" x="137.461" y="382.422"/><use xlink:href="#Y" x="141.348" y="382.422"/><use xlink:href="#ae" x="149.941" y="382.422"/><use xlink:href="#o" x="158.848" y="382.422"/><use xlink:href="#q" x="167.754" y="382.422"/></g><path d="M 197.308594 354.894531 L 305.308594 354.894531 L 305.308594 394.894531 L 197.308594 394.894531 Z M 197.308594 354.894531" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 360.894531 L 197.308594 354.894531 C 193.996094 354.894531 191.308594 357.582031 191.308594 360.894531 Z M 197.308594 360.894531" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 305.308594 360.894531 L 311.308594 360.894531 C 311.308594 357.582031 308.625 354.894531 305.308594 354.894531 Z M 305.308594 360.894531" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 191.308594 360.894531 L 311.308594 360.894531 L 311.308594 388.894531 L 191.308594 388.894531 Z M 191.308594 360.894531" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 197.308594 388.894531 L 191.308594 388.894531 C 191.308594 392.210938 193.996094 394.894531 197.308594 394.894531 Z M 197.308594 388.894531" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 305.308594 388.894531 L 305.308594 394.894531 C 308.625 394.894531 311.308594 392.210938 311.308594 388.894531 Z M 305.308594 388.894531" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 34.00943 31.975927 L 39.40943 31.975927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 33.975927 L 39.40943 33.975927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 34.00943 31.975927 L 34.00943 31.975927 C 33.843805 31.975927 33.70943 32.110302 33.70943 32.275927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 39.70943 32.275927 L 39.70943 32.275927 C 39.70943 32.110302 39.57525 31.975927 39.40943 31.975927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 32.275927 L 33.70943 33.675927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 39.70943 32.275927 L 39.70943 33.675927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 33.70943 33.675927 L 33.70943 33.675927 C 33.70943 33.841747 33.843805 33.975927 34.00943 33.975927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 39.40943 33.975927 L 39.40943 33.975927 C 39.57525 33.975927 39.70943 33.841747 39.70943 33.675927" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 477.308594 283.667969 L 605.308594 283.667969 L 605.308594 323.667969 L 477.308594 323.667969 Z M 477.308594 283.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 477.308594 289.667969 L 477.308594 283.667969 C 473.996094 283.667969 471.308594 286.355469 471.308594 289.667969 Z M 477.308594 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.308594 289.667969 L 611.308594 289.667969 C 611.308594 286.355469 608.625 283.667969 605.308594 283.667969 Z M 605.308594 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 471.308594 289.667969 L 611.308594 289.667969 L 611.308594 317.667969 L 471.308594 317.667969 Z M 471.308594 289.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 477.308594 317.667969 L 471.308594 317.667969 C 471.308594 320.980469 473.996094 323.667969 477.308594 323.667969 Z M 477.308594 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 605.308594 317.667969 L 605.308594 323.667969 C 608.625 323.667969 611.308594 320.980469 611.308594 317.667969 Z M 605.308594 317.667969" fill-rule="evenodd" fill="#f2f2f2"/><path d="M 48.00943 28.414598 L 54.40943 28.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 48.00943 30.414598 L 54.40943 30.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 48.00943 28.414598 L 48.00943 28.414598 C 47.843805 28.414598 47.70943 28.548973 47.70943 28.714598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.70943 28.714598 L 54.70943 28.714598 C 54.70943 28.548973 54.57525 28.414598 54.40943 28.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 47.70943 28.714598 L 47.70943 30.114598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.70943 28.714598 L 54.70943 30.114598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 47.70943 30.114598 L 47.70943 30.114598 C 47.70943 30.280223 47.843805 30.414598 48.00943 30.414598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 54.40943 30.414598 L 54.40943 30.414598 C 54.57525 30.414598 54.70943 30.280223 54.70943 30.114598" transform="matrix(20 0 0 20 -482.88 -284.624)" fill="none" stroke-width=".1" stroke="#4d4d4d" stroke-miterlimit="10"/><path d="M 422.511719 290.542969 L 460.3125 290.542969 L 460.3125 316.792969 L 422.511719 316.792969 Z M 422.511719 290.542969" fill-rule="evenodd" fill="#fff"/><g><use xlink:href="#af" x="423.063" y="311.191"/><use xlink:href="#Z" x="431.852" y="311.191"/><use xlink:href="#ag" x="437.672" y="311.191"/><use xlink:href="#Z" x="445.934" y="311.191"/><use xlink:href="#q" x="451.754" y="311.191"/></g></svg>
diff --git a/_images/mercure/chrome.png b/_images/mercure/chrome.png
new file mode 100644
index 00000000000..8ccc55a0a88
Binary files /dev/null and b/_images/mercure/chrome.png differ
diff --git a/_images/mercure/discovery.png b/_images/mercure/discovery.png
new file mode 100644
index 00000000000..0ef38271de6
Binary files /dev/null and b/_images/mercure/discovery.png differ
diff --git a/_images/mercure/schema.png b/_images/mercure/schema.png
new file mode 100644
index 00000000000..4616046e5cc
Binary files /dev/null and b/_images/mercure/schema.png differ
diff --git a/_images/profiler/web-interface.png b/_images/profiler/web-interface.png
new file mode 100644
index 00000000000..2e6c6061892
Binary files /dev/null and b/_images/profiler/web-interface.png differ
diff --git a/_images/sources/README.md b/_images/sources/README.md
new file mode 100644
index 00000000000..9e40e0ac884
--- /dev/null
+++ b/_images/sources/README.md
@@ -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
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
new file mode 100644
index 00000000000..aebdadb4170
Binary files /dev/null and b/_images/sources/form/form-custom-type-postal-address-fragment-names.dia differ
diff --git a/_images/sources/form/form-custom-type-postal-address.dia b/_images/sources/form/form-custom-type-postal-address.dia
new file mode 100644
index 00000000000..35a1eaebfd6
Binary files /dev/null and b/_images/sources/form/form-custom-type-postal-address.dia differ
diff --git a/_includes/_annotation_loader_tip.rst.inc b/_includes/_annotation_loader_tip.rst.inc
index ed43b8f51d8..0f4267b07f5 100644
--- a/_includes/_annotation_loader_tip.rst.inc
+++ b/_includes/_annotation_loader_tip.rst.inc
@@ -8,7 +8,7 @@
     Annotation classes aren't loaded automatically, so you must load them
     using a class loader like this::
 
-        use Composer\Autoload\ClassLoader;
+        use Composer\Autoload\ClassLoader;
         use Doctrine\Common\Annotations\AnnotationRegistry;
 
         /** @var ClassLoader $loader */
diff --git a/_includes/service_container/_my_mailer.rst.inc b/_includes/service_container/_my_mailer.rst.inc
index decb1c1a23b..01eafdfe87a 100644
--- a/_includes/service_container/_my_mailer.rst.inc
+++ b/_includes/service_container/_my_mailer.rst.inc
@@ -15,7 +15,7 @@
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="app.mailer" class="App\Mailer">
diff --git a/best_practices/business-logic.rst b/best_practices/business-logic.rst
index 417f57c004a..81b724a8fd8 100644
--- a/best_practices/business-logic.rst
+++ b/best_practices/business-logic.rst
@@ -57,8 +57,8 @@ post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``::
     }
 
 If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-this class is auto-registered as a service whose ID is ``App\Utils\Slugger`` (or
-simply ``Slugger::class`` if the class is already imported in your code).
+this class is auto-registered as a service with the ID ``App\Utils\Slugger`` (to
+prevent against typos, import the class and write ``Slugger::class`` in your code).
 
 .. best-practice::
 
@@ -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
-use any of the other formats if you prefer another format.
+We recommend YAML because it's friendly to newcomers and concise, but you can
+use whatever format you like.
 
 Using a Persistence Layer
 -------------------------
@@ -122,6 +122,15 @@ 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.
+
+Doctrine support is not enabled by default in Symfony. So to use Doctrine
+as shown in the examples below you will need to install :doc:`Doctrine ORM support </doctrine>`
+by executing the following command:
+
+.. code-block:: terminal
+
+    $ composer require symfony/orm-pack
+
 Just like with business logic, we recommend storing Doctrine entities in the
 ``src/Entity/`` directory.
 
@@ -154,8 +163,8 @@ looking for mapping information::
 
     namespace App\Entity;
 
-    use Doctrine\ORM\Mapping as ORM;
     use Doctrine\Common\Collections\ArrayCollection;
+    use Doctrine\ORM\Mapping as ORM;
 
     /**
      * @ORM\Entity
@@ -226,7 +235,7 @@ the following command to install the Doctrine fixtures bundle:
 
 .. code-block:: terminal
 
-    $ composer require "doctrine/doctrine-fixtures-bundle"
+    $ composer require --dev doctrine/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
index 33a781edef3..80d4273c6a1 100644
--- a/best_practices/configuration.rst
+++ b/best_practices/configuration.rst
@@ -6,8 +6,6 @@ and security credentials) and different environments (development, production).
 That's why Symfony recommends that you split the application configuration into
 three parts.
 
-.. _config-parameters.yml:
-
 Infrastructure-Related Configuration
 ------------------------------------
 
@@ -18,9 +16,8 @@ application behavior.
 .. best-practice::
 
     Define the infrastructure-related configuration options as
-    :doc:`environment variables </configuration/external_parameters>`. 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:
@@ -53,8 +50,6 @@ To override these variables with machine-specific or sensitive values, create a
     environment variables, exposing sensitive information such as the database
     credentials.
 
-.. _best-practices-canonical-parameters:
-
 Canonical Parameters
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -88,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.
 
@@ -104,8 +99,8 @@ paginated results.
     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:
+Symfony applications 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
 
@@ -142,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 can now easily access these values,
-whereas they cannot access the container parameters::
+And Doctrine entities and repositories can access these values too, whereas they
+cannot access the container parameters::
 
     namespace App\Repository;
 
@@ -159,7 +154,7 @@ whereas they cannot access the container parameters::
     }
 
 The only notable disadvantage of using constants for this kind of configuration
-values is that you cannot redefine them easily in your tests.
+values is that it's complicated to redefine their values in your tests.
 
 Parameter Naming
 ----------------
diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst
index 64538972c26..c2e9827b32e 100644
--- a/best_practices/controllers.rst
+++ b/best_practices/controllers.rst
@@ -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
-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).
+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 (unless you're using a
+view layer).
 
 What does the Controller look like
 ----------------------------------
@@ -128,7 +128,7 @@ Fetching Services
 
 If you extend the base ``AbstractController`` class, 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: most easily done by
+Instead, you must use dependency injection to fetch services by
 :ref:`type-hinting action method arguments <controller-accessing-services>`:
 
 .. best-practice::
@@ -218,9 +218,9 @@ flexible::
         // ...
     }
 
-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.
+The point is this: the ParamConverter shortcut is great for most situations.
+However, there is nothing wrong with querying for entities directly if the
+ParamConverter would get complicated.
 
 Pre and Post Hooks
 ------------------
diff --git a/best_practices/creating-the-project.rst b/best_practices/creating-the-project.rst
index 6ea123c0b6f..2c5ea8a5d55 100644
--- a/best_practices/creating-the-project.rst
+++ b/best_practices/creating-the-project.rst
@@ -39,10 +39,9 @@ create files and execute the following commands:
 This command creates a new directory called ``blog`` that contains a fresh new
 project based on the most recent stable Symfony version available.
 
-.. tip::
+.. seealso::
 
-    The technical requirements to run Symfony are simple. If you want to check
-    if your system meets those requirements, read :doc:`/reference/requirements`.
+    Check out the :ref:`technical requirements for running Symfony applications <symfony-tech-requirements>`.
 
 Structuring the Application
 ---------------------------
@@ -76,13 +75,13 @@ 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 used bundles to divide their code into logical features: UserBundle,
+applications used 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, if InvoiceBundle depends on
-ProductBundle, then there's no advantage to having two separate bundles.
+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.
 
 .. best-practice::
 
diff --git a/best_practices/forms.rst b/best_practices/forms.rst
index 31ffa4d5707..07596e73e54 100644
--- a/best_practices/forms.rst
+++ b/best_practices/forms.rst
@@ -21,11 +21,11 @@ PHP class::
 
     use App\Entity\Post;
     use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
+    use Symfony\Component\Form\Extension\Core\Type\EmailType;
+    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
-    use Symfony\Component\Form\Extension\Core\Type\EmailType;
-    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
 
     class PostType extends AbstractType
     {
@@ -103,9 +103,9 @@ some developers configure form buttons in the controller::
 
     use App\Entity\Post;
     use App\Form\PostType;
-    use Symfony\Component\HttpFoundation\Request;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\HttpFoundation\Request;
 
     class PostController extends AbstractController
     {
@@ -134,7 +134,7 @@ view layer:
     {{ form_start(form) }}
         {{ form_widget(form) }}
 
-        <input type="submit" class="btn" value="Create" />
+        <input type="submit" class="btn" value="Create"/>
     {{ form_end(form) }}
 
 Validation
@@ -177,7 +177,7 @@ One of the simplest ways - which is especially useful during development -
 is to render the form tags and use the ``form_widget()`` function to render
 all of the fields:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ form_start(form, {attr: {class: 'my-form-class'} }) }}
         {{ form_widget(form) }}
@@ -212,6 +212,8 @@ Handling a form submit usually follows a similar template::
         // render the template
     }
 
+.. _best-practice-handle-form:
+
 We recommend that you use a single action for both rendering the form and
 handling the form submit. For example, you *could* have a ``new()`` action that
 *only* renders the form and a ``create()`` action that *only* processes the form
diff --git a/best_practices/introduction.rst b/best_practices/introduction.rst
index 3bce1615273..7575eb8c408 100644
--- a/best_practices/introduction.rst
+++ b/best_practices/introduction.rst
@@ -19,13 +19,13 @@ What is this Guide About?
 -------------------------
 
 This guide aims to fix that by describing the **best practices for developing
-web apps with the Symfony full-stack Framework**. These are best practices that
-fit the philosophy of the framework as envisioned by its original creator
+web applications with the Symfony full-stack Framework**. These are best practices
+that fit the philosophy of the framework as envisioned by its original creator
 `Fabien Potencier`_.
 
 .. note::
 
-    **Best practice** is a noun that means *"a well defined 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.
@@ -44,8 +44,8 @@ then **extend and fit to your specific needs**:
 
 We know that old habits die hard and some of you will be shocked by some
 of these best practices. But by following these, you'll be able to develop
-apps faster, with less complexity and with the same or even higher quality.
-It's also a moving target that will continue to improve.
+applications faster, with less complexity and with the same or even higher
+quality. It's also a moving target that will continue to improve.
 
 Keep in mind that these are **optional recommendations** that you and your
 team may or may not follow to develop Symfony applications. If you want to
diff --git a/best_practices/security.rst b/best_practices/security.rst
index 957d8bedfdd..bd68fb21b4d 100644
--- a/best_practices/security.rst
+++ b/best_practices/security.rst
@@ -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.
-For this reason, you only need *one* firewall entry. There are exceptions
-of course, especially if you have separated web and API sections on your
-site. But the point is to 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, you will 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
@@ -39,7 +39,7 @@ remain resistant to brute-force search attacks.
 
 .. note::
 
-    :ref:`Argon2i <reference-security-argon2i>` is the hashing algorithm as
+    :ref:`Sodium <reference-security-sodium>` is the hashing algorithm as
     recommended by industry standards, but this won't be available to you unless
     you are using PHP 7.2+ or have the `libsodium`_ extension installed.
     ``bcrypt`` is sufficient for most applications.
@@ -105,13 +105,10 @@ The @Security Annotation
 ------------------------
 
 For controlling access on a controller-by-controller basis, use the ``@Security``
-annotation whenever possible. It's easy to read and is placed consistently
-above each action.
+annotation whenever possible. Placing it above each action makes it consistent and readable.
 
 In our application, you need the ``ROLE_ADMIN`` in order to create a new post.
-Using ``@Security``, this looks like:
-
-.. code-block:: php
+Using ``@Security``, this looks like::
 
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
     use Symfony\Component\Routing\Annotation\Route;
@@ -121,7 +118,7 @@ Using ``@Security``, this looks like:
      * Displays a form to create a new Post entity.
      *
      * @Route("/new", name="admin_post_new")
-     * @Security("has_role('ROLE_ADMIN')")
+     * @Security("is_granted('ROLE_ADMIN')")
      */
     public function new()
     {
@@ -153,18 +150,18 @@ Notice that this requires the use of the `ParamConverter`_, which automatically
 queries for the ``Post`` object and puts it on the ``$post`` argument. This
 is what makes it possible to use the ``post`` variable in the expression.
 
-This has one major drawback: an expression in an annotation cannot easily
+This has one major drawback: an expression in an annotation cannot
 be reused in other parts of the application. Imagine that you want to add
 a link in a template that will only be seen by authors. Right now you'll
 need to repeat the expression code using Twig syntax:
 
-.. code-block:: html+jinja
+.. code-block:: html+twig
 
     {% if app.user and app.user.email == post.authorEmail %}
         <a href=""> ... </a>
     {% endif %}
 
-The easiest solution - if your logic is simple enough - is to add a new method
+A good solution - if your logic is simple enough - can be to add a new method
 to the ``Post`` entity that checks if a given user is its author::
 
     // src/Entity/Post.php
@@ -200,7 +197,7 @@ Now you can reuse this method both in the template and in the security expressio
         // ...
     }
 
-.. code-block:: html+jinja
+.. code-block:: html+twig
 
     {% if post.isAuthor(app.user) %}
         <a href=""> ... </a>
@@ -359,7 +356,7 @@ via the even easier shortcut in a controller::
         $this->denyAccessUnlessGranted('edit', $post);
 
         // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
-        // use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface
+        // use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
         //
         // ...
         //
@@ -379,6 +376,4 @@ via the even easier shortcut in a controller::
 Next: :doc:`/best_practices/web-assets`
 
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
-.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
 .. _`libsodium`: https://pecl.php.net/package/libsodium
diff --git a/best_practices/templates.rst b/best_practices/templates.rst
index 79633868ecf..6570690dc56 100644
--- a/best_practices/templates.rst
+++ b/best_practices/templates.rst
@@ -44,7 +44,7 @@ and ``edit_form.html.twig`` instead of ``EditForm.html.twig``).
     Use a prefixed underscore for partial templates in template names.
 
 You often want to reuse template code using the ``include`` function to avoid
-redundant code. To determine those partials easily in the filesystem you should
+redundant code. To determine those partials in the filesystem you should
 prefix partials and any other template without HTML body or ``extends`` tag
 with a single underscore.
 
@@ -119,4 +119,3 @@ be used as a Twig extension.
 Next: :doc:`/best_practices/forms`
 
 .. _`Twig`: https://twig.symfony.com/
-.. _`Parsedown`: http://parsedown.org/
diff --git a/best_practices/tests.rst b/best_practices/tests.rst
index 2c1230cc452..856ec055271 100644
--- a/best_practices/tests.rst
+++ b/best_practices/tests.rst
@@ -106,8 +106,8 @@ The built-in functional testing client is great, but it can't be used to
 test any JavaScript behavior on your pages. If you need to test this, consider
 using the `Mink`_ library from within PHPUnit.
 
-Of course, if you have a heavy JavaScript front-end, you should consider using
-pure JavaScript-based testing tools.
+If you have a heavy JavaScript frontend, you should consider using pure
+JavaScript-based testing tools.
 
 Learn More about Functional Tests
 ---------------------------------
diff --git a/bundles.rst b/bundles.rst
index 2f0fb608c04..cdef74b5c87 100644
--- a/bundles.rst
+++ b/bundles.rst
@@ -18,7 +18,7 @@ SecurityBundle, DebugBundle, etc.) They are also used to add new features in
 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
@@ -37,7 +37,7 @@ file::
 
 .. tip::
 
-    In a default Symfony application that uses :doc:`Symfony Flex </setup/flex>`,
+    In a default Symfony application that uses :ref:`Symfony Flex <symfony-flex>`,
     bundles are enabled/disabled automatically for you when installing/removing
     them, so you don't need to look at or edit this ``bundles.php`` file.
 
diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst
index c7572451c4f..431a267db97 100644
--- a/bundles/best_practices.rst
+++ b/bundles/best_practices.rst
@@ -4,10 +4,10 @@
 Best Practices for Reusable Bundles
 ===================================
 
-This article is all about how to structure your **reusable bundles** so that
-they're easy to configure and extend. Reusable bundles are those meant to be
-shared privately across many company projects or publicly so any Symfony project
-can install them.
+This article is all about how to structure your **reusable bundles** to be
+configurable and extendable. Reusable bundles are those meant to be shared
+privately across many company projects or publicly so any Symfony project can
+install them.
 
 .. index::
    pair: Bundle; Naming conventions
@@ -197,9 +197,9 @@ of Symfony and the latest beta release:
         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
@@ -246,11 +246,11 @@ Installation
 ------------
 
 Bundles should set ``"type": "symfony-bundle"`` in their ``composer.json`` file.
-With this, :doc:`Symfony Flex </setup/flex>` will be able to automatically
+With this, :ref:`Symfony Flex <symfony-flex>` will be able to automatically
 enable your bundle when it's installed.
 
 If your bundle requires any setup (e.g. configuration, new files, changes to
-`.gitignore`, etc), then you should create a `Symfony Flex recipe`_.
+``.gitignore``, etc), then you should create a `Symfony Flex recipe`_.
 
 Documentation
 -------------
@@ -306,27 +306,15 @@ following standardized instructions in your ``README.md`` file.
         ### 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
-        <?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
@@ -363,29 +351,13 @@ following standardized instructions in your ``README.md`` file.
         ~~~~~~~~~~~~~~~~~~~~~~~~~
 
         Then, enable the bundle by adding it to the list of registered bundles
-        in the ``app/AppKernel.php`` file of your project:
-
-        .. code-block:: php
-
-            <?php
-            // 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
 
@@ -450,7 +422,7 @@ The end user can provide values in any configuration file:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <parameters>
                 <parameter key="acme_blog.author.email">fabien@example.com</parameter>
@@ -521,7 +493,12 @@ The ``composer.json`` file should include at least the following metadata:
 
 ``autoload``
     This information is used by Symfony to load the classes of the bundle. It's
-    recommended to use the `PSR-4`_ autoload standard.
+    recommended to use the `PSR-4`_ autoload standard: use the namespace as key,
+    and the location of the bundle's main class (relative to ``composer.json``)
+    as value. For example, if the main class is located in the bundle root
+    directory: ``"autoload": { "psr-4": { "SomeVendor\\BlogBundle\\": "" } }``.
+    If the main class is located in the ``src/`` directory of the bundle:
+    ``"autoload": { "psr-4": { "SomeVendor\\BlogBundle\\": "src/" } }``.
 
 In order to make it easier for developers to find your bundle, register it on
 `Packagist`_, the official repository for Composer packages.
@@ -554,4 +531,4 @@ Learn more
 .. _`choose any license`: https://choosealicense.com/
 .. _`valid license identifier`: https://spdx.org/licenses/
 .. _`Travis CI`: https://travis-ci.org/
-.. _`Travis Cron`: https://docs.travis-ci.com/user/cron-jobs/
+.. _`Travis cron`: https://docs.travis-ci.com/user/cron-jobs/
diff --git a/bundles/configuration.rst b/bundles/configuration.rst
index a61cbe8a6e1..f8927103123 100644
--- a/bundles/configuration.rst
+++ b/bundles/configuration.rst
@@ -29,12 +29,12 @@ as integration of other related components:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:form />
+                <framework:form/>
             </framework:config>
         </container>
 
@@ -48,8 +48,8 @@ Using the Bundle Extension
 --------------------------
 
 Imagine you are creating a new bundle - AcmeSocialBundle - which provides
-integration with Twitter, etc. To make your bundle easy to use, you want to
-allow users to configure it with some configuration that looks like this:
+integration with Twitter. To make your bundle configurable to the user, you
+can add some configuration that looks like this:
 
 .. configuration-block::
 
@@ -69,13 +69,13 @@ allow users to configure it with some configuration that looks like this:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:acme-social="http://example.org/schema/dic/acme_social"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
-           <acme-social:config>
-               <acme-social:twitter client-id="123" client-secret="your_secret" />
-           </acme-social:config>
+            <acme-social:config>
+                <acme-social:twitter client-id="123" client-secret="your_secret"/>
+            </acme-social:config>
 
-           <!-- ... -->
+            <!-- ... -->
         </container>
 
     .. code-block:: php
@@ -180,10 +180,9 @@ The ``Configuration`` class to handle the sample configuration looks like::
     {
         public function getConfigTreeBuilder()
         {
-            $treeBuilder = new TreeBuilder();
-            $rootNode = $treeBuilder->root('acme_social');
+            $treeBuilder = new TreeBuilder('acme_social');
 
-            $rootNode
+            $treeBuilder->getRootNode()
                 ->children()
                     ->arrayNode('twitter')
                         ->children()
@@ -198,6 +197,10 @@ The ``Configuration`` class to handle the sample configuration looks like::
         }
     }
 
+.. deprecated:: 4.2
+
+    Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.
+
 .. seealso::
 
     The ``Configuration`` class can be much more complicated than shown here,
@@ -237,7 +240,7 @@ For example, imagine your bundle has the following example config:
     <container xmlns="http://symfony.com/schema/dic/services"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://symfony.com/schema/dic/services
-            http://symfony.com/schema/dic/services/services-1.0.xsd">
+            https://symfony.com/schema/dic/services/services-1.0.xsd">
 
         <services>
             <service id="acme.social.twitter_client" class="Acme\SocialBundle\TwitterClient">
@@ -252,8 +255,8 @@ In your extension, you can load this and dynamically set its arguments::
     // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
     // ...
 
-    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
     use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 
     public function load(array $configs, ContainerBuilder $container)
     {
@@ -298,9 +301,7 @@ In your extension, you can load this and dynamically set its arguments::
     Using the Config component is fully optional. The ``load()`` method gets an
     array of configuration values. You can instead parse these arrays yourself
     (e.g. by overriding configurations and using :phpfunction:`isset` to check
-    for the existence of a value). Be aware that it'll be very hard to support XML.
-
-    .. code-block:: php
+    for the existence of a value). Be aware that it'll be very hard to support XML::
 
         public function load(array $configs, ContainerBuilder $container)
         {
@@ -380,7 +381,7 @@ Providing an XML Schema
 
 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 (an xsd file). This XSD file is used by IDEs for auto completion and
+Definition (an XSD 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
@@ -408,7 +409,7 @@ can place it anywhere you like. You should return this path as the base path::
     }
 
 Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
-``http://acme_company.com/schema/dic/hello/hello-1.0.xsd``:
+``https://acme_company.com/schema/dic/hello/hello-1.0.xsd``:
 
 .. code-block:: xml
 
@@ -418,7 +419,7 @@ Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:acme-hello="http://acme_company.com/schema/dic/hello"
         xsi:schemaLocation="http://acme_company.com/schema/dic/hello
-            http://acme_company.com/schema/dic/hello/hello-1.0.xsd">
+            https://acme_company.com/schema/dic/hello/hello-1.0.xsd">
 
         <acme-hello:config>
             <!-- ... -->
diff --git a/bundles/extension.rst b/bundles/extension.rst
index adef497bcf8..2518b51a93f 100644
--- a/bundles/extension.rst
+++ b/bundles/extension.rst
@@ -7,7 +7,8 @@ How to Load Service Configuration inside a Bundle
 
 Services created by bundles are not defined in the main ``config/services.yaml``
 file used by the application but in the bundles themselves. This article
-explains how to create and load those bundle services files.
+explains how to create and load service files using the bundle directory
+structure.
 
 Creating an Extension Class
 ---------------------------
@@ -88,8 +89,8 @@ but it is more common if you put these definitions in a configuration file
 For instance, assume you have a file called ``services.xml`` in the
 ``Resources/config/`` directory of your bundle, your ``load()`` method looks like::
 
-    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
     use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 
     // ...
     public function load(array $configs, ContainerBuilder $container)
diff --git a/bundles/index.rst b/bundles/index.rst
index 78dd8c6d4fb..e4af2cd357b 100644
--- a/bundles/index.rst
+++ b/bundles/index.rst
@@ -7,7 +7,6 @@ Bundles
     :maxdepth: 2
 
     override
-    inheritance
     best_practices
     configuration
     extension
diff --git a/bundles/inheritance.rst b/bundles/inheritance.rst
deleted file mode 100644
index d8ce372adb4..00000000000
--- a/bundles/inheritance.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. index::
-   single: Bundle; Inheritance
-
-How to Use Bundle Inheritance to Override Parts of a Bundle
-===========================================================
-
-.. caution::
-
-    Bundle inheritance was removed in Symfony 4.0, but you can
-    :doc:`override any part of a bundle </bundles/override>` without
-    using bundle inheritance.
diff --git a/bundles/override.rst b/bundles/override.rst
index f4cadb965b1..726c6770a51 100644
--- a/bundles/override.rst
+++ b/bundles/override.rst
@@ -45,7 +45,7 @@ extend from the original template, not from the overridden one:
 
     {# templates/bundles/FOSUserBundle/Registration/confirmed.html.twig #}
     {# the special '!' prefix avoids errors when extending from an overridden template #}
-    {% extends "@!FOSUserBundle/Registration/confirmed.html.twig" %}
+    {% extends "@!FOSUser/Registration/confirmed.html.twig" %}
 
     {% block some_block %}
         ...
@@ -143,7 +143,7 @@ to a new validation group:
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="FOS\UserBundle\Model\User">
                 <property name="plainPassword">
@@ -178,6 +178,6 @@ For this reason, you can override any bundle translation file from the main
 
 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
diff --git a/bundles/prepend_extension.rst b/bundles/prepend_extension.rst
index dd8841ec2bd..f742df5ec69 100644
--- a/bundles/prepend_extension.rst
+++ b/bundles/prepend_extension.rst
@@ -27,9 +27,9 @@ To give an Extension the power to do this, it needs to implement
     // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
     namespace Acme\HelloBundle\DependencyInjection;
 
-    use Symfony\Component\HttpKernel\DependencyInjection\Extension;
-    use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
+    use Symfony\Component\HttpKernel\DependencyInjection\Extension;
 
     class AcmeHelloExtension extends Extension implements PrependExtensionInterface
     {
@@ -122,13 +122,13 @@ registered and the ``entity_manager_name`` setting for ``acme_hello`` is set to
             xmlns:acme-something="http://example.org/schema/dic/acme_something"
             xmlns:acme-other="http://example.org/schema/dic/acme_other"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <acme-something:config use-acme-goodbye="false">
                 <acme-something:entity-manager-name>non_default</acme-something:entity-manager-name>
             </acme-something:config>
 
-            <acme-other:config use-acme-goodbye="false" />
+            <acme-other:config use-acme-goodbye="false"/>
 
         </container>
 
diff --git a/cache.rst b/cache.rst
new file mode 100644
index 00000000000..52d615d541d
--- /dev/null
+++ b/cache.rst
@@ -0,0 +1,652 @@
+.. index::
+    single: Cache
+
+Cache
+=====
+
+Using cache is a great way of making your application run quicker. The Symfony cache
+component is shipped with many adapters to different storages. Every adapter is
+developed for high performance.
+
+Basic uses of the cache looks like this::
+
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    // The callable will only be executed on a cache miss.
+    $value = $pool->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
+
+        // ... do some HTTP request or heavy computations
+        $computedValue = 'foobar';
+
+        return $computedValue;
+    });
+
+    echo $value; // 'foobar'
+
+    // ... and to remove the cache key
+    $pool->delete('my_cache_key');
+
+Symfony supports the Cache Contracts, PSR-6/16 and Doctrine Cache interfaces.
+You can read more about these at the :doc:`component documentation </components/cache>`.
+
+.. versionadded:: 4.2
+
+    The cache contracts were introduced in Symfony 4.2.
+
+.. _cache-configuration-with-frameworkbundle:
+
+Configuring Cache with FrameworkBundle
+--------------------------------------
+
+When configuring the cache component there are a few concepts you should know
+of:
+
+**Pool**
+    This is a service that you will interact with. Each pool will always have
+    its own namespace and cache items. There is never a conflict between pools.
+**Adapter**
+    An adapter is a *template* that you use to create Pools.
+**Provider**
+    A provider is a service that some adapters are using to connect to the storage.
+    Redis and Memcached are example of such adapters. If a DSN is used as the
+    provider then a service is automatically created.
+
+There are two pools that are always enabled by default. They are ``cache.app`` and
+``cache.system``. The system cache is used for things like annotations, serializer,
+and validation. The ``cache.app`` can be used in your code. You can configure which
+adapter (template) they use by using the ``app`` and ``system`` key like:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                app: cache.adapter.filesystem
+                system: cache.adapter.system
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <framework:cache app="cache.adapter.filesystem"
+                    system="cache.adapter.system"
+                />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'app' => 'cache.adapter.filesystem',
+                'system' => 'cache.adapter.system',
+            ],
+        ]);
+
+The Cache component comes with a series of adapters pre-configured:
+
+* :doc:`cache.adapter.apcu </components/cache/adapters/apcu_adapter>`
+* :doc:`cache.adapter.array </components/cache/adapters/array_cache_adapter>`
+* :doc:`cache.adapter.doctrine </components/cache/adapters/doctrine_adapter>`
+* :doc:`cache.adapter.filesystem </components/cache/adapters/filesystem_adapter>`
+* :doc:`cache.adapter.memcached </components/cache/adapters/memcached_adapter>`
+* :doc:`cache.adapter.pdo </components/cache/adapters/pdo_doctrine_dbal_adapter>`
+* :doc:`cache.adapter.psr6 </components/cache/adapters/proxy_adapter>`
+* :doc:`cache.adapter.redis </components/cache/adapters/redis_adapter>`
+
+Some of these adapters could be configured via shortcuts. Using these shortcuts
+will create pool with service id of ``cache.[type]``
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                directory: '%kernel.cache_dir%/pools' # Only used with cache.adapter.filesystem
+
+                # service: cache.doctrine
+                default_doctrine_provider: 'app.doctrine_cache'
+                # service: cache.psr6
+                default_psr6_provider: 'app.my_psr6_service'
+                # service: cache.redis
+                default_redis_provider: 'redis://localhost'
+                # service: cache.memcached
+                default_memcached_provider: 'memcached://localhost'
+                # service: cache.pdo
+                default_pdo_provider: 'doctrine.dbal.default_connection'
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <!--
+                default_doctrine_provider: Service: cache.doctrine
+                default_psr6_provider: Service: cache.psr6
+                default_redis_provider: Service: cache.redis
+                default_memcached_provider: Service: cache.memcached
+                default_pdo_provider: Service: cache.pdo
+                -->
+                <framework:cache directory="%kernel.cache_dir%/pools"
+                    default_doctrine_provider="app.doctrine_cache"
+                    default_psr6_provider="app.my_psr6_service"
+                    default_redis_provider="redis://localhost"
+                    default_memcached_provider="memcached://localhost"
+                    default_pdo_provider="doctrine.dbal.default_connection"
+                />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                // Only used with cache.adapter.filesystem
+                'directory' => '%kernel.cache_dir%/pools',
+
+                // Service: cache.doctrine
+                'default_doctrine_provider' => 'app.doctrine_cache',
+                // Service: cache.psr6
+                'default_psr6_provider' => 'app.my_psr6_service',
+                // Service: cache.redis
+                'default_redis_provider' => 'redis://localhost',
+                // Service: cache.memcached
+                'default_memcached_provider' => 'memcached://localhost',
+                // Service: cache.pdo
+                'default_pdo_provider' => 'doctrine.dbal.default_connection',
+            ],
+        ]);
+
+Creating Custom (Namespaced) Pools
+----------------------------------
+
+You can also create more customized pools:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                default_memcached_provider: 'memcached://localhost'
+
+                pools:
+                    # creates a "custom_thing.cache" service
+                    # autowireable via "CacheInterface $customThingCache"
+                    # uses the "app" cache configuration
+                    custom_thing.cache:
+                        adapter: cache.app
+
+                    # creates a "my_cache_pool" service
+                    # autowireable via "CacheInterface $myCachePool"
+                    my_cache_pool:
+                        adapter: cache.adapter.array
+
+                    # uses the default_memcached_provider from above
+                    acme.cache:
+                        adapter: cache.adapter.memcached
+
+                    # control adapter's configuration
+                    foobar.cache:
+                        adapter: cache.adapter.memcached
+                        provider: 'memcached://user:password@example.com'
+
+                    # uses the "foobar.cache" pool as its backend but controls
+                    # the lifetime and (like all pools) has a separate cache namespace
+                    short_cache:
+                        adapter: foobar.cache
+                        default_lifetime: 60
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <framework:cache default_memcached_provider="memcached://localhost">
+                    <framework:pool name="custom_thing.cache" adapter="cache.app"/>
+                    <framework:pool name="my_cache_pool" adapter="cache.adapter.array"/>
+                    <framework:pool name="acme.cache" adapter="cache.adapter.memcached"/>
+                    <framework:pool name="foobar.cache" adapter="cache.adapter.memcached" provider="memcached://user:password@example.com"/>
+                    <framework:pool name="short_cache" adapter="foobar.cache" default_lifetime="60"/>
+                </framework:cache>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'default_memcached_provider' => 'memcached://localhost',
+                'pools' => [
+                    'custom_thing.cache' => [
+                        'adapter' => 'cache.app',
+                    ],
+                    'my_cache_pool' => [
+                        'adapter' => 'cache.adapter.array',
+                    ],
+                    'acme.cache' => [
+                        'adapter' => 'cache.adapter.memcached',
+                    ],
+                    'foobar.cache' => [
+                        'adapter' => 'cache.adapter.memcached',
+                        'provider' => 'memcached://user:password@example.com',
+                    ],
+                    'short_cache' => [
+                        'adapter' => 'foobar.cache',
+                        'default_lifetime' => 60,
+                    ],
+                ],
+            ],
+        ]);
+
+Each pool manages a set of independent cache keys: keys of different pools
+*never* collide, even if they share the same backend. This is achieved by prefixing
+keys with a namespace that's generated by hashing the name of the pool, the name
+of the compiled container class and a :ref:`configurable seed<reference-cache-prefix-seed>`
+that defaults to the project directory.
+
+Each custom pool becomes a service where the service id is the name of the pool
+(e.g. ``custom_thing.cache``). An autowiring alias is also created for each pool
+using the camel case version of its name - e.g. ``custom_thing.cache`` can be
+injected automatically by naming the argument ``$customThingCache`` and type-hinting it
+with either :class:`Symfony\\Contracts\\Cache\\CacheInterface` or
+``Psr\Cache\CacheItemPoolInterface``::
+
+    use Symfony\Contracts\Cache\CacheInterface;
+
+    // from a controller method
+    public function listProducts(CacheInterface $customThingCache)
+    {
+        // ...
+    }
+
+    // in a service
+    public function __construct(CacheInterface $customThingCache)
+    {
+        // ...
+    }
+
+Custom Provider Options
+-----------------------
+
+Some providers have specific options that can be configured. The
+:doc:`RedisAdapter </components/cache/adapters/redis_adapter>` allows you to
+create providers with option ``timeout``, ``retry_interval``. etc. To use these
+options with non-default values you need to create your own ``\Redis`` provider
+and use that when configuring the pool.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                pools:
+                    cache.my_redis:
+                        adapter: cache.adapter.redis
+                        provider: app.my_custom_redis_provider
+
+        services:
+            app.my_custom_redis_provider:
+                class: \Redis
+                factory: ['Symfony\Component\Cache\Adapter\RedisAdapter', 'createConnection']
+                arguments:
+                    - 'redis://localhost'
+                    - { retry_interval: 2, timeout: 10 }
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <framework:cache>
+                    <framework:pool name="cache.my_redis" adapter="cache.adapter.redis" provider="app.my_custom_redis_provider"/>
+                </framework:cache>
+            </framework:config>
+
+            <services>
+                <service id="app.my_custom_redis_provider" class="\Redis">
+                    <argument>redis://localhost</argument>
+                    <argument type="collection">
+                        <argument key="retry_interval">2</argument>
+                        <argument key="timeout">10</argument>
+                    </argument>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'pools' => [
+                    'cache.my_redis' => [
+                        'adapter' => 'cache.adapter.redis',
+                        'provider' => 'app.my_custom_redis_provider',
+                    ],
+                ],
+            ],
+        ]);
+
+        $container->getDefinition('app.my_custom_redis_provider', \Redis::class)
+            ->addArgument('redis://localhost')
+            ->addArgument([
+                'retry_interval' => 2,
+                'timeout' => 10
+            ]);
+
+Creating a Cache Chain
+----------------------
+
+Different cache adapters have different strengths and weaknesses. Some might be really
+quick but small and some may be able to contain a lot of data but are quite slow.
+To get the best of both worlds you may use a chain of adapters. The idea is to
+first look at the quick adapter and then move on to slower adapters. In the worst
+case the value needs to be recalculated.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                pools:
+                    my_cache_pool:
+                        adapter: cache.adapter.psr6
+                        provider: app.my_cache_chain_adapter
+                    cache.my_redis:
+                        adapter: cache.adapter.redis
+                        provider: 'redis://user:password@example.com'
+                    cache.apcu:
+                        adapter: cache.adapter.apcu
+                    cache.array:
+                        adapter: cache.adapter.array
+
+
+        services:
+            app.my_cache_chain_adapter:
+                class: Symfony\Component\Cache\Adapter\ChainAdapter
+                arguments:
+                    - ['@cache.array', '@cache.apcu', '@cache.my_redis']
+                    - 31536000 # One year
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <framework:cache>
+                    <framework:pool name="my_cache_pool" adapter="cache.adapter.psr6" provider="app.my_cache_chain_adapter"/>
+                    <framework:pool name="cache.my_redis" adapter="cache.adapter.redis" provider="redis://user:password@example.com"/>
+                    <framework:pool name="cache.apcu" adapter="cache.adapter.apcu"/>
+                    <framework:pool name="cache.array" adapter="cache.adapter.array"/>
+                </framework:cache>
+            </framework:config>
+
+            <services>
+                <service id="app.my_cache_chain_adapter" class="Symfony\Component\Cache\Adapter\ChainAdapter">
+                    <argument type="collection">
+                        <argument type="service" value="cache.array"/>
+                        <argument type="service" value="cache.apcu"/>
+                        <argument type="service" value="cache.my_redis"/>
+                    </argument>
+                    <argument>31536000</argument>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'pools' => [
+                    'my_cache_pool' => [
+                        'adapter' => 'cache.adapter.psr6',
+                        'provider' => 'app.my_cache_chain_adapter',
+                    ],
+                    'cache.my_redis' => [
+                        'adapter' => 'cache.adapter.redis',
+                        'provider' => 'redis://user:password@example.com',
+                    ],
+                    'cache.apcu' => [
+                        'adapter' => 'cache.adapter.apcu',
+                    ],
+                    'cache.array' => [
+                        'adapter' => 'cache.adapter.array',
+                    ],
+                ],
+            ],
+        ]);
+
+        $container->getDefinition('app.my_cache_chain_adapter', \Symfony\Component\Cache\Adapter\ChainAdapter::class)
+            ->addArgument([
+                new Reference('cache.array'),
+                new Reference('cache.apcu'),
+                new Reference('cache.my_redis'),
+            ])
+            ->addArgument(31536000);
+
+.. note::
+
+    In this configuration the ``my_cache_pool`` pool is using the ``cache.adapter.psr6``
+    adapter and the ``app.my_cache_chain_adapter`` service as a provider. That is
+    because ``ChainAdapter`` does not support the ``cache.pool`` tag. So it is decorated
+    with the ``ProxyAdapter``.
+
+
+Using Cache Tags
+----------------
+
+In applications with many cache keys it could be useful to organize the data stored
+to be able to invalidate the cache more efficient. One way to achieve that is to
+use cache tags. One or more tags could be added to the cache item. All items with
+the same key could be invalidate with one function call::
+
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    $value0 = $pool->get('item_0', function (ItemInterface $item) {
+        $item->tag(['foo', 'bar']);
+
+        return 'debug';
+    });
+
+    $value1 = $pool->get('item_1', function (ItemInterface $item) {
+        $item->tag('foo');
+
+        return 'debug';
+    });
+
+    // Remove all cache keys tagged with "bar"
+    $pool->invalidateTags(['bar']);
+
+The cache adapter needs to implement :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface``
+to enable this feature. This could be added by using the following configuration.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                pools:
+                    my_cache_pool:
+                        adapter: cache.adapter.redis
+                        tags: true
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <framework:cache>
+                  <framework:pool name="my_cache_pool" adapter="cache.adapter.redis" tags="true"/>
+                </framework:cache>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'pools' => [
+                    'my_cache_pool' => [
+                        'adapter' => 'cache.adapter.redis',
+                        'tags' => true,
+                    ],
+                ],
+            ],
+        ]);
+
+Tags are stored in the same pool by default. This is good in most scenarios. But
+sometimes it might be better to store the tags in a different pool. That could be
+achieved by specifying the adapter.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        framework:
+            cache:
+                pools:
+                    my_cache_pool:
+                        adapter: cache.adapter.redis
+                        tags: tag_pool
+                    tag_pool:
+                        adapter: cache.adapter.apcu
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <framework:config>
+                <framework:cache>
+                  <framework:pool name="my_cache_pool" adapter="cache.adapter.redis" tags="tag_pool"/>
+                  <framework:pool name="tag_pool" adapter="cache.adapter.apcu"/>
+                </framework:cache>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'pools' => [
+                    'my_cache_pool' => [
+                        'adapter' => 'cache.adapter.redis',
+                        'tags' => 'tag_pool',
+                    ],
+                    'tag_pool' => [
+                        'adapter' => 'cache.adapter.apcu',
+                    ],
+                ],
+            ],
+        ]);
+
+.. note::
+
+    The interface :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface` is
+    autowired to the ``cache.app`` service.
+
+Clearing the Cache
+------------------
+
+To clear the cache you can use the ``bin/console cache:pool:clear [pool]`` command.
+That will remove all the entries from your storage and you will have to recalculate
+all values. You can also group your pools into "cache clearers". There are 3 cache
+clearers by default:
+
+* ``cache.global_clearer``
+* ``cache.system_clearer``
+* ``cache.app_clearer``
+
+The global clearer clears all the cache in every pool. The system cache clearer
+is used in the ``bin/console cache:clear`` command. The app clearer is the default
+clearer.
+
+To see all available cache pools:
+
+.. code-block:: terminal
+
+    $ php bin/console cache:pool:list
+
+.. versionadded:: 4.3
+
+    The ``cache:pool:list`` command was introduced in Symfony 4.3.
+
+Clear one pool:
+
+.. code-block:: terminal
+
+    $ php bin/console cache:pool:clear my_cache_pool
+
+Clear all custom pools:
+
+.. code-block:: terminal
+
+    $ php bin/console cache:pool:clear cache.app_clearer
+
+Clear all caches everywhere:
+
+.. code-block:: terminal
+
+    $ php bin/console cache:pool:clear cache.global_clearer
diff --git a/components/asset.rst b/components/asset.rst
index f911c5cad86..625a3ea9f2f 100644
--- a/components/asset.rst
+++ b/components/asset.rst
@@ -30,7 +30,7 @@ simple. Hardcoding URLs can be a disadvantage because:
   is essential for some applications because it allows you to control how
   the assets are cached. The Asset component allows you to define different
   versioning strategies for each package;
-* **Moving assets location** is cumbersome and error-prone: it requires you to
+* **Moving assets' location** is cumbersome and error-prone: it requires you to
   carefully update the URLs of all assets included in all templates. The Asset
   component allows to move assets effortlessly just by changing the base path
   value associated with the package of assets;
@@ -46,8 +46,6 @@ Installation
 
     $ composer require symfony/asset
 
-Alternatively, you can clone the `<https://github.com/symfony/asset>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -225,8 +223,8 @@ If you are also using the :doc:`HttpFoundation </components/http_foundation>`
 component in your project (for instance, in a Symfony application), the ``PathPackage``
 class can take into account the context of the current request::
 
-    use Symfony\Component\Asset\PathPackage;
     use Symfony\Component\Asset\Context\RequestStackContext;
+    use Symfony\Component\Asset\PathPackage;
     // ...
 
     $pathPackage = new PathPackage(
@@ -304,7 +302,7 @@ constructor::
     // result: http://static2.example.com/images/icon.png?v1
 
 For each asset, one of the URLs will be randomly used. But, the selection
-is deterministic, meaning that each asset will be always served by the same
+is deterministic, meaning that each asset will always be served by the same
 domain. This behavior simplifies the management of HTTP cache.
 
 Request Context Aware Assets
@@ -315,8 +313,8 @@ account the context of the current request. In this case, only the request
 scheme is considered, in order to select the appropriate base URL (HTTPs or
 protocol-relative URLs for HTTPs requests, any base URL for HTTP requests)::
 
-    use Symfony\Component\Asset\UrlPackage;
     use Symfony\Component\Asset\Context\RequestStackContext;
+    use Symfony\Component\Asset\UrlPackage;
     // ...
 
     $urlPackage = new UrlPackage(
@@ -341,9 +339,9 @@ In the following example, all packages use the same versioning strategy, but
 they all have different base paths::
 
     use Symfony\Component\Asset\Package;
+    use Symfony\Component\Asset\Packages;
     use Symfony\Component\Asset\PathPackage;
     use Symfony\Component\Asset\UrlPackage;
-    use Symfony\Component\Asset\Packages;
     // ...
 
     $versionStrategy = new StaticVersionStrategy('v1');
@@ -372,8 +370,36 @@ document inside a template::
     echo $packages->getUrl('resume.pdf', 'doc');
     // result: /somewhere/deep/for/documents/resume.pdf?v1
 
+Local Files and Other Protocols
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to HTTP this component supports other protocols (such as ``file://``
+and ``ftp://``). This allows for example to serve local files in order to
+improve performance::
+
+    use Symfony\Component\Asset\UrlPackage;
+    // ...
+
+    $localPackage = new UrlPackage(
+        'file:///path/to/images/',
+        new EmptyVersionStrategy()
+    );
+
+    $ftpPackage = new UrlPackage(
+        'ftp://example.com/images/',
+        new EmptyVersionStrategy()
+    );
+
+    echo $localPackage->getUrl('/logo.png');
+    // result: file:///path/to/images/logo.png
+
+    echo $ftpPackage->getUrl('/logo.png');
+    // result: ftp://example.com/images/logo.png
+
 Learn more
 ----------
 
-.. _Packagist: https://packagist.org/packages/symfony/asset
+* :doc:`How to manage CSS and JavaScript assets in Symfony applications </frontend>`
+* :doc:`WebLink component </components/web_link>` to preload assets using HTTP/2.
+
 .. _`Webpack`: https://webpack.js.org/
diff --git a/components/browser_kit.rst b/components/browser_kit.rst
index e9693042650..1fa554a5c0f 100644
--- a/components/browser_kit.rst
+++ b/components/browser_kit.rst
@@ -10,9 +10,10 @@ The BrowserKit Component
 
 .. note::
 
-    The BrowserKit component can only make internal requests to your application.
-    If you need to make requests to external sites and applications, consider
-    using `Goutte`_, a simple web scraper based on Symfony Components.
+    In Symfony versions prior to 4.3, the BrowserKit component could only make
+    internal requests to your application. Starting from Symfony 4.3, this
+    component can also :ref:`make HTTP requests to any public site <component-browserkit-external-requests>`
+    when using it in combination with the :doc:`HttpClient component </components/http_client>`.
 
 Installation
 ------------
@@ -21,8 +22,6 @@ Installation
 
     $ composer require symfony/browser-kit
 
-Alternatively, you can clone the `<https://github.com/symfony/browser-kit>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Basic Usage
@@ -91,20 +90,25 @@ make AJAX requests::
     // the required HTTP_X_REQUESTED_WITH header is added automatically
     $crawler = $client->xmlHttpRequest('GET', '/');
 
-.. versionadded:: 4.1
-    The ``xmlHttpRequest()`` method was introduced in Symfony 4.1.
-
 Clicking Links
 ~~~~~~~~~~~~~~
 
-The ``Crawler`` object is capable of simulating link clicks. First, pass the
-text content of the link to the ``selectLink()`` method, which returns a
-``Link`` object. Then, pass this object to the ``click()`` method, which
-performs the needed HTTP GET request to simulate the link click::
+The ``Client`` object is capable of simulating link clicks. Pass the text
+content of the link and the client will perform the needed HTTP GET request to
+simulate the link click::
 
     use Acme\Client;
 
     $client = new Client();
+    $client->request('GET', '/product/123');
+
+    $crawler = $client->clickLink('Go elsewhere...');
+
+If you need the :class:`Symfony\\Component\\DomCrawler\\Link` object that
+provides access to the link properties (e.g. ``$link->getMethod()``,
+``$link->getUri()``), use this other method::
+
+    // ...
     $crawler = $client->request('GET', '/product/123');
     $link = $crawler->selectLink('Go elsewhere...')->link();
     $client->click($link);
@@ -112,27 +116,48 @@ performs the needed HTTP GET request to simulate the link click::
 Submitting Forms
 ~~~~~~~~~~~~~~~~
 
-The ``Crawler`` object is also capable of selecting forms. First, select any of
-the form's buttons with the ``selectButton()`` method. Then, use the ``form()``
-method to select the form which the button belongs to.
-
-After selecting the form, fill in its data and send it using the ``submit()``
-method (which makes the needed HTTP POST request to submit the form contents)::
+The ``Client`` object is also capable of submitting forms. First, select the
+form using any of its buttons and then override any of its properties (method,
+field values, etc.) before submitting it::
 
     use Acme\Client;
 
-    // make a real request to an external site
     $client = new Client();
     $crawler = $client->request('GET', 'https://github.com/login');
 
+    // find the form with the 'Log in' button and submit it
+    // 'Log in' can be the text content, id, value or name of a <button> or <input type="submit">
+    $client->submitForm('Log in');
+
+    // the second optional argument lets you override the default form field values
+    $client->submitForm('Log in', [
+        'login' => 'my_user',
+        'password' => 'my_pass',
+        // to upload a file, the value must be the absolute file path
+        'file' => __FILE__,
+    ]);
+
+    // you can override other form options too
+    $client->submitForm(
+        'Log in',
+        ['login' => 'my_user', 'password' => 'my_pass'],
+        // override the default form HTTP method
+        'PUT',
+        // override some $_SERVER parameters (e.g. HTTP headers)
+        ['HTTP_ACCEPT_LANGUAGE' => 'es']
+    );
+
+If you need the :class:`Symfony\\Component\\DomCrawler\\Form` object that
+provides access to the form properties (e.g. ``$form->getUri()``,
+``$form->getValues()``, ``$form->getFields()``), use this other method::
+
+    // ...
+
     // select the form and fill in some values
     $form = $crawler->selectButton('Log in')->form();
     $form['login'] = 'symfonyfan';
     $form['password'] = 'anypass';
 
-    // To upload a file, the value should be the absolute file path
-    $form['file'] = __FILE__;
-
     // submit that form
     $crawler = $client->submit($form);
 
@@ -255,6 +280,41 @@ also delete all the cookies::
     // reset the client (history and cookies are cleared too)
     $client->restart();
 
+.. _component-browserkit-external-requests:
+
+Making External HTTP Requests
+-----------------------------
+
+So far, all the examples in this article have assumed that you are making
+internal requests to your own application. However, you can run the exact same
+examples when making HTTP requests to external web sites and applications.
+
+First, install and configure the :doc:`HttpClient component </components/http_client>`.
+Then, use the :class:`Symfony\\Component\\BrowserKit\\HttpBrowser` to create
+the client that will make the external HTTP requests::
+
+    use Symfony\Component\BrowserKit\HttpBrowser;
+    use Symfony\Component\HttpClient\HttpClient;
+
+    $browser = new HttpBrowser(HttpClient::create());
+
+You can now use any of the methods shown in this article to extract information,
+click links, submit forms, etc. This means that you no longer need to use a
+dedicated web crawler or scraper such as `Goutte`_::
+
+    $browser = new HttpBrowser(HttpClient::create());
+
+    $browser->request('GET', 'https://github.com');
+    $browser->clickLink('Sign in');
+    $browser->submitForm('Sign in', ['login' => '...', 'password' => '...']);
+    $openPullRequests = trim($browser->clickLink('Pull requests')->filter(
+        '.table-list-header-toggle a:nth-child(1)'
+    )->text());
+
+.. versionadded:: 4.3
+
+    The feature to make external HTTP requests was introduced in Symfony 4.3.
+
 Learn more
 ----------
 
@@ -262,5 +322,4 @@ Learn more
 * :doc:`/components/css_selector`
 * :doc:`/components/dom_crawler`
 
-.. _`Packagist`: https://packagist.org/packages/symfony/browser-kit
 .. _`Goutte`: https://github.com/FriendsOfPHP/Goutte
diff --git a/components/cache.rst b/components/cache.rst
index c8f9174a1fe..d323113e9bd 100644
--- a/components/cache.rst
+++ b/components/cache.rst
@@ -8,11 +8,17 @@
 The Cache Component
 ===================
 
-    The Cache component provides an extended `PSR-6`_ implementation as well as
-    a `PSR-16`_ "Simple Cache" implementation for adding cache to your applications.
-    It is designed for performance and resiliency, and ships with ready to use
-    adapters for the most common caching backends, including proxies for adapting
-    from/to `Doctrine Cache`_.
+    The Cache component provides features covering simple to advanced caching needs.
+    It natively implements `PSR-6`_ and the `Cache Contracts`_ for greatest
+    interoperability. It is designed for performance and resiliency, ships with
+    ready to use adapters for the most common caching backends. It enables tag-based
+    invalidation and cache stampede protection via locking and early expiration.
+
+.. tip::
+
+    The component also contains adapters to convert between PSR-6, PSR-16 and
+    Doctrine caches. See :doc:`/components/cache/psr6_psr16_adapters` and
+    :doc:`/components/cache/adapters/doctrine_adapter`.
 
 Installation
 ------------
@@ -21,121 +27,128 @@ Installation
 
     $ composer require symfony/cache
 
-Alternatively, you can clone the `<https://github.com/symfony/cache>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
-Cache (PSR-6) Versus Simple Cache (PSR-16)
-------------------------------------------
+Cache Contracts versus PSR-6
+----------------------------
 
 This component includes *two* different approaches to caching:
 
 :ref:`PSR-6 Caching <cache-component-psr6-caching>`:
-     A fully-featured cache system, which includes cache "pools", more advanced
-     cache "items", and :ref:`cache tagging for invalidation <cache-component-tags>`.
-
-:ref:`PSR-16 Simple Caching <cache-component-psr16-caching>`:
-    A simple way to store, fetch and remove items from a cache.
+    A generic cache system, which involves cache "pools" and cache "items".
 
-Both methods support the *same* cache adapters and will give you very similar performance.
+:ref:`Cache Contracts <cache-component-contracts>`:
+    A simpler yet more powerful way to cache values based on recomputation callbacks.
 
 .. tip::
 
-    The component also contains adapters to convert between PSR-6 and PSR-16 caches.
-    See :doc:`/components/cache/psr6_psr16_adapters`.
+    Using the Cache Contracts approach is recommended: it requires less
+    code boilerplate and provides cache stampede protection by default.
 
-.. _cache-component-psr16-caching:
+.. _cache-component-contracts:
 
-Simple Caching (PSR-16)
------------------------
+Cache Contracts
+---------------
 
-This part of the component is an implementation of `PSR-16`_, which means that its
-basic API is the same as defined in the standard. First, create a cache object from
-one of the built-in cache classes. For example, to create a filesystem-based cache,
-instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`::
+All adapters support the Cache Contracts. They contain only two methods:
+``get()`` and ``delete()``. There's no ``set()`` method because the ``get()``
+method both gets and sets the cache values.
 
-    use Symfony\Component\Cache\Simple\FilesystemCache;
+The first thing you need is to instantiate a cache adapter. The
+:class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter` is used in this
+example::
 
-    $cache = new FilesystemCache();
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
-Now you can create, retrieve, update and delete items using this object::
+    $cache = new FilesystemAdapter();
 
-    // save a new item in the cache
-    $cache->set('stats.products_count', 4711);
+Now you can retrieve and delete cached data using this object. The first
+argument of the ``get()`` method is a key, an arbitrary string that you
+associate to the cached value so you can retrieve it later. The second argument
+is a PHP callable which is executed when the key is not found in the cache to
+generate and return the value::
 
-    // or set it with a custom ttl
-    // $cache->set('stats.products_count', 4711, 3600);
+    use Symfony\Contracts\Cache\ItemInterface;
 
-    // retrieve the cache item
-    if (!$cache->has('stats.products_count')) {
-        // ... item does not exists in the cache
-    }
+    // The callable will only be executed on a cache miss.
+    $value = $cache->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
 
-    // retrieve the value stored by the item
-    $productsCount = $cache->get('stats.products_count');
+        // ... do some HTTP request or heavy computations
+        $computedValue = 'foobar';
 
-    // or specify a default value, if the key doesn't exist
-    // $productsCount = $cache->get('stats.products_count', 100);
+        return $computedValue;
+    });
 
-    // remove the cache key
-    $cache->delete('stats.products_count');
+    echo $value; // 'foobar'
 
-    // clear *all* cache keys
-    $cache->clear();
+    // ... and to remove the cache key
+    $cache->delete('my_cache_key');
 
-You can also work with multiple items at once::
+.. note::
 
-    $cache->setMultiple([
-        'stats.products_count' => 4711,
-        'stats.users_count' => 1356,
-    ]);
+    Use cache tags to delete more than one key at the time. Read more at
+    :doc:`/components/cache/cache_invalidation`.
 
-    $stats = $cache->getMultiple([
-        'stats.products_count',
-        'stats.users_count',
-    ]);
+The Cache Contracts also comes with built in `Stampede prevention`_. This will
+remove CPU spikes at the moments when the cache is cold. If an example application
+spends 5 seconds to compute data that is cached for 1 hour and this data is accessed
+10 times every second, this means that you mostly have cache hits and everything
+is fine. But after 1 hour, we get 10 new requests to a cold cache. So the data
+is computed again. The next second the same thing happens. So the data is computed
+about 50 times before the cache is warm again. This is where you need stampede
+prevention
 
-    $cache->deleteMultiple([
-        'stats.products_count',
-        'stats.users_count',
-    ]);
+The first solution is to use locking: only allow one PHP process (on a per-host basis)
+to compute a specific key at a time. Locking is built-in by default, so
+you don't need to do anything beyond leveraging the Cache Contracts.
 
-Available Simple Cache (PSR-16) Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The second solution is also built-in when using the Cache Contracts: instead of
+waiting for the full delay before expiring a value, recompute it ahead of its
+expiration date. The `Probabilistic early expiration`_ algorithm randomly fakes a
+cache miss for one user while others are still served the cached value. You can
+control its behavior with the third optional parameter of
+:method:`Symfony\\Contracts\\Cache\\CacheInterface::get`,
+which is a float value called "beta".
+
+By default the beta is ``1.0`` and higher values mean earlier recompute. Set it
+to ``0`` to disable early recompute and set it to ``INF`` to force an immediate
+recompute::
+
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    $beta = 1.0;
+    $value = $cache->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
+        $item->tag(['tag_0', 'tag_1']);
+
+        return '...';
+    }, $beta);
+
+Available Cache Adapters
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following cache adapters are available:
 
-.. tip::
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    cache/adapters/*
 
-    To find out more about each of these classes, you can read the
-    :doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page. These "Simple"
-    (PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but
-    each share constructor arguments and use-cases.
-
-* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\NullCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\PhpFilesCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache`
-* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache`
 
 .. _cache-component-psr6-caching:
 
-More Advanced Caching (PSR-6)
------------------------------
+Generic Caching (PSR-6)
+-----------------------
 
-To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
+To use the generic PSR-6 Caching abilities, you'll need to learn its key
 concepts:
 
 **Item**
     A single unit of information stored as a key/value pair, where the key is
     the unique identifier of the information and the value is its contents;
+    see the :doc:`/components/cache/cache_items` article for more details.
 **Pool**
     A logical repository of cache items. All cache operations (saving items,
     looking for items, etc.) are performed through the pool. Applications can
@@ -149,7 +162,7 @@ Basic Usage (PSR-6)
 -------------------
 
 This part of the component is an implementation of `PSR-6`_, which means that its
-basic API is the same as defined in the standard. Before starting to cache information,
+basic API is the same as defined in the document. Before starting to cache information,
 create the cache pool using any of the built-in adapters. For example, to create
 a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`::
 
@@ -169,7 +182,7 @@ Now you can create, retrieve, update and delete items using this cache pool::
     // retrieve the cache item
     $productsCount = $cache->getItem('stats.products_count');
     if (!$productsCount->isHit()) {
-        // ... item does not exists in the cache
+        // ... item does not exist in the cache
     }
     // retrieve the value stored by the item
     $total = $productsCount->get();
@@ -179,8 +192,8 @@ Now you can create, retrieve, update and delete items using this cache pool::
 
 For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
 
-Advanced Usage (PSR-6)
-----------------------
+Advanced Usage
+--------------
 
 .. toctree::
     :glob:
@@ -189,5 +202,6 @@ Advanced Usage (PSR-6)
     cache/*
 
 .. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
-.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
-.. _Doctrine Cache: https://www.doctrine-project.org/projects/cache.html
+.. _`Cache Contracts`: https://github.com/symfony/contracts/blob/master/Cache/CacheInterface.php
+.. _`Stampede prevention`: https://en.wikipedia.org/wiki/Cache_stampede
+.. _Probabilistic early expiration: https://en.wikipedia.org/wiki/Cache_stampede#Probabilistic_early_expiration
diff --git a/components/cache/adapters/apcu_adapter.rst b/components/cache/adapters/apcu_adapter.rst
index 54507ccfc66..17ecd4058e6 100644
--- a/components/cache/adapters/apcu_adapter.rst
+++ b/components/cache/adapters/apcu_adapter.rst
@@ -1,6 +1,6 @@
 .. index::
     single: Cache Pool
-    single: APC Cache, APCu Cache
+    single: APCu Cache
 
 .. _apcu-adapter:
 
diff --git a/components/cache/adapters/chain_adapter.rst b/components/cache/adapters/chain_adapter.rst
index c1ad7630565..de7555029d2 100644
--- a/components/cache/adapters/chain_adapter.rst
+++ b/components/cache/adapters/chain_adapter.rst
@@ -15,16 +15,15 @@ given adapters. This exposes a simple and efficient method for creating a layere
 The ChainAdapter must be provided an array of adapters and optionally a maximum cache
 lifetime as its constructor arguments::
 
-    use Symfony\Component\Cache\Adapter\ApcuAdapter;
-
-    $cache = new ChainAdapter([
+    use Symfony\Component\Cache\Adapter\ChainAdapter;
 
+    $cache = new ChainAdapter(
         // The ordered list of adapters used to fetch cached items
         array $adapters,
 
         // The max lifetime of items propagated from lower adapters to upper ones
         $maxLifetime = 0
-    ]);
+    );
 
 .. note::
 
@@ -59,11 +58,5 @@ incompatible adapters are silently ignored::
         new FilesystemAdapter(),  // DOES implement PruneableInterface
     ]);
 
-    // prune will proxy the call to FilesystemAdapter while silently skipping ApcuAdapter
+    // prune will proxy the call to FilesystemAdapter while silently skip ApcuAdapter
     $cache->prune();
-
-.. note::
-
-    Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
-    allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
-    calling its ``prune()`` method.
diff --git a/components/cache/adapters/doctrine_adapter.rst b/components/cache/adapters/doctrine_adapter.rst
index f8f95126ae9..198ae19338c 100644
--- a/components/cache/adapters/doctrine_adapter.rst
+++ b/components/cache/adapters/doctrine_adapter.rst
@@ -34,4 +34,9 @@ third parameters::
         $defaultLifetime = 0
     );
 
+.. tip::
+
+    A :class:`Symfony\\Component\\Cache\\DoctrineProvider` class is also provided by the
+    component to use any PSR6-compatible implementations with Doctrine-compatible classes.
+
 .. _`Doctrine Cache`: https://github.com/doctrine/cache
diff --git a/components/cache/adapters/memcached_adapter.rst b/components/cache/adapters/memcached_adapter.rst
index 4e60abd8115..69d7afa48be 100644
--- a/components/cache/adapters/memcached_adapter.rst
+++ b/components/cache/adapters/memcached_adapter.rst
@@ -64,6 +64,16 @@ helper method allows creating and configuring a `Memcached`_ class instance usin
         // etc...
     ]);
 
+    // a single DSN can define multiple servers using the following syntax:
+    // host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
+    $client = MemcachedAdapter::createConnection(
+        'memcached:?host[localhost]&host[localhost:12345]&host[/some/memcached.sock:]=3'
+    );
+
+.. versionadded:: 4.2
+
+    The option to define multiple servers in a single DSN was introduced in Symfony 4.2.
+
 The `Data Source Name (DSN)`_ for this adapter must use the following format:
 
 .. code-block:: text
@@ -231,7 +241,7 @@ Available Options
 
 ``server_failure_limit`` (type: ``int``, default: ``0``)
     Specifies the failure limit for server connection attempts before marking
-    the server as "dead". The server will remaining in the server pool unless
+    the server as "dead". The server will remain in the server pool unless
     ``auto_eject_hosts`` is enabled.
 
     Valid option values include *any positive integer*.
@@ -291,4 +301,3 @@ Available Options
 .. _`Memcached server`: https://memcached.org/
 .. _`Memcached`: http://php.net/manual/en/class.memcached.php
 .. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
-.. _`Domain Name System (DNS)`: https://en.wikipedia.org/wiki/Domain_Name_System
diff --git a/components/cache/adapters/pdo_doctrine_dbal_adapter.rst b/components/cache/adapters/pdo_doctrine_dbal_adapter.rst
index 2ac27a83e24..cc8c43976c5 100644
--- a/components/cache/adapters/pdo_doctrine_dbal_adapter.rst
+++ b/components/cache/adapters/pdo_doctrine_dbal_adapter.rst
@@ -31,6 +31,12 @@ third, and forth parameters::
         $options = []
     );
 
+The table where values are stored is created automatically on the first call to
+the :method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::save` method.
+You can also create this table explicitly by calling the
+:method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::createTable` method in
+your code.
+
 .. tip::
 
     When passed a `Data Source Name (DSN)`_ string (instead of a database connection
diff --git a/components/cache/adapters/php_array_cache_adapter.rst b/components/cache/adapters/php_array_cache_adapter.rst
index dfc29f62002..6fc5729705d 100644
--- a/components/cache/adapters/php_array_cache_adapter.rst
+++ b/components/cache/adapters/php_array_cache_adapter.rst
@@ -6,10 +6,11 @@ Php Array Cache Adapter
 =======================
 
 This adapter is a high performance cache for static data (e.g. application configuration)
-that is optimized and preloaded into OPcache memory storage::
+that is optimized and preloaded into OPcache memory storage. It is suited for any data that
+is mostly read-only after warmup::
 
-    use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+    use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
 
     // somehow, decide it's time to warm up the cache!
     if ($needsWarmup) {
@@ -34,5 +35,4 @@ that is optimized and preloaded into OPcache memory storage::
 
 .. note::
 
-    This adapter requires PHP 7.x and should be used with the php.ini setting
-    ``opcache.enable`` on.
+    This adapter requires turning on the ``opcache.enable`` php.ini setting.
diff --git a/components/cache/adapters/php_files_adapter.rst b/components/cache/adapters/php_files_adapter.rst
index 078394aeaf0..c6e78cf52c0 100644
--- a/components/cache/adapters/php_files_adapter.rst
+++ b/components/cache/adapters/php_files_adapter.rst
@@ -29,15 +29,16 @@ file similar to the following::
 
 .. note::
 
+    This adapter requires turning on the ``opcache.enable`` php.ini setting.
     As cache items are included and parsed as native PHP code and due to the way `OPcache`_
     handles file includes, this adapter has the potential to be much faster than other
     filesystem-based caches.
 
 .. caution::
 
-    If you have configured OPcache to
-    :ref:`not check the file timestamps <performance-dont-check-timestamps>`
-    the cached items will not not be invalidated unless you clear OPcache.
+    While it supports updates and because it is using OPcache as a backend, this adapter is
+    better suited for append-mostly needs. Using it in other scenarios might lead to
+    periodical reset of the OPcache memory, potentially leading to degraded performance.
 
 The PhpFilesAdapter can optionally be provided a namespace, default cache lifetime, and cache
 directory path as constructor arguments::
diff --git a/components/cache/adapters/proxy_adapter.rst b/components/cache/adapters/proxy_adapter.rst
index 86b24ead50f..85d41d2c6d1 100644
--- a/components/cache/adapters/proxy_adapter.rst
+++ b/components/cache/adapters/proxy_adapter.rst
@@ -9,14 +9,18 @@ This adapter wraps a `PSR-6`_ compliant `cache item pool interface`_. It is used
 your application's cache item pool implementation with the Symfony :ref:`Cache Component <cache-component>`
 by consuming any implementation of ``Psr\Cache\CacheItemPoolInterface``.
 
+It can also be used to prefix all keys automatically before storing items in the decorated pool,
+effectively allowing the creation of several namespaced pools out of a single one.
+
 This adapter expects a ``Psr\Cache\CacheItemPoolInterface`` instance as its first parameter,
 and optionally a namespace and default cache lifetime as its second and third parameters::
 
     use Psr\Cache\CacheItemPoolInterface;
     use Symfony\Component\Cache\Adapter\ProxyAdapter;
 
-    $psr6CachePool = \\ create your own cache pool instance that implements the PSR-6
-                     \\ interface `CacheItemPoolInterface`
+    // create your own cache pool instance that implements
+    // the PSR-6 CacheItemPoolInterface
+    $psr6CachePool = ...
 
     $cache = new ProxyAdapter(
 
diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst
index f85fe2081ea..53b28c58466 100644
--- a/components/cache/adapters/redis_adapter.rst
+++ b/components/cache/adapters/redis_adapter.rst
@@ -7,7 +7,15 @@
 Redis Cache Adapter
 ===================
 
-This adapter stores the values in-memory using  one (or more) `Redis server`_ instances.
+.. seealso::
+
+    This article explains how to configure the Redis adapter when using the
+    Cache as an independent component in any PHP application. Read the
+    :ref:`Symfony Cache configuration <cache-configuration-with-frameworkbundle>`
+    article if you are using it in a Symfony application.
+
+This adapter stores the values in-memory using one (or more) `Redis server`_ instances.
+
 Unlike the :ref:`APCu adapter <apcu-adapter>`, and similarly to the
 :ref:`Memcached adapter <memcached-adapter>`, it is not limited to the current server's
 shared memory; you can store contents independent of your PHP environment. The ability
@@ -53,8 +61,8 @@ helper method allows creating and configuring the Redis client class instance us
         'redis://localhost'
     );
 
-The DSN can specify either an IP/host (and an optional port) or a socket path, as well as a user
-and password and a database index.
+The DSN can specify either an IP/host (and an optional port) or a socket path, as well as a
+password and a database index.
 
 .. note::
 
@@ -62,7 +70,7 @@ and password and a database index.
 
     .. code-block:: text
 
-        redis://[user:pass@][ip|host|socket[:port]][/db-index]
+        redis://[pass@][ip|host|socket[:port]][/db-index]
 
 Below are common examples of valid DSNs showing a combination of available values::
 
@@ -74,11 +82,38 @@ Below are common examples of valid DSNs showing a combination of available value
     // host "my.server.com" and port "6379" and database index "20"
     RedisAdapter::createConnection('redis://my.server.com:6379/20');
 
-    // host "localhost" and SASL use "rmf" and pass "abcdef"
-    RedisAdapter::createConnection('redis://rmf:abcdef@localhost');
+    // host "localhost", auth "abcdef" and timeout 5 seconds
+    RedisAdapter::createConnection('redis://abcdef@localhost?timeout=5');
+
+    // socket "/var/run/redis.sock" and auth "bad-pass"
+    RedisAdapter::createConnection('redis://bad-pass@/var/run/redis.sock');
+
+    // a single DSN can define multiple servers using the following syntax:
+    // host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
+    RedisAdapter::createConnection(
+        'redis:?host[localhost]&host[localhost:6379]&host[/var/run/redis.sock:]&auth=my-password&redis_cluster=1'
+    );
+
+`Redis Sentinel`_, which provides high availability for Redis, is also supported
+when using the Predis library. Use the ``redis_sentinel`` parameter to set the
+name of your service group::
+
+    RedisAdapter::createConnection(
+        'redis:?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster'
+    );
 
-    // socket "/var/run/redis.sock" and SASL user "user1" and pass "bad-pass"
-    RedisAdapter::createConnection('redis://user1:bad-pass@/var/run/redis.sock');
+.. versionadded:: 4.2
+
+    The option to define multiple servers in a single DSN was introduced in Symfony 4.2.
+
+.. versionadded:: 4.4
+
+    Redis Sentinel support was introduced in Symfony 4.4.
+
+.. note::
+
+    See the :class:`Symfony\\Component\\Cache\\Traits\\RedisTrait` for more options
+    you can pass as DSN parameters.
 
 Configure the Options
 ---------------------
@@ -96,9 +131,11 @@ array of ``key => value`` pairs representing option names and their respective v
 
         // associative array of configuration options
         [
+            'compression' => true,
             'lazy' => false,
             'persistent' => 0,
             'persistent_id' => null,
+            'tcp_keepalive' => 0,
             'timeout' => 30,
             'read_timeout' => 0,
             'retry_interval' => 0,
@@ -114,6 +151,10 @@ Available Options
     If none is specified, it will return ``\Redis`` if the ``redis`` extension is
     available, and ``\Predis\Client`` otherwise.
 
+``compression`` (type: ``bool``, default: ``true``)
+    Enables or disables compression of items. This requires phpredis v4 or higher with
+    LZF support enabled.
+
 ``lazy`` (type: ``bool``, default: ``false``)
     Enables or disables lazy connections to the backend. It's ``false`` by
     default when using this as a stand-alone component and ``true`` by default
@@ -134,6 +175,10 @@ Available Options
     Specifies the delay (in milliseconds) between reconnection attempts in case the client
     loses connection with the server.
 
+``tcp_keepalive`` (type: ``int``, default: ``0``)
+    Specifies the `TCP-keepalive`_ timeout (in seconds) of the connection. This
+    requires phpredis v4 or higher and a TCP-keepalive enabled server.
+
 ``timeout`` (type: ``int``, default: ``30``)
     Specifies the time (in seconds) used to connect to a Redis server before the
     connection attempt times out.
@@ -150,3 +195,5 @@ Available Options
 .. _`RedisCluster`: https://github.com/phpredis/phpredis/blob/master/cluster.markdown#readme
 .. _`Predis`: https://packagist.org/packages/predis/predis
 .. _`Predis Connection Parameters`: https://github.com/nrk/predis/wiki/Connection-Parameters#list-of-connection-parameters
+.. _`TCP-keepalive`: https://redis.io/topics/clients#tcp-keepalive
+.. _`Redis Sentinel`: https://redis.io/topics/sentinel
diff --git a/components/cache/cache_invalidation.rst b/components/cache/cache_invalidation.rst
index c0b570b21d5..e56153b9ce1 100644
--- a/components/cache/cache_invalidation.rst
+++ b/components/cache/cache_invalidation.rst
@@ -10,10 +10,10 @@ change in the state of your model. The most basic kind of invalidation is direct
 items deletion. But when the state of a primary resource has spread across
 several cached items, keeping them in sync can be difficult.
 
-The Symfony Cache component provides two mechanisms to help solving this problem:
+The Symfony Cache component provides two mechanisms to help solve this problem:
 
 * :ref:`Tags-based invalidation <cache-component-tags>` for managing data dependencies;
-* :ref:`Expiration based invalidation <cache-component-expiration>` for time related dependencies.
+* :ref:`Expiration based invalidation <cache-component-expiration>` for time-related dependencies.
 
 .. _cache-component-tags:
 
@@ -25,28 +25,27 @@ each cached item. Each tag is a plain string identifier that you can use at any
 time to trigger the removal of all items associated with this tag.
 
 To attach tags to cached items, you need to use the
-:method:`Symfony\\Component\\Cache\\CacheItem::tag` method that is implemented by
-cache items, as returned by cache adapters::
+:method:`Symfony\\Contracts\\Cache\\ItemInterface::tag` method that is implemented by
+cache items::
 
-    $item = $cache->getItem('cache_key');
-    // ...
-    // add one or more tags
-    $item->tag('tag_1');
-    $item->tag(['tag_2', 'tag_3']);
-    $cache->save($item);
+    $item = $cache->get('cache_key', function (ItemInterface $item) {
+        // [...]
+        // add one or more tags
+        $item->tag('tag_1');
+        $item->tag(['tag_2', 'tag_3']);
 
-If ``$cache`` implements :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface`,
+        return $cachedValue;
+    });
+
+If ``$cache`` implements :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface`,
 you can invalidate the cached items by calling
-:method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface::invalidateTags`::
+:method:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface::invalidateTags`::
 
     // invalidate all items related to `tag_1` or `tag_3`
     $cache->invalidateTags(['tag_1', 'tag_3']);
 
     // if you know the cache key, you can also delete the item directly
-    $cache->deleteItem('cache_key');
-
-    // If you don't remember the item key, you can use the getKey() method
-    $cache->deleteItem($item->getKey());
+    $cache->delete('cache_key');
 
 Using tags invalidation is very useful when tracking cache keys becomes difficult.
 
@@ -55,7 +54,7 @@ Tag Aware Adapters
 
 To store tags, you need to wrap a cache adapter with the
 :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class or implement
-:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface` and its only
+:class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface` and its
 :method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface::invalidateTags`
 method.
 
@@ -69,9 +68,9 @@ in the same place. By using two adapters, you can e.g. store some big cached ite
 on the filesystem or in the database and keep tags in a Redis database to sync all
 your fronts and have very fast invalidation checks::
 
-    use Symfony\Component\Cache\Adapter\TagAwareAdapter;
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
     use Symfony\Component\Cache\Adapter\RedisAdapter;
+    use Symfony\Component\Cache\Adapter\TagAwareAdapter;
 
     $cache = new TagAwareAdapter(
         // Adapter for cached items
diff --git a/components/cache/cache_items.rst b/components/cache/cache_items.rst
index 9cc126e45de..027bb59f4a9 100644
--- a/components/cache/cache_items.rst
+++ b/components/cache/cache_items.rst
@@ -9,6 +9,7 @@ Cache Items
 Cache items are the information units stored in the cache as a key/value pair.
 In the Cache component they are represented by the
 :class:`Symfony\\Component\\Cache\\CacheItem` class.
+They are used in both the Cache Contracts and the PSR-6 interfaces.
 
 Cache Item Keys and Values
 --------------------------
@@ -27,14 +28,22 @@ arrays and objects.
 Creating Cache Items
 --------------------
 
-Cache items are created with the ``getItem($key)`` method of the cache pool. The
-argument is the key of the item::
+The only way to create cache items is via cache pools. When using the Cache
+Contracts, they are passed as arguments to the recomputation callback::
+
+    // $cache pool object was created before
+    $productsCount = $cache->get('stats.products_count', function (ItemInterface $item) {
+        // [...]
+    });
+
+When using PSR-6, they are created with the ``getItem($key)`` method of the cache
+pool::
 
     // $cache pool object was created before
     $productsCount = $cache->getItem('stats.products_count');
 
-Then, use the ``Psr\\Cache\\CacheItemInterface::set`` method to set
-the data stored in the cache item::
+Then, use the ``Psr\Cache\CacheItemInterface::set`` method to set the data stored
+in the cache item (this step is done automatically when using the Cache Contracts)::
 
     // storing a simple integer
     $productsCount->set(4711);
@@ -58,7 +67,7 @@ corresponding *getter* methods::
 Cache Item Expiration
 ~~~~~~~~~~~~~~~~~~~~~
 
-By default cache items are stored permanently. In practice, this "permanent
+By default, cache items are stored permanently. In practice, this "permanent
 storage" can vary greatly depending on the type of cache being used, as
 explained in the :doc:`/components/cache/cache_pools` article.
 
@@ -67,7 +76,6 @@ lifespan. Consider for example an application which caches the latest news just
 for one minute. In those cases, use the ``expiresAfter()`` method to set the
 number of seconds to cache the item::
 
-    $latestNews = $cache->getItem('latest_news');
     $latestNews->expiresAfter(60);  // 60 seconds = 1 minute
 
     // this method also accepts \DateInterval instances
@@ -76,23 +84,22 @@ number of seconds to cache the item::
 Cache items define another related method called ``expiresAt()`` to set the
 exact date and time when the item will expire::
 
-    $mostPopularNews = $cache->getItem('popular_news');
     $mostPopularNews->expiresAt(new \DateTime('tomorrow'));
 
 Cache Item Hits and Misses
 --------------------------
 
 Using a cache mechanism is important to improve the application performance, but
-it should not be required to make the application work. In fact, the PSR-6
-standard states that caching errors should not result in application failures.
+it should not be required to make the application work. In fact, the PSR-6 document
+wisely states that caching errors should not result in application failures.
 
-In practice this means that the ``getItem()`` method always returns an object
-which implements the ``Psr\Cache\CacheItemInterface`` interface, even when the
-cache item doesn't exist. Therefore, you don't have to deal with ``null`` return
+In practice with PSR-6, this means that the ``getItem()`` method always returns an
+object which implements the ``Psr\Cache\CacheItemInterface`` interface, even when
+the cache item doesn't exist. Therefore, you don't have to deal with ``null`` return
 values and you can safely store in the cache values such as ``false`` and ``null``.
 
-In order to decide if the returned object is correct or not, caches use the
-concept of hits and misses:
+In order to decide if the returned object represents a value coming from the storage
+or not, caches use the concept of hits and misses:
 
 * **Cache Hits** occur when the requested item is found in the cache, its value
   is not corrupted or invalid and it hasn't expired;
diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst
index 8917b40ef61..15afe615000 100644
--- a/components/cache/cache_pools.rst
+++ b/components/cache/cache_pools.rst
@@ -1,6 +1,6 @@
 .. index::
     single: Cache Pool
-    single: APC Cache, APCu Cache
+    single: APCu Cache
     single: Array Cache
     single: Chain Cache
     single: Doctrine Cache
@@ -16,7 +16,7 @@ Cache Pools and Supported Adapters
 
 Cache Pools are the logical repositories of cache items. They perform all the
 common operations on items, such as saving them or looking for them. Cache pools
-are independent from the actual cache implementation. Therefore, applications
+are independent of the actual cache implementation. Therefore, applications
 can keep using the same cache pool even if the underlying cache mechanism
 changes from a file system based cache to a Redis or database based cache.
 
@@ -26,8 +26,9 @@ Creating Cache Pools
 --------------------
 
 Cache Pools are created through the **cache adapters**, which are classes that
-implement :class:`Symfony\\Component\\Cache\\Adapter\\AdapterInterface`. This
-component provides several adapters ready to use in your applications.
+implement both :class:`Symfony\\Contracts\\Cache\\CacheInterface` and
+``Psr\Cache\CacheItemPoolInterface``. This component provides several adapters
+ready to use in your applications.
 
 .. toctree::
     :glob:
@@ -35,8 +36,53 @@ component provides several adapters ready to use in your applications.
 
     adapters/*
 
+
+Using the Cache Contracts
+-------------------------
+
+The :class:`Symfony\\Contracts\\Cache\\CacheInterface` allows fetching, storing
+and deleting cache items using only two methods and a callback::
+
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    $cache = new FilesystemAdapter();
+
+    // The callable will only be executed on a cache miss.
+    $value = $cache->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
+
+        // ... do some HTTP request or heavy computations
+        $computedValue = 'foobar';
+
+        return $computedValue;
+    });
+
+    echo $value; // 'foobar'
+
+    // ... and to remove the cache key
+    $cache->delete('my_cache_key');
+
+Out of the box, using this interface provides stampede protection via locking
+and early expiration. Early expiration can be controlled via the third "beta"
+argument of the :method:`Symfony\\Contracts\\Cache\\CacheInterface::get()` method.
+See the :doc:`/components/cache` article for more information.
+
+Early expiration can be detected inside the callback by calling the
+:method:`Symfony\\Contracts\\Cache\\ItemInterface::isHit()` method: if this
+returns ``true``, it means we are currently recomputing a value ahead of its
+expiration date.
+
+For advanced use cases, the callback can accept a second ``bool &$save``
+argument passed by reference. By setting ``$save`` to ``false`` inside the
+callback, you can instruct the cache pool that the returned value *should not*
+be stored in the backend.
+
+Using PSR-6
+-----------
+
 Looking for Cache Items
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Cache Pools define three methods to look for cache items. The most common method
 is ``getItem($key)``, which returns the cache item identified by the given key::
@@ -66,10 +112,10 @@ returns ``true`` if there is a cache item identified by the given key::
     $hasBadges = $cache->hasItem('user_'.$userId.'_badges');
 
 Saving Cache Items
-------------------
+~~~~~~~~~~~~~~~~~~
 
 The most common method to save cache items is
-``Psr\\Cache\\CacheItemPoolInterface::save``, which stores the
+``Psr\Cache\CacheItemPoolInterface::save``, which stores the
 item in the cache immediately (it returns ``true`` if the item was saved or
 ``false`` if some error occurred)::
 
@@ -80,9 +126,9 @@ item in the cache immediately (it returns ``true`` if the item was saved or
 
 Sometimes you may prefer to not save the objects immediately in order to
 increase the application performance. In those cases, use the
-``Psr\\Cache\\CacheItemPoolInterface::saveDeferred`` method to mark cache
+``Psr\Cache\CacheItemPoolInterface::saveDeferred`` method to mark cache
 items as "ready to be persisted" and then call to
-``Psr\\Cache\\CacheItemPoolInterface::commit`` method when you are ready
+``Psr\Cache\CacheItemPoolInterface::commit`` method when you are ready
 to persist them all::
 
     // ...
@@ -100,17 +146,17 @@ method returns ``true`` when all the pending items are successfully saved or
 ``false`` otherwise.
 
 Removing Cache Items
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 Cache Pools include methods to delete a cache item, some of them or all of them.
-The most common is ``Psr\\Cache\\CacheItemPoolInterface::deleteItem``,
+The most common is ``Psr\Cache\CacheItemPoolInterface::deleteItem``,
 which deletes the cache item identified by the given key (it returns ``true``
 when the item is successfully deleted or doesn't exist and ``false`` otherwise)::
 
     // ...
     $isDeleted = $cache->deleteItem('user_'.$userId);
 
-Use the ``Psr\\Cache\\CacheItemPoolInterface::deleteItems`` method to
+Use the ``Psr\Cache\CacheItemPoolInterface::deleteItems`` method to
 delete several cache items simultaneously (it returns ``true`` only if all the
 items have been deleted, even when any or some of them don't exist)::
 
@@ -118,7 +164,7 @@ items have been deleted, even when any or some of them don't exist)::
     $areDeleted = $cache->deleteItems(['category1', 'category2']);
 
 Finally, to remove all the cache items stored in the pool, use the
-``Psr\\Cache\\CacheItemPoolInterface::clear`` method (which returns ``true``
+``Psr\Cache\CacheItemPoolInterface::clear`` method (which returns ``true``
 when all items are successfully deleted)::
 
     // ...
@@ -151,10 +197,6 @@ when all items are successfully deleted)::
         # clears the "cache.validation" and "cache.app" pool
         $ php bin/console cache:pool:clear cache.validation cache.app
 
-.. versionadded:: 4.1
-
-    The ``cache:pool:delete`` command was introduced in Symfony 4.1.
-
 .. _component-cache-cache-pool-prune:
 
 Pruning Cache Items
@@ -163,7 +205,7 @@ Pruning Cache Items
 Some cache pools do not include an automated mechanism for pruning expired cache items.
 For example, the :ref:`FilesystemAdapter <component-cache-filesystem-adapter>` cache
 does not remove expired cache items *until an item is explicitly requested and determined to
-be expired*, for example, via a call to ``Psr\\Cache\\CacheItemPoolInterface::getItem``.
+be expired*, for example, via a call to ``Psr\Cache\CacheItemPoolInterface::getItem``.
 Under certain workloads, this can cause stale cache entries to persist well past their
 expiration, resulting in a sizable consumption of wasted disk or memory space from excess,
 expired cache items.
diff --git a/components/cache/psr6_psr16_adapters.rst b/components/cache/psr6_psr16_adapters.rst
index 88f1e7c93e2..3c1e683b278 100644
--- a/components/cache/psr6_psr16_adapters.rst
+++ b/components/cache/psr6_psr16_adapters.rst
@@ -6,7 +6,7 @@
 Adapters For Interoperability between PSR-6 and PSR-16 Cache
 ============================================================
 
-Sometimes, you may have a Cache object that implements the :ref:`PSR-16 <cache-component-psr16-caching>`
+Sometimes, you may have a Cache object that implements the `PSR-16`_
 standard, but need to pass it to an object that expects a :ref:`PSR-6 <cache-component-psr6-caching>`
 cache adapter. Or, you might have the opposite situation. The cache component contains
 two classes for bidirectional interoperability between PSR-6 and PSR-16 caches.
@@ -33,21 +33,23 @@ example::
 
 But, you already have a PSR-16 cache object, and you'd like to pass this to the class
 instead. No problem! The Cache component provides the
-:class:`Symfony\\Component\\Cache\\Adapter\\SimpleCacheAdapter` class for exactly
+:class:`Symfony\\Component\\Cache\\Adapter\\Psr16Adapter` class for exactly
 this use-case::
 
-    use Symfony\Component\Cache\Simple\FilesystemCache;
-    use Symfony\Component\Cache\Adapter\SimpleCacheAdapter;
+    use Symfony\Component\Cache\Adapter\Psr16Adapter;
 
-    // the PSR-16 cache object that you want to use
-    $psr16Cache = new FilesystemCache();
+    // $psr16Cache is the PSR-16 object that you want to use as a PSR-6 one
 
     // a PSR-6 cache that uses your cache internally!
-    $psr6Cache = new SimpleCacheAdapter($psr16Cache);
+    $psr6Cache = new Psr16Adapter($psr16Cache);
 
     // now use this wherever you want
     $githubApiClient = new GitHubApiClient($psr6Cache);
 
+.. versionadded:: 4.3
+
+    The ``Psr16Adapter`` class was introduced in Symfony 4.3.
+
 Using a PSR-6 Cache Object as a PSR-16 Cache
 --------------------------------------------
 
@@ -70,17 +72,23 @@ example::
 
 But, you already have a PSR-6 cache pool object, and you'd like to pass this to
 the class instead. No problem! The Cache component provides the
-:class:`Symfony\\Component\\Cache\\Simple\\Psr6Cache` class for exactly
+:class:`Symfony\\Component\\Cache\\Psr16Cache` class for exactly
 this use-case::
 
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
-    use Symfony\Component\Cache\Simple\Psr6Cache;
+    use Symfony\Component\Cache\Psr16Cache;
 
     // the PSR-6 cache object that you want to use
     $psr6Cache = new FilesystemAdapter();
 
     // a PSR-16 cache that uses your cache internally!
-    $psr16Cache = new Psr6Cache($psr6Cache);
+    $psr16Cache = new Psr16Cache($psr6Cache);
 
     // now use this wherever you want
     $githubApiClient = new GitHubApiClient($psr16Cache);
+
+.. versionadded:: 4.3
+
+    The ``Psr16Cache`` class was introduced in Symfony 4.3.
+
+.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
diff --git a/components/config.rst b/components/config.rst
index 8134007103d..c41b1a54a81 100644
--- a/components/config.rst
+++ b/components/config.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/config
 
-Alternatively, you can clone the `<https://github.com/symfony/config>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Learn More
@@ -31,5 +29,3 @@ Learn More
     /bundles/configuration
     /bundles/extension
     /bundles/prepend_extension
-
-.. _Packagist: https://packagist.org/packages/symfony/config
diff --git a/components/config/definition.rst b/components/config/definition.rst
index e313f9bc019..6cc72276e7c 100644
--- a/components/config/definition.rst
+++ b/components/config/definition.rst
@@ -52,22 +52,26 @@ implements the :class:`Symfony\\Component\\Config\\Definition\\ConfigurationInte
 
     namespace Acme\DatabaseConfiguration;
 
-    use Symfony\Component\Config\Definition\ConfigurationInterface;
     use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+    use Symfony\Component\Config\Definition\ConfigurationInterface;
 
     class DatabaseConfiguration implements ConfigurationInterface
     {
         public function getConfigTreeBuilder()
         {
-            $treeBuilder = new TreeBuilder();
-            $rootNode = $treeBuilder->root('database');
+            $treeBuilder = new TreeBuilder('database');
 
             // ... add node definitions to the root of the tree
+            // $treeBuilder->getRootNode()->...
 
             return $treeBuilder;
         }
     }
 
+.. deprecated:: 4.2
+
+    Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.
+
 Adding Node Definitions to the Tree
 -----------------------------------
 
@@ -284,8 +288,8 @@ Or the following XML configuration:
 
 .. code-block:: xml
 
-    <connection table="symfony" user="root" password="null" />
-    <connection table="foo" user="root" password="pa$$" />
+    <connection table="symfony" user="root" password="null"/>
+    <connection table="foo" user="root" password="pa$$"/>
 
 The processed configuration is::
 
@@ -353,9 +357,9 @@ same YAML configuration shown before or the following XML configuration:
 .. code-block:: xml
 
     <connection name="sf_connection"
-        table="symfony" user="root" password="null" />
+        table="symfony" user="root" password="null"/>
     <connection name="default"
-        table="foo" user="root" password="pa$$" />
+        table="foo" user="root" password="pa$$"/>
 
 In both cases, the processed configuration maintains the ``sf_connection`` and
 ``default`` keys::
@@ -392,7 +396,7 @@ has a certain value:
     (``null``, ``true``, ``false``), provide a replacement value in case
     the value is ``*.``
 
-.. code-block:: php
+The following example shows these methods in practice::
 
     $rootNode
         ->children()
@@ -472,14 +476,14 @@ In YAML you may have:
 .. code-block:: yaml
 
     # This value is only used for the search results page.
-    entries_per_page:     25
+    entries_per_page: 25
 
 and in XML:
 
 .. code-block:: xml
 
     <!-- entries-per-page: This value is only used for the search results page. -->
-    <config entries-per-page="25" />
+    <config entries-per-page="25"/>
 
 Optional Sections
 -----------------
@@ -527,17 +531,16 @@ For all nodes:
 Appending Sections
 ------------------
 
-If you have a complex configuration to validate then the tree can grow to
+If you have a complex configuration to validate, then the tree can grow to
 be large and you may want to split it up into sections. You can do this
 by making a section a separate node and then appending it into the main
 tree with ``append()``::
 
     public function getConfigTreeBuilder()
     {
-        $treeBuilder = new TreeBuilder();
-        $rootNode = $treeBuilder->root('database');
+        $treeBuilder = new TreeBuilder('database');
 
-        $rootNode
+        $treeBuilder->getRootNode()
             ->children()
                 ->arrayNode('connection')
                     ->children()
@@ -564,10 +567,9 @@ tree with ``append()``::
 
     public function addParametersNode()
     {
-        $treeBuilder = new TreeBuilder();
-        $node = $treeBuilder->root('parameters');
+        $treeBuilder = new TreeBuilder('parameters');
 
-        $node
+        $node = $treeBuilder->getRootNode()
             ->isRequired()
             ->requiresAtLeastOneElement()
             ->useAttributeAsKey('name')
@@ -700,8 +702,8 @@ and sometimes only:
 
     <connection>default</connection>
 
-By default ``connection`` would be an array in the first case and a string
-in the second making it difficult to validate. You can ensure it is always
+By default, ``connection`` would be an array in the first case and a string
+in the second, making it difficult to validate. You can ensure it is always
 an array with ``fixXmlConfig()``.
 
 You can further control the normalization process if you need to. For example,
@@ -790,15 +792,11 @@ for the node, instead of the node's original value.
 Configuring the Node Path Separator
 -----------------------------------
 
-.. versionadded:: 4.1
-    The option to configure the node path separator was introduced in Symfony 4.1.
-
 Consider the following config builder example::
 
-    $treeBuilder = new TreeBuilder();
-    $rootNode = $treeBuilder->root('database');
+    $treeBuilder = new TreeBuilder('database');
 
-    $rootNode
+    $treeBuilder->getRootNode()
         ->children()
             ->arrayNode('connection')
                 ->children()
@@ -840,9 +838,9 @@ any value is not of the expected type, is mandatory and yet undefined, or
 could not be validated in some other way, an exception will be thrown.
 Otherwise the result is a clean array of configuration values::
 
-    use Symfony\Component\Yaml\Yaml;
-    use Symfony\Component\Config\Definition\Processor;
     use Acme\DatabaseConfiguration;
+    use Symfony\Component\Config\Definition\Processor;
+    use Symfony\Component\Yaml\Yaml;
 
     $config = Yaml::parse(
         file_get_contents(__DIR__.'/src/Matthias/config/config.yaml')
diff --git a/components/config/resources.rst b/components/config/resources.rst
index 5c72a23bf36..3ee380a9828 100644
--- a/components/config/resources.rst
+++ b/components/config/resources.rst
@@ -10,6 +10,8 @@ Loading Resources
     :phpfunction:`parse_ini_file` function. Therefore, you can only set
     parameters to string values. To set parameters to other data types
     (e.g. boolean, integer, etc), the other loaders are recommended.
+    
+Loaders populate the application's configuration from different sources like YAML files. The Config component defines the interface for such loaders. The :doc:`Dependency Injection </components/dependency_injection>` and :doc:`Routing </components/routing>` components come with specialized loaders for different file formats.
 
 Locating Resources
 ------------------
@@ -40,6 +42,8 @@ defined. Each loader should implement
 abstract :class:`Symfony\\Component\\Config\\Loader\\FileLoader` class,
 which allows for recursively importing other resources::
 
+    namespace Acme\Config\Loader;
+
     use Symfony\Component\Config\Loader\FileLoader;
     use Symfony\Component\Yaml\Yaml;
 
@@ -81,8 +85,9 @@ When it is asked to load a resource, it delegates this question to the
 resolver has found a suitable loader, this loader will be asked to load
 the resource::
 
-    use Symfony\Component\Config\Loader\LoaderResolver;
+    use Acme\Config\Loader\YamlUserLoader;
     use Symfony\Component\Config\Loader\DelegatingLoader;
+    use Symfony\Component\Config\Loader\LoaderResolver;
 
     $loaderResolver = new LoaderResolver([new YamlUserLoader($fileLocator)]);
     $delegatingLoader = new DelegatingLoader($loaderResolver);
diff --git a/components/console.rst b/components/console.rst
index 3c516e3e3ce..6a2abe2366e 100644
--- a/components/console.rst
+++ b/components/console.rst
@@ -19,8 +19,6 @@ Installation
 
     $ composer require symfony/console
 
-Alternatively, you can clone the `<https://github.com/symfony/console>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Creating a Console Application
@@ -67,5 +65,3 @@ Learn more
     /components/console/*
     /components/console/helpers/index
     /console/*
-
-.. _Packagist: https://packagist.org/packages/symfony/console
diff --git a/components/console/changing_default_command.rst b/components/console/changing_default_command.rst
index 77c40efacec..6eb9f2b5227 100644
--- a/components/console/changing_default_command.rst
+++ b/components/console/changing_default_command.rst
@@ -16,10 +16,11 @@ name to the ``setDefaultCommand()`` method::
 
     class HelloWorldCommand extends Command
     {
+        protected static $defaultName = 'hello:world';
+
         protected function configure()
         {
-            $this->setName('hello:world')
-                ->setDescription('Outputs \'Hello World\'');
+            $this->setDescription('Outputs "Hello World"');
         }
 
         protected function execute(InputInterface $input, OutputInterface $output)
@@ -31,7 +32,6 @@ name to the ``setDefaultCommand()`` method::
 Executing the application and changing the default command::
 
     // application.php
-
     use Acme\Console\Command\HelloWorldCommand;
     use Symfony\Component\Console\Application;
 
diff --git a/components/console/console_arguments.rst b/components/console/console_arguments.rst
index d49b34701d7..79f5c6c1f4c 100644
--- a/components/console/console_arguments.rst
+++ b/components/console/console_arguments.rst
@@ -23,10 +23,11 @@ Have a look at the following command that has three options::
 
     class DemoArgsCommand extends Command
     {
+        protected static $defaultName = 'demo:args';
+
         protected function configure()
         {
             $this
-                ->setName('demo:args')
                 ->setDescription('Describe args behaviors')
                 ->setDefinition(
                     new InputDefinition([
@@ -39,7 +40,7 @@ Have a look at the following command that has three options::
 
         protected function execute(InputInterface $input, OutputInterface $output)
         {
-           // ...
+            // ...
         }
     }
 
diff --git a/components/console/events.rst b/components/console/events.rst
index c61db7baa78..93f6d1a3791 100644
--- a/components/console/events.rst
+++ b/components/console/events.rst
@@ -33,8 +33,8 @@ Just before executing any command, the ``ConsoleEvents::COMMAND`` event is
 dispatched. Listeners receive a
 :class:`Symfony\\Component\\Console\\Event\\ConsoleCommandEvent` event::
 
-    use Symfony\Component\Console\Event\ConsoleCommandEvent;
     use Symfony\Component\Console\ConsoleEvents;
+    use Symfony\Component\Console\Event\ConsoleCommandEvent;
 
     $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) {
         // gets the input instance
@@ -62,10 +62,10 @@ method, you can disable a command inside a listener. The application
 will then *not* execute the command, but instead will return the code ``113``
 (defined in ``ConsoleCommandEvent::RETURN_CODE_DISABLED``). This code is one
 of the `reserved exit codes`_ for console commands that conform with the
-C/C++ standard.::
+C/C++ standard::
 
-    use Symfony\Component\Console\Event\ConsoleCommandEvent;
     use Symfony\Component\Console\ConsoleEvents;
+    use Symfony\Component\Console\Event\ConsoleCommandEvent;
 
     $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) {
         // gets the command to be executed
@@ -97,8 +97,8 @@ thrown by the application.
 Listeners receive a
 :class:`Symfony\\Component\\Console\\Event\\ConsoleErrorEvent` event::
 
-    use Symfony\Component\Console\Event\ConsoleErrorEvent;
     use Symfony\Component\Console\ConsoleEvents;
+    use Symfony\Component\Console\Event\ConsoleErrorEvent;
 
     $dispatcher->addListener(ConsoleEvents::ERROR, function (ConsoleErrorEvent $event) {
         $output = $event->getOutput();
@@ -131,8 +131,8 @@ listener (like sending logs, closing a database connection, sending emails,
 Listeners receive a
 :class:`Symfony\\Component\\Console\\Event\\ConsoleTerminateEvent` event::
 
-    use Symfony\Component\Console\Event\ConsoleTerminateEvent;
     use Symfony\Component\Console\ConsoleEvents;
+    use Symfony\Component\Console\Event\ConsoleTerminateEvent;
 
     $dispatcher->addListener(ConsoleEvents::TERMINATE, function (ConsoleTerminateEvent $event) {
         // gets the output
@@ -154,4 +154,4 @@ Listeners receive a
     It is then dispatched just after the ``ConsoleEvents::ERROR`` event.
     The exit code received in this case is the exception code.
 
-.. _`reserved exit codes`: http://www.tldp.org/LDP/abs/html/exitcodes.html
+.. _`reserved exit codes`: https://www.tldp.org/LDP/abs/html/exitcodes.html
diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst
index 853890a00cd..ba3c2743d24 100644
--- a/components/console/helpers/formatterhelper.rst
+++ b/components/console/helpers/formatterhelper.rst
@@ -108,6 +108,7 @@ If you don't want to use suffix at all, pass an empty string::
 
     $truncatedMessage = $formatter->truncate($message, 7, '!!'); // result: This is!!
     $truncatedMessage = $formatter->truncate($message, 7, '');   // result: This is
-    $truncatedMessage = $formatter->truncate('test', 10));
-    /* result: test
-       because length of the "test..." string is shorter than 10 */
+
+    $truncatedMessage = $formatter->truncate('test', 10);
+    // result: test
+    // because length of the "test..." string is shorter than 10
diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst
index 1c99e067636..51c33738049 100644
--- a/components/console/helpers/progressbar.rst
+++ b/components/console/helpers/progressbar.rst
@@ -64,9 +64,6 @@ value and then call the ``setMaxSteps()`` method to update it as needed::
     // a complex task has just been created: increase the progressbar to 200 units
     $progressBar->setMaxSteps(200);
 
-.. versionadded:: 4.1
-    The ``setMaxSteps()`` method was introduced in Symfony 4.1.
-
 Another solution is to omit the steps argument when creating the
 :class:`Symfony\\Component\\Console\\Helper\\ProgressBar` instance::
 
@@ -98,6 +95,33 @@ that the progress bar display is refreshed with a 100% completion.
     :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::display`
     to show the progress bar again.
 
+If the progress information is stored in an iterable variable (such as an array
+or a PHP generator) you can use the
+:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::iterate` method,
+which starts, advances and finishes the progress bar automatically::
+
+    use Symfony\Component\Console\Helper\ProgressBar;
+
+    $progressBar = new ProgressBar($output);
+
+    // $iterable can be for example an array ([1, 2, 3, ...]) or a generator
+    // $iterable = function () { yield 1; yield 2; ... };
+    foreach ($progressBar->iterate($iterable) as $value) {
+        // ... do some work
+    }
+
+If ``$iterable = [1, 2]``, the previous code will output the following:
+
+.. code-block:: console
+
+     0/2 [>---------------------------]   0%
+     1/2 [==============>-------------]  50%
+     2/2 [============================] 100%
+
+.. versionadded:: 4.3
+
+    The ``iterate()`` method was introduced in Symfony 4.3.
+
 Customizing the Progress Bar
 ----------------------------
 
@@ -348,10 +372,6 @@ of the custom placeholders::
 Displaying Multiple Progress Bars
 ---------------------------------
 
-.. versionadded:: 4.1
-    The feature to display multiple progress bars using output sections was
-    introduced in Symfony 4.1.
-
 When using :ref:`Console output sections <console-output-sections>` it's
 possible to display multiple progress bars at the same time and change their
 progress independently::
diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst
index 60651b83e5f..aeee9dbe30b 100644
--- a/components/console/helpers/questionhelper.rst
+++ b/components/console/helpers/questionhelper.rst
@@ -179,6 +179,45 @@ will be autocompleted as the user types::
         $bundleName = $helper->ask($input, $output, $question);
     }
 
+In more complex use cases, it may be necessary to generate suggestions on the
+fly, for instance if you wish to autocomplete a file path. In that case, you can
+provide a callback function to dynamically generate suggestions::
+
+    use Symfony\Component\Console\Question\Question;
+
+    // ...
+    public function execute(InputInterface $input, OutputInterface $output)
+    {
+        $helper = $this->getHelper('question');
+
+        // This function is called whenever the input changes and new
+        // suggestions are needed.
+        $callback = function (string $userInput): array {
+            // Strip any characters from the last slash to the end of the string
+            // to keep only the last directory and generate suggestions for it
+            $inputPath = preg_replace('%(/|^)[^/]*$%', '$1', $userInput);
+            $inputPath = '' === $inputPath ? '.' : $inputPath;
+
+            // CAUTION - this example code allows unrestricted access to the
+            // entire filesystem. In real applications, restrict the directories
+            // where files and dirs can be found
+            $foundFilesAndDirs = @scandir($inputPath) ?: [];
+
+            return array_map(function ($dirOrFile) use ($inputPath) {
+                return $inputPath.$dirOrFile;
+            }, $foundFilesAndDirs);
+        };
+
+        $question = new Question('Please provide the full path of a file to parse');
+        $question->setAutocompleterCallback($callback);
+
+        $filePath = $helper->ask($input, $output, $question);
+    }
+
+.. versionadded:: 4.3
+
+    The ``setAutocompleterCallback()`` method was introduced in Symfony 4.3.
+
 Hiding the User's Response
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -340,8 +379,8 @@ Testing a Command that Expects Input
 If you want to write a unit test for a command which expects some kind of input
 from the command line, you need to set the inputs that the command expects::
 
-    use Symfony\Component\Console\Helper\QuestionHelper;
     use Symfony\Component\Console\Helper\HelperSet;
+    use Symfony\Component\Console\Helper\QuestionHelper;
     use Symfony\Component\Console\Tester\CommandTester;
 
     // ...
diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst
index 0a50a147c83..bc680cc5ad0 100644
--- a/components/console/helpers/table.rst
+++ b/components/console/helpers/table.rst
@@ -69,7 +69,26 @@ You can add a table separator anywhere in the output by passing an instance of
     | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
     +---------------+--------------------------+------------------+
 
-By default the width of the columns is calculated automatically based on their
+You can optionally display titles at the top and the bottom of the table::
+
+    // ...
+    $table->setHeaderTitle('Books')
+    $table->setFooterTitle('Page 1/2')
+    $table->render();
+
+.. code-block:: terminal
+
+    +---------------+----------- Books --------+------------------+
+    | ISBN          | Title                    | Author           |
+    +---------------+--------------------------+------------------+
+    | 99921-58-10-7 | Divine Comedy            | Dante Alighieri  |
+    | 9971-5-0210-0 | A Tale of Two Cities     | Charles Dickens  |
+    +---------------+--------------------------+------------------+
+    | 960-425-059-0 | The Lord of the Rings    | J. R. R. Tolkien |
+    | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
+    +---------------+--------- Page 1/2 -------+------------------+
+
+By default, the width of the columns is calculated automatically based on their
 contents. Use the :method:`Symfony\\Component\\Console\\Helper\\Table::setColumnWidths`
 method to set the column widths explicitly::
 
@@ -79,7 +98,19 @@ method to set the column widths explicitly::
 
 In this example, the first column width will be ``10``, the last column width
 will be ``30`` and the second column width will be calculated automatically
-because of the ``0`` value. The output of this command will be:
+because of the ``0`` value.
+
+You can also set the width individually for each column with the
+:method:`Symfony\\Component\\Console\\Helper\\Table::setColumnWidth` method.
+Its first argument is the column index (starting from ``0``) and the second
+argument is the column width::
+
+    // ...
+    $table->setColumnWidth(0, 10);
+    $table->setColumnWidth(2, 30);
+    $table->render();
+
+The output of this command will be:
 
 .. code-block:: terminal
 
@@ -98,16 +129,27 @@ widths. If the contents don't fit, the given column width is increased up to the
 longest content length. That's why in the previous example the first column has
 a ``13`` character length although the user defined ``10`` as its width.
 
-You can also set the width individually for each column with the
-:method:`Symfony\\Component\\Console\\Helper\\Table::setColumnWidth` method.
-Its first argument is the column index (starting from ``0``) and the second
-argument is the column width::
+If you prefer to wrap long contents in multiple rows, use the
+:method:`Symfony\\Component\\Console\\Helper\\Table::setColumnMaxWidth` method::
 
     // ...
-    $table->setColumnWidth(0, 10);
-    $table->setColumnWidth(2, 30);
+    $table->setColumnMaxWidth(0, 5);
+    $table->setColumnMaxWidth(1, 10);
     $table->render();
 
+The output of this command will be:
+
+.. code-block:: terminal
+
+    +-------+------------+--------------------------------+
+    | ISBN  | Title      | Author                         |
+    +-------+------------+--------------------------------+
+    | 99921 | Divine Com | Dante Alighieri                |
+    | -58-1 | edy        |                                |
+    | 0-7   |            |                                |
+    |                (the rest of rows...)                |
+    +-------+------------+--------------------------------+
+
 The table style can be changed to any built-in styles via
 :method:`Symfony\\Component\\Console\\Helper\\Table::setStyle`::
 
@@ -164,9 +206,6 @@ which outputs:
     │ 80-902734-1-6 │ And Then There Were None │ Agatha Christie  │
     └───────────────┴──────────────────────────┴──────────────────┘
 
-.. versionadded:: 4.1
-    The ``box`` style was introduced in Symfony 4.1.
-
 You can also set the style to ``box-double``::
 
     $table->setStyle('box-double');
@@ -185,9 +224,6 @@ which outputs:
     ║ 80-902734-1-6 │ And Then There Were None │ Agatha Christie  ║
     ╚═══════════════╧══════════════════════════╧══════════════════╝
 
-.. versionadded:: 4.1
-    The ``box-double`` style was introduced in Symfony 4.1.
-
 If the built-in styles do not fit your need, define your own::
 
     use Symfony\Component\Console\Helper\TableStyle;
@@ -217,17 +253,6 @@ Here is a full list of things you can customize:
 *  :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setBorderFormat`
 *  :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setPadType`
 
-.. versionadded:: 4.1
-    The ``setDefaultCrossingChars`` method was introduced in Symfony 4.1.
-    It replaces the deprecated ``setHorizontalBorderChar`` method.
-
-    Also, the ``setVerticalBorderChars`` method was introduced. Use this instead
-    of the deprecated ``setVerticalBorderChar`` method.
-
-    The ``setCrossingChars()`` and ``setDefaultCrossingChar()`` methods are also
-    new. Previously you could only use the now deprecated ``setCrossingChar()``
-    method.
-
 .. tip::
 
     You can also register a style globally::
@@ -246,8 +271,8 @@ Spanning Multiple Columns and Rows
 To make a table cell that spans multiple columns you can use a :class:`Symfony\\Component\\Console\\Helper\\TableCell`::
 
     use Symfony\Component\Console\Helper\Table;
-    use Symfony\Component\Console\Helper\TableSeparator;
     use Symfony\Component\Console\Helper\TableCell;
+    use Symfony\Component\Console\Helper\TableSeparator;
 
     $table = new Table($output);
     $table
@@ -280,7 +305,7 @@ This results in:
         $table->setHeaders([
             [new TableCell('Main table title', ['colspan' => 3])],
             ['ISBN', 'Title', 'Author'],
-        ))
+        ])
         // ...
 
     This generates:
@@ -333,9 +358,6 @@ you to create any table layout you may wish.
 Modifying Rendered Tables
 -------------------------
 
-.. versionadded:: 4.1
-    The feature to modify rendered tables was introduced in Symfony 4.1.
-
 The ``render()`` method requires passing the entire table contents. However,
 sometimes that information is not available beforehand because it's generated
 dynamically. In those cases, use the
diff --git a/components/console/logger.rst b/components/console/logger.rst
index d221d4c98eb..8f029e47002 100644
--- a/components/console/logger.rst
+++ b/components/console/logger.rst
@@ -39,15 +39,16 @@ You can rely on the logger to use this dependency inside a command::
     use Acme\MyDependency;
     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
-    use Symfony\Component\Console\Output\OutputInterface;
     use Symfony\Component\Console\Logger\ConsoleLogger;
+    use Symfony\Component\Console\Output\OutputInterface;
 
     class MyCommand extends Command
     {
+        protected static $defaultName = 'my:command';
+
         protected function configure()
         {
             $this
-                ->setName('my:command')
                 ->setDescription(
                     'Use an external dependency requiring a PSR-3 logger'
                 )
diff --git a/components/console/single_command_tool.rst b/components/console/single_command_tool.rst
index b1fce6b9746..74c554c46ef 100644
--- a/components/console/single_command_tool.rst
+++ b/components/console/single_command_tool.rst
@@ -8,26 +8,26 @@ When building a command line tool, you may not need to provide several commands.
 In such case, having to pass the command name each time is tedious. Fortunately,
 it is possible to remove this need by declaring a single command application::
 
-  #!/usr/bin/env php
-  <?php
-  require __DIR__.'/vendor/autoload.php';
-
-  use Symfony\Component\Console\Application;
-  use Symfony\Component\Console\Input\InputArgument;
-  use Symfony\Component\Console\Input\InputInterface;
-  use Symfony\Component\Console\Input\InputOption;
-  use Symfony\Component\Console\Output\OutputInterface;
-
-  (new Application('echo', '1.0.0'))
-    ->register('echo')
-        ->addArgument('foo', InputArgument::OPTIONAL, 'The directory')
-        ->addOption('bar', null, InputOption::VALUE_REQUIRED)
-        ->setCode(function(InputInterface $input, OutputInterface $output) {
-            // output arguments and options
-        })
-    ->getApplication()
-    ->setDefaultCommand('echo', true) // Single command application
-    ->run();
+    #!/usr/bin/env php
+    <?php
+    require __DIR__.'/vendor/autoload.php';
+
+    use Symfony\Component\Console\Application;
+    use Symfony\Component\Console\Input\InputArgument;
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Input\InputOption;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    (new Application('echo', '1.0.0'))
+        ->register('echo')
+            ->addArgument('foo', InputArgument::OPTIONAL, 'The directory')
+            ->addOption('bar', null, InputOption::VALUE_REQUIRED)
+            ->setCode(function(InputInterface $input, OutputInterface $output) {
+                // output arguments and options
+            })
+        ->getApplication()
+        ->setDefaultCommand('echo', true) // Single command application
+        ->run();
 
 The method :method:`Symfony\\Component\\Console\\Application::setDefaultCommand`
 accepts a boolean as second parameter. If true, the command ``echo`` will then
@@ -35,17 +35,17 @@ always be used, without having to pass its name.
 
 You can still register a command as usual::
 
-  #!/usr/bin/env php
-  <?php
-  require __DIR__.'/vendor/autoload.php';
+    #!/usr/bin/env php
+    <?php
+    require __DIR__.'/vendor/autoload.php';
 
-  use Acme\Command\DefaultCommand;
-  use Symfony\Component\Console\Application;
+    use Acme\Command\DefaultCommand;
+    use Symfony\Component\Console\Application;
 
-  $application = new Application('echo', '1.0.0');
-  $command = new DefaultCommand();
+    $application = new Application('echo', '1.0.0');
+    $command = new DefaultCommand();
 
-  $application->add($command);
+    $application->add($command);
 
-  $application->setDefaultCommand($command->getName(), true);
-  $application->run();
+    $application->setDefaultCommand($command->getName(), true);
+    $application->run();
diff --git a/components/contracts.rst b/components/contracts.rst
new file mode 100644
index 00000000000..4f84c5f2935
--- /dev/null
+++ b/components/contracts.rst
@@ -0,0 +1,78 @@
+.. index::
+   single: Contracts
+   single: Components; Contracts
+
+The Contracts Component
+=======================
+
+    The Contracts component provides a set of abstractions extracted out of the
+    Symfony components. They can be used to build on semantics that the Symfony
+    components proved useful - and that already have battle-tested implementations.
+
+Installation
+------------
+
+Contracts are provided as separate packages, so you can install only the ones
+your projects really need:
+
+.. code-block:: terminal
+
+    $ composer require symfony/cache-contracts
+    $ composer require symfony/event-dispatcher-contracts
+    $ composer require symfony/http-client-contracts
+    $ composer require symfony/service-contracts
+    $ composer require symfony/translation-contracts
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+The abstractions in this package are useful to achieve loose coupling and
+interoperability. By using the provided interfaces as type hints, you are able
+to reuse any implementations that match their contracts. It could be a Symfony
+component, or another package provided by the PHP community at large.
+
+Depending on their semantics, some interfaces can be combined with
+:doc:`autowiring </service_container/autowiring>` to seamlessly inject a service
+in your classes.
+
+Others might be useful as labeling interfaces, to hint about a specific behavior
+that can be enabled when using :ref:`autoconfiguration <services-autoconfigure>`
+or manual :doc:`service tagging </service_container/tags>` (or any other means
+provided by your framework.)
+
+Design Principles
+-----------------
+
+* Contracts are split by domain, each into their own sub-namespaces;
+* Contracts are small and consistent sets of PHP interfaces, traits, normative
+  docblocks and reference test suites when applicable, ...;
+* Contracts must have a proven implementation to enter this repository;
+* Contracts must be backward compatible with existing Symfony components.
+
+Packages that implement specific contracts should list them in the ``provide``
+section of their ``composer.json`` file, using the ``symfony/*-implementation``
+convention. For example:
+
+.. code-block:: javascript
+
+    {
+        "...": "...",
+        "provide": {
+            "symfony/cache-implementation": "1.0"
+        }
+    }
+
+Frequently Asked Questions
+--------------------------
+
+How Is this Different From PHP-FIG's PSRs?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When applicable, the provided contracts are built on top of `PHP-FIG`_'s PSRs.
+However, PHP-FIG has different goals and different processes. Symfony Contracts
+focuses  on providing abstractions that are useful on their own while still
+compatible with implementations provided by Symfony.
+
+.. _`PHP-FIG`: https://www.php-fig.org/
diff --git a/components/css_selector.rst b/components/css_selector.rst
index ca664e07aaf..2c15ef432dd 100644
--- a/components/css_selector.rst
+++ b/components/css_selector.rst
@@ -14,8 +14,6 @@ Installation
 
     $ composer require symfony/css-selector
 
-Alternatively, you can clone the `<https://github.com/symfony/css-selector>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -97,9 +95,7 @@ Several pseudo-classes are not yet supported:
 
 * ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
   ``*:nth-last-of-type``, ``*:only-of-type``. (These work with an element
-  name (e.g. ``li:first-of-type``) but not with ``*``.
-
-.. _Packagist: https://packagist.org/packages/symfony/css-selector
+  name (e.g. ``li:first-of-type``) but not with ``*``).
 
 Learn more
 ----------
diff --git a/components/debug.rst b/components/debug.rst
index 2b8910b56e1..6f116e25af6 100644
--- a/components/debug.rst
+++ b/components/debug.rst
@@ -14,15 +14,13 @@ Installation
 
     $ composer require symfony/debug
 
-Alternatively, you can clone the `<https://github.com/symfony/debug>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
 -----
 
 The Debug component provides several tools to help you debug PHP code.
-Enabling them all can be done by calling the static method ``Debug::enable()``::
+Enable all of them by calling this method::
 
     use Symfony\Component\Debug\Debug;
 
@@ -83,11 +81,9 @@ throw more helpful exceptions when a class isn't found by the registered
 autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
 with a ``DebugClassLoader`` wrapper.
 
-To activate the ``DebugClassLoader``, call its static
+Using the ``DebugClassLoader`` is done by calling its static
 :method:`Symfony\\Component\\Debug\\DebugClassLoader::enable` method::
 
     use Symfony\Component\Debug\DebugClassLoader;
 
     DebugClassLoader::enable();
-
-.. _Packagist: https://packagist.org/packages/symfony/debug
diff --git a/components/dependency_injection.rst b/components/dependency_injection.rst
index eb9a85bcc28..af13905456c 100644
--- a/components/dependency_injection.rst
+++ b/components/dependency_injection.rst
@@ -19,8 +19,6 @@ Installation
 
     $ composer require symfony/dependency-injection
 
-Alternatively, you can clone the `<https://github.com/symfony/dependency-injection>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Basic Usage
@@ -200,8 +198,8 @@ files. To do this you also need to install
 
 Loading an XML config file::
 
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 
     $containerBuilder = new ContainerBuilder();
@@ -210,8 +208,8 @@ Loading an XML config file::
 
 Loading a YAML config file::
 
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 
     $containerBuilder = new ContainerBuilder();
@@ -235,8 +233,8 @@ Loading a YAML config file::
 If you *do* want to use PHP to create the services then you can move this
 into a separate config file and load it in a similar way::
 
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 
     $containerBuilder = new ContainerBuilder();
@@ -268,7 +266,7 @@ config files:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <parameters>
                 <!-- ... -->
@@ -282,7 +280,7 @@ config files:
 
                 <service id="newsletter_manager" class="NewsletterManager">
                     <call method="setMailer">
-                        <argument type="service" id="mailer" />
+                        <argument type="service" id="mailer"/>
                     </call>
                 </service>
             </services>
@@ -313,4 +311,3 @@ Learn More
     /service_container/*
 
 .. _`PSR-11`: http://www.php-fig.org/psr/psr-11/
-.. _Packagist: https://packagist.org/packages/symfony/dependency-injection
diff --git a/components/dependency_injection/_imports-parameters-note.rst.inc b/components/dependency_injection/_imports-parameters-note.rst.inc
index eb68a4dbdcc..92868df1985 100644
--- a/components/dependency_injection/_imports-parameters-note.rst.inc
+++ b/components/dependency_injection/_imports-parameters-note.rst.inc
@@ -19,10 +19,10 @@
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <imports>
-                    <import resource="%kernel.project_dir%/somefile.yaml" />
+                    <import resource="%kernel.project_dir%/somefile.yaml"/>
                 </imports>
             </container>
 
diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst
index 83fc81d57aa..369de563625 100644
--- a/components/dependency_injection/compilation.rst
+++ b/components/dependency_injection/compilation.rst
@@ -57,10 +57,10 @@ added but are processed when the container's ``compile()`` method is called.
 
 A very simple extension may just load configuration files into the container::
 
+    use Symfony\Component\Config\FileLocator;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
-    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
     use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
-    use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 
     class AcmeDemoExtension implements ExtensionInterface
     {
@@ -113,8 +113,8 @@ If this file is loaded into the configuration then the values in it are
 only processed when the container is compiled at which point the Extensions
 are loaded::
 
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
 
     $containerBuilder = new ContainerBuilder();
@@ -201,7 +201,7 @@ The XML version of the config would then look like this:
     <container xmlns="http://symfony.com/schema/dic/services"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:acme_demo="http://www.example.com/symfony/schema/"
-        xsi:schemaLocation="http://www.example.com/symfony/schema/ http://www.example.com/symfony/schema/hello-1.0.xsd">
+        xsi:schemaLocation="http://www.example.com/symfony/schema/ https://www.example.com/symfony/schema/hello-1.0.xsd">
 
         <acme_demo:config>
             <acme_demo:foo>fooValue</acme_demo:foo>
@@ -325,7 +325,7 @@ compilation::
     {
         public function process(ContainerBuilder $container)
         {
-           // ... do something during the compilation
+            // ... do something during the compilation
         }
 
         // ...
@@ -379,7 +379,7 @@ class implementing the ``CompilerPassInterface``::
     {
         public function process(ContainerBuilder $container)
         {
-           // ... do something during the compilation
+            // ... do something during the compilation
         }
     }
 
@@ -469,7 +469,7 @@ serves at dumping the compiled container::
     }
 
 ``ProjectServiceContainer`` is the default name given to the dumped container
-class. However you can change this with the ``class`` option when you
+class. However, you can change this with the ``class`` option when you
 dump it::
 
     // ...
diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
index 5ddaf8ca0a9..855fd707446 100644
--- a/components/dom_crawler.rst
+++ b/components/dom_crawler.rst
@@ -19,8 +19,6 @@ Installation
 
     $ composer require symfony/dom-crawler
 
-Alternatively, you can clone the `<https://github.com/symfony/dom-crawler>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -36,7 +34,7 @@ The :class:`Symfony\\Component\\DomCrawler\\Crawler` class provides methods
 to query and manipulate HTML and XML documents.
 
 An instance of the Crawler represents a set of :phpclass:`DOMElement` objects,
-which are basically nodes that you can traverse easily::
+which are nodes that can be traversed as follows::
 
     use Symfony\Component\DomCrawler\Crawler;
 
@@ -72,6 +70,17 @@ tree.
     isn't meant to dump content, you can see the "fixed" version of your HTML
     by :ref:`dumping it <component-dom-crawler-dumping>`.
 
+.. note::
+
+    If you need better support for HTML5 contents or want to get rid of the
+    inconsistencies of PHP's DOM extension, install the `html5-php library`_.
+    The DomCrawler component will use it automatically when the content has
+    an HTML5 doctype.
+
+    .. versionadded:: 4.3
+
+        The automatic support of the html5-php library was introduced in Symfony 4.3.
+
 Node Filtering
 ~~~~~~~~~~~~~~
 
@@ -182,6 +191,10 @@ Get all the child or parent nodes::
     $crawler->filter('body')->children();
     $crawler->filter('body > p')->parents();
 
+Get all the direct child nodes matching a CSS selector::
+
+    $crawler->filter('body')->children('p.lorem');
+
 .. note::
 
     All the traversal methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`
@@ -197,8 +210,16 @@ Access the node name (HTML tag name) of the first node of the current selection
 
 Access the value of the first node of the current selection::
 
+    // if the node does not exist, calling to text() will result in an exception
     $message = $crawler->filterXPath('//body/p')->text();
 
+    // avoid the exception passing an argument that text() returns when node does not exist
+    $message = $crawler->filterXPath('//body/p')->text('Default text content');
+
+.. versionadded:: 4.3
+
+    The default argument of ``text()`` was introduced in Symfony 4.3.
+
 Access the attribute value of the first node of the current selection::
 
     $class = $crawler->filterXPath('//body/p')->attr('class');
@@ -207,12 +228,17 @@ Extract attribute and/or node values from the list of nodes::
 
     $attributes = $crawler
         ->filterXpath('//body/p')
-        ->extract(['_text', 'class'])
+        ->extract(['_name', '_text', 'class'])
     ;
 
 .. note::
 
-    Special attribute ``_text`` represents a node value.
+    Special attribute ``_text`` represents a node value, while ``_name``
+    represents the element name (the HTML tag name).
+
+    .. versionadded:: 4.3
+
+        The special attribute ``_name`` was introduced in Symfony 4.3.
 
 Call an anonymous function on each node of the list::
 
@@ -226,21 +252,33 @@ Call an anonymous function on each node of the list::
 The anonymous function receives the node (as a Crawler) and the position as arguments.
 The result is an array of values returned by the anonymous function calls.
 
+When using nested crawler, beware that ``filterXPath()`` is evaluated in the
+context of the crawler::
+
+    $crawler->filterXPath('parent')->each(function (Crawler $parentCrawler, $i) {
+        // DON'T DO THIS: direct child can not be found
+        $subCrawler = $parentCrawler->filterXPath('sub-tag/sub-child-tag');
+
+        // DO THIS: specify the parent tag too
+        $subCrawler = $parentCrawler->filterXPath('parent/sub-tag/sub-child-tag');
+        $subCrawler = $parentCrawler->filterXPath('node()/sub-tag/sub-child-tag');
+    });
+
 Adding the Content
 ~~~~~~~~~~~~~~~~~~
 
 The crawler supports multiple ways of adding the content::
 
-    $crawler = new Crawler('<html><body /></html>');
+    $crawler = new Crawler('<html><body/></html>');
 
-    $crawler->addHtmlContent('<html><body /></html>');
-    $crawler->addXmlContent('<root><node /></root>');
+    $crawler->addHtmlContent('<html><body/></html>');
+    $crawler->addXmlContent('<root><node/></root>');
 
-    $crawler->addContent('<html><body /></html>');
-    $crawler->addContent('<root><node /></root>', 'text/xml');
+    $crawler->addContent('<html><body/></html>');
+    $crawler->addContent('<root><node/></root>', 'text/xml');
 
-    $crawler->add('<html><body /></html>');
-    $crawler->add('<root><node /></root>');
+    $crawler->add('<html><body/></html>');
+    $crawler->add('<root><node/></root>');
 
 .. note::
 
@@ -258,7 +296,7 @@ to interact with native :phpclass:`DOMDocument`, :phpclass:`DOMNodeList`
 and :phpclass:`DOMNode` objects::
 
     $domDocument = new \DOMDocument();
-    $domDocument->loadXml('<root><node /><node /></root>');
+    $domDocument->loadXml('<root><node/><node/></root>');
     $nodeList = $domDocument->getElementsByTagName('node');
     $node = $domDocument->getElementsByTagName('node')->item(0);
 
@@ -289,8 +327,16 @@ and :phpclass:`DOMNode` objects::
     Or you can get the HTML of the first node using
     :method:`Symfony\\Component\\DomCrawler\\Crawler::html`::
 
+        // if the node does not exist, calling to html() will result in an exception
         $html = $crawler->html();
 
+        // avoid the exception passing an argument that html() returns when node does not exist
+        $html = $crawler->html('Default <strong>HTML</strong> content');
+
+    .. versionadded:: 4.3
+
+        The default argument of ``html()`` was introduced in Symfony 4.3.
+
 Expression Evaluation
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -316,32 +362,36 @@ This behavior is best illustrated with examples::
     $crawler->addHtmlContent($html);
 
     $crawler->filterXPath('//span[contains(@id, "article-")]')->evaluate('substring-after(@id, "-")');
-    /* array:3 [
-         0 => "100"
-         1 => "101"
-         2 => "102"
-       ]
-     */
+    /* Result:
+    [
+        0 => '100',
+        1 => '101',
+        2 => '102',
+    ];
+    */
 
     $crawler->evaluate('substring-after(//span[contains(@id, "article-")]/@id, "-")');
-    /* array:1 [
-         0 => "100"
-       ]
-     */
+    /* Result:
+    [
+        0 => '100',
+    ]
+    */
 
     $crawler->filterXPath('//span[@class="article"]')->evaluate('count(@id)');
-    /* array:3 [
-         0 => 1.0
-         1 => 1.0
-         2 => 1.0
-       ]
-     */
+    /* Result:
+    [
+        0 => 1.0,
+        1 => 1.0,
+        2 => 1.0,
+    ]
+    */
 
     $crawler->evaluate('count(//span[@class="article"])');
-    /* array:1 [
-         0 => 3.0
-       ]
-     */
+    /* Result:
+    [
+        0 => 3.0,
+    ]
+    */
 
     $crawler->evaluate('//span[1]');
     // A Symfony\Component\DomCrawler\Crawler instance
@@ -458,9 +508,12 @@ You can virtually set and get values on the form::
 To work with multi-dimensional fields::
 
     <form>
-        <input name="multi[]" />
-        <input name="multi[]" />
-        <input name="multi[dimensional]" />
+        <input name="multi[]"/>
+        <input name="multi[]"/>
+        <input name="multi[dimensional]"/>
+        <input name="multi[dimensional][]" value="1"/>
+        <input name="multi[dimensional][]" value="2"/>
+        <input name="multi[dimensional][]" value="3"/>
     </form>
 
 Pass an array of values::
@@ -474,6 +527,11 @@ Pass an array of values::
         'dimensional' => 'an other value',
     ]]);
 
+    // tick multiple checkboxes at once
+    $form->setValues(['multi' => [
+        'dimensional' => [1, 3] // it uses the input value to determine which checkbox to tick
+    ]]);
+
 This is great, but it gets better! The ``Form`` object allows you to interact
 with your form like a browser, selecting radio values, ticking checkboxes,
 and uploading files::
@@ -548,11 +606,11 @@ the whole form or specific field(s)::
     $form->disableValidation();
     $form['country']->select('Invalid value');
 
-.. _`Goutte`: https://github.com/FriendsOfPHP/Goutte
-.. _Packagist: https://packagist.org/packages/symfony/dom-crawler
-
 Learn more
 ----------
 
 * :doc:`/testing`
 * :doc:`/components/css_selector`
+
+.. _`Goutte`: https://github.com/FriendsOfPHP/Goutte
+.. _`html5-php library`: https://github.com/Masterminds/html5-php
diff --git a/components/dotenv.rst b/components/dotenv.rst
index 017a2614b0d..acd67399a9c 100644
--- a/components/dotenv.rst
+++ b/components/dotenv.rst
@@ -6,16 +6,14 @@ The Dotenv Component
 ====================
 
     The Dotenv Component parses ``.env`` files to make environment variables
-    stored in them accessible via ``getenv()``, ``$_ENV`` or ``$_SERVER``.
+    stored in them accessible via ``$_ENV`` or ``$_SERVER``.
 
 Installation
 ------------
 
 .. code-block:: terminal
 
-    $ composer require --dev symfony/dotenv
-
-Alternatively, you can clone the `<https://github.com/symfony/dotenv>`_ repository.
+    $ composer require symfony/dotenv
 
 .. include:: /components/require_autoload.rst.inc
 
@@ -47,24 +45,72 @@ Load a ``.env`` file in your PHP application via ``Dotenv::load()``::
 
 Given the following ``.env`` file content:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     # .env
     DB_USER=root
     DB_PASS=pass
 
-Access the value with ``getenv()`` in your code::
+Access the value with ``$_ENV`` in your code::
+
+    $dbUser = $_ENV['DB_USER'];
+    // you can also use ``$_SERVER``
+
+The ``load()`` method never overwrites existing environment variables. Use the
+``overload()`` method if you need to overwrite them::
+
+    // ...
+    $dotenv->overload(__DIR__.'/.env');
 
-    $dbUser = getenv('DB_USER');
-    // you can also use ``$_ENV`` or ``$_SERVER``
+As you're working with the Dotenv component you'll notice that you might want
+to have different files depending on the environment you're working in. Typically
+this happens for local development or Continuous Integration where you might
+want to have different files for your ``test`` and ``dev`` environments.
+
+You can use ``Dotenv::loadEnv()`` to ease this process::
+
+    use Symfony\Component\Dotenv\Dotenv;
+
+    $dotenv = new Dotenv();
+    $dotenv->loadEnv(__DIR__.'/.env');
+
+The Dotenv component will then look for the correct ``.env`` file to load
+in the following order whereas the files loaded later override the variables
+defined in previously loaded files:
+
+#. If ``.env`` exists, it is loaded first. In case there's no ``.env`` file but a
+   ``.env.dist``, this one will be loaded instead.
+#. If one of the previously mentioned files contains the ``APP_ENV`` variable, the
+   variable is populated and used to load environment-specific files hereafter. If
+   ``APP_ENV`` is not defined in either of the previously mentioned files, ``dev`` is
+   assumed for ``APP_ENV`` and populated by default.
+#. If there's a ``.env.local`` representing general local environment variables it's loaded now.
+#. If there's a ``.env.$env.local`` file, this one is loaded. Otherwise, it falls
+   back to ``.env.$env``.
+
+This might look complicated at first glance but it gives you the opportunity to
+commit multiple environment-specific files that can then be adjusted to your
+local environment. Given you commit ``.env``, ``.env.test`` and ``.env.dev`` to
+represent different configuration settings for your environments, each of them
+can be adjusted by using ``.env.local``, ``.env.test.local`` and
+``.env.dev.local`` respectively.
 
 .. note::
 
-    Symfony Dotenv never overwrites existing environment variables.
+    ``.env.local`` is always ignored in ``test`` environment because tests should produce the
+    same results for everyone.
+
+You can adjust the variable defining the environment, default environment and test
+environments by passing them as additional arguments to ``Dotenv::loadEnv()``
+(see :method:`Symfony\\Component\\Dotenv\\Dotenv::loadEnv` for details).
+
+.. versionadded:: 4.2
+
+    The ``Dotenv::loadEnv()`` method was introduced in Symfony 4.2.
 
 You should never store a ``.env`` file in your code repository as it might
-contain sensitive information; create a ``.env.dist`` file with sensible
-defaults instead.
+contain sensitive information; create a ``.env.dist`` file (or multiple
+environment-specific ones as shown above) with sensible defaults instead.
 
 .. note::
 
@@ -82,7 +128,7 @@ shell scripts:
 
 Add comments by prefixing them with ``#``:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     # Database credentials
     DB_USER=root
@@ -90,14 +136,22 @@ Add comments by prefixing them with ``#``:
 
 Use environment variables in values by prefixing variables with ``$``:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     DB_USER=root
     DB_PASS=${DB_USER}pass # Include the user as a password prefix
 
+.. note::
+
+    The order is important when some env var depends on the value of other env
+    vars. In the above example, ``DB_PASS`` must be defined after ``DB_USER``.
+    Moreover, if you define multiple ``.env`` files and put ``DB_PASS`` first,
+    its value will depend on the ``DB_USER`` value defined in other files
+    instead of the value defined in this file.
+
 Embed commands via ``$()`` (not supported on Windows):
 
-.. code-block:: bash
+.. code-block:: terminal
 
     START_TIME=$(date)
 
@@ -105,5 +159,4 @@ Embed commands via ``$()`` (not supported on Windows):
 
     Note that using ``$()`` might not work depending on your shell.
 
-.. _Packagist: https://packagist.org/packages/symfony/dotenv
 .. _twelve-factor applications: http://www.12factor.net/
diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst
index 658de8c358f..89853d22941 100644
--- a/components/event_dispatcher.rst
+++ b/components/event_dispatcher.rst
@@ -13,7 +13,7 @@ Introduction
 ------------
 
 Object-oriented code has gone a long way to ensuring code extensibility.
-By creating classes that have well defined responsibilities, your code becomes
+By creating classes that have well-defined responsibilities, your code becomes
 more flexible and a developer can extend them with subclasses to modify
 their behaviors. But if they want to share the changes with other developers
 who have also made their own subclasses, code inheritance is no longer the
@@ -56,8 +56,6 @@ Installation
 
     $ composer require symfony/event-dispatcher
 
-Alternatively, you can clone the `<https://github.com/symfony/event-dispatcher>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -74,7 +72,7 @@ Events
 
 When an event is dispatched, it's identified by a unique name (e.g.
 ``kernel.response``), which any number of listeners might be listening to.
-An :class:`Symfony\\Component\\EventDispatcher\\Event` instance is also
+An :class:`Symfony\\Contracts\\EventDispatcher\\Event` instance is also
 created and passed to all of the listeners. As you'll see later, the ``Event``
 object itself often contains data about the event being dispatched.
 
@@ -88,7 +86,7 @@ The unique event name can be any string, but optionally follows a few
 naming conventions:
 
 * Use only lowercase letters, numbers, dots (``.``) and underscores (``_``);
-* Prefix names with a namespace followed by a dot (e.g. ``order.``, ``user.*``);
+* Prefix names with a namespace followed by a dot (e.g. ``order.*``, ``user.*``);
 * End names with a verb that indicates what action has been taken (e.g.
   ``order.placed``).
 
@@ -113,7 +111,7 @@ Often times, data about a specific event needs to be passed along with the
 case, a special subclass that has additional methods for retrieving and
 overriding information can be passed when dispatching an event. For example,
 the ``kernel.response`` event uses a
-:class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`, which
+:class:`Symfony\\Component\\HttpKernel\\Event\\ResponseEvent`, which
 contains methods to get and even replace the ``Response`` object.
 
 The Dispatcher
@@ -163,7 +161,7 @@ The ``addListener()`` method takes up to three arguments:
     So far, you've seen how PHP objects can be registered as listeners.
     You can also register PHP `Closures`_ as event listeners::
 
-        use Symfony\Component\EventDispatcher\Event;
+        use Symfony\Contracts\EventDispatcher\Event;
 
         $dispatcher->addListener('acme.foo.action', function (Event $event) {
             // will be executed when the acme.foo.action event is dispatched
@@ -174,7 +172,7 @@ is notified. In the above example, when the ``acme.foo.action`` event is dispatc
 the dispatcher calls the ``AcmeListener::onFooAction()`` method and passes
 the ``Event`` object as the single argument::
 
-    use Symfony\Component\EventDispatcher\Event;
+    use Symfony\Contracts\EventDispatcher\Event;
 
     class AcmeListener
     {
@@ -201,8 +199,8 @@ determine which instance is passed.
         use Symfony\Component\DependencyInjection\ContainerBuilder;
         use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
         use Symfony\Component\DependencyInjection\Reference;
-        use Symfony\Component\EventDispatcher\EventDispatcher;
         use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;
+        use Symfony\Component\EventDispatcher\EventDispatcher;
 
         $containerBuilder = new ContainerBuilder(new ParameterBag());
         // register the compiler pass that handles the 'kernel.event_listener'
@@ -253,8 +251,8 @@ order. Start by creating this custom event class and documenting it::
 
     namespace Acme\Store\Event;
 
-    use Symfony\Component\EventDispatcher\Event;
     use Acme\Store\Order;
+    use Symfony\Contracts\EventDispatcher\Event;
 
     /**
      * The order.placed event is dispatched each time an order is created
@@ -262,7 +260,7 @@ order. Start by creating this custom event class and documenting it::
      */
     class OrderPlacedEvent extends Event
     {
-        const NAME = 'order.placed';
+        public const NAME = 'order.placed';
 
         protected $order;
 
@@ -283,7 +281,7 @@ Each listener now has access to the order via the ``getOrder()`` method.
 
     If you don't need to pass any additional data to the event listeners, you
     can also use the default
-    :class:`Symfony\\Component\\EventDispatcher\\Event` class. In such case,
+    :class:`Symfony\\Contracts\\EventDispatcher\\Event` class. In such case,
     you can document the event and its name in a generic ``StoreEvents`` class,
     similar to the :class:`Symfony\\Component\\HttpKernel\\KernelEvents`
     class.
@@ -293,11 +291,11 @@ Dispatch the Event
 
 The :method:`Symfony\\Component\\EventDispatcher\\EventDispatcher::dispatch`
 method notifies all listeners of the given event. It takes two arguments:
-the name of the event to dispatch and the ``Event`` instance to pass to
-each listener of that event::
+the ``Event`` instance to pass to each listener of that event and the name
+of the event to dispatch and ::
 
-    use Acme\Store\Order;
     use Acme\Store\Event\OrderPlacedEvent;
+    use Acme\Store\Order;
 
     // the order is somehow created or retrieved
     $order = new Order();
@@ -305,7 +303,7 @@ each listener of that event::
 
     // creates the OrderPlacedEvent and dispatches it
     $event = new OrderPlacedEvent($order);
-    $dispatcher->dispatch(OrderPlacedEvent::NAME, $event);
+    $dispatcher->dispatch($event, OrderPlacedEvent::NAME);
 
 Notice that the special ``OrderPlacedEvent`` object is created and passed to
 the ``dispatch()`` method. Now, any listener to the ``order.placed``
@@ -334,10 +332,10 @@ Take the following example of a subscriber that subscribes to the
 
     namespace Acme\Store\Event;
 
+    use Acme\Store\Event\OrderPlacedEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-    use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
+    use Symfony\Component\HttpKernel\Event\ResponseEvent;
     use Symfony\Component\HttpKernel\KernelEvents;
-    use Acme\Store\Event\OrderPlacedEvent;
 
     class StoreSubscriber implements EventSubscriberInterface
     {
@@ -352,12 +350,12 @@ Take the following example of a subscriber that subscribes to the
             ];
         }
 
-        public function onKernelResponsePre(FilterResponseEvent $event)
+        public function onKernelResponsePre(ResponseEvent $event)
         {
             // ...
         }
 
-        public function onKernelResponsePost(FilterResponseEvent $event)
+        public function onKernelResponsePost(ResponseEvent $event)
         {
             // ...
         }
@@ -421,11 +419,11 @@ Now, any listeners to ``order.placed`` that have not yet been called will
 *not* be called.
 
 It is possible to detect if an event was stopped by using the
-:method:`Symfony\\Component\\EventDispatcher\\Event::isPropagationStopped`
+:method:`Symfony\\Contracts\\EventDispatcher\\Event::isPropagationStopped`
 method which returns a boolean value::
 
     // ...
-    $dispatcher->dispatch('foo.event', $event);
+    $dispatcher->dispatch($event, 'foo.event');
     if ($event->isPropagationStopped()) {
         // ...
     }
@@ -443,36 +441,6 @@ name and a reference to itself to the listeners. This can lead to some advanced
 applications of the ``EventDispatcher`` including dispatching other events inside
 listeners, chaining events or even lazy loading listeners into the dispatcher object.
 
-.. index::
-   single: EventDispatcher; Dispatcher shortcuts
-
-.. _event_dispatcher-shortcuts:
-
-Dispatcher Shortcuts
-~~~~~~~~~~~~~~~~~~~~
-
-If you do not need a custom event object, you can rely on a plain
-:class:`Symfony\\Component\\EventDispatcher\\Event` object. You do not even
-need to pass this to the dispatcher as it will create one by default unless you
-specifically pass one::
-
-    $dispatcher->dispatch('order.placed');
-
-Moreover, the event dispatcher always returns whichever event object that
-was dispatched, i.e. either the event that was passed or the event that
-was created internally by the dispatcher. This allows for nice shortcuts::
-
-    if (!$dispatcher->dispatch('foo.event')->isPropagationStopped()) {
-        // ...
-    }
-
-Or::
-
-    $event = new OrderPlacedEvent($order);
-    $order = $dispatcher->dispatch('bar.event', $event)->getOrder();
-
-and so on.
-
 .. index::
    single: EventDispatcher; Event name introspection
 
@@ -484,8 +452,8 @@ Event Name Introspection
 The ``EventDispatcher`` instance, as well as the name of the event that
 is dispatched, are passed as arguments to the listener::
 
-    use Symfony\Component\EventDispatcher\Event;
-    use Symfony\Component\EventDispatcher\EventDispatcherInterface;
+    use Symfony\Contracts\EventDispatcher\Event;
+    use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
     class Foo
     {
@@ -522,4 +490,3 @@ Learn More
 .. _Observer: https://en.wikipedia.org/wiki/Observer_pattern
 .. _Closures: https://php.net/manual/en/functions.anonymous.php
 .. _PHP callable: https://php.net/manual/en/language.pseudo-types.php#language.types.callback
-.. _Packagist: https://packagist.org/packages/symfony/event-dispatcher
diff --git a/components/event_dispatcher/generic_event.rst b/components/event_dispatcher/generic_event.rst
index cc00d26ac20..1f9be477151 100644
--- a/components/event_dispatcher/generic_event.rst
+++ b/components/event_dispatcher/generic_event.rst
@@ -4,7 +4,7 @@
 The Generic Event Object
 ========================
 
-The base :class:`Symfony\\Component\\EventDispatcher\\Event` class provided
+The base :class:`Symfony\\Contracts\\EventDispatcher\\Event` class provided
 by the EventDispatcher component is deliberately sparse to allow the creation
 of API specific event objects by inheritance using OOP. This allows for
 elegant and readable code in complex applications.
@@ -18,7 +18,7 @@ arguments.
 
 :class:`Symfony\\Component\\EventDispatcher\\GenericEvent` adds some more
 methods in addition to the base class
-:class:`Symfony\\Component\\EventDispatcher\\Event`
+:class:`Symfony\\Contracts\\EventDispatcher\\Event`
 
 * :method:`Symfony\\Component\\EventDispatcher\\GenericEvent::__construct`:
   Constructor takes the event subject and any arguments;
@@ -53,7 +53,7 @@ Passing a subject::
     use Symfony\Component\EventDispatcher\GenericEvent;
 
     $event = new GenericEvent($subject);
-    $dispatcher->dispatch('foo', $event);
+    $dispatcher->dispatch($event, 'foo');
 
     class FooListener
     {
@@ -74,7 +74,7 @@ access the event arguments::
         $subject,
         ['type' => 'foo', 'counter' => 0]
     );
-    $dispatcher->dispatch('foo', $event);
+    $dispatcher->dispatch($event, 'foo');
 
     class FooListener
     {
@@ -93,7 +93,7 @@ Filtering data::
     use Symfony\Component\EventDispatcher\GenericEvent;
 
     $event = new GenericEvent($subject, ['data' => 'Foo']);
-    $dispatcher->dispatch('foo', $event);
+    $dispatcher->dispatch($event, 'foo');
 
     class FooListener
     {
diff --git a/components/event_dispatcher/traceable_dispatcher.rst b/components/event_dispatcher/traceable_dispatcher.rst
index 57f05ba6e0d..87d58023445 100644
--- a/components/event_dispatcher/traceable_dispatcher.rst
+++ b/components/event_dispatcher/traceable_dispatcher.rst
@@ -38,7 +38,7 @@ to register event listeners and dispatch events::
 
     // dispatches an event
     $event = ...;
-    $traceableEventDispatcher->dispatch('event.the_name', $event);
+    $traceableEventDispatcher->dispatch($event, 'event.the_name');
 
 After your application has been processed, you can use the
 :method:`Symfony\\Component\\EventDispatcher\\Debug\\TraceableEventDispatcherInterface::getCalledListeners`
diff --git a/components/expression_language.rst b/components/expression_language.rst
index 1e75bdeb78f..7e955a8b891 100644
--- a/components/expression_language.rst
+++ b/components/expression_language.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/expression-language
 
-Alternatively, you can clone the `<https://github.com/symfony/expression-language>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 How can the Expression Engine Help Me?
@@ -131,5 +129,3 @@ Learn More
     /components/expression_language/*
     /service_container/expression_language
     /reference/constraints/Expression
-
-.. _Packagist: https://packagist.org/packages/symfony/expression-language
diff --git a/components/expression_language/caching.rst b/components/expression_language/caching.rst
index 5bfaf15133a..770c2768ca5 100644
--- a/components/expression_language/caching.rst
+++ b/components/expression_language/caching.rst
@@ -31,8 +31,8 @@ uses an :class:`Symfony\\Component\\Cache\\Adapter\\ArrayAdapter`). You can
 customize this by creating a custom cache pool or using one of the available
 ones and injecting this using the constructor::
 
-    use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
     use Symfony\Component\Cache\Adapter\RedisAdapter;
+    use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
     $cache = new RedisAdapter(...);
     $expressionLanguage = new ExpressionLanguage($cache);
diff --git a/components/expression_language/extending.rst b/components/expression_language/extending.rst
index 9f055d84156..e3ec448a495 100644
--- a/components/expression_language/extending.rst
+++ b/components/expression_language/extending.rst
@@ -29,7 +29,7 @@ This method has 3 arguments:
   function;
 * **evaluator** - A function executed when the expression is evaluated.
 
-.. code-block:: php
+Example::
 
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
@@ -127,7 +127,7 @@ or by using the second argument of the constructor::
         {
             public function __construct(CacheItemPoolInterface $parser = null, array $providers = [])
             {
-                // prepends the default provider to let users override it easily
+                // prepends the default provider to let users override it
                 array_unshift($providers, new StringExpressionLanguageProvider());
 
                 parent::__construct($parser, $providers);
diff --git a/components/filesystem.rst b/components/filesystem.rst
index 5aee48f7c23..10406ce68c9 100644
--- a/components/filesystem.rst
+++ b/components/filesystem.rst
@@ -13,8 +13,6 @@ Installation
 
     $ composer require symfony/filesystem
 
-Alternatively, you can clone the `<https://github.com/symfony/filesystem>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -23,13 +21,13 @@ Usage
 The :class:`Symfony\\Component\\Filesystem\\Filesystem` class is the unique
 endpoint for filesystem operations::
 
-    use Symfony\Component\Filesystem\Filesystem;
     use Symfony\Component\Filesystem\Exception\IOExceptionInterface;
+    use Symfony\Component\Filesystem\Filesystem;
 
-    $fileSystem = new Filesystem();
+    $filesystem = new Filesystem();
 
     try {
-        $fileSystem->mkdir(sys_get_temp_dir().'/'.random_int(0, 1000));
+        $filesystem->mkdir(sys_get_temp_dir().'/'.random_int(0, 1000));
     } catch (IOExceptionInterface $exception) {
         echo "An error occurred while creating your directory at ".$exception->getPath();
     }
@@ -53,7 +51,7 @@ mkdir
 On POSIX filesystems, directories are created with a default mode value
 `0777`. You can use the second argument to set your own mode::
 
-    $fileSystem->mkdir('/tmp/photos', 0700);
+    $filesystem->mkdir('/tmp/photos', 0700);
 
 .. note::
 
@@ -79,11 +77,11 @@ presence of one or more files or directories and returns ``false`` if any of
 them is missing::
 
     // if this absolute directory exists, returns true
-    $fileSystem->exists('/tmp/photos');
+    $filesystem->exists('/tmp/photos');
 
     // if rabbit.jpg exists and bottle.png does not exist, returns false
     // non-absolute paths are relative to the directory where the running PHP script is stored
-    $fileSystem->exists(['rabbit.jpg', 'bottle.png']);
+    $filesystem->exists(['rabbit.jpg', 'bottle.png']);
 
 .. note::
 
@@ -100,10 +98,10 @@ source modification date is later than the target. This behavior can be overridd
 by the third boolean argument::
 
     // works only if image-ICC has been modified after image.jpg
-    $fileSystem->copy('image-ICC.jpg', 'image.jpg');
+    $filesystem->copy('image-ICC.jpg', 'image.jpg');
 
     // image.jpg will be overridden
-    $fileSystem->copy('image-ICC.jpg', 'image.jpg', true);
+    $filesystem->copy('image-ICC.jpg', 'image.jpg', true);
 
 touch
 ~~~~~
@@ -113,11 +111,11 @@ modification time for a file. The current time is used by default. You can set
 your own with the second argument. The third argument is the access time::
 
     // sets modification time to the current timestamp
-    $fileSystem->touch('file.txt');
+    $filesystem->touch('file.txt');
     // sets modification time 10 seconds in the future
-    $fileSystem->touch('file.txt', time() + 10);
+    $filesystem->touch('file.txt', time() + 10);
     // sets access time 10 seconds in the past
-    $fileSystem->touch('file.txt', time(), time() - 10);
+    $filesystem->touch('file.txt', time(), time() - 10);
 
 .. note::
 
@@ -131,9 +129,9 @@ chown
 a file. The third argument is a boolean recursive option::
 
     // sets the owner of the lolcat video to www-data
-    $fileSystem->chown('lolcat.mp4', 'www-data');
+    $filesystem->chown('lolcat.mp4', 'www-data');
     // changes the owner of the video directory recursively
-    $fileSystem->chown('/video', 'www-data', true);
+    $filesystem->chown('/video', 'www-data', true);
 
 .. note::
 
@@ -147,9 +145,9 @@ chgrp
 a file. The third argument is a boolean recursive option::
 
     // sets the group of the lolcat video to nginx
-    $fileSystem->chgrp('lolcat.mp4', 'nginx');
+    $filesystem->chgrp('lolcat.mp4', 'nginx');
     // changes the group of the video directory recursively
-    $fileSystem->chgrp('/video', 'nginx', true);
+    $filesystem->chgrp('/video', 'nginx', true);
 
 .. note::
 
@@ -163,9 +161,9 @@ chmod
 permissions of a file. The fourth argument is a boolean recursive option::
 
     // sets the mode of the video to 0600
-    $fileSystem->chmod('video.ogg', 0600);
+    $filesystem->chmod('video.ogg', 0600);
     // changes the mod of the src directory recursively
-    $fileSystem->chmod('src', 0700, 0000, true);
+    $filesystem->chmod('src', 0700, 0000, true);
 
 .. note::
 
@@ -178,7 +176,7 @@ remove
 :method:`Symfony\\Component\\Filesystem\\Filesystem::remove` deletes files,
 directories and symlinks::
 
-    $fileSystem->remove(['symlink', '/path/to/directory', 'activity.log']);
+    $filesystem->remove(['symlink', '/path/to/directory', 'activity.log']);
 
 .. note::
 
@@ -192,9 +190,9 @@ rename
 of a single file or directory::
 
     // renames a file
-    $fileSystem->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
+    $filesystem->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
     // renames a directory
-    $fileSystem->rename('/tmp/files', '/path/to/store/files');
+    $filesystem->rename('/tmp/files', '/path/to/store/files');
 
 symlink
 ~~~~~~~
@@ -204,10 +202,10 @@ symbolic link from the target to the destination. If the filesystem does not
 support symbolic links, a third boolean argument is available::
 
     // creates a symbolic link
-    $fileSystem->symlink('/path/to/source', '/path/to/destination');
+    $filesystem->symlink('/path/to/source', '/path/to/destination');
     // duplicates the source directory if the filesystem
     // does not support symbolic links
-    $fileSystem->symlink('/path/to/source', '/path/to/destination', true);
+    $filesystem->symlink('/path/to/source', '/path/to/destination', true);
 
 readlink
 ~~~~~~~~
@@ -223,10 +221,10 @@ The :method:`Symfony\\Component\\Filesystem\\Filesystem::readlink` method provid
 by the Filesystem component always behaves in the same way::
 
     // returns the next direct target of the link without considering the existence of the target
-    $fileSystem->readlink('/path/to/link');
+    $filesystem->readlink('/path/to/link');
 
     // returns its absolute fully resolved final version of the target (if there are nested links, they are resolved)
-    $fileSystem->readlink('/path/to/link', true);
+    $filesystem->readlink('/path/to/link', true);
 
 Its behavior is the following::
 
@@ -247,12 +245,12 @@ makePathRelative
 absolute paths and returns the relative path from the second path to the first one::
 
     // returns '../'
-    $fileSystem->makePathRelative(
+    $filesystem->makePathRelative(
         '/var/lib/symfony/src/Symfony/',
         '/var/lib/symfony/src/Symfony/Component'
     );
     // returns 'videos/'
-    $fileSystem->makePathRelative('/tmp/videos', '/tmp')
+    $filesystem->makePathRelative('/tmp/videos', '/tmp')
 
 mirror
 ~~~~~~
@@ -262,7 +260,7 @@ contents of the source directory into the target one (use the
 :method:`Symfony\\Component\\Filesystem\\Filesystem::copy` method to copy single
 files)::
 
-    $fileSystem->mirror('/path/to/source', '/path/to/target');
+    $filesystem->mirror('/path/to/source', '/path/to/target');
 
 isAbsolutePath
 ~~~~~~~~~~~~~~
@@ -271,13 +269,13 @@ isAbsolutePath
 ``true`` if the given path is absolute, ``false`` otherwise::
 
     // returns true
-    $fileSystem->isAbsolutePath('/tmp');
+    $filesystem->isAbsolutePath('/tmp');
     // returns true
-    $fileSystem->isAbsolutePath('c:\\Windows');
+    $filesystem->isAbsolutePath('c:\\Windows');
     // returns false
-    $fileSystem->isAbsolutePath('tmp');
+    $filesystem->isAbsolutePath('tmp');
     // returns false
-    $fileSystem->isAbsolutePath('../dir');
+    $filesystem->isAbsolutePath('../dir');
 
 tempnam
 ~~~~~~~
@@ -296,7 +294,7 @@ file first and then moves it to the new file location when it's finished.
 This means that the user will always see either the complete old file or
 complete new file (but never a partially-written file)::
 
-    $fileSystem->dumpFile('file.txt', 'Hello World');
+    $filesystem->dumpFile('file.txt', 'Hello World');
 
 The ``file.txt`` file contains ``Hello World`` now.
 
@@ -306,7 +304,7 @@ appendToFile
 :method:`Symfony\\Component\\Filesystem\\Filesystem::appendToFile` adds new
 contents at the end of some file::
 
-    $fileSystem->appendToFile('logs.txt', 'Email sent to user@example.com');
+    $filesystem->appendToFile('logs.txt', 'Email sent to user@example.com');
 
 If either the file or its containing directory doesn't exist, this method
 creates them before appending the contents.
@@ -323,5 +321,4 @@ Whenever something wrong happens, an exception implementing
     An :class:`Symfony\\Component\\Filesystem\\Exception\\IOException` is
     thrown if directory creation fails.
 
-.. _`Packagist`: https://packagist.org/packages/symfony/filesystem
 .. _`umask`: https://en.wikipedia.org/wiki/Umask
diff --git a/components/finder.rst b/components/finder.rst
index ab47dbd09db..2201150ffa1 100644
--- a/components/finder.rst
+++ b/components/finder.rst
@@ -5,8 +5,8 @@
 The Finder Component
 ====================
 
-    The Finder component finds files and directories via an intuitive fluent
-    interface.
+    The Finder component finds files and directories based on different criteria
+    (name, file size, modification time, etc.) via an intuitive fluent interface.
 
 Installation
 ------------
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/finder
 
-Alternatively, you can clone the `<https://github.com/symfony/finder>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -28,57 +26,36 @@ directories::
     use Symfony\Component\Finder\Finder;
 
     $finder = new Finder();
+    // find all files in the current directory
     $finder->files()->in(__DIR__);
 
-    foreach ($finder as $file) {
-        // dumps the absolute path
-        var_dump($file->getRealPath());
-
-        // dumps the relative path to the file, omitting the filename
-        var_dump($file->getRelativePath());
-
-        // dumps the relative path to the file
-        var_dump($file->getRelativePathname());
+    // check if there are any search results
+    if ($finder->hasResults()) {
+        // ...
     }
 
-The ``$file`` is an instance of :class:`Symfony\\Component\\Finder\\SplFileInfo`
-which extends PHP's own :phpclass:`SplFileInfo` to provide methods to work with relative
-paths.
-
-The above code prints the names of all the files in the current directory
-recursively. The Finder class uses a fluent interface, so all methods return
-the Finder instance.
+    foreach ($finder as $file) {
+        $absoluteFilePath = $file->getRealPath();
+        $fileNameWithExtension = $file->getRelativePathname();
 
-.. tip::
+        // ...
+    }
 
-    A Finder instance is a PHP :phpclass:`IteratorAggregate`. So, in addition to iterating over the
-    Finder with ``foreach``, you can also convert it to an array with the
-    :phpfunction:`iterator_to_array` function, or get the number of items with
-    :phpfunction:`iterator_count`.
+The ``$file`` variable is an instance of
+:class:`Symfony\\Component\\Finder\\SplFileInfo` which extends PHP's own
+:phpclass:`SplFileInfo` to provide methods to work with relative paths.
 
 .. caution::
 
     The ``Finder`` object doesn't reset its internal state automatically.
     This means that you need to create a new instance if you do not want
-    get mixed results.
+    to get mixed results.
 
-.. caution::
+Searching for Files and Directories
+-----------------------------------
 
-    When searching through multiple locations passed to the
-    :method:`Symfony\\Component\\Finder\\Finder::in` method, a separate iterator
-    is created internally for every location. This means we have multiple result
-    sets aggregated into one.
-    Since :phpfunction:`iterator_to_array` uses keys of result sets by default,
-    when converting to an array, some keys might be duplicated and their values
-    overwritten. This can be avoided by passing ``false`` as a second parameter
-    to :phpfunction:`iterator_to_array`.
-
-Criteria
---------
-
-There are lots of ways to filter and sort your results. You can also use the
-:method:`Symfony\\Component\\Finder\\Finder::hasResults` method to check if
-there's any file or directory matching the search criteria.
+The component provides lots of methods to define the search criteria. They all
+can be chained because they implement a `fluent interface`_.
 
 Location
 ~~~~~~~~
@@ -97,12 +74,11 @@ Search in several locations by chaining calls to
     // same as above
     $finder->in(__DIR__)->in('/elsewhere');
 
-Use wildcard characters to search in the directories matching a pattern::
+Use ``*`` as a wildcard character to search in the directories matching a
+pattern (each pattern has to resolve to at least one directory path)::
 
     $finder->in('src/Symfony/*/*/Resources');
 
-Each pattern has to resolve to at least one directory path.
-
 Exclude directories from matching with the
 :method:`Symfony\\Component\\Finder\\Finder::exclude` method::
 
@@ -114,7 +90,7 @@ It's also possible to ignore directories that you don't have permission to read:
     $finder->ignoreUnreadableDirs()->in(__DIR__);
 
 As the Finder uses PHP iterators, you can pass any URL with a supported
-`protocol`_::
+`PHP wrapper for URL-style protocols`_ (``ftp://``, ``zlib://``, etc.)::
 
     // always add a trailing slash when looking for in the FTP root dir
     $finder->in('ftp://example.com/');
@@ -126,8 +102,9 @@ And it also works with user-defined streams::
 
     use Symfony\Component\Finder\Finder;
 
-    $s3 = new \Zend_Service_Amazon_S3($key, $secret);
-    $s3->registerStreamWrapper('s3');
+    // register a 's3://' wrapper with the official AWS SDK
+    $s3Client = new Aws\S3\S3Client([/* config options */]);
+    $s3Client->registerStreamWrapper();
 
     $finder = new Finder();
     $finder->name('photos*')->size('< 100K')->date('since 1 hour ago');
@@ -135,9 +112,9 @@ And it also works with user-defined streams::
         // ... do something with the file
     }
 
-.. note::
+.. seealso::
 
-    Read the `Streams`_ documentation to learn how to create your own streams.
+    Read the `PHP streams`_ documentation to learn how to create your own streams.
 
 Files or Directories
 ~~~~~~~~~~~~~~~~~~~~
@@ -146,77 +123,72 @@ By default, the Finder returns files and directories; but the
 :method:`Symfony\\Component\\Finder\\Finder::files` and
 :method:`Symfony\\Component\\Finder\\Finder::directories` methods control that::
 
+    // look for files only; ignore directories
     $finder->files();
 
+    // look for directories only; ignore files
     $finder->directories();
 
-If you want to follow links, use the ``followLinks()`` method::
+If you want to follow `symbolic links`_, use the ``followLinks()`` method::
 
     $finder->files()->followLinks();
 
-By default, the iterator ignores popular VCS files. This can be changed with
-the ``ignoreVCS()`` method::
-
-    $finder->ignoreVCS(false);
-
-Sorting
-~~~~~~~
-
-Sort the result by name or by type (directories first, then files)::
-
-    $finder->sortByName();
-
-    $finder->sortByType();
+Version Control Files
+~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+`Version Control Systems`_ (or "VCS" for short), such as Git and Mercurial,
+create some special files to store their metadata. Those files are ignored by
+default when looking for files and directories, but you can change this with the
+``ignoreVCS()`` method::
 
-    By default, the ``sortByName()`` method uses the :phpfunction:`strcmp` PHP
-    function (e.g. ``file1.txt``, ``file10.txt``, ``file2.txt``). Pass ``true``
-    as its argument to use PHP's `natural sort order`_ algorithm instead (e.g.
-    ``file1.txt``, ``file2.txt``, ``file10.txt``).
-
-    .. versionadded:: 4.2
-        The option to use the natural sort order was introduced in Symfony 4.2.
-
-Sort the files and directories by the last accessed, changed or modified time::
-
-    $finder->sortByAccessedTime();
-
-    $finder->sortByChangedTime();
+    $finder->ignoreVCS(false);
 
-    $finder->sortByModifiedTime();
+If the search directory contains a ``.gitignore`` file, you can reuse those
+rules to exclude files and directories from the results with the
+:method:`Symfony\\Component\\Finder\\Finder::ignoreVCSIgnored` method::
 
-You can also define your own sorting algorithm with ``sort()`` method::
+    // excludes files/directories matching the .gitignore patterns
+    $finder->ignoreVCSIgnored(true);
 
-    $finder->sort(function (\SplFileInfo $a, \SplFileInfo $b) {
-        return strcmp($a->getRealPath(), $b->getRealPath());
-    });
+.. versionadded:: 4.3
 
-.. note::
-
-    Notice that the ``sort*`` methods need to get all matching elements to do
-    their jobs. For large iterators, it is slow.
+    The ``ignoreVCSIgnored()`` method was introduced in Symfony 4.3.
 
 File Name
 ~~~~~~~~~
 
-Restrict files by name with the
+Find files by name with the
 :method:`Symfony\\Component\\Finder\\Finder::name` method::
 
     $finder->files()->name('*.php');
 
-The ``name()`` method accepts globs, strings, or regexes::
+The ``name()`` method accepts globs, strings, regexes or an array of globs,
+strings or regexes::
 
     $finder->files()->name('/\.php$/');
 
+Multiple filenames can be defined by chaining calls or passing an array::
+
+    $finder->files()->name('*.php')->name('*.twig');
+
+    // same as above
+    $finder->files()->name(['*.php', '*.twig']);
+
 The ``notName()`` method excludes files matching a pattern::
 
     $finder->files()->notName('*.rb');
 
+Multiple filenames can be excluded by chaining calls or passing an array::
+
+    $finder->files()->notName('*.rb')->notName('*.py');
+
+    // same as above
+    $finder->files()->notName(['*.rb', '*.py']);
+
 File Contents
 ~~~~~~~~~~~~~
 
-Restrict files by contents with the
+Find files by content with the
 :method:`Symfony\\Component\\Finder\\Finder::contains` method::
 
     $finder->files()->contains('lorem ipsum');
@@ -232,7 +204,7 @@ The ``notContains()`` method excludes files containing given pattern::
 Path
 ~~~~
 
-Restrict files and directories by path with the
+Find files and directories by path with the
 :method:`Symfony\\Component\\Finder\\Finder::path` method::
 
     // matches files that contain "data" anywhere in their paths (files or directories)
@@ -240,39 +212,66 @@ Restrict files and directories by path with the
     // for example this will match data/*.xml and data.xml if they exist
     $finder->path('data')->name('*.xml');
 
-On all platforms slash (i.e. ``/``) should be used as the directory separator.
+Use the forward slash (i.e. ``/``) as the directory separator on all platforms,
+including Windows. The component makes the necessary conversion internally.
 
-The ``path()`` method accepts a string or a regular expression::
+The ``path()`` method accepts a string, a regular expression or an array of
+strings or regulars expressions::
 
     $finder->path('foo/bar');
     $finder->path('/^foo\/bar/');
 
+Multiple paths can be defined by chaining calls or passing an array::
+
+    $finder->path('data')->path('foo/bar');
+
+    // same as above
+    $finder->path(['data', 'foo/bar']);
+
 Internally, strings are converted into regular expressions by escaping slashes
 and adding delimiters:
 
-.. code-block:: text
-
-    dirname    ===>    /dirname/
-    a/b/c      ===>    /a\/b\/c/
+=====================  =======================
+Original Given String  Regular Expression Used
+=====================  =======================
+``dirname``            ``/dirname/``
+``a/b/c``              ``/a\/b\/c/``
+=====================  =======================
 
-The :method:`Symfony\\Component\\Finder\\Finder::notPath` method excludes files by path::
+The :method:`Symfony\\Component\\Finder\\Finder::notPath` method excludes files
+by path::
 
     $finder->notPath('other/dir');
 
+Multiple paths can be excluded by chaining calls or passing an array::
+
+    $finder->notPath('first/dir')->notPath('other/dir');
+
+    // same as above
+    $finder->notPath(['first/dir', 'other/dir']);
+
+.. versionadded:: 4.2
+
+    Support for passing arrays to ``notPath()`` was introduced in Symfony
+    4.2
+
 File Size
 ~~~~~~~~~
 
-Restrict files by size with the
+Find files by size with the
 :method:`Symfony\\Component\\Finder\\Finder::size` method::
 
     $finder->files()->size('< 1.5K');
 
-Restrict by a size range by chaining calls::
+Restrict by a size range by chaining calls or passing an array::
 
     $finder->files()->size('>= 1K')->size('<= 2K');
 
-The comparison operator can be any of the following: ``>``, ``>=``, ``<``, ``<=``,
-``==``, ``!=``.
+    // same as above
+    $finder->files()->size(['>= 1K', '<= 2K']);
+
+The comparison operator can be any of the following: ``>``, ``>=``, ``<``,
+``<=``, ``==``, ``!=``.
 
 The target value may use magnitudes of kilobytes (``k``, ``ki``), megabytes
 (``m``, ``mi``), or gigabytes (``g``, ``gi``). Those suffixed with an ``i`` use
@@ -281,30 +280,44 @@ the appropriate ``2**n`` version in accordance with the `IEC standard`_.
 File Date
 ~~~~~~~~~
 
-Restrict files by last modified dates with the
+Find files by last modified dates with the
 :method:`Symfony\\Component\\Finder\\Finder::date` method::
 
     $finder->date('since yesterday');
 
-The comparison operator can be any of the following: ``>``, ``>=``, ``<``, ``<=``,
-``==``. You can also use ``since`` or ``after`` as an alias for ``>``, and
-``until`` or ``before`` as an alias for ``<``.
+Restrict by a date range by chaining calls or passing an array::
+
+    $finder->date('>= 2018-01-01')->date('<= 2018-12-31');
+
+    // same as above
+    $finder->date(['>= 2018-01-01', '<= 2018-12-31']);
+
+The comparison operator can be any of the following: ``>``, ``>=``, ``<``,
+``<=``, ``==``. You can also use ``since`` or ``after`` as an alias for ``>``,
+and ``until`` or ``before`` as an alias for ``<``.
 
-The target value can be any date supported by the `strtotime`_ function.
+The target value can be any date supported by :phpfunction:`strtotime`.
 
 Directory Depth
 ~~~~~~~~~~~~~~~
 
-By default, the Finder recursively traverse directories. Restrict the depth of
+By default, the Finder recursively traverses directories. Restrict the depth of
 traversing with :method:`Symfony\\Component\\Finder\\Finder::depth`::
 
     $finder->depth('== 0');
     $finder->depth('< 3');
 
+Restrict by a depth range by chaining calls or passing an array::
+
+    $finder->depth('> 2')->depth('< 5');
+
+    // same as above
+    $finder->depth(['> 2', '< 5']);
+
 Custom Filtering
 ~~~~~~~~~~~~~~~~
 
-To restrict the matching file with your own strategy, use
+To filter results with your own strategy, use
 :method:`Symfony\\Component\\Finder\\Finder::filter`::
 
     $filter = function (\SplFileInfo $file)
@@ -321,8 +334,63 @@ it is called with the file as a :class:`Symfony\\Component\\Finder\\SplFileInfo`
 instance. The file is excluded from the result set if the Closure returns
 ``false``.
 
+Sorting Results
+---------------
+
+Sort the results by name or by type (directories first, then files)::
+
+    $finder->sortByName();
+
+    $finder->sortByType();
+
+.. tip::
+
+    By default, the ``sortByName()`` method uses the :phpfunction:`strcmp` PHP
+    function (e.g. ``file1.txt``, ``file10.txt``, ``file2.txt``). Pass ``true``
+    as its argument to use PHP's `natural sort order`_ algorithm instead (e.g.
+    ``file1.txt``, ``file2.txt``, ``file10.txt``).
+
+Sort the files and directories by the last accessed, changed or modified time::
+
+    $finder->sortByAccessedTime();
+
+    $finder->sortByChangedTime();
+
+    $finder->sortByModifiedTime();
+
+You can also define your own sorting algorithm with the ``sort()`` method::
+
+    $finder->sort(function (\SplFileInfo $a, \SplFileInfo $b) {
+        return strcmp($a->getRealPath(), $b->getRealPath());
+    });
+
+You can reverse any sorting by using the ``reverseSorting()`` method::
+
+    // results will be sorted "Z to A" instead of the default "A to Z"
+    $finder->sortByName()->reverseSorting();
+
+.. note::
+
+    Notice that the ``sort*`` methods need to get all matching elements to do
+    their jobs. For large iterators, it is slow.
+
+Transforming Results into Arrays
+--------------------------------
+
+A Finder instance is an :phpclass:`IteratorAggregate` PHP class. So, in addition
+to iterating over the Finder results with ``foreach``, you can also convert it
+to an array with the :phpfunction:`iterator_to_array` function, or get the
+number of items with :phpfunction:`iterator_count`.
+
+If you call to the :method:`Symfony\\Component\\Finder\\Finder::in` method more
+than once to search through multiple locations, pass ``false`` as a second
+parameter to :phpfunction:`iterator_to_array` to avoid issues (a separate
+iterator is created for each location and, if you don't pass ``false`` to
+:phpfunction:`iterator_to_array`, keys of result sets are used and some of them
+might be duplicated and their values overwritten).
+
 Reading Contents of Returned Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 The contents of returned files can be read with
 :method:`Symfony\\Component\\Finder\\SplFileInfo::getContents`::
@@ -338,9 +406,10 @@ The contents of returned files can be read with
         // ...
     }
 
-.. _strtotime:          https://php.net/manual/en/datetime.formats.php
-.. _protocol:           https://php.net/manual/en/wrappers.php
-.. _Streams:            https://php.net/streams
-.. _IEC standard:       https://physics.nist.gov/cuu/Units/binary.html
-.. _Packagist:          https://packagist.org/packages/symfony/finder
+.. _`fluent interface`: https://en.wikipedia.org/wiki/Fluent_interface
+.. _`symbolic links`: https://en.wikipedia.org/wiki/Symbolic_link
+.. _`Version Control Systems`: https://en.wikipedia.org/wiki/Version_control
+.. _`PHP wrapper for URL-style protocols`: https://php.net/manual/en/wrappers.php
+.. _`PHP streams`: https://php.net/streams
+.. _`IEC standard`: https://physics.nist.gov/cuu/Units/binary.html
 .. _`natural sort order`: https://en.wikipedia.org/wiki/Natural_sort_order
diff --git a/components/form.rst b/components/form.rst
index 9d143766f86..bcfce8939d7 100644
--- a/components/form.rst
+++ b/components/form.rst
@@ -20,8 +20,6 @@ Installation
 
     $ composer require symfony/form
 
-Alternatively, you can clone the `<https://github.com/symfony/form>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Configuration
@@ -82,8 +80,8 @@ object to read data off of the correct PHP superglobals (i.e. ``$_POST`` or
 .. seealso::
 
     If you need more control over exactly when your form is submitted or which
-    data is passed to it, you can use the :method:`Symfony\\Component\\Form\\FormInterface::submit`
-    for this. Read more about it :ref:`form-call-submit-directly`.
+    data is passed to it,
+    :doc:`use the submit() method to handle form submissions </form/direct_submit>`.
 
 .. sidebar:: Integration with the HttpFoundation Component
 
@@ -91,8 +89,8 @@ object to read data off of the correct PHP superglobals (i.e. ``$_POST`` or
     :class:`Symfony\\Component\\Form\\Extension\\HttpFoundation\\HttpFoundationExtension`
     to your form factory::
 
-        use Symfony\Component\Form\Forms;
         use Symfony\Component\Form\Extension\HttpFoundation\HttpFoundationExtension;
+        use Symfony\Component\Form\Forms;
 
         $formFactory = Forms::createFormFactoryBuilder()
             ->addExtension(new HttpFoundationExtension())
@@ -121,12 +119,12 @@ use the built-in support, first install the Security CSRF component:
 
 The following snippet adds CSRF protection to the form factory::
 
+    use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
     use Symfony\Component\Form\Forms;
     use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
-    use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
-    use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
     use Symfony\Component\Security\Csrf\CsrfTokenManager;
+    use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
+    use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
 
     // creates a Session object from the HttpFoundation component
     $session = new Session();
@@ -157,7 +155,7 @@ the CSRF generator and validated when binding the form.
 
 You can disable CSRF protection per form using the ``csrf_protection`` option::
 
-    use Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType
+    use Symfony\Component\Form\Extension\Core\Type\FormType;
 
     $form = $formFactory->createBuilder(FormType::class, null, ['csrf_protection' => false])
         ->getForm();
@@ -165,10 +163,10 @@ You can disable CSRF protection per form using the ``csrf_protection`` option::
 Twig Templating
 ~~~~~~~~~~~~~~~
 
-If you're using the Form component to process HTML forms, you'll need a way
-to render your form as HTML form fields (complete with field values,
-errors, and labels). If you use `Twig`_ as your template engine, the Form
-component offers a rich integration.
+If you're using the Form component to process HTML forms, you'll need a way to
+render your form as HTML form fields (complete with field values, errors, and
+labels). If you use `Twig`_ as your template engine, the Form component offers a
+rich integration.
 
 To use the integration, you'll need the twig bridge, which provides integration
 between Twig and several Symfony components:
@@ -183,10 +181,10 @@ that help you render the HTML widget, label, help and errors for each field
 (as well as a few other things). To configure the integration, you'll need
 to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension\\FormExtension`::
 
-    use Symfony\Component\Form\Forms;
     use Symfony\Bridge\Twig\Extension\FormExtension;
-    use Symfony\Component\Form\FormRenderer;
     use Symfony\Bridge\Twig\Form\TwigRendererEngine;
+    use Symfony\Component\Form\FormRenderer;
+    use Symfony\Component\Form\Forms;
     use Twig\Environment;
     use Twig\Loader\FilesystemLoader;
     use Twig\RuntimeLoader\FactoryRuntimeLoader;
@@ -226,7 +224,7 @@ to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension
 
 .. versionadded:: 1.30
 
-    The ``Twig\\RuntimeLoader\\FactoryRuntimeLoader`` was introduced in Twig 1.30.
+    The ``Twig\RuntimeLoader\FactoryRuntimeLoader`` was introduced in Twig 1.30.
 
 The exact details of your `Twig Configuration`_ will vary, but the goal is
 always to add the :class:`Symfony\\Bridge\\Twig\\Extension\\FormExtension`
@@ -266,12 +264,12 @@ installed:
     $ composer require symfony/translation symfony/config
 
 Next, add the :class:`Symfony\\Bridge\\Twig\\Extension\\TranslationExtension`
-to your ``Twig\\Environment`` instance::
+to your ``Twig\Environment`` instance::
 
+    use Symfony\Bridge\Twig\Extension\TranslationExtension;
     use Symfony\Component\Form\Forms;
-    use Symfony\Component\Translation\Translator;
     use Symfony\Component\Translation\Loader\XliffFileLoader;
-    use Symfony\Bridge\Twig\Extension\TranslationExtension;
+    use Symfony\Component\Translation\Translator;
 
     // creates the Translator
     $translator = new Translator('en');
@@ -318,8 +316,8 @@ errors are then mapped to the correct field and rendered.
 
 Your integration with the Validation component will look something like this::
 
-    use Symfony\Component\Form\Forms;
     use Symfony\Component\Form\Extension\Validator\ValidatorExtension;
+    use Symfony\Component\Form\Forms;
     use Symfony\Component\Validator\Validation;
 
     $vendorDirectory = realpath(__DIR__.'/../vendor');
@@ -519,7 +517,7 @@ done by passing a special form "view" object to your template (notice the
     {{ form_start(form) }}
         {{ form_widget(form) }}
 
-        <input type="submit" />
+        <input type="submit"/>
     {{ form_end(form) }}
 
 .. image:: /_images/form/simple-form.png
@@ -756,6 +754,18 @@ method to access the list of errors. It returns a
     // a FormErrorIterator instance representing the form tree structure
     $errors = $form->getErrors(true, false);
 
+Clearing Form Errors
+~~~~~~~~~~~~~~~~~~~~
+
+Any errors can be manually cleared using the
+:method:`Symfony\\Component\\Form\\ClearableErrorsInterface::clearErrors`
+method. This is useful when you'd like to validate the form without showing
+validation errors to the user (i.e. during a partial AJAX submission or
+:doc:`dynamic form modification </form/dynamic_form_modification>`).
+
+Because clearing the errors makes the form valid, ``clearErrors()`` should only
+be called after testing whether the form is valid.
+
 Learn more
 ----------
 
@@ -765,6 +775,5 @@ Learn more
 
     /form/*
 
-.. _Packagist: https://packagist.org/packages/symfony/form
 .. _Twig: https://twig.symfony.com
 .. _`Twig Configuration`: https://twig.symfony.com/doc/2.x/intro.html
diff --git a/components/http_client.rst b/components/http_client.rst
new file mode 100644
index 00000000000..f3ed12a74ef
--- /dev/null
+++ b/components/http_client.rst
@@ -0,0 +1,836 @@
+.. index::
+   single: HttpClient
+   single: Components; HttpClient
+
+The HttpClient Component
+========================
+
+    The HttpClient component is a low-level HTTP client with support for both
+    PHP stream wrappers and cURL. It provides utilities to consume APIs and
+    supports synchronous and asynchronous operations.
+
+.. versionadded:: 4.3
+
+    The HttpClient component was introduced in Symfony 4.3 and it's still
+    considered an :doc:`experimental feature </contributing/code/experimental>`.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/http-client
+
+.. include:: /components/require_autoload.rst.inc
+
+Basic Usage
+-----------
+
+Use the :class:`Symfony\\Component\\HttpClient\\HttpClient` class to create the
+low-level HTTP client that makes requests, like the following ``GET`` request::
+
+    use Symfony\Component\HttpClient\HttpClient;
+
+    $client = HttpClient::create();
+    $response = $client->request('GET', 'https://api.github.com/repos/symfony/symfony-docs');
+
+    $statusCode = $response->getStatusCode();
+    // $statusCode = 200
+    $contentType = $response->getHeaders()['content-type'][0];
+    // $contentType = 'application/json'
+    $content = $response->getContent();
+    // $content = '{"id":521583, "name":"symfony-docs", ...}'
+    $content = $response->toArray();
+    // $content = ['id' => 521583, 'name' => 'symfony-docs', ...]
+
+Performance
+-----------
+
+The component is built for maximum HTTP performance. By design, it is compatible
+with HTTP/2 and with doing concurrent asynchronous streamed and multiplexed
+requests/responses. Even when doing regular synchronous calls, this design
+allows keeping connections to remote hosts open between requests, improving
+performance by saving repetitive DNS resolution, SSL negotiation, etc.
+To leverage all these design benefits, the cURL extension is needed.
+
+Enabling cURL Support
+~~~~~~~~~~~~~~~~~~~~~
+
+This component supports both the native PHP streams and cURL to make the HTTP
+requests. Although both are interchangeable and provide the same features,
+including concurrent requests, HTTP/2 is only supported when using cURL.
+
+``HttpClient::create()`` selects the cURL transport if the `cURL PHP extension`_
+is enabled and falls back to PHP streams otherwise. If you prefer to select
+the transport explicitly, use the following classes to create the client::
+
+    use Symfony\Component\HttpClient\CurlHttpClient;
+    use Symfony\Component\HttpClient\NativeHttpClient;
+
+    // uses native PHP streams
+    $client = new NativeHttpClient();
+
+    // uses the cURL PHP extension
+    $client = new CurlHttpClient();
+
+When using this component in a full-stack Symfony application, this behavior is
+not configurable and cURL will be used automatically if the cURL PHP extension
+is installed and enabled. Otherwise, the native PHP streams will be used.
+
+HTTP/2 Support
+~~~~~~~~~~~~~~
+
+When requesting an ``https`` URL, HTTP/2 is enabled by default if libcurl >= 7.36
+is used. To force HTTP/2 for ``http`` URLs, you need to enable it explicitly via
+the ``http_version`` option::
+
+    $client = HttpClient::create(['http_version' => '2.0']);
+
+Support for HTTP/2 PUSH works out of the box when libcurl >= 7.61 is used with
+PHP >= 7.2.17 / 7.3.4: pushed responses are put into a temporary cache and are
+used when a subsequent request is triggered for the corresponding URLs.
+
+Making Requests
+---------------
+
+The client created with the ``HttpClient`` class provides a single ``request()``
+method to perform all kinds of HTTP requests::
+
+    $response = $client->request('GET', 'https://...');
+    $response = $client->request('POST', 'https://...');
+    $response = $client->request('PUT', 'https://...');
+    // ...
+
+Responses are always asynchronous, so that the call to the method returns
+immediately instead of waiting to receive the response::
+
+    // code execution continues immediately; it doesn't wait to receive the response
+    $response = $client->request('GET', 'http://releases.ubuntu.com/18.04.2/ubuntu-18.04.2-desktop-amd64.iso');
+
+    // getting the response headers waits until they arrive
+    $contentType = $response->getHeaders()['content-type'][0];
+
+    // trying to get the response contents will block the execution until
+    // the full response contents are received
+    $contents = $response->getContent();
+
+This component also supports :ref:`streaming responses <http-client-streaming-responses>`
+for full asynchronous applications.
+
+.. note::
+
+    HTTP compression and chunked transfer encoding are automatically enabled when
+    both your PHP runtime and the remote server support them.
+
+Authentication
+~~~~~~~~~~~~~~
+
+The HTTP client supports different authentication mechanisms. They can be
+defined globally when creating the client (to apply it to all requests) and to
+each request (which overrides any global authentication)::
+
+    // Use the same authentication for all requests
+    $client = HttpClient::create([
+        // HTTP Basic authentication with only the username and not a password
+        'auth_basic' => ['the-username'],
+
+        // HTTP Basic authentication with a username and a password
+        'auth_basic' => ['the-username', 'the-password'],
+
+        // HTTP Bearer authentication (also called token authentication)
+        'auth_bearer' => 'the-bearer-token',
+    ]);
+
+    $response = $client->request('GET', 'https://...', [
+        // use a different HTTP Basic authentication only for this request
+        'auth_basic' => ['the-username', 'the-password'],
+
+        // ...
+    ]);
+
+Query String Parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can either append them manually to the requested URL, or define them as an
+associative array via the ``query`` option, that will be merged with the URL::
+
+    // it makes an HTTP GET request to https://httpbin.org/get?token=...&name=...
+    $response = $client->request('GET', 'https://httpbin.org/get', [
+        // these values are automatically encoded before including them in the URL
+        'query' => [
+            'token' => '...',
+            'name' => '...',
+        ],
+    ]);
+
+Headers
+~~~~~~~
+
+Use the ``headers`` option to define both the default headers added to all
+requests and the specific headers for each request::
+
+    // this header is added to all requests made by this client
+    $client = HttpClient::create(['headers' => [
+        'User-Agent' => 'My Fancy App',
+    ]]);
+
+    // this header is only included in this request and overrides the value
+    // of the same header if defined globally by the HTTP client
+    $response = $client->request('POST', 'https://...', [
+        'headers' => [
+            'Content-Type' => 'text/plain',
+        ],
+    ]);
+
+Uploading Data
+~~~~~~~~~~~~~~
+
+This component provides several methods for uploading data using the ``body``
+option. You can use regular strings, closures, iterables and resources and they'll be
+processed automatically when making the requests::
+
+    $response = $client->request('POST', 'https://...', [
+        // defining data using a regular string
+        'body' => 'raw data',
+
+        // defining data using an array of parameters
+        'body' => ['parameter1' => 'value1', '...'],
+
+        // using a closure to generate the uploaded data
+        'body' => function (int $size): string {
+            // ...
+        },
+
+        // using a resource to get the data from it
+        'body' => fopen('/path/to/file', 'r'),
+    ]);
+
+When uploading data with the ``POST`` method, if you don't define the
+``Content-Type`` HTTP header explicitly, Symfony assumes that you're uploading
+form data and adds the required
+``'Content-Type: application/x-www-form-urlencoded'`` header for you.
+
+When the ``body`` option is set as a closure, it will be called several times until
+it returns the empty string, which signals the end of the body. Each time, the
+closure should return a string smaller than the amount requested as argument.
+
+A generator or any ``Traversable`` can also be used instead of a closure.
+
+.. tip::
+
+    When uploading JSON payloads, use the ``json`` option instead of ``body``. The
+    given content will be JSON-encoded automatically and the request will add the
+    ``Content-Type: application/json`` automatically too::
+
+        $response = $client->request('POST', 'https://...', [
+            'json' => ['param1' => 'value1', '...'],
+        ]);
+
+        $decodedPayload = $response->toArray();
+
+To submit a form with file uploads, it is your responsibility to encode the body
+according to the ``multipart/form-data`` content-type. The
+:doc:`Symfony Mime </components/mime>` component makes it a few lines of code::
+
+    use Symfony\Component\Mime\Part\DataPart;
+    use Symfony\Component\Mime\Part\Multipart\FormDataPart;
+
+    $formFields = [
+        'regular_field' => 'some value',
+        'file_field' => DataPart::fromPath('/path/to/uploaded/file'),
+    ];
+    $formData = new FormDataPart($formFields);
+    $client->request('POST', 'https://...', [
+        'headers' => $formData->getPreparedHeaders()->toArray(),
+        'body' => $formData->bodyToIterable(),
+    ]);
+
+Cookies
+~~~~~~~
+
+The HTTP client provided by this component is stateless but handling cookies
+requires a stateful storage (because responses can update cookies and they must
+be used for subsequent requests). That's why this component doesn't handle
+cookies automatically.
+
+You can either handle cookies yourself using the ``Cookie`` HTTP header or use
+the :doc:`BrowserKit component </components/browser_kit>` which provides this
+feature and integrates seamlessly with the HttpClient component.
+
+Redirects
+~~~~~~~~~
+
+By default, the HTTP client follows redirects, up to a maximum of 20, when
+making a request. Use the ``max_redirects`` setting to configure this behavior
+(if the number of redirects is higher than the configured value, you'll get a
+:class:`Symfony\\Component\\HttpClient\\Exception\\RedirectionException`)::
+
+    $response = $client->request('GET', 'https://...', [
+        // 0 means to not follow any redirect
+        'max_redirects' => 0,
+    ]);
+
+HTTP Proxies
+~~~~~~~~~~~~
+
+By default, this component honors the standard environment variables that your
+Operating System defines to direct the HTTP traffic through your local proxy.
+This means there is usually nothing to configure to have the client work with
+proxies, provided these env vars are properly configured.
+
+You can still set or override these settings using the ``proxy`` and ``no_proxy``
+options:
+
+* ``proxy`` should be set to the ``http://...`` URL of the proxy to get through
+
+* ``no_proxy`` disables the proxy for a comma-separated list of hosts that do not
+  require it to get reached.
+
+Progress Callback
+~~~~~~~~~~~~~~~~~
+
+By providing a callable to the ``on_progress`` option, one can track
+uploads/downloads as they complete. This callback is guaranteed to be called on
+DNS resolution, on arrival of headers and on completion; additionally it is
+called when new data is uploaded or downloaded and at least once per second::
+
+    $response = $client->request('GET', 'https://...', [
+        'on_progress' => function (int $dlNow, int $dlSize, array $info): void {
+            // $dlNow is the number of bytes downloaded so far
+            // $dlSize is the total size to be downloaded or -1 if it is unknown
+            // $info is what $response->getInfo() would return at this very time
+        },
+    ]);
+
+Any exceptions thrown from the callback will be wrapped in an instance of
+``TransportExceptionInterface`` and will abort the request.
+
+Advanced Options
+~~~~~~~~~~~~~~~~
+
+The :class:`Symfony\\Contracts\\HttpClient\\HttpClientInterface` defines all the
+options you might need to take full control of the way the request is performed,
+including DNS pre-resolution, SSL parameters, public key pinning, etc.
+
+Processing Responses
+--------------------
+
+The response returned by all HTTP clients is an object of type
+:class:`Symfony\\Contracts\\HttpClient\\ResponseInterface` which provides the
+following methods::
+
+    $response = $client->request('GET', 'https://...');
+
+    // gets the HTTP status code of the response
+    $statusCode = $response->getStatusCode();
+
+    // gets the HTTP headers as string[][] with the header names lower-cased
+    $headers = $response->getHeaders();
+
+    // gets the response body as a string
+    $content = $response->getContent();
+
+    // cancels the request/response
+    $response->cancel();
+
+    // returns info coming from the transport layer, such as "response_headers",
+    // "redirect_count", "start_time", "redirect_url", etc.
+    $httpInfo = $response->getInfo();
+    // you can get individual info too
+    $startTime = $response->getInfo('start_time');
+
+.. note::
+
+    ``$response->getInfo()`` is non-blocking: it returns *live* information
+    about the response. Some of them might not be known yet (e.g. ``http_code``)
+    when you'll call it.
+
+.. tip::
+
+    Call ``$response->getInfo('debug')`` to get detailed logs about the HTTP transaction.
+
+.. _http-client-streaming-responses:
+
+Streaming Responses
+~~~~~~~~~~~~~~~~~~~
+
+Call the ``stream()`` method of the HTTP client to get *chunks* of the
+response sequentially instead of waiting for the entire response::
+
+    $url = 'https://releases.ubuntu.com/18.04.1/ubuntu-18.04.1-desktop-amd64.iso';
+    $response = $client->request('GET', $url, [
+        // optional: if you don't want to buffer the response in memory
+        'buffer' => false,
+    ]);
+
+    // Responses are lazy: this code is executed as soon as headers are received
+    if (200 !== $response->getStatusCode()) {
+        throw new \Exception('...');
+    }
+
+    // get the response contents in chunk and save them in a file
+    // response chunks implement Symfony\Contracts\HttpClient\ChunkInterface
+    $fileHandler = fopen('/ubuntu.iso', 'w');
+    foreach ($client->stream($response) as $chunk) {
+        fwrite($fileHandler, $chunk->getContent());
+    }
+
+Canceling Responses
+~~~~~~~~~~~~~~~~~~~
+
+To abort a request (e.g. because it didn't complete in due time, or you want to
+fetch only the first bytes of the response, etc.), you can either use the
+``cancel()`` method of ``ResponseInterface``::
+
+    $response->cancel()
+
+Or throw an exception from a progress callback::
+
+    $response = $client->request('GET', 'https://...', [
+        'on_progress' => function (int $dlNow, int $dlSize, array $info): void {
+            // ...
+
+            throw new \MyException();
+        },
+    ]);
+
+The exception will be wrapped in an instance of ``TransportExceptionInterface``
+and will abort the request.
+
+Handling Exceptions
+~~~~~~~~~~~~~~~~~~~
+
+When the HTTP status code of the response is in the 300-599 range (i.e. 3xx,
+4xx or 5xx) your code is expected to handle it. If you don't do that, the
+``getHeaders()`` and ``getContent()`` methods throw an appropriate exception::
+
+    // the response of this request will be a 403 HTTP error
+    $response = $client->request('GET', 'https://httpbin.org/status/403');
+
+    // this code results in a Symfony\Component\HttpClient\Exception\ClientException
+    // because it doesn't check the status code of the response
+    $content = $response->getContent();
+
+    // pass FALSE as the optional argument to not throw an exception and return
+    // instead the original response content (even if it's an error message)
+    $content = $response->getContent(false);
+
+Concurrent Requests
+-------------------
+
+Thanks to responses being lazy, requests are always managed concurrently.
+On a fast enough network, the following code makes 379 requests in less than
+half a second when cURL is used::
+
+    use Symfony\Component\HttpClient\CurlHttpClient;
+
+    $client = new CurlHttpClient();
+
+    $responses = [];
+
+    for ($i = 0; $i < 379; ++$i) {
+        $uri = "https://http2.akamai.com/demo/tile-$i.png";
+        $responses[] = $client->request('GET', $uri);
+    }
+
+    foreach ($responses as $response) {
+        $content = $response->getContent();
+        // ...
+    }
+
+As you can read in the first "for" loop, requests are issued but are not consumed
+yet. That's the trick when concurrency is desired: requests should be sent
+first and be read later on. This will allow the client to monitor all pending
+requests while your code waits for a specific one, as done in each iteration of
+the above "foreach" loop.
+
+Multiplexing Responses
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you look again at the snippet above, responses are read in requests' order.
+But maybe the 2nd response came back before the 1st? Fully asynchronous operations
+require being able to deal with the responses in whatever order they come back.
+
+In order to do so, the ``stream()`` method of HTTP clients accepts a list of
+responses to monitor. As mentioned :ref:`previously <http-client-streaming-responses>`,
+this method yields response chunks as they arrive from the network. By replacing
+the "foreach" in the snippet with this one, the code becomes fully async::
+
+    foreach ($client->stream($responses) as $response => $chunk) {
+        if ($chunk->isFirst()) {
+            // headers of $response just arrived
+            // $response->getHeaders() is now a non-blocking call
+        } elseif ($chunk->isLast()) {
+            // the full content of $response just completed
+            // $response->getContent() is now a non-blocking call
+        } else {
+            // $chunk->getContent() will return a piece
+            // of the response body that just arrived
+        }
+    }
+
+.. tip::
+
+    Use the ``user_data`` option combined with ``$response->getInfo('user_data')``
+    to track the identity of the responses in your foreach loops.
+
+Dealing with Network Timeouts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This component allows dealing with both request and response timeouts.
+
+A timeout can happen when e.g. DNS resolution takes too much time, when the TCP
+connection cannot be opened in the given time budget, or when the response
+content pauses for too long. This can be configured with the ``timeout`` request
+option::
+
+    // A TransportExceptionInterface will be issued if nothing
+    // happens for 2.5 seconds when accessing from the $response
+    $response = $client->request('GET', 'https://...', ['timeout' => 2.5]);
+
+The ``default_socket_timeout`` PHP ini setting is used if the option is not set.
+
+The option can be overridden by using the 2nd argument of the ``stream()`` method.
+This allows monitoring several responses at once and applying the timeout to all
+of them in a group. If all responses become inactive for the given duration, the
+method will yield a special chunk whose ``isTimeout()`` will return ``true``::
+
+    foreach ($client->stream($responses, 1.5) as $response => $chunk) {
+        if ($chunk->isTimeout()) {
+            // $response staled for more than 1.5 seconds
+        }
+    }
+
+A timeout is not necessarily an error: you can decide to stream again the
+response and get remaining contents that might come back in a new timeout, etc.
+
+.. tip::
+
+    Passing ``0`` as timeout allows monitoring responses in a non-blocking way.
+
+.. note::
+
+    Timeouts control how long one is willing to wait *while the HTTP transaction
+    is idle*. Big responses can last as long as needed to complete, provided they
+    remain active during the transfer and never pause for longer than specified.
+
+Dealing with Network Errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Network errors (broken pipe, failed DNS resolution, etc.) are thrown as instances
+of :class:`Symfony\\Contracts\\HttpClient\\Exception\\TransportExceptionInterface`.
+
+First of all, you don't *have* to deal with them: letting errors bubble to your
+generic exception-handling stack might be really fine in most use cases.
+
+If you want to handle them, here is what you need to know:
+
+To catch errors, you need to wrap calls to ``$client->request()`` but also calls
+to any methods of the returned responses. This is because responses are lazy, so
+that network errors can happen when calling e.g. ``getStatusCode()`` too::
+
+    try {
+        // both lines can potentially throw
+        $response = $client->request(...);
+        $headers = $response->getHeaders();
+        // ...
+    } catch (TransportExceptionInterface $e) {
+        // ...
+    }
+
+.. note::
+
+    Because ``$response->getInfo()`` is non-blocking, it shouldn't throw by design.
+
+When multiplexing responses, you can deal with errors for individual streams by
+catching ``TransportExceptionInterface`` in the foreach loop::
+
+    foreach ($client->stream($responses) as $response => $chunk) {
+        try {
+            if ($chunk->isLast()) {
+                // ... do something with $response
+            }
+        } catch (TransportExceptionInterface $e) {
+            // ...
+        }
+    }
+
+Caching Requests and Responses
+------------------------------
+
+This component provides a :class:`Symfony\\Component\\HttpClient\\CachingHttpClient`
+decorator that allows caching responses and serving them from the local storage
+for next requests. The implementation leverages the
+:class:`Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache` class under the hood
+so that the :doc:`HttpKernel component </components/http_kernel>` needs to be
+installed in your application::
+
+    use Symfony\Component\HttpClient\CachingHttpClient;
+    use Symfony\Component\HttpClient\HttpClient;
+    use Symfony\Component\HttpKernel\HttpCache\Store;
+
+    $store = new Store('/path/to/cache/storage/');
+    $client = HttpClient::create();
+    $client = new CachingHttpClient($client, $store);
+
+    // this won't hit the network if the resource is already in the cache
+    $response = $client->request('GET', 'https://example.com/cacheable-resource');
+
+``CachingHttpClient`` accepts a third argument to set the options of the ``HttpCache``.
+
+Scoping Client
+--------------
+
+It's common that some of the HTTP client options depend on the URL of the
+request (e.g. you must set some headers when making requests to GitHub API but
+not for other hosts). If that's your case, this component provides a special
+HTTP client via the :class:`Symfony\\Component\\HttpClient\\ScopingHttpClient`
+class to autoconfigure the HTTP client based on the requested URL::
+
+    use Symfony\Component\HttpClient\HttpClient;
+    use Symfony\Component\HttpClient\ScopingHttpClient;
+
+    $client = HttpClient::create();
+    $client = new ScopingHttpClient($client, [
+        // the options defined as values apply only to the URLs matching
+        // the regular expressions defined as keys
+        'https://api\.github\.com/' => [
+            'headers' => [
+                'Accept' => 'application/vnd.github.v3+json',
+                'Authorization' => 'token '.$githubToken,
+            ],
+        ],
+        // ...
+    ]);
+
+You can define several scopes, so that each set of options is added only if a
+requested URL matches one of the regular expressions provided as keys.
+
+If the request URL is relative (because you use the ``base_uri`` option), the
+scoping HTTP client can't make a match. That's why you can define a third
+optional argument in its constructor which will be considered the default
+regular expression applied to relative URLs::
+
+    // ...
+
+    $client = new ScopingHttpClient($client,
+        [
+            'https://api\.github\.com/' => [
+                'base_uri' => 'https://api.github.com/',
+                // ...
+            ],
+        ],
+        // this is the index in the previous array that defines
+        // the base URI that shoud be used to resolve relative URLs
+        'https://api\.github\.com/'
+    );
+
+The above example can be reduced to a simpler call::
+
+    // ...
+
+    $client = ScopingHttpClient::forBaseUri($client, 'https://api.github.com/', [
+        // ...
+    ]);
+
+This way, the provided options will be used only if the requested URL is relative
+or if it matches the ``https://api.github.com/`` base URI.
+
+Interoperability
+----------------
+
+The component is interoperable with two different abstractions for HTTP clients:
+`Symfony Contracts`_ and `PSR-18`_. If your application uses libraries that need
+any of them, the component is compatible with both. They also benefit from
+:ref:`autowiring aliases <service-autowiring-alias>` when the
+:ref:`framework bundle <framework-bundle-configuration>` is used.
+
+If you are writing or maintaining a library that makes HTTP requests, you can
+decouple it from any specific HTTP client implementations by coding against
+either Symfony Contracts (recommended) or PSR-18.
+
+Symfony Contracts
+~~~~~~~~~~~~~~~~~
+
+The interfaces found in the ``symfony/http-client-contracts`` package define
+the primary abstractions implemented by the component. Its entry point is the
+:class:`Symfony\\Contracts\\HttpClient\\HttpClientInterface`. That's the
+interface you need to code against when a client is needed::
+
+    use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+    class MyApiLayer
+    {
+        private $client;
+
+        public function __construct(HttpClientInterface $client)
+        {
+            $this->client = $client
+        }
+
+        // [...]
+    }
+
+All request options mentioned above (e.g. timeout management) are also defined
+in the wordings of the interface, so that any compliant implementations (like
+this component) is guaranteed to provide them. That's a major difference with
+the PSR-18 abstraction, which provides none related to the transport itself.
+
+Another major feature covered by the Symfony Contracts is async/multiplexing,
+as described in the previous sections.
+
+PSR-18
+~~~~~~
+
+This component implements the `PSR-18`_ (HTTP Client) specifications via the
+:class:`Symfony\\Component\\HttpClient\\Psr18Client` class, which is an adapter
+to turn a Symfony ``HttpClientInterface`` into a PSR-18 ``ClientInterface``.
+
+To use it, you need the ``psr/http-client`` package and a `PSR-17`_ implementation:
+
+.. code-block:: terminal
+
+    # installs the PSR-18 ClientInterface
+    $ composer require psr/http-client
+
+    # installs an efficient implementation of response and stream factories
+    # with autowiring aliases provided by Symfony Flex
+    $ composer require nyholm/psr7
+
+Now you can make HTTP requests with the PSR-18 client as follows::
+
+    use Nyholm\Psr7\Factory\Psr17Factory;
+    use Symfony\Component\HttpClient\Psr18Client;
+
+    $psr17Factory = new Psr17Factory();
+    $psr18Client = new Psr18Client();
+
+    $url = 'https://symfony.com/versions.json';
+    $request = $psr17Factory->createRequest('GET', $url);
+    $response = $psr18Client->sendRequest($request);
+
+    $content = json_decode($response->getBody()->getContents(), true);
+
+Symfony Framework Integration
+-----------------------------
+
+When using this component in a full-stack Symfony application, you can configure
+multiple clients with different configurations and inject them into your services.
+
+Configuration
+~~~~~~~~~~~~~
+
+Use the ``framework.http_client`` key to configure the default HTTP client used
+in the application. Check out the full
+:ref:`http_client config reference <reference-http-client>` to learn about all
+the available config options:
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        # ...
+        http_client:
+            max_host_connections: 10
+            default_options:
+                max_redirects: 7
+
+If you want to define multiple HTTP clients, use this other expanded configuration:
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        # ...
+        http_client:
+            scoped_clients:
+                crawler.client:
+                    headers: { 'X-Powered-By': 'ACME App' }
+                    http_version: '1.0'
+                some_api.client:
+                    max_redirects: 5
+
+Injecting the HTTP Client into Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your application only needs one HTTP client, you can inject the default one
+into any services by type-hinting a constructor argument with the
+:class:`Symfony\\Contracts\\HttpClient\\HttpClientInterface`::
+
+    use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+    class SomeService
+    {
+        private $client;
+
+        public function __construct(HttpClientInterface $client)
+        {
+            $this->client = $client;
+        }
+    }
+
+If you have several clients, you must use any of the methods defined by Symfony
+to :ref:`choose a specific service <services-wire-specific-service>`. Each client
+has a unique service named after its configuration.
+
+Each scoped client also defines a corresponding named autowiring alias.
+If you use for example
+``Symfony\Contracts\HttpClient\HttpClientInterface $myApiClient``
+as the type and name of an argument, autowiring will inject the ``my_api.client``
+service into your autowired classes.
+
+Testing HTTP Clients and Responses
+----------------------------------
+
+This component includes the ``MockHttpClient`` and ``MockResponse`` classes to
+use them in tests that need an HTTP client which doesn't make actual HTTP
+requests.
+
+The first way of using ``MockHttpClient`` is to pass a list of responses to its
+constructor. These will be yielded in order when requests are made::
+
+    use Symfony\Component\HttpClient\MockHttpClient;
+    use Symfony\Component\HttpClient\Response\MockResponse;
+
+    $responses = [
+        new MockResponse($body1, $info1),
+        new MockResponse($body2, $info2),
+    ];
+
+    $client = new MockHttpClient($responses);
+    // responses are returned in the same order as passed to MockHttpClient
+    $response1 = $client->request('...'); // returns $responses[0]
+    $response2 = $client->request('...'); // returns $responses[1]
+
+Another way of using ``MockHttpClient`` is to pass a callback that generates the
+responses dynamically when it's called::
+
+    use Symfony\Component\HttpClient\MockHttpClient;
+    use Symfony\Component\HttpClient\Response\MockResponse;
+
+    $callback = function ($method, $url, $options) {
+        return new MockResponse('...');
+    };
+
+    $client = new MockHttpClient($callback);
+    $response = $client->request('...'); // calls $callback to get the response
+
+The responses provided to the mock client don't have to be instances of
+``MockResponse``. Any class implementing ``ResponseInterface`` will work (e.g.
+``$this->createMock(ResponseInterface::class)``).
+
+However, using ``MockResponse`` allows simulating chunked responses and timeouts::
+
+    $body = function () {
+        yield 'hello';
+        // empty strings are turned into timeouts so that they are easy to test
+        yield '';
+        yield 'world';
+    };
+
+    $mockResponse = new MockResponse($body());
+
+.. _`cURL PHP extension`: https://php.net/curl
+.. _`PSR-17`: https://www.php-fig.org/psr/psr-17/
+.. _`PSR-18`: https://www.php-fig.org/psr/psr-18/
+.. _`Symfony Contracts`: https://github.com/symfony/contracts
diff --git a/components/http_foundation.rst b/components/http_foundation.rst
index aede539a852..3a728812b07 100644
--- a/components/http_foundation.rst
+++ b/components/http_foundation.rst
@@ -23,8 +23,6 @@ Installation
 
     $ composer require symfony/http-foundation
 
-Alternatively, you can clone the `<https://github.com/symfony/http-foundation>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 .. seealso::
@@ -242,18 +240,9 @@ the
 method tells you if the request contains a session which was started in one of
 the previous requests.
 
-.. versionadded:: 4.1
-    Using :method:`Symfony\\Component\\HttpFoundation\\Request::getSession`
-    when no session has been set was deprecated in Symfony 4.1. It will throw
-    an exception in Symfony 5.0 when the session is ``null``. Check for an existing session
-    first by calling :method:`Symfony\\Component\\HttpFoundation\\Request::hasSession`.
-
 Processing HTTP Headers
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.1
-    The ``HeaderUtils`` class was introduced in Symfony 4.1.
-
 Processing HTTP headers is not a trivial task because of the escaping and white
 space handling of their contents. Symfony provides a
 :class:`Symfony\\Component\\HttpFoundation\\HeaderUtils` class that abstracts
@@ -325,10 +314,6 @@ are also supported::
     $quality = $accept->get('text/xml')->getQuality(); // $quality = 0.8
     $quality = $accept->get('application/xml')->getQuality(); // $quality = 0.3
 
-.. versionadded:: 4.1
-    The support of default values in the ``Accept-*`` headers was introduced in
-    Symfony 4.1.
-
 Accessing other Data
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -428,7 +413,7 @@ attribute::
 
     use Symfony\Component\HttpFoundation\Cookie;
 
-    $response->headers->setCookie(new Cookie('foo', 'bar'));
+    $response->headers->setCookie(Cookie::create('foo', 'bar'));
 
 The
 :method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::setCookie`
@@ -547,17 +532,18 @@ Serving Files
 When sending a file, you must add a ``Content-Disposition`` header to your
 response. While creating this header for basic file downloads is straightforward,
 using non-ASCII filenames is more involving. The
-:method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::makeDisposition`
+:method:`Symfony\\Component\\HttpFoundation\\HeaderUtils::makeDisposition`
 abstracts the hard work behind a simple API::
 
+    use Symfony\Component\HttpFoundation\HeaderUtils;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 
     $fileContent = ...; // the generated file content
     $response = new Response($fileContent);
 
-    $disposition = $response->headers->makeDisposition(
-        ResponseHeaderBag::DISPOSITION_ATTACHMENT,
+    $disposition = HeaderUtils::makeDisposition(
+        HeaderUtils::DISPOSITION_ATTACHMENT,
         'foo.pdf'
     );
 
@@ -580,6 +566,26 @@ if it should::
 
     BinaryFileResponse::trustXSendfileTypeHeader();
 
+.. note::
+
+    The ``BinaryFileResponse`` will only handle ``X-Sendfile`` if the particular header is present.
+    For Apache, this is not the default case.
+
+    To add the header use the ``mod_headers`` Apache module and add the following to the Apache configuration:
+
+    .. code-block:: apache
+
+        <IfModule mod_xsendfile.c>
+          # This is already present somewhere...
+          XSendFile on
+          XSendFilePath ...some path...
+
+          # This needs to be added:
+          <IfModule mod_headers.c>
+            RequestHeader set X-Sendfile-Type X-Sendfile
+          </IfModule>
+        </IfModule>
+
 With the ``BinaryFileResponse``, you can still set the ``Content-Type`` of the sent file,
 or change its ``Content-Disposition``::
 
@@ -692,7 +698,6 @@ Learn More
     /session/*
     /http_cache/*
 
-.. _Packagist: https://packagist.org/packages/symfony/http-foundation
 .. _Nginx: https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/
 .. _Apache: https://tn123.org/mod_xsendfile/
 .. _`JSON Hijacking`: http://haacked.com/archive/2009/06/25/json-hijacking.aspx
diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst
index 327000a6c0c..547a98ad917 100644
--- a/components/http_foundation/session_configuration.rst
+++ b/components/http_foundation/session_configuration.rst
@@ -42,8 +42,8 @@ Symfony provides drivers for the following native save handler as an example:
 Example usage::
 
     use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
     use Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeFileSessionHandler;
+    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
 
     $sessionStorage = new NativeSessionStorage([], new NativeFileSessionHandler());
     $session = new Session($sessionStorage);
@@ -81,8 +81,8 @@ serve as examples if you wish to write your own.
 Example usage::
 
     use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
     use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
+    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
 
     $pdo = new \PDO(...);
     $sessionStorage = new NativeSessionStorage([], new PdoSessionHandler($pdo));
@@ -91,9 +91,6 @@ Example usage::
 Migrating Between Save Handlers
 -------------------------------
 
-.. versionadded:: 4.1
-    The ``MigratingSessionHandler`` class was introduced in Symfony 4.1.
-
 If your application changes the way sessions are stored, use the
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler`
 to migrate between old and new save handlers without losing session data.
diff --git a/components/http_foundation/session_php_bridge.rst b/components/http_foundation/session_php_bridge.rst
index 295c0976854..00f57e59e4f 100644
--- a/components/http_foundation/session_php_bridge.rst
+++ b/components/http_foundation/session_php_bridge.rst
@@ -12,7 +12,7 @@ As stated elsewhere, Symfony Sessions are designed to replace the use of
 PHP's native ``session_*()`` functions and use of the ``$_SESSION``
 superglobal. Additionally, it is mandatory for Symfony to start the session.
 
-However when there really are circumstances where this is not possible, you
+However, when there really are circumstances where this is not possible, you
 can use a special storage bridge
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\PhpBridgeSessionStorage`
 which is designed to allow Symfony to work with a session started outside of
@@ -46,4 +46,3 @@ of your application to Symfony sessions.
     cannot access arbitrary keys in ``$_SESSION`` that may be set by the legacy
     application, although all the ``$_SESSION`` contents will be saved when
     the session is saved.
-
diff --git a/components/http_foundation/session_testing.rst b/components/http_foundation/session_testing.rst
index 54a3363a4d2..7d8a570c17e 100644
--- a/components/http_foundation/session_testing.rst
+++ b/components/http_foundation/session_testing.rst
@@ -6,8 +6,8 @@ Testing with Sessions
 =====================
 
 Symfony is designed from the ground up with code-testability in mind. In order
-to make your code which utilizes session easily testable, we provide two separate
-mock storage mechanisms for both unit testing and functional testing.
+to test your code which utilizes sessions, we provide two separate mock storage
+mechanisms for both unit testing and functional testing.
 
 Testing code using real sessions is tricky because PHP's workflow state is global
 and it is not possible to have multiple concurrent sessions in the same PHP
@@ -40,8 +40,8 @@ For unit testing where it is not necessary to persist the session, you should
 swap out the default storage engine with
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MockArraySessionStorage`::
 
-    use Symfony\Component\HttpFoundation\Session\Storage\MockArraySessionStorage;
     use Symfony\Component\HttpFoundation\Session\Session;
+    use Symfony\Component\HttpFoundation\Session\Storage\MockArraySessionStorage;
 
     $session = new Session(new MockArraySessionStorage());
 
diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst
index e15d44411f6..7cb56159d71 100644
--- a/components/http_foundation/sessions.rst
+++ b/components/http_foundation/sessions.rst
@@ -207,6 +207,8 @@ Example::
     // ...
     $session->clear();
 
+.. _namespaced-attributes:
+
 Namespaced Attributes
 .....................
 
@@ -226,8 +228,7 @@ store it again::
         ],
     ];
 
-So any processing of this might quickly get ugly, even simply adding a token to
-the array::
+So any processing of this might quickly get ugly, even adding a token to the array::
 
     $tokens = $session->get('tokens');
     $tokens['c'] = $value;
diff --git a/components/http_kernel.rst b/components/http_kernel.rst
index e5c36fd4283..2b2ebe3b5fc 100644
--- a/components/http_kernel.rst
+++ b/components/http_kernel.rst
@@ -18,8 +18,6 @@ Installation
 
     $ composer require symfony/http-kernel
 
-Alternatively, you can clone the `<https://github.com/symfony/http-kernel>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 The Workflow of a Request
@@ -47,12 +45,12 @@ This is a simplified overview of the request workflow in Symfony applications:
 #. The **browser** displays the **resource** to the **user**.
 
 Typically, some sort of framework or system is built to handle all the repetitive
-tasks (e.g. routing, security, etc) so that a developer can easily build
-each *page* of the application. Exactly *how* these systems are built varies
-greatly. The HttpKernel component provides an interface that formalizes
-the process of starting with a request and creating the appropriate response.
-The component is meant to be the heart of any application or framework, no
-matter how varied the architecture of that system::
+tasks (e.g. routing, security, etc) so that a developer can build each *page* of
+the application. Exactly *how* these systems are built varies greatly. The HttpKernel
+component provides an interface that formalizes the process of starting with a
+request and creating the appropriate response. The component is meant to be the
+heart of any application or framework, no matter how varied the architecture of
+that system::
 
     namespace Symfony\Component\HttpKernel;
 
@@ -103,12 +101,12 @@ not take many steps. You create an
 (explained below). To complete your working kernel, you'll add more event
 listeners to the events discussed below::
 
-    use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\HttpKernel\HttpKernel;
     use Symfony\Component\EventDispatcher\EventDispatcher;
+    use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\RequestStack;
     use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
     use Symfony\Component\HttpKernel\Controller\ControllerResolver;
+    use Symfony\Component\HttpKernel\HttpKernel;
 
     // create the Request object
     $request = Request::createFromGlobals();
@@ -174,7 +172,7 @@ to the login page or a 403 Access Denied response.
 If a ``Response`` is returned at this stage, the process skips directly to
 the :ref:`kernel.response <component-http-kernel-kernel-response>` event.
 
-Other listeners simply initialize things or add more information to the request.
+Other listeners initialize things or add more information to the request.
 For example, a listener might determine and set the locale on the ``Request``
 object.
 
@@ -294,7 +292,7 @@ have been determined (e.g. the controller, routing information) but before
 the controller is executed. For some examples, see the Symfony section below.
 
 Listeners to this event can also change the controller callable completely
-by calling :method:`FilterControllerEvent::setController <Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent::setController>`
+by calling :method:`ControllerEvent::setController <Symfony\\Component\\HttpKernel\\Event\\ControllerEvent::setController>`
 on the event object that's passed to listeners on this event.
 
 .. sidebar:: ``kernel.controller`` in the Symfony Framework
@@ -526,9 +524,9 @@ to the exception.
 
     <object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"></object>
 
-Each listener to this event is passed a :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`
+Each listener to this event is passed a :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`
 object, which you can use to access the original exception via the
-:method:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent::getException`
+:method:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent::getException`
 method. A typical listener on this event will check for a certain type of
 exception and create an appropriate error ``Response``.
 
@@ -604,17 +602,31 @@ each event has their own event object:
 
 .. _component-http-kernel-event-table:
 
-=====================  ================================  ===================================================================================
-Name                   ``KernelEvents`` Constant         Argument passed to the listener
-=====================  ================================  ===================================================================================
-kernel.request         ``KernelEvents::REQUEST``         :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`
-kernel.controller      ``KernelEvents::CONTROLLER``      :class:`Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent`
-kernel.view            ``KernelEvents::VIEW``            :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForControllerResultEvent`
-kernel.response        ``KernelEvents::RESPONSE``        :class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`
-kernel.finish_request  ``KernelEvents::FINISH_REQUEST``  :class:`Symfony\\Component\\HttpKernel\\Event\\FinishRequestEvent`
-kernel.terminate       ``KernelEvents::TERMINATE``       :class:`Symfony\\Component\\HttpKernel\\Event\\PostResponseEvent`
-kernel.exception       ``KernelEvents::EXCEPTION``       :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`
-=====================  ================================  ===================================================================================
+===========================  ======================================  ========================================================================
+Name                         ``KernelEvents`` Constant               Argument passed to the listener
+===========================  ======================================  ========================================================================
+kernel.request               ``KernelEvents::REQUEST``               :class:`Symfony\\Component\\HttpKernel\\Event\\RequestEvent`
+kernel.controller            ``KernelEvents::CONTROLLER``            :class:`Symfony\\Component\\HttpKernel\\Event\\ControllerEvent`
+kernel.controller_arguments  ``KernelEvents::CONTROLLER_ARGUMENTS``  :class:`Symfony\\Component\\HttpKernel\\Event\\ControllerArgumentsEvent`
+kernel.view                  ``KernelEvents::VIEW``                  :class:`Symfony\\Component\\HttpKernel\\Event\\ViewEvent`
+kernel.response              ``KernelEvents::RESPONSE``              :class:`Symfony\\Component\\HttpKernel\\Event\\ResponseEvent`
+kernel.finish_request        ``KernelEvents::FINISH_REQUEST``        :class:`Symfony\\Component\\HttpKernel\\Event\\FinishRequestEvent`
+kernel.terminate             ``KernelEvents::TERMINATE``             :class:`Symfony\\Component\\HttpKernel\\Event\\TerminateEvent`
+kernel.exception             ``KernelEvents::EXCEPTION``             :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`
+===========================  ======================================  ========================================================================
+
+.. deprecated:: 4.3
+
+    Since Symfony 4.3, most of the event classes were renamed.
+    The following old classes were deprecated:
+
+    * `GetResponseEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\RequestEvent`
+    * `FilterControllerEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\ControllerEvent`
+    * `FilterControllerArgumentsEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\ControllerArgumentsEvent`
+    * `GetResponseForControllerResultEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\ViewEvent`
+    * `FilterResponseEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\ResponseEvent`
+    * `PostResponseEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\TerminateEvent`
+    * `GetResponseForExceptionEvent` renamed to :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`
 
 .. _http-kernel-working-example:
 
@@ -710,10 +722,10 @@ can be used to check if the current request is a "master" or "sub" request.
 For example, a listener that only needs to act on the master request may
 look like this::
 
-    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+    use Symfony\Component\HttpKernel\Event\RequestEvent;
     // ...
 
-    public function onKernelRequest(GetResponseEvent $event)
+    public function onKernelRequest(RequestEvent $event)
     {
         if (!$event->isMasterRequest()) {
             return;
@@ -757,10 +769,8 @@ Learn more
 
    /reference/events
 
-.. _Packagist: https://packagist.org/packages/symfony/http-kernel
 .. _reflection: https://php.net/manual/en/book.reflection.php
 .. _FOSRestBundle: https://github.com/friendsofsymfony/FOSRestBundle
-.. _`Create your own framework... on top of the Symfony2 Components`: http://fabien.potencier.org/article/50/create-your-own-framework-on-top-of-the-symfony2-components-part-1
 .. _`PHP FPM`: https://php.net/manual/en/install.fpm.php
 .. _`SensioFrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
diff --git a/components/inflector.rst b/components/inflector.rst
new file mode 100644
index 00000000000..5e9f4325884
--- /dev/null
+++ b/components/inflector.rst
@@ -0,0 +1,64 @@
+.. index::
+   single: Inflector
+   single: Components; Inflector
+
+The Inflector Component
+=======================
+
+    The Inflector component converts English words between their singular and
+    plural forms.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/inflector
+
+.. include:: /components/require_autoload.rst.inc
+
+When you May Need an Inflector
+------------------------------
+
+In some scenarios such as code generation and code introspection, it's usually
+required to convert words from/to singular/plural. For example, if you need to
+know which property is associated with an *adder* method, you must convert from
+plural to singular (``addStories()`` method -> ``$story`` property).
+
+Although most human languages define simple pluralization rules, they also
+define lots of exceptions. For example, the general rule in English is to add an
+``s`` at the end of the word (``book`` -> ``books``) but there are lots of
+exceptions even for common words (``woman`` -> ``women``, ``life`` -> ``lives``,
+``news`` -> ``news``, ``radius`` -> ``radii``, etc.)
+
+This component abstracts all those pluralization rules so you can convert
+from/to singular/plural with confidence. However, due to the complexity of the
+human languages, this component only provides support for the English language.
+
+Usage
+-----
+
+The Inflector component provides two static methods to convert from/to
+singular/plural::
+
+    use Symfony\Component\Inflector\Inflector;
+
+    Inflector::singularize('alumni');   // 'alumnus'
+    Inflector::singularize('knives');   // 'knife'
+    Inflector::singularize('mice');     // 'mouse'
+
+    Inflector::pluralize('grandchild'); // 'grandchildren'
+    Inflector::pluralize('news');       // 'news'
+    Inflector::pluralize('bacterium');  // 'bacteria'
+
+Sometimes it's not possible to determine a unique singular/plural form for the
+given word. In those cases, the methods return an array with all the possible
+forms::
+
+    use Symfony\Component\Inflector\Inflector;
+
+    Inflector::singularize('indices'); // ['index', 'indix', 'indice']
+    Inflector::singularize('leaves');  // ['leaf', 'leave', 'leaff']
+
+    Inflector::pluralize('matrix');    // ['matricies', 'matrixes']
+    Inflector::pluralize('person');    // ['persons', 'people']
diff --git a/components/intl.rst b/components/intl.rst
index 6a5fc5e3d7f..94ee45ff018 100644
--- a/components/intl.rst
+++ b/components/intl.rst
@@ -5,8 +5,8 @@
 The Intl Component
 ==================
 
-    A PHP replacement layer for the C `intl extension`_ that also provides
-    access to the localization data of the `ICU library`_.
+    This component provides access to the localization data of the `ICU library`_.
+    It also provides a PHP replacement layer for the C `intl extension`_.
 
 .. caution::
 
@@ -26,8 +26,6 @@ Installation
 
     $ composer require symfony/intl
 
-Alternatively, you can clone the `<https://github.com/symfony/intl>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 If you install the component via Composer, the following classes and functions
@@ -54,282 +52,290 @@ replace the intl classes:
 
 Composer automatically exposes these classes in the global namespace.
 
-Writing and Reading Resource Bundles
-------------------------------------
+Accessing ICU Data
+------------------
 
-The :phpclass:`ResourceBundle` class is not currently supported by this component.
-Instead, it includes a set of readers and writers for reading and writing
-arrays (or array-like objects) from/to resource bundle files. The following
-classes are supported:
+This component provides the following ICU data:
 
-* `TextBundleWriter`_
-* `PhpBundleWriter`_
-* `BinaryBundleReader`_
-* `PhpBundleReader`_
-* `BufferedBundleReader`_
-* `StructuredBundleReader`_
+* `Language and Script Names`_
+* `Country Names`_
+* `Locales`_
+* `Currencies`_
+* `Timezones`_
 
-Continue reading if you are interested in how to use these classes. Otherwise
-skip this section and jump to `Accessing ICU Data`_.
+Language and Script Names
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TextBundleWriter
-~~~~~~~~~~~~~~~~
+The ``Languages`` class provides access to the name of all languages
+according to the `ISO 639-1 alpha-2`_ list and the `ISO 639-2 alpha-3`_ list::
 
-The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Writer\\TextBundleWriter`
-writes an array or an array-like object to a plain-text resource bundle. The
-resulting .txt file can be converted to a binary .res file with the
-:class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler`
-class::
+    use Symfony\Component\Intl\Languages;
 
-    use Symfony\Component\Intl\ResourceBundle\Writer\TextBundleWriter;
-    use Symfony\Component\Intl\ResourceBundle\Compiler\BundleCompiler;
+    \Locale::setDefault('en');
 
-    $writer = new TextBundleWriter();
-    $writer->write('/path/to/bundle', 'en', [
-        'Data' => [
-            'entry1',
-            'entry2',
-            // ...
-        ],
-    ]);
+    $languages = Languages::getNames();
+    // ('languageCode' => 'languageName')
+    // => ['ab' => 'Abkhazian', 'ace' => 'Achinese', ...]
 
-    $compiler = new BundleCompiler();
-    $compiler->compile('/path/to/bundle', '/path/to/binary/bundle');
+    $language = Languages::getName('fr');
+    // => 'French'
 
-The command "genrb" must be available for the
-:class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler` to
-work. If the command is located in a non-standard location, you can pass its
-path to the
-:class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler`
-constructor.
+All methods accept the translation locale as the last, optional parameter,
+which defaults to the current default locale::
 
-PhpBundleWriter
-~~~~~~~~~~~~~~~
+    $languages = Languages::getNames('de');
+    // => ['ab' => 'Abchasisch', 'ace' => 'Aceh', ...]
 
-The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Writer\\PhpBundleWriter`
-writes an array or an array-like object to a .php resource bundle::
+    $language = Languages::getName('fr', 'de');
+    // => 'Französisch'
 
-    use Symfony\Component\Intl\ResourceBundle\Writer\PhpBundleWriter;
+If the given locale doesn't exist, the methods trigger a
+:class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
+to catching the exception, you can also check if a given language code is valid::
 
-    $writer = new PhpBundleWriter();
-    $writer->write('/path/to/bundle', 'en', [
-        'Data' => [
-            'entry1',
-            'entry2',
-            // ...
-        ],
-    ]);
+    $isValidLanguage = Languages::exists($languageCode);
 
-BinaryBundleReader
-~~~~~~~~~~~~~~~~~~
+.. versionadded:: 4.3
 
-The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\BinaryBundleReader`
-reads binary resource bundle files and returns an array or an array-like object.
-This class currently only works with the `intl extension`_ installed::
+    The ``Languages`` class was introduced in Symfony 4.3.
 
-    use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
+The ``Scripts`` class provides access to the optional four-letter script code
+that can follow the language code according to the `Unicode ISO 15924 Registry`_
+(e.g. ``HANS`` in ``zh_HANS`` for simplified Chinese and ``HANT`` in ``zh_HANT``
+for traditional Chinese)::
 
-    $reader = new BinaryBundleReader();
-    $data = $reader->read('/path/to/bundle', 'en');
+    use Symfony\Component\Intl\Scripts;
 
-    var_dump($data['Data']['entry1']);
+    \Locale::setDefault('en');
 
-PhpBundleReader
-~~~~~~~~~~~~~~~
+    $scripts = Scripts::getNames();
+    // ('scriptCode' => 'scriptName')
+    // => ['Adlm' => 'Adlam', 'Afak' => 'Afaka', ...]
 
-The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\PhpBundleReader`
-reads resource bundles from .php files and returns an array or an array-like
-object::
+    $script = Scripts::getName('Hans');
+    // => 'Simplified'
 
-    use Symfony\Component\Intl\ResourceBundle\Reader\PhpBundleReader;
+All methods accept the translation locale as the last, optional parameter,
+which defaults to the current default locale::
 
-    $reader = new PhpBundleReader();
-    $data = $reader->read('/path/to/bundle', 'en');
+    $scripts = Scripts::getNames('de');
+    // => ['Adlm' => 'Adlam', 'Afak' => 'Afaka', ...]
 
-    var_dump($data['Data']['entry1']);
+    $script = Scripts::getName('Hans', 'de');
+    // => 'Vereinfacht'
 
-BufferedBundleReader
-~~~~~~~~~~~~~~~~~~~~
+If the given script code doesn't exist, the methods trigger a
+:class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
+to catching the exception, you can also check if a given script code is valid::
 
-The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\BufferedBundleReader`
-wraps another reader, but keeps the last N reads in a buffer, where N is a
-buffer size passed to the constructor::
+    $isValidScript = Scripts::exists($scriptCode);
 
-    use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
-    use Symfony\Component\Intl\ResourceBundle\Reader\BufferedBundleReader;
+.. versionadded:: 4.3
 
-    $reader = new BufferedBundleReader(new BinaryBundleReader(), 10);
+    The ``Scripts`` class was introduced in Symfony 4.3.
 
-    // actually reads the file
-    $data = $reader->read('/path/to/bundle', 'en');
+Country Names
+~~~~~~~~~~~~~
 
-    // returns data from the buffer
-    $data = $reader->read('/path/to/bundle', 'en');
+The ``Countries`` class provides access to the name of all countries according
+to the `ISO 3166-1 alpha-2`_ list of officially recognized countries and
+territories::
 
-    // actually reads the file
-    $data = $reader->read('/path/to/bundle', 'fr');
+    use Symfony\Component\Intl\Countries;
 
-StructuredBundleReader
-~~~~~~~~~~~~~~~~~~~~~~
+    \Locale::setDefault('en');
 
-The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\StructuredBundleReader`
-wraps another reader and offers a
-:method:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\StructuredBundleReaderInterface::readEntry`
-method for reading an entry of the resource bundle without having to worry
-whether array keys are set or not. If a path cannot be resolved, ``null`` is
-returned::
+    $countries = Countries::getNames();
+    // ('countryCode' => 'countryName')
+    // => ['AF' => 'Afghanistan', 'AX' => 'Åland Islands', ...]
 
-    use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
-    use Symfony\Component\Intl\ResourceBundle\Reader\StructuredBundleReader;
+    $country = Countries::getName('GB');
+    // => 'United Kingdom'
 
-    $reader = new StructuredBundleReader(new BinaryBundleReader());
+All methods accept the translation locale as the last, optional parameter,
+which defaults to the current default locale::
 
-    $data = $reader->read('/path/to/bundle', 'en');
+    $countries = Countries::getNames('de');
+    // => ['AF' => 'Afghanistan', 'EG' => 'Ägypten', ...]
 
-    // produces an error if the key "Data" does not exist
-    var_dump($data['Data']['entry1']);
+    $country = Countries::getName('GB', 'de');
+    // => 'Vereinigtes Königreich'
 
-    // returns null if the key "Data" does not exist
-    var_dump($reader->readEntry('/path/to/bundle', 'en', ['Data', 'entry1']));
+If the given country code doesn't exist, the methods trigger a
+:class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
+to catching the exception, you can also check if a given country code is valid::
 
-Additionally, the
-:method:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\StructuredBundleReaderInterface::readEntry`
-method resolves fallback locales. For example, the fallback locale of "en_GB" is
-"en". For single-valued entries (strings, numbers etc.), the entry will be read
-from the fallback locale if it cannot be found in the more specific locale. For
-multi-valued entries (arrays), the values of the more specific and the fallback
-locale will be merged. In order to suppress this behavior, the last parameter
-``$fallback`` can be set to ``false``::
+    $isValidCountry = Countries::exists($countryCode);
 
-    var_dump($reader->readEntry(
-        '/path/to/bundle',
-        'en',
-        ['Data', 'entry1'],
-        false
-    ));
+.. versionadded:: 4.3
 
-Accessing ICU Data
-------------------
+    The ``Countries`` class was introduced in Symfony 4.3.
 
-The ICU data is located in several "resource bundles". You can access a PHP
-wrapper of these bundles through the static
-:class:`Symfony\\Component\\Intl\\Intl` class. At the moment, the following
-data is supported:
+Locales
+~~~~~~~
 
-* `Language and Script Names`_
-* `Country Names`_
-* `Locales`_
-* `Currencies`_
+A locale is the combination of a language and a region. For example, "Chinese"
+is the language and ``zh_Hans_MO`` is the locale for "Chinese" (language) +
+"Simplified" (script) + "Macau SAR China" (region). The ``Locales`` class
+provides access to the name of all locales::
 
-Language and Script Names
-~~~~~~~~~~~~~~~~~~~~~~~~~
+    use Symfony\Component\Intl\Locales;
 
-The translations of language and script names can be found in the language
-bundle::
+    \Locale::setDefault('en');
 
-    use Symfony\Component\Intl\Intl;
+    $locales = Locales::getNames();
+    // ('localeCode' => 'localeName')
+    // => ['af' => 'Afrikaans', 'af_NA' => 'Afrikaans (Namibia)', ...]
 
-    \Locale::setDefault('en');
+    $locale = Locales::getName('zh_Hans_MO');
+    // => 'Chinese (Simplified, Macau SAR China)'
 
-    $languages = Intl::getLanguageBundle()->getLanguageNames();
-    // => ['ab' => 'Abkhazian', ...]
+All methods accept the translation locale as the last, optional parameter,
+which defaults to the current default locale::
 
-    $language = Intl::getLanguageBundle()->getLanguageName('de');
-    // => 'German'
+    $locales = Locales::getNames('de');
+    // => ['af' => 'Afrikaans', 'af_NA' => 'Afrikaans (Namibia)', ...]
 
-    $language = Intl::getLanguageBundle()->getLanguageName('de', 'AT');
-    // => 'Austrian German'
+    $locale = Locales::getName('zh_Hans_MO', 'de');
+    // => 'Chinesisch (Vereinfacht, Sonderverwaltungsregion Macau)'
 
-    $scripts = Intl::getLanguageBundle()->getScriptNames();
-    // => ['Arab' => 'Arabic', ...]
+If the given locale code doesn't exist, the methods trigger a
+:class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
+to catching the exception, you can also check if a given locale code is valid::
 
-    $script = Intl::getLanguageBundle()->getScriptName('Hans');
-    // => 'Simplified'
+    $isValidLocale = Locales::exists($localeCode);
 
-All methods accept the translation locale as the last, optional parameter,
-which defaults to the current default locale::
+.. versionadded:: 4.3
 
-    $languages = Intl::getLanguageBundle()->getLanguageNames('de');
-    // => ['ab' => 'Abchasisch', ...]
+    The ``Locales`` class was introduced in Symfony 4.3.
 
-Country Names
-~~~~~~~~~~~~~
+Currencies
+~~~~~~~~~~
 
-The translations of country names can be found in the region bundle::
+The ``Currencies`` class provides access to the name of all currencies as well
+as some of their information (symbol, fraction digits, etc.)::
 
-    use Symfony\Component\Intl\Intl;
+    use Symfony\Component\Intl\Currencies;
 
     \Locale::setDefault('en');
 
-    $countries = Intl::getRegionBundle()->getCountryNames();
-    // => ['AF' => 'Afghanistan', ...]
+    $currencies = Currencies::getNames();
+    // ('currencyCode' => 'currencyName')
+    // => ['AFN' => 'Afghan Afghani', 'ALL' => 'Albanian Lek', ...]
 
-    $country = Intl::getRegionBundle()->getCountryName('GB');
-    // => 'United Kingdom'
+    $currency = Currencies::getName('INR');
+    // => 'Indian Rupee'
 
-All methods accept the translation locale as the last, optional parameter,
-which defaults to the current default locale::
+    $symbol = Currencies::getSymbol('INR');
+    // => '₹'
 
-    $countries = Intl::getRegionBundle()->getCountryNames('de');
-    // => ['AF' => 'Afghanistan', ...]
+    $fractionDigits = Currencies::getFractionDigits('INR');
+    // => 2
 
-Locales
-~~~~~~~
+    $roundingIncrement = Currencies::getRoundingIncrement('INR');
+    // => 0
+
+All methods (except for ``getFractionDigits()`` and ``getRoundingIncrement()``)
+accept the translation locale as the last, optional parameter, which defaults to
+the current default locale::
+
+    $currencies = Currencies::getNames('de');
+    // => ['AFN' => 'Afghanischer Afghani', 'EGP' => 'Ägyptisches Pfund', ...]
+
+    $currency = Currencies::getName('INR', 'de');
+    // => 'Indische Rupie'
 
-The translations of locale names can be found in the locale bundle::
+If the given currency code doesn't exist, the methods trigger a
+:class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
+to catching the exception, you can also check if a given currency code is valid::
 
-    use Symfony\Component\Intl\Intl;
+    $isValidCurrency = Currencies::exists($currencyCode);
+
+.. versionadded:: 4.3
+
+    The ``Currencies`` class was introduced in Symfony 4.3.
+
+.. _component-intl-timezones:
+
+Timezones
+~~~~~~~~~
+
+The ``Timezones`` class provides several utilities related to timezones. First,
+you can get the name and values of all timezones in all languages::
+
+    use Symfony\Component\Intl\Timezones;
 
     \Locale::setDefault('en');
 
-    $locales = Intl::getLocaleBundle()->getLocaleNames();
-    // => ['af' => 'Afrikaans', ...]
+    $timezones = Timezones::getNames();
+    // ('timezoneID' => 'timezoneValue')
+    // => ['America/Eirunepe' => 'Acre Time (Eirunepe)', 'America/Rio_Branco' => 'Acre Time (Rio Branco)', ...]
 
-    $locale = Intl::getLocaleBundle()->getLocaleName('zh_Hans_MO');
-    // => 'Chinese (Simplified, Macau SAR China)'
+    $timezone = Timezones::getName('Africa/Nairobi');
+    // => 'East Africa Time (Nairobi)'
 
 All methods accept the translation locale as the last, optional parameter,
 which defaults to the current default locale::
 
-    $locales = Intl::getLocaleBundle()->getLocaleNames('de');
-    // => ['af' => 'Afrikaans', ...]
+    $timezones = Timezones::getNames('de');
+    // => ['America/Eirunepe' => 'Acre-Zeit (Eirunepe)', 'America/Rio_Branco' => 'Acre-Zeit (Rio Branco)', ...]
 
-Currencies
-~~~~~~~~~~
+    $timezone = Timezones::getName('Africa/Nairobi', 'de');
+    // => 'Ostafrikanische Zeit (Nairobi)'
 
-The translations of currency names and other currency-related information can
-be found in the currency bundle::
+You can also get all the timezones that exist in a given country. The
+``forCountryCode()`` method returns one or more timezone IDs, which you can
+translate into any locale with the ``getName()`` method shown earlier::
 
-    use Symfony\Component\Intl\Intl;
+    // unlike language codes, country codes are always uppercase (CL = Chile)
+    $timezones = Timezones::forCountryCode('CL');
+    // => ['America/Punta_Arenas', 'America/Santiago', 'Pacific/Easter']
 
-    \Locale::setDefault('en');
+The reverse lookup is also possible thanks to the ``getCountryCode()`` method,
+which returns the code of the country where the given timezone ID belongs to::
 
-    $currencies = Intl::getCurrencyBundle()->getCurrencyNames();
-    // => ['AFN' => 'Afghan Afghani', ...]
+    $countryCode = Timezones::getCountryCode('America/Vancouver')
+    // => $countryCode = 'CA' (CA = Canada)
 
-    $currency = Intl::getCurrencyBundle()->getCurrencyName('INR');
-    // => 'Indian Rupee'
+The `UTC/GMT time offsets`_ of all timezones are provided by ``getRawOffset()``
+(which returns an integer representing the offset in seconds) and
+``getGmtOffset()`` (which returns a string representation of the offset to
+display it to users)::
 
-    $symbol = Intl::getCurrencyBundle()->getCurrencySymbol('INR');
-    // => '₹'
+    $offset = Timezones::getRawOffset('Etc/UTC');              // $offset = 0
+    $offset = Timezones::getRawOffset('America/Buenos_Aires'); // $offset = -10800
+    $offset = Timezones::getRawOffset('Asia/Katmandu');        // $offset = 20700
 
-    $fractionDigits = Intl::getCurrencyBundle()->getFractionDigits('INR');
-    // => 2
+    $offset = Timezones::getGmtOffset('Etc/UTC');              // $offset = 'GMT+00:00'
+    $offset = Timezones::getGmtOffset('America/Buenos_Aires'); // $offset = 'GMT-03:00'
+    $offset = Timezones::getGmtOffset('Asia/Katmandu');        // $offset = 'GMT+05:45'
 
-    $roundingIncrement = Intl::getCurrencyBundle()->getRoundingIncrement('INR');
-    // => 0
+The timezone offset can vary in time because of the `daylight saving time (DST)`_
+practice. By default these methods use the ``time()`` PHP function to get the
+current timezone offset value, but you can pass a timestamp as their second
+arguments to get the offset at any given point in time::
+
+    // In 2019, the DST period in Madrid (Spain) went from March 31 to October 27
+    $offset = Timezones::getRawOffset('Europe/Madrid', strtotime('March 31, 2019'));   // $offset = 3600
+    $offset = Timezones::getRawOffset('Europe/Madrid', strtotime('April 1, 2019'));    // $offset = 7200
+    $offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 27, 2019')); // $offset = 'GMT+02:00'
+    $offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019')); // $offset = 'GMT+01:00'
+
+The string representation of the GMT offset can vary depending on the locale, so
+you can pass the locale as the third optional argument::
+
+    $offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'ar')); // $offset = 'غرينتش+01:00'
+    $offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'dz')); // $offset = 'ཇི་ཨེམ་ཏི་+01:00'
+
+If the given timezone ID doesn't exist, the methods trigger a
+:class:`Symfony\\Component\\Intl\\Exception\\MissingResourceException`. In addition
+to catching the exception, you can also check if a given timezone ID is valid::
 
-All methods (except for
-:method:`Symfony\\Component\\Intl\\ResourceBundle\\CurrencyBundleInterface::getFractionDigits`
-and
-:method:`Symfony\\Component\\Intl\\ResourceBundle\\CurrencyBundleInterface::getRoundingIncrement`)
-accept the translation locale as the last, optional parameter, which defaults
-to the current default locale::
+    $isValidTimezone = Timezones::exists($timezoneId);
 
-    $currencies = Intl::getCurrencyBundle()->getCurrencyNames('de');
-    // => ['AFN' => 'Afghanische Afghani', ...]
+.. versionadded:: 4.3
 
-That's all you need to know for now. Have fun coding!
+    The ``Timezones`` class was introduced in Symfony 4.3.
 
 Learn more
 ----------
@@ -342,9 +348,14 @@ Learn more
     /reference/forms/types/currency
     /reference/forms/types/language
     /reference/forms/types/locale
+    /reference/forms/types/timezone
 
-.. _Packagist: https://packagist.org/packages/symfony/intl
-.. _Icu component: https://packagist.org/packages/symfony/icu
 .. _intl extension: https://php.net/manual/en/book.intl.php
 .. _install the intl extension: https://php.net/manual/en/intl.setup.php
 .. _ICU library: http://site.icu-project.org/
+.. _`Unicode ISO 15924 Registry`: https://www.unicode.org/iso15924/iso15924-codes.html
+.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+.. _`UTC/GMT time offsets`: https://en.wikipedia.org/wiki/List_of_UTC_time_offsets
+.. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time
+.. _`ISO 639-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_639-1
+.. _`ISO 639-2 alpha-3`: https://en.wikipedia.org/wiki/ISO_639-2
diff --git a/components/ldap.rst b/components/ldap.rst
index 4747529b1e7..50b7eb5b917 100644
--- a/components/ldap.rst
+++ b/components/ldap.rst
@@ -14,8 +14,6 @@ Installation
 
     $ composer require symfony/ldap
 
-Alternatively, you can clone the `<https://github.com/symfony/ldap>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -42,7 +40,7 @@ following options:
     The encryption protocol: ``ssl``, ``tls`` or ``none`` (default)
 
 ``connection_string``
-    You may use this option instead of ``host`` and ``port`` to connect to the
+    You may use this option instead of ``host`` and ``port`` to connect to the
     LDAP server
 
 ``optReferrals``
@@ -103,14 +101,24 @@ array, you may use the
 
     // Do something with the results array
 
+By default, LDAP queries use the ``Symfony\Component\Ldap\Adapter::SCOPE_SUB``
+scope, which corresponds to the ``LDAP_SCOPE_SUBTREE`` scope of the
+:phpfunction:`ldap_search` function. You can also use ``SCOPE_BASE`` (related
+to the ``LDAP_SCOPE_BASE`` scope of :phpfunction:`ldap_read`) and ``SCOPE_ONE``
+(related to the ``LDAP_SCOPE_ONELEVEL`` scope of :phpfunction:`ldap_list`)::
+
+    use Symfony\Component\Ldap\Adapter;
+
+    $query = $ldap->query('dc=symfony,dc=com', '...', ['scope' => Adapter::SCOPE_ONE]);
+
 Creating or Updating Entries
 ----------------------------
 
 The Ldap component provides means to create new LDAP entries, update or even
 delete existing ones::
 
-    use Symfony\Component\Ldap\Ldap;
     use Symfony\Component\Ldap\Entry;
+    use Symfony\Component\Ldap\Ldap;
     // ...
 
     $entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', [
@@ -137,15 +145,14 @@ delete existing ones::
     // Removing an existing entry
     $entryManager->remove(new Entry('cn=Test User,dc=symfony,dc=com'));
 
-
 Batch Updating
 ______________
 
 Use the entry manager's :method:`Symfony\\Component\\Ldap\\Adapter\\ExtLdap\\EntryManager::applyOperations`
 method to update multiple attributes at once::
 
-    use Symfony\Component\Ldap\Ldap;
     use Symfony\Component\Ldap\Entry;
+    use Symfony\Component\Ldap\Ldap;
     // ...
 
     $entry = new Entry('cn=Fabien Potencier,dc=symfony,dc=com', [
@@ -165,12 +172,3 @@ Possible operation types are ``LDAP_MODIFY_BATCH_ADD``, ``LDAP_MODIFY_BATCH_REMO
 ``LDAP_MODIFY_BATCH_REMOVE_ALL``, ``LDAP_MODIFY_BATCH_REPLACE``. Parameter
 ``$values`` must be ``NULL`` when using ``LDAP_MODIFY_BATCH_REMOVE_ALL``
 operation type.
-
-.. versionadded:: 4.2
-    The ``applyOperations()`` method was introduced in Symfony 4.2.
-
-.. versionadded:: 4.1
-    The ``addAttributeValues()`` and ``removeAttributeValues()`` methods
-    were introduced in Symfony 4.1.
-
-.. _Packagist: https://packagist.org/packages/symfony/ldap
diff --git a/components/lock.rst b/components/lock.rst
index e49164b6c59..d6e1220f2b7 100644
--- a/components/lock.rst
+++ b/components/lock.rst
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/lock
 
-Alternatively, you can clone the `<https://github.com/symfony/lock>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -157,9 +155,54 @@ to reset the TTL to its original value::
         // refresh the lock for 600 seconds (next refresh() call will be 30 seconds again)
         $lock->refresh(600);
 
-    .. versionadded:: 4.1
-        The feature to pass a custom TTL as an argument of the ``refresh()``
-        method was introduced in Symfony 4.1.
+This component also provides two useful methods related to expiring locks:
+``getExpiringDate()`` (which returns ``null`` or a ``\DateTimeImmutable``
+object) and ``isExpired()`` (which returns a boolean).
+
+The Owner of The Lock
+---------------------
+
+Locks that are acquired for the first time are owned[1]_ by the ``Lock`` instance that acquired
+it. If you need to check whether the current ``Lock`` instance is (still) the owner of
+a lock, you can use the ``isAcquired()`` method::
+
+    if ($lock->isAcquired()) {
+        // We (still) own the lock
+    }
+
+Because of the fact that some lock stores have expiring locks (as seen and explained
+above), it is possible for an instance to lose the lock it acquired automatically::
+
+    // If we cannot acquire ourselves, it means some other process is already working on it
+    if (!$lock->acquire()) {
+        return;
+    }
+
+    $this->beginTransaction();
+
+    // Perform a very long process that might exceed TTL of the lock
+
+    if ($lock->isAcquired()) {
+        // Still all good, no other instance has acquired the lock in the meantime, we're safe
+        $this->commit();
+    } else {
+        // Bummer! Our lock has apparently exceeded TTL and another process has started in
+        // the meantime so it's not safe for us to commit.
+        $this->rollback();
+        throw new \Exception('Process failed');
+    }
+
+.. caution::
+
+    A common pitfall might be to use the ``isAcquired()`` method to check if
+    a lock has already been acquired by any process. As you can see in this example
+    you have to use ``acquire()`` for this. The ``isAcquired()`` method is used to check
+    if the lock has been acquired by the **current process** only!
+
+.. [1] Technically, the true owners of the lock are the ones that share the same instance of ``Key``,
+    not ``Lock``. But from a user perspective, ``Key`` is internal and you will likely only be working
+    with the ``Lock`` instance so it's easier to think of the ``Lock`` instance as being the one that
+    is the owner of the lock.
 
 Available Stores
 ----------------
@@ -173,8 +216,10 @@ Store                                         Scope   Blocking  Expiring
 ============================================  ======  ========  ========
 :ref:`FlockStore <lock-store-flock>`          local   yes       no
 :ref:`MemcachedStore <lock-store-memcached>`  remote  no        yes
+:ref:`PdoStore <lock-store-pdo>`              remote  no        yes
 :ref:`RedisStore <lock-store-redis>`          remote  no        yes
 :ref:`SemaphoreStore <lock-store-semaphore>`  local   yes       no
+:ref:`ZookeeperStore <lock-store-zookeeper>`  remote  no        no
 ============================================  ======  ========  ========
 
 .. _lock-store-flock:
@@ -195,7 +240,7 @@ PHP process is terminated::
 
     Beware that some file systems (such as some types of NFS) do not support
     locking. In those cases, it's better to use a directory on a local disk
-    drive or a remote store based on Redis or Memcached.
+    drive or a remote store based on PDO, Redis or Memcached.
 
 .. _lock-store-memcached:
 
@@ -217,6 +262,45 @@ support blocking, and expects a TTL to avoid stalled locks::
 
     Memcached does not support TTL lower than 1 second.
 
+.. _lock-store-pdo:
+
+PdoStore
+~~~~~~~~
+
+The PdoStore saves locks in an SQL database. It requires a `PDO`_ connection, a
+`Doctrine DBAL Connection`_, or a `Data Source Name (DSN)`_. This store does not
+support blocking, and expects a TTL to avoid stalled locks::
+
+    use Symfony\Component\Lock\Store\PdoStore;
+
+    // a PDO, a Doctrine DBAL connection or DSN for lazy connecting through PDO
+    $databaseConnectionOrDSN = 'mysql:host=127.0.0.1;dbname=lock';
+    $store = new PdoStore($databaseConnectionOrDSN, ['db_username' => 'myuser', 'db_password' => 'mypassword']);
+
+.. note::
+
+    This store does not support TTL lower than 1 second.
+
+Before storing locks in the database, you must create the table that stores
+the information. The store provides a method called
+:method:`Symfony\\Component\\Lock\\Store\\PdoStore::createTable`
+to set up this table for you according to the database engine used::
+
+    try {
+        $store->createTable();
+    } catch (\PDOException $exception) {
+        // the table could not be created for some reason
+    }
+
+A great way to set up the table in production is to call the ``createTable()``
+method in your local computer and then generate a
+:ref:`database migration <doctrine-creating-the-database-tables-schema>`:
+
+.. code-block:: terminal
+
+    $ php bin/console doctrine:migrations:diff
+    $ php bin/console doctrine:migrations:migrate
+
 .. _lock-store-redis:
 
 RedisStore
@@ -256,9 +340,9 @@ is being acquired, it forwards the call to all the managed stores, and it
 collects their responses. If a simple majority of stores have acquired the lock,
 then the lock is considered as acquired; otherwise as not acquired::
 
-    use Symfony\Component\Lock\Strategy\ConsensusStrategy;
     use Symfony\Component\Lock\Store\CombinedStore;
     use Symfony\Component\Lock\Store\RedisStore;
+    use Symfony\Component\Lock\Strategy\ConsensusStrategy;
 
     $stores = [];
     foreach (['server1', 'server2', 'server3'] as $server) {
@@ -281,6 +365,29 @@ the stores.
     working when a single server fails (because this strategy requires that the
     lock is acquired in more than half of the servers).
 
+.. _lock-store-zookeeper:
+
+ZookeeperStore
+~~~~~~~~~~~~~~
+
+The ZookeeperStore saves locks on a `ZooKeeper`_ server. It requires a ZooKeeper
+connection implementing the ``\Zookeeper`` class. This store does not
+support blocking and expiration but the lock is automatically released when the
+PHP process is terminated::
+
+    use Symfony\Component\Lock\Store\ZookeeperStore;
+
+    $zookeeper = new \Zookeeper('localhost:2181');
+    // use the following to define a high-availability cluster:
+    // $zookeeper = new \Zookeeper('localhost1:2181,localhost2:2181,localhost3:2181');
+
+    $store = new ZookeeperStore($zookeeper);
+
+.. note::
+
+    Zookeeper does not require a TTL as the nodes used for locking are ephemeral
+    and die when the PHP process is terminated.
+
 Reliability
 -----------
 
@@ -290,11 +397,13 @@ the component is used in the following way.
 Remote Stores
 ~~~~~~~~~~~~~
 
-Remote stores (:ref:`MemcachedStore <lock-store-memcached>` and
-:ref:`RedisStore <lock-store-redis>`) use an unique token to recognize the true
-owner of the lock. This token is stored in the
-:class:`Symfony\\Component\\Lock\\Key` object and is used internally by the
-``Lock``, therefore this key must not be shared between processes (session,
+Remote stores (:ref:`MemcachedStore <lock-store-memcached>`,
+:ref:`PdoStore <lock-store-pdo>`,
+:ref:`RedisStore <lock-store-redis>` and
+:ref:`ZookeeperStore <lock-store-zookeeper>`) use a unique token to recognize
+the true owner of the lock. This token is stored in the
+:class:`Symfony\\Component\\Lock\\Key` object and is used internally by
+the ``Lock``, therefore this key must not be shared between processes (session,
 caching, fork, ...).
 
 .. caution::
@@ -313,11 +422,12 @@ different machines may allow two different processes to acquire the same ``Lock`
 Expiring Stores
 ~~~~~~~~~~~~~~~
 
-Expiring stores (:ref:`MemcachedStore <lock-store-memcached>` and
-:ref:`RedisStore <lock-store-redis>`) guarantee that the lock is acquired
-only for the defined duration of time. If the task takes longer to be
-accomplished, then the lock can be released by the store and acquired by
-someone else.
+Expiring stores (:ref:`MemcachedStore <lock-store-memcached>`,
+:ref:`PdoStore <lock-store-pdo>` and
+:ref:`RedisStore <lock-store-redis>`)
+guarantee that the lock is acquired only for the defined duration of time. If
+the task takes longer to be accomplished, then the lock can be released by the
+store and acquired by someone else.
 
 The ``Lock`` provides several methods to check its health. The ``isExpired()``
 method checks whether or not it lifetime is over and the ``getRemainingLifetime()``
@@ -431,6 +541,30 @@ method uses the Memcached's ``flush()`` method which purges and removes everythi
     The method ``flush()`` must not be called, or locks should be stored in a
     dedicated Memcached service away from Cache.
 
+PdoStore
+~~~~~~~~~~
+
+The PdoStore relies on the `ACID`_ properties of the SQL engine.
+
+.. caution::
+
+    In a cluster configured with multiple primaries, ensure writes are
+    synchronously propagated to every nodes, or always use the same node.
+
+.. caution::
+
+    Some SQL engines like MySQL allow to disable the unique constraint check.
+    Ensure that this is not the case ``SET unique_checks=1;``.
+
+In order to purge old locks, this store uses a current datetime to define an
+expiration date reference. This mechanism relies on all server nodes to
+have synchronized clocks.
+
+.. caution::
+
+    To ensure locks don't expire prematurely; the TTLs should be set with
+    enough extra time to account for any clock drift between nodes.
+
 RedisStore
 ~~~~~~~~~~
 
@@ -493,6 +627,30 @@ can be two running containers in parallel.
     concurrent process on a new machine, check that other process are stopped
     on the old one.
 
+ZookeeperStore
+~~~~~~~~~~~~~~
+
+The way ZookeeperStore works is by maintaining locks as ephemeral nodes on the
+server. That means that by using :ref:`ZookeeperStore <lock-store-zookeeper>`
+the locks will be automatically released at the end of the session in case the
+client cannot unlock for any reason.
+
+If the ZooKeeper service or the machine hosting it restarts, every lock would
+be lost without notifying the running processes.
+
+.. tip::
+
+    To use ZooKeeper's high-availability feature, you can setup a cluster of
+    multiple servers so that in case one of the server goes down, the majority
+    will still be up and serving the requests. All the available servers in the
+    cluster will see the same state.
+
+.. note::
+
+    As this store does not support multi-level node locks, since the clean up of
+    intermediate nodes becomes an overhead, all locks are maintained at the root
+    level.
+
 Overall
 ~~~~~~~
 
@@ -501,6 +659,10 @@ instance, during the deployment of a new version. Processes with new
 configuration must not be started while old processes with old configuration
 are still running.
 
+.. _`ACID`: https://en.wikipedia.org/wiki/ACID
 .. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science)
-.. _Packagist: https://packagist.org/packages/symfony/lock
-.. _`PHP semaphore functions`: http://php.net/manual/en/book.sem.php
+.. _`PHP semaphore functions`: https://php.net/manual/en/book.sem.php
+.. _`PDO`: https://php.net/pdo
+.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
+.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
+.. _`ZooKeeper`: https://zookeeper.apache.org/
diff --git a/components/mailer.rst b/components/mailer.rst
new file mode 100644
index 00000000000..36caa78c972
--- /dev/null
+++ b/components/mailer.rst
@@ -0,0 +1,169 @@
+.. index::
+   single: Mailer
+   single: Components; Mailer
+
+The Mailer Component
+====================
+
+    The Mailer component helps sending emails.
+
+If you're using the Symfony Framework, read the
+:doc:`Symfony Framework Mailer documentation </mailer>`.
+
+.. versionadded:: 4.3
+
+    The Mailer component was introduced in Symfony 4.3 and it's still
+    considered an :doc:`experimental feature </contributing/code/experimental>`.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/mailer
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+The Mailer component has two main classes: a ``Transport`` and the ``Mailer`` itself::
+
+    use Symfony\Component\Mailer\Mailer;
+    use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport;
+
+    $transport = new SmtpTransport('localhost');
+    $mailer = new Mailer($transport);
+    $mailer->send($email);
+
+The ``$email`` object is created via the :doc:`Mime component </components/mime>`.
+
+Transport
+---------
+
+The only transport that comes pre-installed is SMTP.
+
+Below is the list of other popular providers with built-in support:
+
+==================  =============================================
+Service             Install with
+==================  =============================================
+Amazon SES          ``composer require symfony/amazon-mailer``
+Gmail               ``composer require symfony/google-mailer``
+MailChimp           ``composer require symfony/mailchimp-mailer``
+Mailgun             ``composer require symfony/mailgun-mailer``
+Postmark            ``composer require symfony/postmark-mailer``
+SendGrid            ``composer require symfony/sendgrid-mailer``
+==================  =============================================
+
+For example, suppose you want to use Google's Gmail SMTP server. First, install
+it:
+
+.. code-block:: terminal
+
+    $ composer require symfony/google-mailer
+
+Then, use the SMTP Gmail transport::
+
+    use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport;
+
+    $transport = new GmailTransport('user', 'pass');
+    $mailer = new Mailer($transport);
+    $mailer->send($email);
+
+Each provider provides up to 3 transports: standard SMTP, HTTP (it uses the
+provider's API but the body is created by the mailer component), API (it uses
+the full API of the provider with no control over the body creation -- features
+might be limited as well).
+
+.. _mailer_dsn:
+
+The mailer component provides a convenient way to create a transport from a
+DSN::
+
+    use Symfony\Component\Mailer\Transport;
+
+    $transport = Transport::fromDsn($dsn);
+
+Where ``$dsn`` depends on the provider you want to use. For plain SMTP, use
+``smtp://user:pass@example.com`` or ``smtp://sendmail`` to use the ``sendmail``
+binary. For third-party providers, refers to the following table:
+
+==================== ================================== ================================== ================================
+ Provider             SMTP                               HTTP                               API
+==================== ================================== ================================== ================================
+ Amazon SES           smtp://ACCESS_KEY:SECRET_KEY@ses   http://ACCESS_KEY:SECRET_KEY@ses   api://ACCESS_KEY:SECRET_KEY@ses
+ Google Gmail         smtp://USERNAME:PASSWORD@gmail     n/a                                n/a
+ Mailchimp Mandrill   smtp://USERNAME:PASSWORD@mandrill  http://KEY@mandrill                api://KEY@mandrill
+ Mailgun              smtp://USERNAME:PASSWORD@mailgun   http://KEY:DOMAIN@mailgun          api://KEY:DOMAIN@mailgun
+ Postmark             smtp://ID:ID@postmark              n/a                                api://KEY@postmark
+ Sendgrid             smtp://apikey:KEY@sendgrid         n/a                                api://KEY@sendgrid
+==================== ================================== ================================== ================================
+
+Failover Transport
+------------------
+
+You can create failover transport with the help of `||` operator::
+
+    $dsn = 'api://id@postmark || smtp://key@sendgrid';
+
+So if the first transport fails, the mailer will attempt to send through the
+second transport.
+
+Round Robin
+-----------
+
+If you want to send emails by using multiple transports in a round-robin fashion,
+you can use the ``&&`` operator between the transports::
+
+    $dsn = 'api://id@postmark && smtp://key@sendgrid'
+
+Sending emails asynchronously
+-----------------------------
+
+If you want to send emails asynchronously, install the :doc:`Messenger component
+</components/messenger>`.
+
+.. code-block:: terminal
+
+    $ composer require symfony/messenger
+
+Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``::
+
+    use Symfony\Component\Mailer\Mailer;
+    use Symfony\Component\Mailer\Messenger\MessageHandler;
+    use Symfony\Component\Mailer\Messenger\SendEmailMessage;
+    use Symfony\Component\Mailer\SmtpEnvelope;
+    use Symfony\Component\Mailer\Transport;
+    use Symfony\Component\Messenger\Handler\HandlersLocator;
+    use Symfony\Component\Messenger\MessageBus;
+    use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;
+    use Symfony\Component\Mime\Address;
+
+    $dsn = 'change-dsn-accordingly';
+
+    $transport = Transport::fromDsn($dsn);
+    $handler = new MessageHandler($transport);
+
+    $bus = new MessageBus([
+        new HandleMessageMiddleware(new HandlersLocator([
+            SendEmailMessage::class => [$handler],
+        ])),
+    ]);
+
+    $mailer = new Mailer($transport, $bus);
+    $mailer->send($email);
+
+    // you can pass an optional Envelope
+    $mailer->send($email, new SmtpEnvelope(
+        new Address('sender@example.com'),
+        [
+            new Address('recipient@example.com'),
+        ]
+    ));
+
+Learn More
+-----------
+
+To learn more about how to use the mailer component, refer to the
+:doc:`Symfony Framework Mailer documentation </mailer>`.
diff --git a/components/mercure.rst b/components/mercure.rst
new file mode 100644
index 00000000000..adfd7a38f5f
--- /dev/null
+++ b/components/mercure.rst
@@ -0,0 +1,46 @@
+.. index::
+   single: Mercure
+   single: Components; Mercure
+
+The Mercure Component
+=====================
+
+    `Mercure`_ is an open protocol allowing to push data updates to web
+    browsers and other HTTP clients in a convenient, fast, reliable
+    and battery-friendly way.
+    It is especially useful to publish real-time updates of resources served
+    through web APIs, to reactive web and mobile applications.
+
+The Mercure Component implements the "publisher" part of the Mercure Protocol.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/mercure
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+The following example shows the component in action::
+
+    // change these values accordingly to your hub installation
+    define('HUB_URL', 'https://demo.mercure.rocks/hub');
+    define('JWT', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InN1YnNjcmliZSI6WyJmb28iLCJiYXIiXSwicHVibGlzaCI6WyJmb28iXX19.LRLvirgONK13JgacQ_VbcjySbVhkSmHy3IznH3tA9PM');
+
+    use Symfony\Component\Mercure\Jwt\StaticJwtProvider;
+    use Symfony\Component\Mercure\Publisher;
+    use Symfony\Component\Mercure\Update;
+
+    $publisher = new Publisher(HUB_URL, new StaticJwtProvider(JWT));
+    // Serialize the update, and dispatch it to the hub, that will broadcast it to the clients
+    $id = $publisher(new Update('https://example.com/books/1.jsonld', 'Hi from Symfony!', ['target1', 'target2']));
+
+Read the full :doc:`Mercure integration documentation </mercure>` to learn
+about all the features of this component and its integration with the Symfony
+framework.
+
+.. _`Mercure`: https://mercure.rocks
diff --git a/components/messenger.rst b/components/messenger.rst
index faa03e8e875..bbe6a55c135 100644
--- a/components/messenger.rst
+++ b/components/messenger.rst
@@ -8,8 +8,8 @@ The Messenger Component
     The Messenger component helps applications send and receive messages to/from
     other applications or via message queues.
 
-    The component is greatly inspired by Matthias Noback's series of `blog posts
-    about command buses`_ and the `SimpleBus project`_.
+    The component is greatly inspired by Matthias Noback's series of
+    `blog posts about command buses`_ and the `SimpleBus project`_.
 
 .. seealso::
 
@@ -24,8 +24,6 @@ Installation
 
     $ composer require symfony/messenger
 
-Alternatively, you can clone the `<https://github.com/symfony/messenger>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Concepts
@@ -55,15 +53,15 @@ Concepts
    applicable throughout the application and affecting the entire message bus.
    For instance: logging, validating a message, starting a transaction, ...
    They are also responsible for calling the next middleware in the chain,
-   which means they can tweak the envelope, by adding items to it or even
+   which means they can tweak the envelope, by adding stamps to it or even
    replacing it, as well as interrupt the middleware chain.
 
 **Envelope**
    Messenger specific concept, it gives full flexibility inside the message bus,
    by wrapping the messages into it, allowing to add useful information inside
-   through *envelope items*.
+   through *envelope stamps*.
 
-**Envelope Items**
+**Envelope Stamps**
    Piece of information you need to attach to your message: serializer context
    to use for transport, markers identifying a received message or any sort of
    metadata your middleware or transport layer may use.
@@ -78,19 +76,24 @@ When using the message bus with Symfony's FrameworkBundle, the following middlew
 are configured for you:
 
 #. :class:`Symfony\\Component\\Messenger\\Middleware\\LoggingMiddleware` (logs the processing of your messages)
-#. :class:`Symfony\\Component\\Messenger\\Asynchronous\\Middleware\\SendMessageMiddleware` (enables asynchronous processing)
+#. :class:`Symfony\\Component\\Messenger\\Middleware\\SendMessageMiddleware` (enables asynchronous processing)
 #. :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware` (calls the registered handler(s))
 
+.. deprecated:: 4.3
+
+    The ``LoggingMiddleware`` is deprecated since Symfony 4.3 and will be
+    removed in 5.0. Pass a logger to ``SendMessageMiddleware`` instead.
+
 Example::
 
     use App\Message\MyMessage;
+    use Symfony\Component\Messenger\Handler\HandlersLocator;
     use Symfony\Component\Messenger\MessageBus;
-    use Symfony\Component\Messenger\Handler\Locator\HandlerLocator;
     use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;
 
     $bus = new MessageBus([
-        new HandleMessageMiddleware(new HandlerLocator([
-            MyMessage::class => $handler,
+        new HandleMessageMiddleware(new HandlersLocator([
+            MyMessage::class => ['dummy' => $handler],
         ])),
     ]);
 
@@ -113,72 +116,83 @@ that will do the required processing for your message::
 
     class MyMessageHandler
     {
-       public function __invoke(MyMessage $message)
-       {
-           // Message processing...
-       }
+        public function __invoke(MyMessage $message)
+        {
+            // Message processing...
+        }
     }
 
 Adding Metadata to Messages (Envelopes)
 ---------------------------------------
 
 If you need to add metadata or some configuration to a message, wrap it with the
-:class:`Symfony\\Component\\Messenger\\Envelope` class. For example, to set the
-serialization groups used when the message goes through the transport layer, use
-the ``SerializerConfiguration`` envelope::
+:class:`Symfony\\Component\\Messenger\\Envelope` class and add stamps.
+For example, to set the serialization groups used when the message goes
+through the transport layer, use the ``SerializerStamp`` stamp::
 
     use Symfony\Component\Messenger\Envelope;
-    use Symfony\Component\Messenger\Transport\Serialization\SerializerConfiguration;
+    use Symfony\Component\Messenger\Stamp\SerializerStamp;
 
     $bus->dispatch(
-        (new Envelope($message))->with(new SerializerConfiguration([
+        (new Envelope($message))->with(new SerializerStamp([
             'groups' => ['my_serialization_groups'],
         ]))
     );
 
-At the moment, the Symfony Messenger has the following built-in envelope items:
+At the moment, the Symfony Messenger has the following built-in envelope stamps:
 
-#. :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\SerializerConfiguration`,
+#. :class:`Symfony\\Component\\Messenger\\Stamp\\SerializerStamp`,
    to configure the serialization groups used by the transport.
-#. :class:`Symfony\\Component\\Messenger\\Middleware\\Configuration\\ValidationConfiguration`,
+#. :class:`Symfony\\Component\\Messenger\\Stamp\\ValidationStamp`,
    to configure the validation groups used when the validation middleware is enabled.
-#. :class:`Symfony\\Component\\Messenger\\Asynchronous\\Transport\\ReceivedMessage`,
-   an internal item that marks the message as received from a transport.
-
-Instead of dealing directly with the messages in the middleware you can receive the
-envelope by implementing the :class:`Symfony\\Component\\Messenger\\EnvelopeAwareInterface`
-marker, like this::
-
-    use Symfony\Component\Messenger\Asynchronous\Transport\ReceivedMessage;
+#. :class:`Symfony\\Component\\Messenger\\Stamp\\ReceivedStamp`,
+   an internal stamp that marks the message as received from a transport.
+#. :class:`Symfony\\Component\\Messenger\\Stamp\\SentStamp`,
+   a stamp that marks the message as sent by a specific sender.
+   Allows accessing the sender FQCN and the alias if available from the
+   :class:`Symfony\\Component\\Messenger\\Transport\\Sender\\SendersLocator`.
+#. :class:`Symfony\\Component\\Messenger\\Stamp\\HandledStamp`,
+   a stamp that marks the message as handled by a specific handler.
+   Allows accessing the handler returned value, the handler callable name
+   and its alias if available from the :class:`Symfony\\Component\\Messenger\\Handler\\HandlersLocator`.
+
+Instead of dealing directly with the messages in the middleware you receive the envelope.
+Hence you can inspect the envelope content and its stamps, or add any::
+
+    use App\Message\Stamp\AnotherStamp;
     use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
-    use Symfony\Component\Messenger\EnvelopeAwareInterface;
+    use Symfony\Component\Messenger\Middleware\StackInterface;
+    use Symfony\Component\Messenger\Stamp\ReceivedStamp;
 
-    class MyOwnMiddleware implements MiddlewareInterface, EnvelopeAwareInterface
+    class MyOwnMiddleware implements MiddlewareInterface
     {
-        public function handle($envelope, callable $next)
+        public function handle(Envelope $envelope, StackInterface $stack): Envelope
         {
-            // $envelope here is an `Envelope` object, because this middleware
-            // implements the EnvelopeAwareInterface interface.
-
-            if (null !== $envelope->get(ReceivedMessage::class)) {
+            if (null !== $envelope->last(ReceivedStamp::class)) {
                 // Message just has been received...
 
-                // You could for example add another item.
-                $envelope = $envelope->with(new AnotherEnvelopeItem(/* ... */));
+                // You could for example add another stamp.
+                $envelope = $envelope->with(new AnotherStamp(/* ... */));
             }
 
-            return $next($envelope);
+            return $stack->next()->handle($envelope, $stack);
         }
     }
 
-The above example will forward the message to the next middleware with an additional
-envelope item *if* the message has just been received (i.e. has the `ReceivedMessage` item).
-You can create your own items by implementing :class:`Symfony\\Component\\Messenger\\EnvelopeAwareInterface`.
+The above example will forward the message to the next middleware with an
+additional stamp *if* the message has just been received (i.e. has at least one
+``ReceivedStamp`` stamp). You can create your own stamps by implementing
+:class:`Symfony\\Component\\Messenger\\Stamp\\StampInterface`.
+
+If you want to examine all stamps on an envelope, use the ``$envelope->all()``
+method, which returns all stamps grouped by type (FQCN). Alternatively, you can
+iterate through all stamps of a specific type by using the FQCN as first
+parameter of this method (e.g. ``$envelope->all(ReceivedStamp::class)``).
 
 .. note::
 
-    Any envelope item must be php serializable if going through transport using
-    the :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\Serializer`
+    Any stamp must be serializable using the Symfony Serializer component
+    if going through transport using the :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\Serializer`
     base serializer.
 
 Transports
@@ -190,48 +204,50 @@ transport will be responsible for communicating with your message broker or 3rd
 Your own Sender
 ~~~~~~~~~~~~~~~
 
-Using the :class:`Symfony\\Component\\Messenger\\Transport\\SenderInterface`,
-you can create your own message sender.
 Imagine that you already have an ``ImportantAction`` message going through the
 message bus and being handled by a handler. Now, you also want to send this
-message as an email.
+message as an email (using the :doc:`Mime </components/mime>` and
+:doc:`Mailer </components/mailer>` components).
 
-First, create your sender::
+Using the :class:`Symfony\\Component\\Messenger\\Transport\\Sender\\SenderInterface`,
+you can create your own message sender::
 
     namespace App\MessageSender;
 
     use App\Message\ImportantAction;
-    use Symfony\Component\Messenger\Transport\SenderInterface;
+    use Symfony\Component\Mailer\MailerInterface;
     use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\Transport\Sender\SenderInterface;
+    use Symfony\Component\Mime\Email;
 
     class ImportantActionToEmailSender implements SenderInterface
     {
-       private $mailer;
-       private $toEmail;
-
-       public function __construct(\Swift_Mailer $mailer, string $toEmail)
-       {
-           $this->mailer = $mailer;
-           $this->toEmail = $toEmail;
-       }
-
-       public function send(Envelope $envelope)
-       {
-           $message = $envelope->getMessage();
-
-           if (!$message instanceof ImportantAction) {
-               throw new \InvalidArgumentException(sprintf('This transport only supports "%s" messages.', ImportantAction::class));
-           }
-
-           $this->mailer->send(
-               (new \Swift_Message('Important action made'))
-                   ->setTo($this->toEmail)
-                   ->setBody(
-                       '<h1>Important action</h1><p>Made by '.$message->getUsername().'</p>',
-                       'text/html'
-                   )
-           );
-       }
+        private $mailer;
+        private $toEmail;
+
+        public function __construct(MailerInterface $mailer, string $toEmail)
+        {
+            $this->mailer = $mailer;
+            $this->toEmail = $toEmail;
+        }
+
+        public function send(Envelope $envelope): Envelope
+        {
+            $message = $envelope->getMessage();
+
+            if (!$message instanceof ImportantAction) {
+                throw new \InvalidArgumentException(sprintf('This transport only supports "%s" messages.', ImportantAction::class));
+            }
+
+            $this->mailer->send(
+                (new Email())
+                    ->to($this->toEmail)
+                    ->subject('Important action made')
+                    ->html('<h1>Important action</h1><p>Made by '.$message->getUsername().'</p>')
+            );
+
+            return $envelope;
+        }
     }
 
 Your own Receiver
@@ -246,55 +262,69 @@ application but you can't use an API and need to use a shared CSV file with new
 orders.
 
 You will read this CSV file and dispatch a ``NewOrder`` message. All you need to
-do is to write your custom CSV receiver and Symfony will do the rest.
-
-First, create your receiver::
+do is to write your own CSV receiver::
 
     namespace App\MessageReceiver;
 
     use App\Message\NewOrder;
-    use Symfony\Component\Messenger\Transport\ReceiverInterface;
-    use Symfony\Component\Serializer\SerializerInterface;
     use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface;
+    use Symfony\Component\Serializer\SerializerInterface;
 
     class NewOrdersFromCsvFileReceiver implements ReceiverInterface
     {
-       private $serializer;
-       private $filePath;
-
-       public function __construct(SerializerInterface $serializer, string $filePath)
-       {
-           $this->serializer = $serializer;
-           $this->filePath = $filePath;
-       }
-
-       public function receive(callable $handler): void
-       {
-           $ordersFromCsv = $this->serializer->deserialize(file_get_contents($this->filePath), 'csv');
-
-           foreach ($ordersFromCsv as $orderFromCsv) {
-               $order = new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']);
-
-               $handler(new Envelope($order));
-           }
-       }
-
-       public function stop(): void
-       {
-           // noop
-       }
+        private $serializer;
+        private $filePath;
+
+        public function __construct(SerializerInterface $serializer, string $filePath)
+        {
+            $this->serializer = $serializer;
+            $this->filePath = $filePath;
+        }
+
+        public function get(): iterable
+        {
+            $ordersFromCsv = $this->serializer->deserialize(file_get_contents($this->filePath), 'csv');
+
+            foreach ($ordersFromCsv as $orderFromCsv) {
+                $order = new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']);
+
+                $envelope = new Envelope($order);
+
+                $handler($envelope);
+            }
+
+            return [$envelope];
+        }
+
+        public function ack(Envelope $envelope): void
+        {
+            // Add information about the handled message
+        }
+
+        public function reject(Envelope $envelope): void
+        {
+            // Reject the message if needed
+        }
     }
 
+.. versionadded:: 4.3
+
+    In Symfony 4.3, the ``ReceiverInterface`` has changed its methods as shown
+    in the example above. You may need to update your code if you used this
+    interface in previous Symfony versions.
+
 Receiver and Sender on the same Bus
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To allow sending and receiving messages on the same bus and prevent an infinite
-loop, the message bus will add a :class:`Symfony\\Component\\Messenger\\Asynchronous\\Transport\\ReceivedMessage`
-envelope item to the message envelopes and the :class:`Symfony\\Component\\Messenger\\Asynchronous\\Middleware\\SendMessageMiddleware`
+loop, the message bus will add a :class:`Symfony\\Component\\Messenger\\Stamp\\ReceivedStamp`
+stamp to the message envelopes and the :class:`Symfony\\Component\\Messenger\\Middleware\\SendMessageMiddleware`
 middleware will know it should not route these messages again to a transport.
 
 Learn more
 ----------
+
 .. toctree::
     :maxdepth: 1
     :glob:
@@ -302,5 +332,5 @@ Learn more
     /messenger
     /messenger/*
 
-.. _blog posts about command buses: https://matthiasnoback.nl/tags/command%20bus/
-.. _SimpleBus project: http://simplebus.io
+.. _`blog posts about command buses`: https://matthiasnoback.nl/tags/command%20bus/
+.. _`SimpleBus project`: http://docs.simplebus.io/en/latest/
diff --git a/components/mime.rst b/components/mime.rst
new file mode 100644
index 00000000000..501b10a8dc5
--- /dev/null
+++ b/components/mime.rst
@@ -0,0 +1,306 @@
+.. index::
+   single: MIME
+   single: MIME Messages
+   single: Components; MIME
+
+The Mime Component
+==================
+
+    The Mime component allows manipulating the MIME messages used to send emails
+    and provides utilities related to MIME types.
+
+.. versionadded:: 4.3
+
+    The Mime component was introduced in Symfony 4.3 and it's still
+    considered an :doc:`experimental feature </contributing/code/experimental>`.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/mime
+
+.. include:: /components/require_autoload.rst.inc
+
+Introduction
+------------
+
+`MIME`_ (Multipurpose Internet Mail Extensions) is an Internet standard that
+extends the original basic format of emails to support features like:
+
+* Headers and text contents using non-ASCII characters;
+* Message bodies with multiple parts (e.g. HTML and plain text contents);
+* Non-text attachments: audio, video, images, PDF, etc.
+
+The entire MIME standard is complex and huge, but Symfony abstracts all that
+complexity to provide two ways of creating MIME messages:
+
+* A high-level API based on the :class:`Symfony\\Component\\Mime\\Email` class
+  to quickly create email messages with all the common features;
+* A low-level API based on the :class:`Symfony\\Component\\Mime\\Message` class
+  to have an absolute control over every single part of the email message.
+
+Usage
+-----
+
+Use the :class:`Symfony\\Component\\Mime\\Email` class and their *chainable*
+methods to compose the entire email message::
+
+    use Symfony\Component\Mime\Email;
+
+    $email = (new Email())
+        ->from('fabien@symfony.com')
+        ->to('foo@example.com')
+        ->cc('bar@example.com')
+        ->bcc('baz@example.com')
+        ->replyTo('fabien@symfony.com')
+        ->priority(Email::PRIORITY_HIGH)
+        ->subject('Important Notification')
+        ->text('Lorem ipsum...')
+        ->html('<h1>Lorem ipsum</h1> <p>...</p>')
+    ;
+
+This only purpose of this component is to create the email messages. Use the
+:doc:`Mailer component </components/mailer>` to actually send them. In Symfony
+applications, it's easier to use the :doc:`Mailer integration </mailer>`.
+
+Most of the details about how to create Email objects, including Twig integration,
+can be found in the :doc:`Mailer documentation </mailer>`.
+
+Twig Integration
+----------------
+
+The Mime component comes with excellent integration with Twig, allowing you to
+create messages from Twig templates, embed images, inline CSS and more. Details
+on how to use those features can be found in the Mailer documentation:
+:ref:`Twig: HTML & CSS <mailer-twig>`.
+
+But if you're using the Mime component without the Symfony framework, you'll need
+to handle a few setup details.
+
+Twig Setup
+~~~~~~~~~~
+
+To integrate with Twig, use the :class:`Symfony\\Bridge\\Twig\\Mime\\BodyRenderer`
+class to render the template and update the email message contents with the results::
+
+    // ...
+    use Symfony\Bridge\Twig\Mime\BodyRenderer;
+    use Twig\Environment;
+    use Twig\Loader\FilesystemLoader;
+
+    // when using the Mime component inside a full-stack Symfony application, you
+    // don't need to do this Twig setup. You only have to inject the 'twig' service
+    $loader = new FilesystemLoader(__DIR__.'/templates');
+    $twig = new Environment($loader);
+
+    $renderer = new BodyRenderer($twig);
+    // this updates the $email object contents with the result of rendering
+    // the template defined earlier with the given context
+    $renderer->render($email);
+
+Inlining CSS Styles (and other Extensions)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the :ref:`inline_css <mailer-inline-css>` filter, first install the Twig
+extension:
+
+.. code-block:: terminal
+
+    $ composer require twig/cssinliner-extension
+
+Now, enable the extension::
+
+    // ...
+    use Twig\CssInliner\CssInlinerExtension;
+
+    $loader = new FilesystemLoader(__DIR__.'/templates');
+    $twig = new Environment($loader);
+    $twig->addExtension(new CssInlinerExtension());
+
+The same process should be used for enabling other extensions, like the
+:ref:`MarkdownExtension <mailer-markdown>` and :ref:`InkyExtension <mailer-inky>`.
+
+Creating Raw Email Messages
+---------------------------
+
+This is useful for advanced applications that need absolute control over every
+email part. It's not recommended for applications with regular email
+requirements because it adds complexity for no real gain.
+
+Before continuing, it's important to have a look at the low level structure of
+an email message. Consider a message which includes some content as both text
+and HTML, a single PNG image embedded in those contents and a PDF file attached
+to it. The MIME standard allows structuring this message in different ways, but
+the following tree is the one that works on most email clients:
+
+.. code-block:: text
+
+    multipart/mixed
+    ├── multipart/related
+    │   ├── multipart/alternative
+    │   │   ├── text/plain
+    │   │   └── text/html
+    │   └── image/png
+    └── application/pdf
+
+This is the purpose of each MIME message part:
+
+* ``multipart/alternative``: used when two or more parts are alternatives of the
+  same (or very similar) content. The preferred format must be added last.
+* ``multipart/mixed``: used to send different content types in the same message,
+  such as when attaching files.
+* ``multipart/related``: used to indicate that each message part is a component
+  of an aggregate whole. The most common usage is to display images embedded
+  in the message contents.
+
+When using the low-level :class:`Symfony\\Component\\Mime\\Message` class to
+create the email message, you must keep all the above in mind to define the
+different parts of the email by hand::
+
+    use Symfony\Component\Mime\Header\Headers;
+    use Symfony\Component\Mime\Message;
+    use Symfony\Component\Mime\Part\Multipart\AlternativePart;
+    use Symfony\Component\Mime\Part\TextPart;
+
+    $headers = (new Headers())
+        ->addMailboxListHeader('From', ['fabien@symfony.com'])
+        ->addMailboxListHeader('To', ['foo@example.com'])
+        ->addTextHeader('Subject', 'Important Notification')
+    ;
+
+    $textContent = new TextPart('Lorem ipsum...');
+    $htmlContent = new TextPart('<h1>Lorem ipsum</h1> <p>...</p>', 'html');
+    $body = new AlternativePart($textContent, $htmlContent);
+
+    $email = new Message($headers, $body);
+
+Embedding images and attaching files is possible by creating the appropriate
+email multiparts::
+
+    // ...
+    use Symfony\Component\Mime\Part\DataPart;
+    use Symfony\Component\Mime\Part\Multipart\MixedPart;
+    use Symfony\Component\Mime\Part\Multipart\RelatedPart;
+
+    // ...
+    $embeddedImage = new DataPart(fopen('/path/to/images/logo.png', 'r'), null, 'image/png');
+    $imageCid = $embeddedImage->getContentId();
+
+    $attachedFile = new DataPart(fopen('/path/to/documents/terms-of-use.pdf', 'r'), null, 'application/pdf');
+
+    $textContent = new TextPart('Lorem ipsum...');
+    $htmlContent = new TextPart(sprintf(
+        '<img src="cid:%s"/> <h1>Lorem ipsum</h1> <p>...</p>', $imageCid
+    ), 'html');
+    $bodyContent = new AlternativePart($textContent, $htmlContent);
+    $body = new RelatedPart($bodyContent, $embeddedImage);
+
+    $messageParts = new MixedPart($body, $attachedFile);
+
+    $email = new Message($headers, $messageParts);
+
+Serializing Email Messages
+--------------------------
+
+Email messages created with either the ``Email`` or ``Message`` classes can be
+serialized because they are simple data objects::
+
+    $email = (new Email())
+        ->from('fabien@symfony.com')
+        // ...
+    ;
+
+    $serializedEmail = serialize($email);
+
+A common use case is to store serialized email messages, include them in a
+message sent with the :doc:`Messenger component </components/messenger>` and
+recreate them later when sending them. Use the
+:class:`Symfony\\Component\\Mime\\RawMessage` class to recreate email messages
+from their serialized contents::
+
+    use Symfony\Component\Mime\RawMessage;
+
+    // ...
+    $serializedEmail = serialize($email);
+
+    // later, recreate the original message to actually send it
+    $message = new RawMessage(unserialize($serializedEmail));
+
+MIME Types Utilities
+--------------------
+
+Although MIME was designed mainly for creating emails, the content types (also
+known as `MIME types`_ and "media types") defined by MIME standards are also of
+importance in communication protocols outside of email, such as HTTP. That's
+why this component also provides utilities to work with MIME types.
+
+The :class:`Symfony\\Component\\Mime\\MimeTypes` class transforms between
+MIME types and file name extensions::
+
+    use Symfony\Component\Mime\MimeTypes;
+
+    $mimeTypes = new MimeTypes();
+    $exts = $mimeTypes->getExtensions('application/javascript');
+    // $exts = ['js', 'jsm', 'mjs']
+    $exts = $mimeTypes->getExtensions('image/jpeg');
+    // $exts = ['jpeg', 'jpg', 'jpe']
+
+    $mimeTypes = $mimeTypes->getMimeTypes('js');
+    // $mimeTypes = ['application/javascript', 'application/x-javascript', 'text/javascript']
+    $mimeTypes = $mimeTypes->getMimeTypes('apk');
+    // $mimeTypes = ['application/vnd.android.package-archive']
+
+These methods return arrays with one or more elements. The element position
+indicates its priority, so the first returned extension is the preferred one.
+
+.. _components-mime-type-guess:
+
+Guessing the MIME Type
+~~~~~~~~~~~~~~~~~~~~~~
+
+Another useful utility allows to guess the MIME type of any given file::
+
+    use Symfony\Component\Mime\MimeTypes;
+
+    $mimeTypes = new MimeTypes();
+    $mimeType = $mimeTypes->guessMimeType('/some/path/to/image.gif');
+    // Guessing is not based on the file name, so $mimeType will be 'image/gif'
+    // only if the given file is truly a GIF image
+
+Guessing the MIME type is a time-consuming process that requires inspecting
+part of the file contents. Symfony applies multiple guessing mechanisms, one
+of them based on the PHP `fileinfo extension`_. It's recommended to install
+that extension to improve the guessing performance.
+
+Adding a MIME Type Guesser
+..........................
+
+You can register your own MIME type guesser by creating a class that implements
+:class:`Symfony\\Component\\Mime\\MimeTypeGuesserInterface`::
+
+    namespace App;
+
+    use Symfony\Component\Mime\MimeTypeGuesserInterface;
+
+    class SomeMimeTypeGuesser implements MimeTypeGuesserInterface
+    {
+        public function isGuesserSupported(): bool
+        {
+            // return true when the guesser is supported (might depend on the OS for instance)
+            return true;
+        }
+
+        public function guessMimeType(string $path): ?string
+        {
+            // inspect the contents of the file stored in $path to guess its
+            // type and return a valid MIME type ... or null if unknown
+
+            return '...';
+        }
+    }
+
+.. _`MIME`: https://en.wikipedia.org/wiki/MIME
+.. _`MIME types`: https://en.wikipedia.org/wiki/Media_type
+.. _`fileinfo extension`: https://php.net/fileinfo
diff --git a/components/options_resolver.rst b/components/options_resolver.rst
index bcebfcf5fe7..4c2ef3c1254 100644
--- a/components/options_resolver.rst
+++ b/components/options_resolver.rst
@@ -5,9 +5,10 @@
 The OptionsResolver Component
 =============================
 
-    The OptionsResolver component is :phpfunction:`array_replace` on steroids.
-    It allows you to create an options system with required options, defaults,
-    validation (type, value), normalization and more.
+    The OptionsResolver component is an improved replacement for the
+    :phpfunction:`array_replace` PHP function. It allows you to create an
+    options system with required options, defaults, validation (type, value),
+    normalization and more.
 
 Installation
 ------------
@@ -16,8 +17,6 @@ Installation
 
     $ composer require symfony/options-resolver
 
-Alternatively, you can clone the `<https://github.com/symfony/options-resolver>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -36,7 +35,7 @@ Imagine you have a ``Mailer`` class which has four options: ``host``,
         }
     }
 
-When accessing the ``$options``, you need to add a lot of boilerplate code to
+When accessing the ``$options``, you need to add some boilerplate code to
 check which options are set::
 
     class Mailer
@@ -46,29 +45,17 @@ check which options are set::
         {
             $mail = ...;
 
-            $mail->setHost(isset($this->options['host'])
-                ? $this->options['host']
-                : 'smtp.example.org');
-
-            $mail->setUsername(isset($this->options['username'])
-                ? $this->options['username']
-                : 'user');
-
-            $mail->setPassword(isset($this->options['password'])
-                ? $this->options['password']
-                : 'pa$$word');
-
-            $mail->setPort(isset($this->options['port'])
-                ? $this->options['port']
-                : 25);
+            $mail->setHost($this->options['host'] ?? 'smtp.example.org');
+            $mail->setUsername($this->options['username'] ?? 'user');
+            $mail->setPassword($this->options['password'] ?? 'pa$$word');
+            $mail->setPort($this->options['port'] ?? 25);
 
             // ...
         }
     }
 
-This boilerplate is hard to read and repetitive. Also, the default values of the
-options are buried in the business logic of your code. Use the
-:phpfunction:`array_replace` to fix that::
+Also, the default values of the options are buried in the business logic of your
+code. Use the :phpfunction:`array_replace` to fix that::
 
     class Mailer
     {
@@ -85,13 +72,11 @@ options are buried in the business logic of your code. Use the
         }
     }
 
-Now all four options are guaranteed to be set. But what happens if the user of
-the ``Mailer`` class makes a mistake?
-
-.. code-block:: php
+Now all four options are guaranteed to be set, but you could still make an error
+like the following when using the ``Mailer`` class::
 
     $mailer = new Mailer([
-        'usernme' => 'johndoe',  // usernme misspelled (instead of username)
+        'usernme' => 'johndoe',  // 'username' is wrongly spelled as 'usernme'
     ]);
 
 No error will be shown. In the best case, the bug will appear during testing,
@@ -449,6 +434,16 @@ if you need to use other options during normalization::
         }
     }
 
+To normalize a new allowed value in sub-classes that are being normalized
+in parent classes use :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addNormalizer`.
+This way, the ``$value`` argument will receive the previously normalized
+value, otherwise you can prepend the new normalizer by passing ``true`` as
+third argument.
+
+.. versionadded:: 4.3
+
+    The ``addNormalizer()`` method was introduced in Symfony 4.3.
+
 Default Values that Depend on another Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -534,8 +529,8 @@ Options without Default Values
 In some cases, it is useful to define an option without setting a default value.
 This is useful if you need to know whether or not the user *actually* set
 an option or not. For example, if you set the default value for an option,
-it's not possible to know whether the user passed this value or if it simply
-comes from the default::
+it's not possible to know whether the user passed this value or if it comes
+from the default::
 
     // ...
     class Mailer
@@ -634,6 +629,159 @@ let you find out which options are defined::
         }
     }
 
+Nested Options
+~~~~~~~~~~~~~~
+
+Suppose you have an option named ``spool`` which has two sub-options ``type``
+and ``path``. Instead of defining it as a simple array of values, you can pass a
+closure as the default value of the ``spool`` option with a
+:class:`Symfony\\Component\\OptionsResolver\\OptionsResolver` argument. Based on
+this instance, you can define the options under ``spool`` and its desired
+default value::
+
+    class Mailer
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefault('spool', function (OptionsResolver $spoolResolver) {
+                $spoolResolver->setDefaults([
+                    'type' => 'file',
+                    'path' => '/path/to/spool',
+                ]);
+                $spoolResolver->setAllowedValues('type', ['file', 'memory']);
+                $spoolResolver->setAllowedTypes('path', 'string');
+            });
+        }
+
+        public function sendMail($from, $to)
+        {
+            if ('memory' === $this->options['spool']['type']) {
+                // ...
+            }
+        }
+    }
+
+    $mailer = new Mailer([
+        'spool' => [
+            'type' => 'memory',
+        ],
+    ]);
+
+Nested options also support required options, validation (type, value) and
+normalization of their values. If the default value of a nested option depends
+on another option defined in the parent level, add a second ``Options`` argument
+to the closure to access to them::
+
+    class Mailer
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefault('sandbox', false);
+            $resolver->setDefault('spool', function (OptionsResolver $spoolResolver, Options $parent) {
+                $spoolResolver->setDefaults([
+                    'type' => $parent['sandbox'] ? 'memory' : 'file',
+                    // ...
+                ]);
+            });
+        }
+    }
+
+.. caution::
+
+    The arguments of the closure must be type hinted as ``OptionsResolver`` and
+    ``Options`` respectively. Otherwise, the closure itself is considered as the
+    default value of the option.
+
+In same way, parent options can access to the nested options as normal arrays::
+
+    class Mailer
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefault('spool', function (OptionsResolver $spoolResolver) {
+                $spoolResolver->setDefaults([
+                    'type' => 'file',
+                    // ...
+                ]);
+            });
+            $resolver->setDefault('profiling', function (Options $options) {
+                return 'file' === $options['spool']['type'];
+            });
+        }
+    }
+
+.. note::
+
+    The fact that an option is defined as nested means that you must pass
+    an array of values to resolve it at runtime.
+
+Deprecating the Option
+~~~~~~~~~~~~~~~~~~~~~~
+
+Once an option is outdated or you decided not to maintain it anymore, you can
+deprecate it using the :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDeprecated`
+method::
+
+    $resolver
+        ->setDefined(['hostname', 'host'])
+        // this outputs the following generic deprecation message:
+        // The option "hostname" is deprecated.
+        ->setDeprecated('hostname')
+
+        // you can also pass a custom deprecation message
+        ->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.')
+    ;
+
+.. note::
+
+    The deprecation message will be triggered only if the option is being used
+    somewhere, either its value is provided by the user or the option is evaluated
+    within closures of lazy options and normalizers.
+
+.. note::
+
+    When using an option deprecated by you in your own library, you can pass
+    ``false`` as the second argument of the
+    :method:`Symfony\\Component\\OptionsResolver\\Options::offsetGet()` method
+    to not trigger the deprecation warning.
+
+Instead of passing the message, you may also pass a closure which returns
+a string (the deprecation message) or an empty string to ignore the deprecation.
+This closure is useful to only deprecate some of the allowed types or values of
+the option::
+
+    $resolver
+        ->setDefault('encryption', null)
+        ->setDefault('port', null)
+        ->setAllowedTypes('port', ['null', 'int'])
+        ->setDeprecated('port', function (Options $options, $value) {
+            if (null === $value) {
+                return 'Passing "null" to option "port" is deprecated, pass an integer instead.';
+            }
+
+            // deprecation may also depend on another option
+            if ('ssl' === $options['encryption'] && 456 !== $value) {
+                return 'Passing a different port than "456" when the "encryption" option is set to "ssl" is deprecated.';
+            }
+
+            return '';
+        })
+    ;
+
+.. note::
+
+    Deprecation based on the value is triggered only when the option is provided
+    by the user.
+
+This closure receives as argument the value of the option after validating it
+and before normalizing it when the option is being resolved.
+
 Performance Tweaks
 ~~~~~~~~~~~~~~~~~~
 
@@ -691,6 +839,3 @@ method ``clearOptionsConfig()`` and call it periodically::
 
 That's it! You now have all the tools and knowledge needed to process
 options in your code.
-
-.. _Packagist: https://packagist.org/packages/symfony/options-resolver
-.. _CHANGELOG: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/OptionsResolver/CHANGELOG.md#260
diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst
index 9a55e5e936f..cf1a19727fd 100644
--- a/components/phpunit_bridge.rst
+++ b/components/phpunit_bridge.rst
@@ -6,11 +6,13 @@ The PHPUnit Bridge
 ==================
 
     The PHPUnit Bridge provides utilities to report legacy tests and usage of
-    deprecated code and a helper for time-sensitive tests.
+    deprecated code and helpers for mocking native functions related to time,
+    DNS and class existence.
 
 It comes with the following features:
 
-* Forces the tests to use a consistent locale (``C``);
+* Forces the tests to use a consistent locale (``C``) (if you create
+  locale-sensitive tests, use PHPUnit's ``setLocale()`` method);
 
 * Auto-register ``class_exists`` to load Doctrine annotations (when used);
 
@@ -18,19 +20,20 @@ It comes with the following features:
 
 * Displays the stack trace of a deprecation on-demand;
 
-* Provides a ``ClockMock`` and ``DnsMock`` helper classes for time or network-sensitive tests.
+* Provides a ``ClockMock``, ``DnsMock`` and ``ClassExistsMock`` classes for tests
+  sensitive to time, network or class existence;
 
-* Provides a modified version of PHPUnit that does not embed ``symfony/yaml`` nor
-  ``prophecy`` to prevent any conflicts with these dependencies.
+* Provides a modified version of PHPUnit that allows 1. separating the
+  dependencies of your app from those of phpunit to prevent any unwanted
+  constraints to apply; 2. running tests in parallel when a test suite is split
+  in several phpunit.xml files; 3. recording and replaying skipped tests;
 
 Installation
 ------------
 
 .. code-block:: terminal
 
-    $ composer require --dev "symfony/phpunit-bridge:*"
-
-Alternatively, you can clone the `<https://github.com/symfony/phpunit-bridge>`_ repository.
+    $ composer require --dev symfony/phpunit-bridge
 
 .. include:: /components/require_autoload.rst.inc
 
@@ -49,13 +52,13 @@ to register a new `test listener`_ called ``SymfonyTestsListener``:
 
     <!-- http://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
     <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-             xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/6.0/phpunit.xsd"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
     >
 
         <!-- ... -->
 
         <listeners>
-            <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+            <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
         </listeners>
     </phpunit>
 
@@ -122,9 +125,35 @@ The summary includes:
         <!-- phpunit.xml.dist -->
         <!-- ... -->
         <listeners>
-            <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+            <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
         </listeners>
 
+Running Tests in Parallel
+-------------------------
+
+The modified PHPUnit script allows running tests in parallel by providing
+a directory containing multiple test suites with their own ``phpunit.xml.dist``.
+
+.. code-block:: terminal
+
+    ├── tests/
+    │   ├── Functional/
+    │   │   ├── ...
+    │   │   └── phpunit.xml.dist
+    │   ├── Unit/
+    │   │   ├── ...
+    │   │   └── phpunit.xml.dist
+
+.. code-block:: terminal
+
+    $ ./vendor/bin/simple-phpunit tests/
+
+The modified PHPUnit script will recursively go through the provided directory,
+up to a depth of 3 subfolders or the value specified by the environment variable
+``SYMFONY_PHPUNIT_MAX_DEPTH``, looking for ``phpunit.xml.dist`` files and then
+running each suite it finds in parallel, collecting their output and displaying
+each test suite's results in their own section.
+
 Trigger Deprecation Notices
 ---------------------------
 
@@ -173,59 +202,133 @@ message, enclosed with ``/``. For example, with:
 
     <!-- http://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
     <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-             xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/6.0/phpunit.xsd"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
     >
 
         <!-- ... -->
 
         <php>
-            <server name="KERNEL_CLASS" value="App\Kernel" />
-            <env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/" />
+            <server name="KERNEL_CLASS" value="App\Kernel"/>
+            <env name="SYMFONY_DEPRECATIONS_HELPER" value="regex=/foobar/"/>
         </php>
     </phpunit>
 
-PHPUnit_ will stop your test suite once a deprecation notice is triggered whose
+`PHPUnit`_ will stop your test suite once a deprecation notice is triggered whose
 message contains the ``"foobar"`` string.
 
 Making Tests Fail
 ~~~~~~~~~~~~~~~~~
 
-By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation notices
-will make tests fail. Alternatively, setting ``SYMFONY_DEPRECATIONS_HELPER`` to
-an arbitrary value (ex: ``320``) will make the tests fails only if a higher
-number of deprecation notices is reached (``0`` is the default value). You can
-also set the value ``"weak"`` which will make the bridge ignore any deprecation
-notices. This is useful to projects that must use deprecated interfaces for
-backward compatibility reasons.
+By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation
+notices will make tests fail. Alternatively, you can configure an
+arbitrary threshold by setting ``SYMFONY_DEPRECATIONS_HELPER`` to
+``max[total]=320`` for instance. It will make the tests fails only if a
+higher number of deprecation notices is reached (``0`` is the default
+value).
+
+You can have even finer-grained control by using other keys of the ``max``
+array, which are ``self``, ``direct``, and ``indirect``. The
+``SYMFONY_DEPRECATIONS_HELPER`` environment variable accepts an URL-encoded
+string, meaning you can combine thresholds and any other configuration setting,
+like this: ``SYMFONY_DEPRECATIONS_HELPER=max[total]=42&max[self]=0&verbose=0``
+
+Internal deprecations
+.....................
 
 When you maintain a library, having the test suite fail as soon as a dependency
 introduces a new deprecation is not desirable, because it shifts the burden of
-fixing that deprecation to any contributor that happens to submit a pull
-request shortly after a new vendor release is made with that deprecation. To
-mitigate this, you can either use tighter requirements, in the hope that
+fixing that deprecation to any contributor that happens to submit a pull request
+shortly after a new vendor release is made with that deprecation.
+
+To mitigate this, you can either use tighter requirements, in the hope that
 dependencies will not introduce deprecations in a patch version, or even commit
-the Composer lock file, which would create another class of issues. Libraries
-will often use ``SYMFONY_DEPRECATIONS_HELPER=weak`` because of this. This has
-the drawback of allowing contributions that introduce deprecations but:
+the ``composer.lock`` file, which would create another class of issues.
+Libraries will often use ``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999``
+because of this. This has the drawback of allowing contributions that introduce
+deprecations but:
 
 * forget to fix the deprecated calls if there are any;
 * forget to mark appropriate tests with the ``@group legacy`` annotations.
 
-By using the ``"weak_vendors"`` value, deprecations that are triggered outside
-the ``vendors`` directory will make the test suite fail, while deprecations
-triggered from a library inside it will not, giving you the best of both
-worlds.
+By using ``SYMFONY_DEPRECATIONS_HELPER=max[self]=0``, deprecations that are
+triggered outside the ``vendors`` directory will be accounted for seperately,
+while deprecations triggered from a library inside it will not (unless you reach
+999999 of these), giving you the best of both worlds.
+
+Direct and Indirect Deprecations
+................................
+
+When working on a project, you might be more interested in ``max[direct]``.
+Let's say you want to fix deprecations as soon as they appear. A problem many
+developers experience is that some dependencies they have tend to lag behind
+their own dependencies, meaning they do not fix deprecations as soon as
+possible, which means you should create a pull request on the outdated vendor,
+and ignore these deprecations until your pull request is merged.
+
+The ``max[direct]`` config allows you to put a threshold on direct deprecations
+only, allowing you to notice when *your code* is using deprecated APIs, and to
+keep up with the changes. You can still use ``max[indirect]`` if you want to
+keep indirect deprecations under a given threshold.
+
+Here is a summary that should help you pick the right configuration:
+
++------------------------+-----------------------------------------------------+
+| Value                  | Recommended situation                               |
++========================+=====================================================+
+| max[total]=0           | Recommended for actively maintained projects        |
+|                        | with robust/no dependencies                         |
++------------------------+-----------------------------------------------------+
+| max[direct]=0          | Recommended for projects with dependencies          |
+|                        | that fail to keep up with new deprecations.         |
++------------------------+-----------------------------------------------------+
+| max[self]=0            | Recommended for libraries that use                  |
+|                        | the deprecation system themselves and               |
+|                        | cannot afford to use one of the modes above.        |
++------------------------+-----------------------------------------------------+
+
+Disabling the Verbose Output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the bridge will display a detailed output with the number of
+deprecations and where they arise. If this is too much for you, you can use
+``SYMFONY_DEPRECATIONS_HELPER=verbose=0`` to turn the verbose output off.
 
 Disabling the Deprecation Helper
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to ``disabled`` to
-completely disable the deprecation helper. This is useful to make use of the
+Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to ``disabled=1``
+to completely disable the deprecation helper. This is useful to make use of the
 rest of features provided by this component without getting errors or messages
 related to deprecations.
 
 .. _write-assertions-about-deprecations:
 
+Deprecation Notices at Autoloading Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the PHPUnit Bridge uses ``DebugClassLoader`` from the
+:doc:`Debug component </components/debug>` to throw deprecation notices at
+class autoloading time. This can be disabled with the ``debug-class-loader`` option.
+
+.. code-block:: xml
+
+    <!-- phpunit.xml.dist -->
+    <!-- ... -->
+    <listeners>
+        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
+            <arguments>
+                <array>
+                    <!-- set this option to 0 to disable the DebugClassLoader integration -->
+                    <element key="debug-class-loader"><integer>0</integer></element>
+                </array>
+            </arguments>
+        </listener>
+    </listeners>
+
+.. versionadded:: 4.2
+
+    The ``DebugClassLoader`` integration was introduced in Symfony 4.2.
+
 Write Assertions about Deprecations
 -----------------------------------
 
@@ -255,7 +358,9 @@ By default, the PHPUnit Bridge displays only deprecation messages.
 To show the full stack trace related to a deprecation, set the value of ``SYMFONY_DEPRECATIONS_HELPER``
 to a regular expression matching the deprecation message.
 
-For example, if the following deprecation notice is thrown::
+For example, if the following deprecation notice is thrown:
+
+.. code-block:: bash
 
     1x: Doctrine\Common\ClassLoader is deprecated.
       1x in EntityTypeTest::setUp from Symfony\Bridge\Doctrine\Tests\Form\Type
@@ -305,7 +410,10 @@ Clock Mocking
 
 The :class:`Symfony\\Bridge\\PhpUnit\\ClockMock` class provided by this bridge
 allows you to mock the PHP's built-in time functions ``time()``,
-``microtime()``, ``sleep()`` and ``usleep()``.
+``microtime()``, ``sleep()``, ``usleep()`` and ``gmdate()``. Additionally the function
+``date()`` is mocked so it uses the mocked time if no timestamp is specified.
+Other functions with an optional timestamp parameter that defaults to ``time()``
+will still use the system time instead of the mocked time.
 
 To use the ``ClockMock`` class in your test, add the ``@group time-sensitive``
 annotation to its class or methods. This annotation only works when executing
@@ -317,7 +425,7 @@ following listener in your PHPUnit configuration:
     <!-- phpunit.xml.dist -->
     <!-- ... -->
     <listeners>
-        <listener class="\Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+        <listener class="\Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
     </listeners>
 
 .. note::
@@ -377,6 +485,7 @@ different class, do it explicitly using ``ClockMock::register(MyClass::class)``:
 
     use App\MyClass;
     use PHPUnit\Framework\TestCase;
+    use Symfony\Bridge\PhpUnit\ClockMock;
 
     /**
      * @group time-sensitive
@@ -438,6 +547,7 @@ constraint to test the validity of the email domain::
             $result = $validator->validate('foo@example.com', $constraint);
 
             // ...
+        }
     }
 
 In order to avoid making a real network connection, add the ``@dns-sensitive``
@@ -462,6 +572,7 @@ the data you expect to get for the given hosts::
             $result = $validator->validate('foo@example.com', $constraint);
 
             // ...
+        }
     }
 
 The ``withMockedHosts()`` method configuration is defined as an array. The keys
@@ -482,6 +593,78 @@ conditions::
         ],
     ]);
 
+Class Existence Based Tests
+---------------------------
+
+Tests that behave differently depending on existing classes, for example Composer's
+development dependencies, are often hard to test for the alternate case. For that
+reason, this component also provides mocks for these PHP functions:
+
+* :phpfunction:`class_exists`
+* :phpfunction:`interface_exists`
+* :phpfunction:`trait_exists`
+
+Use Case
+~~~~~~~~
+
+Consider the following example that relies on the ``Vendor\DependencyClass`` to
+toggle a behavior::
+
+    use Vendor\DependencyClass;
+
+    class MyClass
+    {
+        public function hello(): string
+        {
+            if (class_exists(DependencyClass::class)) {
+                return 'The dependency bahavior.';
+            }
+
+            return 'The default behavior.';
+        }
+    }
+
+A regular test case for ``MyClass`` (assuming the development dependencies
+are installed during tests) would look like::
+
+    use MyClass;
+    use PHPUnit\Framework\TestCase;
+
+    class MyClassTest extends TestCase
+    {
+        public function testHello()
+        {
+            $class = new MyClass();
+            $result = $class->hello(); // "The dependency bahavior."
+
+            // ...
+        }
+    }
+
+In order to test the default behavior instead use the
+``ClassExistsMock::withMockedClasses()`` to configure the expected
+classes, interfaces and/or traits for the code to run::
+
+    use MyClass;
+    use PHPUnit\Framework\TestCase;
+    use Vendor\DependencyClass;
+
+    class MyClassTest extends TestCase
+    {
+        // ...
+
+        public function testHelloDefault()
+        {
+            ClassExistsMock::register(MyClass::class);
+            ClassExistsMock::withMockedClasses([DependencyClass::class => false]);
+
+            $class = new MyClass();
+            $result = $class->hello(); // "The default bahavior."
+
+            // ...
+        }
+    }
+
 Troubleshooting
 ---------------
 
@@ -500,7 +683,7 @@ namespaces in the ``phpunit.xml`` file, as done for example in the
 
     <!-- http://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
     <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-             xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.1/phpunit.xsd"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/4.1/phpunit.xsd"
     >
 
         <!-- ... -->
@@ -543,8 +726,8 @@ Modified PHPUnit script
 This bridge provides a modified version of PHPUnit that you can call by using
 its ``bin/simple-phpunit`` command. It has the following features:
 
-* Does not embed ``symfony/yaml`` nor ``prophecy`` to prevent any conflicts with
-  these dependencies;
+* Works with a standalone vendor directory that doesn't conflict with yours;
+* Does not embed ``prophecy`` to prevent any conflicts with its dependencies;
 * Uses PHPUnit 4.8 when run with PHP <=5.5, PHPUnit 5.7 when run with PHP >=5.6
   and PHPUnit 6.5 when run with PHP >=7.2;
 * Collects and replays skipped tests when the ``SYMFONY_PHPUNIT_SKIPPED_TESTS``
@@ -562,16 +745,19 @@ It's also possible to set this env var in the ``phpunit.xml.dist`` file.
 
 If you have installed the bridge through Composer, you can run it by calling e.g.:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     $ vendor/bin/simple-phpunit
 
 .. tip::
 
-    Set the ``SYMFONY_PHPUNIT_VERSION`` env var to e.g. ``5.5`` to change the
-    base version of PHPUnit to ``5.5`` instead of the default ``5.3``.
+    It's possible to change the base version of PHPUnit by setting the
+    ``SYMFONY_PHPUNIT_VERSION`` env var in the ``phpunit.xml.dist`` file (e.g.
+    ``<server name="SYMFONY_PHPUNIT_VERSION" value="5.5"/>``). This is the
+    preferred method as it can be committed to your version control repository.
 
-    It's also possible to set this env var in the ``phpunit.xml.dist`` file.
+    It's also possible to set ``SYMFONY_PHPUNIT_VERSION`` as a real env var
+    (not defined in a :ref:`dotenv file <config-dot-env>`).
 
 .. tip::
 
@@ -580,11 +766,11 @@ If you have installed the bridge through Composer, you can run it by calling e.g
 
     It's also possible to set this env var in the ``phpunit.xml.dist`` file.
 
-Code coverage listener
+Code Coverage Listener
 ----------------------
 
 By default, the code coverage is computed with the following rule: if a line of
-code is executed, then it is marked as covered. And the test which executes a
+code is executed, then it is marked as covered. The test which executes a
 line of code is therefore marked as "covering the line of code". This can be
 misleading.
 
@@ -639,19 +825,19 @@ the ``Test`` part of the classname: ``My\Namespace\Tests\FooTest`` ->
 Installation
 ~~~~~~~~~~~~
 
-Add the following configuration to the ``phpunit.xml.dist`` file
+Add the following configuration to the ``phpunit.xml.dist`` file:
 
 .. code-block:: xml
 
     <!-- http://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
     <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-             xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/6.0/phpunit.xsd"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
     >
 
         <!-- ... -->
 
         <listeners>
-            <listener class="Symfony\Bridge\PhpUnit\CoverageListener" />
+            <listener class="Symfony\Bridge\PhpUnit\CoverageListener"/>
         </listeners>
     </phpunit>
 
@@ -685,12 +871,11 @@ not find the SUT:
         </listener>
     </listeners>
 
-.. _PHPUnit: https://phpunit.de
+.. _`PHPUnit`: https://phpunit.de
 .. _`PHPUnit event listener`: https://phpunit.de/manual/current/en/extending-phpunit.html#extending-phpunit.PHPUnit_Framework_TestListener
 .. _`PHPUnit's assertStringMatchesFormat()`: https://phpunit.de/manual/current/en/appendixes.assertions.html#appendixes.assertions.assertStringMatchesFormat
 .. _`PHP error handler`: https://php.net/manual/en/book.errorfunc.php
 .. _`environment variable`: https://phpunit.de/manual/current/en/appendixes.configuration.html#appendixes.configuration.php-ini-constants-variables
-.. _Packagist: https://packagist.org/packages/symfony/phpunit-bridge
 .. _`@-silencing operator`: https://php.net/manual/en/language.operators.errorcontrol.php
 .. _`@-silenced`: https://php.net/manual/en/language.operators.errorcontrol.php
 .. _`Travis CI`: https://travis-ci.org/
diff --git a/components/polyfill_apcu.rst b/components/polyfill_apcu.rst
index b3b60e95566..80f7aeef809 100644
--- a/components/polyfill_apcu.rst
+++ b/components/polyfill_apcu.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-apcu
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-apcu>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_ctype.rst b/components/polyfill_ctype.rst
index c77af0bc874..f685a8563a2 100644
--- a/components/polyfill_ctype.rst
+++ b/components/polyfill_ctype.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-ctype
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-ctype>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_iconv.rst b/components/polyfill_iconv.rst
index 56346186c60..e50b926e6bd 100644
--- a/components/polyfill_iconv.rst
+++ b/components/polyfill_iconv.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-iconv
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-iconv>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -57,5 +55,3 @@ extension are installed:
 * :phpfunction:`iconv_mime_decode`
 
 .. _`PHP iconv extension`: https://secure.php.net/manual/en/book.iconv.php
-.. _`mbstring`: https://secure.php.net/manual/en/book.mbstring.php
-.. _`xml`: https://secure.php.net/manual/en/book.xml.php
diff --git a/components/polyfill_intl_grapheme.rst b/components/polyfill_intl_grapheme.rst
index bad42f179fc..cb5b020c59b 100644
--- a/components/polyfill_intl_grapheme.rst
+++ b/components/polyfill_intl_grapheme.rst
@@ -17,8 +17,6 @@ Installation
 
     $ composer require symfony/polyfill-intl-grapheme
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-intl-grapheme>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -50,9 +48,11 @@ Provided Functions
 
 .. seealso::
 
-    The :doc:`polyfill-intl-icu </components/polyfill_intl_icu>` and
-    :doc:`polyfill-intl-normalizer </components/polyfill_intl_normalizer>`
-    components provide polyfills for other classes and functions related to the
-    Intl PHP extension.
+    Symfony provides more polyfills for other classes and functions related to
+    the Intl PHP extension:
+    :doc:`polyfill-intl-icu </components/polyfill_intl_icu>`,
+    :doc:`polyfill-intl-idn </components/polyfill_intl_idn>`,
+    :doc:`polyfill-intl-messageformatter </components/polyfill_intl_messageformatter>`,
+    and :doc:`polyfill-intl-normalizer </components/polyfill_intl_normalizer>`.
 
 .. _`PHP intl extension`: https://secure.php.net/manual/en/book.intl.php
diff --git a/components/polyfill_intl_icu.rst b/components/polyfill_intl_icu.rst
index 4dc7c503afc..a00fb7ed35c 100644
--- a/components/polyfill_intl_icu.rst
+++ b/components/polyfill_intl_icu.rst
@@ -17,8 +17,6 @@ Installation
 
     $ composer require symfony/polyfill-intl-icu
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-intl-icu>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -46,9 +44,11 @@ Provided Functions
 
 .. seealso::
 
-    The :doc:`polyfill-intl-grapheme </components/polyfill_intl_grapheme>` and
-    :doc:`polyfill-intl-normalizer </components/polyfill_intl_normalizer>`
-    components provide polyfills for other classes and functions related to the
-    Intl PHP extension.
+    Symfony provides more polyfills for other classes and functions related to
+    the Intl PHP extension:
+    :doc:`polyfill-intl-grapheme </components/polyfill_intl_grapheme>`,
+    :doc:`polyfill-intl-idn </components/polyfill_intl_idn>`,
+    :doc:`polyfill-intl-messageformatter </components/polyfill_intl_messageformatter>`,
+    and :doc:`polyfill-intl-normalizer </components/polyfill_intl_normalizer>`.
 
 .. _`PHP intl extension`: https://secure.php.net/manual/en/book.intl.php
diff --git a/components/polyfill_intl_idn.rst b/components/polyfill_intl_idn.rst
new file mode 100644
index 00000000000..9314f0af35b
--- /dev/null
+++ b/components/polyfill_intl_idn.rst
@@ -0,0 +1,43 @@
+.. index::
+    single: Polyfill
+    single: IDN
+    single: Components; Polyfill
+
+The Symfony Polyfill / Intl IDN Component
+=========================================
+
+    This component provides a collection of functions related to IDN when the
+    Intl extension is not installed.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/polyfill-intl-idn
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+Once this component is installed in your application, you can use the following
+functions, no matter if the `PHP intl extension`_ is installed or not in your
+server.
+
+Provided Functions
+~~~~~~~~~~~~~~~~~~
+
+* :phpfunction:`idn_to_ascii`
+* :phpfunction:`idn_to_utf8`
+
+.. seealso::
+
+    Symfony provides more polyfills for other classes and functions related to
+    the Intl PHP extension:
+    :doc:`polyfill-intl-grapheme </components/polyfill_intl_grapheme>`,
+    :doc:`polyfill-intl-icu </components/polyfill_intl_icu>`,
+    :doc:`polyfill-intl-messageformatter </components/polyfill_intl_messageformatter>`,
+    and :doc:`polyfill-intl-normalizer </components/polyfill_intl_normalizer>`.
+
+.. _`PHP intl extension`: https://secure.php.net/manual/en/book.intl.php
diff --git a/components/polyfill_intl_messageformatter.rst b/components/polyfill_intl_messageformatter.rst
new file mode 100644
index 00000000000..b07533d1e16
--- /dev/null
+++ b/components/polyfill_intl_messageformatter.rst
@@ -0,0 +1,48 @@
+.. index::
+    single: Polyfill
+    single: MessageFormatter
+    single: Components; Polyfill
+
+The Symfony Polyfill / Intl MessageFormatter Component
+======================================================
+
+    This component provides a fallback implementation for the ``MessageFormatter``
+    class to users who run PHP versions without the ``intl`` extension.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/polyfill-intl-messageformatter
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+Once this component is installed in your application, you can use the following
+classes and functions, no matter if the `PHP intl extension`_ is installed or
+not in your server.
+
+Provided Classes
+~~~~~~~~~~~~~~~~
+
+* :phpclass:`IntlException`
+* :phpclass:`MessageFormatter`
+
+Provided Functions
+~~~~~~~~~~~~~~~~~~
+
+* :phpfunction:`msgfmt_format_message`
+
+.. seealso::
+
+    Symfony provides more polyfills for other classes and functions related to
+    the Intl PHP extension:
+    :doc:`polyfill-intl-grapheme </components/polyfill_intl_grapheme>`,
+    :doc:`polyfill-intl-idn </components/polyfill_intl_idn>`,
+    :doc:`polyfill-intl-icu </components/polyfill_intl_icu>`,
+    and :doc:`polyfill-intl-normalizer </components/polyfill_intl_normalizer>`.
+
+.. _`PHP intl extension`: https://secure.php.net/manual/en/book.intl.php
diff --git a/components/polyfill_intl_normalizer.rst b/components/polyfill_intl_normalizer.rst
index 4604f29a259..a9c4ae01a32 100644
--- a/components/polyfill_intl_normalizer.rst
+++ b/components/polyfill_intl_normalizer.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-intl-normalizer
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-intl-normalizer>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -40,8 +38,11 @@ Provided Functions
 
 .. seealso::
 
-    The :doc:`polyfill-intl-grapheme </components/polyfill_intl_grapheme>` and
-    :doc:`polyfill-intl-icu </components/polyfill_intl_icu>` components provide
-    polyfills for other classes and functions related to the Intl PHP extension.
+    Symfony provides more polyfills for other classes and functions related to
+    the Intl PHP extension:
+    :doc:`polyfill-intl-grapheme </components/polyfill_intl_grapheme>`,
+    :doc:`polyfill-intl-idn </components/polyfill_intl_idn>`,
+    :doc:`polyfill-intl-icu </components/polyfill_intl_icu>`,
+    and :doc:`polyfill-intl-messageformatter </components/polyfill_intl_messageformatter>`.
 
 .. _`PHP intl extension`: https://secure.php.net/manual/en/book.intl.php
diff --git a/components/polyfill_mbstring.rst b/components/polyfill_mbstring.rst
index 934301bf432..322f1e338fc 100644
--- a/components/polyfill_mbstring.rst
+++ b/components/polyfill_mbstring.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-mbstring
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-mbstring>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php54.rst b/components/polyfill_php54.rst
index e32a00f6f62..7c2019a0dba 100644
--- a/components/polyfill_php54.rst
+++ b/components/polyfill_php54.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php54
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php54>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php55.rst b/components/polyfill_php55.rst
index 9ac1577dea1..99650499763 100644
--- a/components/polyfill_php55.rst
+++ b/components/polyfill_php55.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php55
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php55>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php56.rst b/components/polyfill_php56.rst
index 44b8f69598b..c68e8d46fd8 100644
--- a/components/polyfill_php56.rst
+++ b/components/polyfill_php56.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php56
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php56>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php70.rst b/components/polyfill_php70.rst
index e95ada92dcc..2169173faf0 100644
--- a/components/polyfill_php70.rst
+++ b/components/polyfill_php70.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php70
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php70>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php71.rst b/components/polyfill_php71.rst
index 6e7f116403e..1cec61b4fa6 100644
--- a/components/polyfill_php71.rst
+++ b/components/polyfill_php71.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php71
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php71>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php72.rst b/components/polyfill_php72.rst
index b3c6c86198e..1a0d0bf87ca 100644
--- a/components/polyfill_php72.rst
+++ b/components/polyfill_php72.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php72
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php72>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/polyfill_php73.rst b/components/polyfill_php73.rst
index 5f1dac15414..be04e57cb63 100644
--- a/components/polyfill_php73.rst
+++ b/components/polyfill_php73.rst
@@ -16,8 +16,6 @@ Installation
 
     $ composer require symfony/polyfill-php73
 
-Alternatively, you can clone the `<https://github.com/symfony/polyfill-php73>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
diff --git a/components/process.rst b/components/process.rst
index 9674e1af96a..7aecb26302d 100644
--- a/components/process.rst
+++ b/components/process.rst
@@ -14,7 +14,6 @@ Installation
 
     $ composer require symfony/process
 
-Alternatively, you can clone the `<https://github.com/symfony/process>`_ repository.
 
 .. include:: /components/require_autoload.rst.inc
 
@@ -27,8 +26,8 @@ escaping arguments to prevent security issues. It replaces PHP functions like
 :phpfunction:`exec`, :phpfunction:`passthru`, :phpfunction:`shell_exec` and
 :phpfunction:`system`::
 
-    use Symfony\Component\Process\Process;
     use Symfony\Component\Process\Exception\ProcessFailedException;
+    use Symfony\Component\Process\Process;
 
     $process = new Process(['ls', '-lsa']);
     $process->run();
@@ -40,19 +39,6 @@ escaping arguments to prevent security issues. It replaces PHP functions like
 
     echo $process->getOutput();
 
-.. tip::
-
-    In addition to passing the command binary and its arguments as a string, you
-    can also pass them as an array, which is useful when building a complex
-    command programmatically::
-
-        // traditional string based commands
-        $builder = new Process('ls -lsa');
-        // same example but using an array
-        $builder = new Process(['ls', '-lsa']);
-        // the array can contain any number of arguments and options
-        $builder = new Process(['ls', '-l', '-s', '-a']);
-
 The ``getOutput()`` method always returns the whole content of the standard
 output of the command and ``getErrorOutput()`` the content of the error
 output. Alternatively, the :method:`Symfony\\Component\\Process\\Process::getIncrementalOutput`
@@ -110,33 +96,57 @@ with a non-zero code)::
         echo $exception->getMessage();
     }
 
-.. tip::
+Using Features From the OS Shell
+--------------------------------
+
+Using array of arguments is the recommended way to define commands. This
+saves you from any escaping and allows sending signals seamlessly
+(e.g. to stop processes before completion)::
+
+    $process = new Process(['/path/command', '--flag', 'arg 1', 'etc.']);
+
+If you need to use stream redirections, conditional execution, or any other
+feature provided by the shell of your operating system, you can also define
+commands as strings using the
+:method:`Symfony\\Component\\Process\\Process::fromShellCommandline` static
+factory.
+
+Each operating system provides a different syntax for their command-lines,
+so it becomes your responsibility to deal with escaping and portability.
 
-    Using array of arguments is the recommended way to define commands. This
-    saves you from any escaping and allows sending signals seamlessly
-    (e.g. to stop processes before completion.)::
+When using strings to define commands, variable arguments are passed as
+environment variables using the second argument of the ``run()``,
+``mustRun()`` or ``start()`` methods. Referencing them is also OS-dependent::
 
-        $process = new Process(['/path/command', '--flag', 'arg 1', 'etc.']);
+    // On Unix-like OSes (Linux, macOS)
+    $process = Process::fromShellCommandline('echo "$MESSAGE"');
 
-    If you need to use stream redirections, conditional execution, or any other
-    feature provided by the shell of your operating system, you can also define
-    commands as strings.
+    // On Windows
+    $process = Process::fromShellCommandline('echo "!MESSAGE!"');
 
-    Please note that each OS provides a different syntax for their command-lines
-    so that it becomes your responsibility to deal with escaping and portability.
+    // On both Unix-like and Windows
+    $process->run(null, ['MESSAGE' => 'Something to output']);
 
-    To provide any variable arguments to command-line string, pass them as
-    environment variables using the second argument of the ``run()``,
-    ``mustRun()`` or ``start()`` methods. Referencing them is also OS-dependent::
+Setting Environment Variables for Processes
+-------------------------------------------
 
-        // On Unix-like OSes (Linux, macOS)
-        $process = new Process('echo "$MESSAGE"');
+The constructor of the :class:`Symfony\\Component\\Process\\Process` class and
+all of its methods related to executing processes (``run()``, ``mustRun()``,
+``start()``, etc.) allow passing an array of environment variables to set while
+running the process::
 
-        // On Windows
-        $process = new Process('echo "!MESSAGE!"');
+    $process = new Process(['...'], null, ['ENV_VAR_NAME' => 'value']);
+    $process = Process::fromShellCommandline('...', null, ['ENV_VAR_NAME' => 'value']);
+    $process->run(null, ['ENV_VAR_NAME' => 'value']);
 
-        // On both Unix-like and Windows
-        $process->run(null, ['MESSAGE' => 'Something to output']);
+In addition to the env vars passed explicitly, processes inherit all the env
+vars defined in your system. You can prevent this by setting to ``false`` the
+env vars you want to remove::
+
+    $process = new Process(['...'], null, [
+        'APP_ENV' => false,
+        'SYMFONY_DOTENV_VARS' => false,
+    ]);
 
 Getting real-time Process Output
 --------------------------------
@@ -229,6 +239,23 @@ in the output and its type::
         }
     });
 
+Instead of waiting until the process has finished, you can use the
+:method:`Symfony\\Component\\Process\\Process::waitUntil` method to keep or stop
+waiting based on some PHP logic. The following example starts a long running
+process and checks its output to wait until its fully initialized::
+
+    $process = new Process(['/usr/bin/php', 'slow-starting-server.php']);
+    $process->start();
+
+    // ... do other things
+
+    // waits until the given anonymous function returns true
+    $process->waitUntil(function ($type, $output) {
+        return $output === 'Ready. Waiting for commands...';
+    });
+
+    // ... do things after the process is ready
+
 Streaming to the Standard Input of a Process
 --------------------------------------------
 
@@ -237,7 +264,7 @@ Before a process is started, you can specify its standard input using either the
 of the constructor. The provided input can be a string, a stream resource or a
 Traversable object::
 
-    $process = new Process('cat');
+    $process = new Process(['cat']);
     $process->setInput('foobar');
     $process->run();
 
@@ -336,7 +363,7 @@ a different timeout (in seconds) to the ``setTimeout()`` method::
     $process->run();
 
 If the timeout is reached, a
-:class:`Symfony\\Component\\Process\\Exception\\RuntimeException` is thrown.
+:class:`Symfony\\Component\\Process\\Exception\\ProcessTimedOutException` is thrown.
 
 For long running commands, it is your responsibility to perform the timeout
 check regularly::
@@ -447,14 +474,6 @@ whether `TTY`_ is supported on the current operating system::
 
     $process = (new Process())->setTty(Process::isTtySupported());
 
-.. versionadded:: 4.1
-    The ``isTtySupported()`` method was introduced in Symfony 4.1.
-
-.. _`Symfony Issue#5759`: https://github.com/symfony/symfony/issues/5759
-.. _`PHP Bug#39992`: https://bugs.php.net/bug.php?id=39992
-.. _`exec`: https://en.wikipedia.org/wiki/Exec_(operating_system)
 .. _`pid`: https://en.wikipedia.org/wiki/Process_identifier
-.. _`PHP Documentation`: https://php.net/manual/en/pcntl.constants.php
-.. _Packagist: https://packagist.org/packages/symfony/process
-.. _`PHP streams`: http://www.php.net/manual/en/book.stream.php
+.. _`PHP streams`: https://www.php.net/manual/en/book.stream.php
 .. _`TTY`: https://en.wikipedia.org/wiki/Tty_(unix)
diff --git a/components/property_access.rst b/components/property_access.rst
index 1181f8ff3a7..81aed5ab2c2 100644
--- a/components/property_access.rst
+++ b/components/property_access.rst
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/property-access
 
-Alternatively, you can clone the `<https://github.com/symfony/property-access>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -168,6 +166,36 @@ getters, this means that you can do something like this::
 
 This will produce: ``He is an author``
 
+Accessing a non Existing Property Path
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The ``disableExceptionOnInvalidPropertyPath()`` method was introduced in
+    Symfony 4.3.
+
+By default a :class:`Symfony\\Component\\PropertyAccess\\Exception\\NoSuchPropertyException`
+is thrown if the property path passed to :method:`PropertyAccessor::getValue<Symfony\\Component\\PropertyAccess\\PropertyAccessor::getValue>`
+does not exist. You can change this behavior using the
+:method:`Symfony\\Component\\PropertyAccess\\PropertyAccessorBuilder::disableExceptionOnInvalidPropertyPath`
+method::
+
+    // ...
+    class Person
+    {
+        public $name;
+    }
+
+    $person = new Person();
+
+    $propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
+        ->disableExceptionOnInvalidPropertyPath()
+        ->getPropertyAccessor();
+
+    // instead of throwing an exception the following code returns null
+    $value = $propertyAccessor->getValue($person, 'birthday');
+
+
 Magic ``__get()`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -296,9 +324,7 @@ can use setters, the magic ``__set()`` method or properties to set values::
     var_dump($person->getChildren()); // [Person()];
 
 You can also use ``__call()`` to set values but you need to enable the feature,
-see `Enable other Features`_.
-
-.. code-block:: php
+see `Enable other Features`_::
 
     // ...
     class Person
@@ -335,9 +361,7 @@ Writing to Array Properties
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``PropertyAccessor`` class allows to update the content of arrays stored in
-properties through *adder* and *remover* methods.
-
-.. code-block:: php
+properties through *adder* and *remover* methods::
 
     // ...
     class Person
@@ -467,5 +491,4 @@ Or you can pass parameters directly to the constructor (not the recommended way)
     // ...
     $propertyAccessor = new PropertyAccessor(true); // this enables handling of magic __call
 
-.. _Packagist: https://packagist.org/packages/symfony/property-access
 .. _The Inflector component: https://github.com/symfony/inflector
diff --git a/components/property_info.rst b/components/property_info.rst
index 21ded9a48d1..5f1c56826d6 100644
--- a/components/property_info.rst
+++ b/components/property_info.rst
@@ -23,8 +23,6 @@ Installation
 
     $ composer require symfony/property-info
 
-Alternatively, you can clone the `<https://github.com/symfony/property-info>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Additional dependencies may be required for some of the
@@ -37,36 +35,38 @@ Usage
 
 To use this component, create a new
 :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor` instance and
-provide it with a set of information extractors.
-
-.. code-block:: php
+provide it with a set of information extractors::
 
-    use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
+    use Example\Namespace\YourAwesomeCoolClass;
     use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
     use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
-    use Example\Namespace\YourAwesomeCoolClass;
+    use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
 
     // a full list of extractors is shown further below
     $phpDocExtractor = new PhpDocExtractor();
     $reflectionExtractor = new ReflectionExtractor();
 
-    // array of PropertyListExtractorInterface
+    // list of PropertyListExtractorInterface (any iterable)
     $listExtractors = [$reflectionExtractor];
 
-    // array of PropertyTypeExtractorInterface
+    // list of PropertyTypeExtractorInterface (any iterable)
     $typeExtractors = [$phpDocExtractor, $reflectionExtractor];
 
-    // array of PropertyDescriptionExtractorInterface
+    // list of PropertyDescriptionExtractorInterface (any iterable)
     $descriptionExtractors = [$phpDocExtractor];
 
-    // array of PropertyAccessExtractorInterface
+    // list of PropertyAccessExtractorInterface (any iterable)
     $accessExtractors = [$reflectionExtractor];
 
+    // list of PropertyInitializableExtractorInterface (any iterable)
+    $propertyInitializableExtractors = [$reflectionExtractor];
+
     $propertyInfo = new PropertyInfoExtractor(
         $listExtractors,
         $typeExtractors,
         $descriptionExtractors,
-        $accessExtractors
+        $accessExtractors,
+        $propertyInitializableExtractors
     );
 
     // see below for more examples
@@ -90,9 +90,7 @@ both provide list and type information it is probably better that:
   just mapped properties) are returned.
 * The :class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`
   has priority for type information so that entity metadata is used instead
-  of type-hinting to provide more accurate type information.
-
-.. code-block:: php
+  of type-hinting to provide more accurate type information::
 
     use Symfony\Bridge\Doctrine\PropertyInfo\DoctrineExtractor;
     use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
@@ -120,12 +118,13 @@ Extractable Information
 -----------------------
 
 The :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
-class exposes public methods to extract four types of information:
+class exposes public methods to extract several types of information:
 
-* :ref:`List of properties <property-info-list>`: `getProperties()`
-* :ref:`Property type <property-info-type>`: `getTypes()`
-* :ref:`Property description <property-info-description>`: `getShortDescription()` and `getLongDescription()`
-* :ref:`Property access details <property-info-access>`: `isReadable()` and `isWritable()`
+* :ref:`List of properties <property-info-list>`: :method:`Symfony\\Component\\PropertyInfo\\PropertyListExtractorInterface::getProperties()`
+* :ref:`Property type <property-info-type>`: :method:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface::getTypes()`
+* :ref:`Property description <property-info-description>`: :method:`Symfony\\Component\\PropertyInfo\\PropertyDescriptionExtractorInterface::getShortDescription()` and :method:`Symfony\\Component\\PropertyInfo\\PropertyDescriptionExtractorInterface::getLongDescription()`
+* :ref:`Property access details <property-info-access>`: :method:`Symfony\\Component\\PropertyInfo\\PropertyAccessExtractorInterface::isReadable()` and  :method:`Symfony\\Component\\PropertyInfo\\PropertyAccessExtractorInterface::isWritable()`
+* :ref:`Property initializable through the constructor <property-info-initializable>`:  :method:`Symfony\\Component\\PropertyInfo\\PropertyInitializableExtractorInterface::isInitializable()`
 
 .. note::
 
@@ -146,19 +145,17 @@ List Information
 
 Extractors that implement :class:`Symfony\\Component\\PropertyInfo\\PropertyListExtractorInterface`
 provide the list of properties that are available on a class as an array
-containing each property name as a string.
-
-.. code-block:: php
+containing each property name as a string::
 
     $properties = $propertyInfo->getProperties($class);
     /*
-      Example Result
-      --------------
-      array(3) {
-        [0] => string(8) "username"
-        [1] => string(8) "password"
-        [2] => string(6) "active"
-      }
+        Example Result
+        --------------
+        array(3) {
+            [0] => string(8) "username"
+            [1] => string(8) "password"
+            [2] => string(6) "active"
+        }
     */
 
 .. _property-info-type:
@@ -168,26 +165,23 @@ Type Information
 
 Extractors that implement :class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface`
 provide :ref:`extensive data type information <components-property-info-type>`
-for a property.
-
-.. code-block:: php
+for a property::
 
     $types = $propertyInfo->getTypes($class, $property);
-
     /*
-      Example Result
-      --------------
-      array(1) {
-        [0] =>
-        class Symfony\Component\PropertyInfo\Type (6) {
-          private $builtinType          => string(6) "string"
-          private $nullable             => bool(false)
-          private $class                => NULL
-          private $collection           => bool(false)
-          private $collectionKeyType    => NULL
-          private $collectionValueType  => NULL
+        Example Result
+        --------------
+        array(1) {
+            [0] =>
+                class Symfony\Component\PropertyInfo\Type (6) {
+                private $builtinType          => string(6) "string"
+                private $nullable             => bool(false)
+                private $class                => NULL
+                private $collection           => bool(false)
+                private $collectionKeyType    => NULL
+                private $collectionValueType  => NULL
+            }
         }
-      }
     */
 
 See :ref:`components-property-info-type` for info about the ``Type`` class.
@@ -199,24 +193,22 @@ Description Information
 
 Extractors that implement :class:`Symfony\\Component\\PropertyInfo\\PropertyDescriptionExtractorInterface`
 provide long and short descriptions from a properties annotations as
-strings.
-
-.. code-block:: php
+strings::
 
     $title = $propertyInfo->getShortDescription($class, $property);
     /*
-      Example Result
-      --------------
-      string(41) "This is the first line of the DocComment."
+        Example Result
+        --------------
+        string(41) "This is the first line of the DocComment."
     */
 
     $paragraph = $propertyInfo->getLongDescription($class, $property);
     /*
-      Example Result
-      --------------
-      string(79):
-        These is the subsequent paragraph in the DocComment.
-        It can span multiple lines.
+        Example Result
+        --------------
+        string(79):
+            These is the subsequent paragraph in the DocComment.
+            It can span multiple lines.
     */
 
 .. _property-info-access:
@@ -225,9 +217,7 @@ Access Information
 ~~~~~~~~~~~~~~~~~~
 
 Extractors that implement :class:`Symfony\\Component\\PropertyInfo\\PropertyAccessExtractorInterface`
-provide whether properties are readable or writable as booleans.
-
-.. code-block:: php
+provide whether properties are readable or writable as booleans::
 
     $propertyInfo->isReadable($class, $property);
     // Example Result: bool(true)
@@ -240,15 +230,25 @@ for getter/isser/setter/hasser method in addition to whether or not a property i
 to determine if it's accessible. This based on how the :doc:`PropertyAccess </components/property_access>`
 works.
 
-.. versionadded:: 4.1
+.. _property-info-initializable:
 
-    The support of hasser methods in the ``ReflectionExtractor`` class was
-    introduced in Symfony 4.1.
+Property Initializable Information
+----------------------------------
+
+Extractors that implement :class:`Symfony\\Component\\PropertyInfo\\PropertyInitializableExtractorInterface`
+provide whether properties are initializable through the class's constructor as booleans::
+
+    $propertyInfo->isInitializable($class, $property);
+    // Example Result: bool(true)
+
+:method:`Symfony\\Component\\PropertyInfo\\Extractor\\ReflectionExtractor::isInitializable`
+returns ``true`` if a constructor's parameter of the given class matches the
+given property name.
 
 .. tip::
 
     The main :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
-    class implements all four interfaces, delegating the extraction of property
+    class implements all interfaces, delegating the extraction of property
     information to the extractors that have been registered with it.
 
     This means that any method available on each of the extractors is also
@@ -315,9 +315,16 @@ a collection - a non-scalar value capable of containing other values. Currently
 this returns ``true`` if:
 
 * The :ref:`built-in PHP data type <components-property-info-type-builtin>`
-  is ``array``, or
+  is ``array``;
 * The mutator method the property is derived from has a prefix of ``add``
-  or ``remove`` (which are defined as the list of array mutator prefixes).
+  or ``remove`` (which are defined as the list of array mutator prefixes);
+* The `phpDocumentor`_ annotation is of type "collection" (e.g.
+  ``@var SomeClass<DateTime>``, ``@var SomeClass<integer,string>``,
+  ``@var Doctrine\Common\Collections\Collection<App\Entity\SomeEntity>``, etc.)
+
+.. versionadded:: 4.2
+
+    The support of phpDocumentor collection types was introduced in Symfony 4.2.
 
 Type::getCollectionKeyType() & Type::getCollectionValueType()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -351,21 +358,9 @@ ReflectionExtractor
 
 Using PHP reflection, the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\ReflectionExtractor`
 provides list, type and access information from setter and accessor methods.
-It can also provide return and scalar types for PHP 7+.
-
-.. note::
-
-    When using the Symfony framework, this service is automatically registered
-    when the ``property_info`` feature is enabled:
-
-    .. code-block:: yaml
-
-        # config/packages/framework.yaml
-        framework:
-            property_info:
-                enabled: true
-
-.. code-block:: php
+It can also give the type of a property (even extracting it from the constructor
+arguments), and if it is initializable through the constructor. It supports
+return and scalar types for PHP 7::
 
     use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
 
@@ -373,12 +368,34 @@ It can also provide return and scalar types for PHP 7+.
 
     // List information.
     $reflectionExtractor->getProperties($class);
+
     // Type information.
     $reflectionExtractor->getTypes($class, $property);
+
     // Access information.
     $reflectionExtractor->isReadable($class, $property);
     $reflectionExtractor->isWritable($class, $property);
 
+    // Initializable information
+    $reflectionExtractor->isInitializable($class, $property);
+
+.. versionadded:: 4.1
+
+    The feature to extract the property types from constructor arguments was
+    introduced in Symfony 4.1.
+
+.. note::
+
+    When using the Symfony framework, this service is automatically registered
+    when the ``property_info`` feature is enabled:
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            property_info:
+                enabled: true
+
 PhpDocExtractor
 ~~~~~~~~~~~~~~~
 
@@ -390,9 +407,7 @@ Using `phpDocumentor Reflection`_ to parse property and method annotations,
 the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
 provides type and description information. This extractor is automatically
 registered with the ``property_info`` in the Symfony Framework *if* the dependent
-library is present.
-
-.. code-block:: php
+library is present::
 
     use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
 
@@ -415,9 +430,7 @@ Using :ref:`groups metadata <serializer-using-serialization-groups-annotations>`
 from the :doc:`Serializer component </components/serializer>`,
 the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
 provides list information. This extractor is *not* registered automatically
-with the ``property_info`` service in the Symfony Framework.
-
-.. code-block:: php
+with the ``property_info`` service in the Symfony Framework::
 
     use Doctrine\Common\Annotations\AnnotationReader;
     use Symfony\Component\PropertyInfo\Extractor\SerializerExtractor;
@@ -443,9 +456,7 @@ DoctrineExtractor
 Using entity mapping data from `Doctrine ORM`_, the
 :class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`
 provides list and type information. This extractor is not registered automatically
-with the ``property_info`` service in the Symfony Framework.
-
-.. code-block:: php
+with the ``property_info`` service in the Symfony Framework::
 
     use Doctrine\ORM\EntityManager;
     use Doctrine\ORM\Tools\Setup;
@@ -456,7 +467,7 @@ with the ``property_info`` service in the Symfony Framework.
         'driver' => 'pdo_sqlite',
         // ...
     ], $config);
-    $doctrineExtractor = new DoctrineExtractor($entityManager->getMetadataFactory());
+    $doctrineExtractor = new DoctrineExtractor($entityManager);
 
     // List information.
     $doctrineExtractor->getProperties($class);
@@ -472,8 +483,9 @@ You can create your own property information extractors by creating a
 class that implements one or more of the following interfaces:
 :class:`Symfony\\Component\\PropertyInfo\\PropertyAccessExtractorInterface`,
 :class:`Symfony\\Component\\PropertyInfo\\PropertyDescriptionExtractorInterface`,
-:class:`Symfony\\Component\\PropertyInfo\\PropertyListExtractorInterface`
-and :class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface`.
+:class:`Symfony\\Component\\PropertyInfo\\PropertyListExtractorInterface`,
+:class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface` and
+:class:`Symfony\\Component\\PropertyInfo\\PropertyInitializableExtractorInterface`.
 
 If you have enabled the PropertyInfo component with the FrameworkBundle,
 you can automatically register your extractor class with the ``property_info``
@@ -485,10 +497,10 @@ service by defining it as a service with one or more of the following
 * ``property_info.description_extractor`` if it provides description information.
 * ``property_info.access_extractor`` if it provides access information.
 
-.. _Packagist: https://packagist.org/packages/symfony/property-info
 .. _`phpDocumentor Reflection`: https://github.com/phpDocumentor/ReflectionDocBlock
 .. _`phpdocumentor/reflection-docblock`: https://packagist.org/packages/phpdocumentor/reflection-docblock
-.. _`Doctrine ORM`: http://www.doctrine-project.org/projects/orm.html
+.. _`Doctrine ORM`: https://www.doctrine-project.org/projects/orm.html
 .. _`symfony/serializer`: https://packagist.org/packages/symfony/serializer
 .. _`symfony/doctrine-bridge`: https://packagist.org/packages/symfony/doctrine-bridge
 .. _`doctrine/orm`: https://packagist.org/packages/doctrine/orm
+.. _`phpDocumentor`: https://www.phpdoc.org/
diff --git a/components/psr7.rst b/components/psr7.rst
index 61b2d1b35e3..2df3c6fc3af 100644
--- a/components/psr7.rst
+++ b/components/psr7.rst
@@ -15,14 +15,16 @@ Installation
 
     $ composer require symfony/psr-http-message-bridge
 
-Alternatively, you can clone the `<https://github.com/symfony/psr-http-message-bridge>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
-The bridge also needs a PSR-7 implementation to allow converting HttpFoundation
-objects to PSR-7 objects. It provides native support for `Zend Diactoros`_.
-Use Composer (`zendframework/zend-diactoros on Packagist <https://packagist.org/packages/zendframework/zend-diactoros>`_)
-or refer to the project documentation to install it.
+The bridge also needs a PSR-7 and `PSR-17`_ implementation to convert
+HttpFoundation objects to PSR-7 objects. The following command installs the
+``nyholm/psr7`` library, a lightweight and fast PSR-7 implementation, but you
+can use any of the `libraries that implement psr/http-factory-implementation`_:
+
+.. code-block:: terminal
+
+    $ composer require nyholm/psr7
 
 Usage
 -----
@@ -33,32 +35,35 @@ Converting from HttpFoundation Objects to PSR-7
 The bridge provides an interface of a factory called
 :class:`Symfony\\Bridge\\PsrHttpMessage\\HttpMessageFactoryInterface`
 that builds objects implementing PSR-7 interfaces from HttpFoundation objects.
-It also provide a default implementation using Zend Diactoros internally.
 
 The following code snippet explains how to convert a :class:`Symfony\\Component\\HttpFoundation\\Request`
-to a ``Zend\Diactoros\ServerRequest`` class implementing the
+to a ``Nyholm\Psr7\ServerRequest`` class implementing the
 ``Psr\Http\Message\ServerRequestInterface`` interface::
 
-    use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory;
+    use Nyholm\Psr7\Factory\Psr17Factory;
+    use Symfony\Bridge\PsrHttpMessage\Factory\PsrHttpFactory;
     use Symfony\Component\HttpFoundation\Request;
 
     $symfonyRequest = new Request([], [], [], [], [], ['HTTP_HOST' => 'dunglas.fr'], 'Content');
     // The HTTP_HOST server key must be set to avoid an unexpected error
 
-    $psr7Factory = new DiactorosFactory();
-    $psrRequest = $psr7Factory->createRequest($symfonyRequest);
+    $psr17Factory = new Psr17Factory();
+    $psrHttpFactory = new PsrHttpFactory($psr17Factory, $psr17Factory, $psr17Factory, $psr17Factory);
+    $psrRequest = $psrHttpFactory->createRequest($symfonyRequest);
 
 And now from a :class:`Symfony\\Component\\HttpFoundation\\Response` to a
-``Zend\Diactoros\Response`` class implementing the
+``Nyholm\Psr7\Response`` class implementing the
 ``Psr\Http\Message\ResponseInterface`` interface::
 
-    use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory;
+    use Nyholm\Psr7\Factory\Psr17Factory;
+    use Symfony\Bridge\PsrHttpMessage\Factory\PsrHttpFactory;
     use Symfony\Component\HttpFoundation\Response;
 
     $symfonyResponse = new Response('Content');
 
-    $psr7Factory = new DiactorosFactory();
-    $psrResponse = $psr7Factory->createResponse($symfonyResponse);
+    $psr17Factory = new Psr17Factory();
+    $psrHttpFactory = new PsrHttpFactory($psr17Factory, $psr17Factory, $psr17Factory, $psr17Factory);
+    $psrResponse = $psrHttpFactory->createResponse($symfonyResponse);
 
 Converting Objects implementing PSR-7 Interfaces to HttpFoundation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -89,5 +94,5 @@ to a :class:`Symfony\\Component\\HttpFoundation\\Response` instance::
     $symfonyResponse = $httpFoundationFactory->createResponse($psrResponse);
 
 .. _`PSR-7`: https://www.php-fig.org/psr/psr-7/
-.. _`Zend Diactoros`: https://github.com/zendframework/zend-diactoros
-.. _`symfony/psr-http-message-bridge on Packagist`: https://packagist.org/packages/symfony/psr-http-message-bridge
+.. _`PSR-17`: https://www.php-fig.org/psr/psr-17/
+.. _`libraries that implement psr/http-factory-implementation`: https://packagist.org/providers/psr/http-factory-implementation
diff --git a/components/routing.rst b/components/routing.rst
index bad49425614..22b9ea9f342 100644
--- a/components/routing.rst
+++ b/components/routing.rst
@@ -6,7 +6,8 @@ The Routing Component
 =====================
 
     The Routing component maps an HTTP request to a set of configuration
-    variables.
+    variables. It's used to build routing systems for web applications where
+    each URL is associated with some code to execute.
 
 Installation
 ------------
@@ -15,52 +16,56 @@ Installation
 
     $ composer require symfony/routing
 
-Alternatively, you can clone the `<https://github.com/symfony/routing>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
 -----
 
-.. seealso::
+The main :doc:`Symfony routing </routing>` article explains all the features of
+this component when used inside a Symfony application. This article only
+explains the things you need to do to use it in a non-Symfony PHP application.
 
-    This article explains how to use the Routing features as an independent
-    component in any PHP application. Read the :doc:`/routing` article to learn
-    about how to use it in Symfony applications.
+Routing System Setup
+--------------------
 
-In order to set up a basic routing system you need three parts:
+A routing system has three parts:
 
-* A :class:`Symfony\\Component\\Routing\\RouteCollection`, which contains the route definitions (instances of the class :class:`Symfony\\Component\\Routing\\Route`)
-* A :class:`Symfony\\Component\\Routing\\RequestContext`, which has information about the request
-* A :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher`, which performs the mapping of the request to a single route
+* A :class:`Symfony\\Component\\Routing\\RouteCollection`, which contains the
+  route definitions (instances of the class :class:`Symfony\\Component\\Routing\\Route`);
+* A :class:`Symfony\\Component\\Routing\\RequestContext`, which has information
+  about the request;
+* A :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher`, which performs
+  the mapping of the path to a single route.
 
-Here is a quick example. Notice that this assumes that you've already configured
-your autoloader to load the Routing component::
+Here is a quick example::
 
+    use App\Controller\BlogController;
     use Symfony\Component\Routing\Matcher\UrlMatcher;
     use Symfony\Component\Routing\RequestContext;
-    use Symfony\Component\Routing\RouteCollection;
     use Symfony\Component\Routing\Route;
+    use Symfony\Component\Routing\RouteCollection;
 
-    $route = new Route('/foo', ['_controller' => 'MyController']);
+    $route = new Route('/blog/{slug}', ['_controller' => BlogController::class])
     $routes = new RouteCollection();
-    $routes->add('route_name', $route);
+    $routes->add('blog_show', $route);
 
     $context = new RequestContext('/');
 
+    // Routing can match routes with incoming requests
     $matcher = new UrlMatcher($routes, $context);
+    $parameters = $matcher->match('/blog/lorem-ipsum');
+    // $parameters = [
+    //     '_controller' => 'App\Controller\BlogController',
+    //     'slug' => 'lorem-ipsum',
+    //     '_route' => 'blog_show'
+    // ]
 
-    $parameters = $matcher->match('/foo');
-    // ['_controller' => 'MyController', '_route' => 'route_name']
-
-.. note::
-
-    The :class:`Symfony\\Component\\Routing\\RequestContext` parameters can be populated
-    with the values stored in ``$_SERVER``, but it's easier to use the HttpFoundation
-    component as explained :ref:`below <components-routing-http-foundation>`.
-
-You can add as many routes as you like to a
-:class:`Symfony\\Component\\Routing\\RouteCollection`.
+    // Routing can also generate URLs for a given route
+    $generator = new UrlGenerator($routes, $context);
+    $url = $generator->generate('blog_show', [
+        'slug' => 'my-blog-post',
+    ]);
+    // $url = '/blog/my-blog-post'
 
 The :method:`RouteCollection::add() <Symfony\\Component\\Routing\\RouteCollection::add>`
 method takes two arguments. The first is the name of the route. The second
@@ -70,42 +75,19 @@ of custom variables can be *anything* that's significant to your application,
 and is returned when that route is matched.
 
 The :method:`UrlMatcher::match() <Symfony\\Component\\Routing\\Matcher\\UrlMatcher::match>`
-returns the variables you set on the route as well as the wildcard placeholders
-(see below). Your application can now use this information to continue
-processing the request. In addition to the configured variables, a ``_route``
-key is added, which holds the name of the matched route.
+returns the variables you set on the route as well as the route parameters.
+Your application can now use this information to continue processing the request.
+In addition to the configured variables, a ``_route`` key is added, which holds
+the name of the matched route.
 
 If no matching route can be found, a
 :class:`Symfony\\Component\\Routing\\Exception\\ResourceNotFoundException` will
 be thrown.
 
 Defining Routes
-~~~~~~~~~~~~~~~
-
-A full route definition can contain up to seven parts:
-
-#. The URL path route. This is matched against the URL passed to the `RequestContext`,
-   and can contain named wildcard placeholders (e.g. ``{placeholders}``)
-   to match dynamic parts in the URL.
-
-#. An array of default values. This contains an array of arbitrary values
-   that will be returned when the request matches the route.
-
-#. An array of requirements. These define constraints for the values of the
-   placeholders as regular expressions.
-
-#. An array of options. These contain internal settings for the route and
-   are the least commonly needed.
-
-#. A host. This is matched against the host of the request. See
-   :doc:`/routing/hostname_pattern` for more details.
-
-#. An array of schemes. These enforce a certain HTTP scheme (``http``, ``https``).
+---------------
 
-#. An array of methods. These enforce a certain HTTP request method (``HEAD``,
-   ``GET``, ``POST``, ...).
-
-Take the following route, which combines several of these ideas::
+A full route definition can contain up to eight parts::
 
     $route = new Route(
         '/archive/{month}', // path
@@ -114,7 +96,8 @@ Take the following route, which combines several of these ideas::
         [], // options
         '{subdomain}.example.com', // host
         [], // schemes
-        [] // methods
+        [], // methods
+        'context.getHost() matches "/(secure|admin).example.com/"' // condition
     );
 
     // ...
@@ -130,33 +113,13 @@ Take the following route, which combines several of these ideas::
     $parameters = $matcher->match('/archive/foo');
     // throws ResourceNotFoundException
 
-In this case, the route is matched by ``/archive/2012-01``, because the ``{month}``
-wildcard matches the regular expression wildcard given. However, ``/archive/foo``
-does *not* match, because "foo" fails the month wildcard.
-
-When using wildcards, these are returned in the array result when calling
-``match``. The part of the path that the wildcard matched (e.g. ``2012-01``) is used
-as value.
-
-.. tip::
-
-    If you want to match all URLs which start with a certain path and end in an
-    arbitrary suffix you can use the following route definition::
-
-        $route = new Route(
-            '/start/{suffix}',
-            ['suffix' => ''],
-            ['suffix' => '.*']
-        );
-
-Using Prefixes
-~~~~~~~~~~~~~~
+Route Collections
+-----------------
 
 You can add routes or other instances of
 :class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection.
-This way you can build a tree of routes. Additionally you can define a prefix
-and default values for the parameters, requirements, options, schemes and the
-host to all routes of a subtree using methods provided by the
+This way you can build a tree of routes. Additionally you can define common
+options for all routes of a subtree using methods provided by the
 ``RouteCollection`` class::
 
     $rootCollection = new RouteCollection();
@@ -166,16 +129,17 @@ host to all routes of a subtree using methods provided by the
     $subCollection->add(...);
     $subCollection->addPrefix('/prefix');
     $subCollection->addDefaults([...]);
-    $subCollection->addRequirements([]);
-    $subCollection->addOptions([]);
-    $subCollection->setHost('admin.example.com');
+    $subCollection->addRequirements([...]);
+    $subCollection->addOptions([...]);
+    $subCollection->setHost('{subdomain}.example.com');
     $subCollection->setMethods(['POST']);
     $subCollection->setSchemes(['https']);
+    $subCollection->setCondition('context.getHost() matches "/(secure|admin).example.com/"');
 
     $rootCollection->addCollection($subCollection);
 
-Set the Request Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Setting the Request Parameters
+------------------------------
 
 The :class:`Symfony\\Component\\Routing\\RequestContext` provides information
 about the current request. You can define all parameters of an HTTP request
@@ -205,67 +169,15 @@ Normally you can pass the values from the ``$_SERVER`` variable to populate the
     $context = new RequestContext();
     $context->fromRequest(Request::createFromGlobals());
 
-Generate a URL
-~~~~~~~~~~~~~~
-
-While the :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher` tries
-to find a route that fits the given request you can also build a URL from
-a certain route::
-
-    use Symfony\Component\Routing\Generator\UrlGenerator;
-    use Symfony\Component\Routing\RequestContext;
-    use Symfony\Component\Routing\Route;
-    use Symfony\Component\Routing\RouteCollection;
-
-    $routes = new RouteCollection();
-    $routes->add('show_post', new Route('/show/{slug}'));
-
-    $context = new RequestContext('/');
-
-    $generator = new UrlGenerator($routes, $context);
-
-    $url = $generator->generate('show_post', [
-        'slug' => 'my-blog-post',
-    ]);
-    // /show/my-blog-post
-
-.. note::
-
-    If you have defined a scheme, an absolute URL is generated if the scheme
-    of the current :class:`Symfony\\Component\\Routing\\RequestContext` does
-    not match the requirement.
-
-Check if a Route Exists
-~~~~~~~~~~~~~~~~~~~~~~~
-
-In highly dynamic applications, it may be necessary to check whether a route
-exists before using it to generate a URL. In those cases, don't use the
-:method:`Symfony\\Component\\Routing\\Router::getRouteCollection` method because
-that regenerates the routing cache and slows down the application.
+Loading Routes
+--------------
 
-Instead, try to generate the URL and catch the
-:class:`Symfony\\Component\\Routing\\Exception\\RouteNotFoundException` thrown
-when the route doesn't exist::
+The Routing component comes with a number of loader classes, each giving you the
+ability to load a collection of route definitions from external resources.
 
-    use Symfony\Component\Routing\Exception\RouteNotFoundException;
+File Routing Loaders
+~~~~~~~~~~~~~~~~~~~~
 
-    // ...
-
-    try {
-        $url = $generator->generate($dynamicRouteName, $parameters);
-    } catch (RouteNotFoundException $e) {
-        // the route is not defined...
-    }
-
-Load Routes from a File
-~~~~~~~~~~~~~~~~~~~~~~~
-
-You've already seen how you can add routes to a collection right inside
-PHP. But you can also load routes from a number of different files.
-
-The Routing component comes with a number of loader classes, each giving
-you the ability to load a collection of route definitions from an external
-file of some format.
 Each loader expects a :class:`Symfony\\Component\\Config\\FileLocator` instance
 as the constructor argument. You can use the :class:`Symfony\\Component\\Config\\FileLocator`
 to define an array of paths in which the loader will look for the requested files.
@@ -277,12 +189,13 @@ If you're using the ``YamlFileLoader``, then route definitions look like this:
 
     # routes.yaml
     route1:
-        path:     /foo
-        defaults: { _controller: 'MyController::fooAction' }
-
+        path:       /foo
+        controller: MyController::fooAction
+        methods:    GET|HEAD
     route2:
-        path:     /foo/bar
-        defaults: { _controller: 'MyController::foobarAction' }
+        path:       /foo/bar
+        controller: FooBarInvokableController
+        methods:    PUT
 
 To load this file, you can use the following code. This assumes that your
 ``routes.yaml`` file is in the same directory as the below code::
@@ -302,23 +215,22 @@ other loaders that work the same way:
 * :class:`Symfony\\Component\\Routing\\Loader\\PhpFileLoader`
 
 If you use the :class:`Symfony\\Component\\Routing\\Loader\\PhpFileLoader` you
-have to provide the name of a PHP file which returns a :class:`Symfony\\Component\\Routing\\RouteCollection`::
+have to provide the name of a PHP file which returns a callable handling a
+:class:`Symfony\\Component\\Routing\\Loader\\Configurator\\RoutingConfigurator`.
+This class allows to chain imports, collections or simple route definition calls::
 
     // RouteProvider.php
-    use Symfony\Component\Routing\RouteCollection;
-    use Symfony\Component\Routing\Route;
+    use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-    $routes = new RouteCollection();
-    $routes->add(
-        'route_name',
-        new Route('/foo', ['_controller' => 'ExampleController'])
-    );
-    // ...
-
-    return $routes;
+    return function (RoutingConfigurator $routes) {
+        $routes->add('route_name', '/foo')
+            ->controller('ExampleController')
+            // ...
+        ;
+    };
 
-Routes as Closures
-..................
+Closure Routing Loaders
+~~~~~~~~~~~~~~~~~~~~~~~
 
 There is also the :class:`Symfony\\Component\\Routing\\Loader\\ClosureLoader`, which
 calls a closure and uses the result as a :class:`Symfony\\Component\\Routing\\RouteCollection`::
@@ -332,14 +244,28 @@ calls a closure and uses the result as a :class:`Symfony\\Component\\Routing\\Ro
     $loader = new ClosureLoader();
     $routes = $loader->load($closure);
 
-Routes as Annotations
-.....................
+Annotation Routing Loaders
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Last but not least there are
 :class:`Symfony\\Component\\Routing\\Loader\\AnnotationDirectoryLoader` and
 :class:`Symfony\\Component\\Routing\\Loader\\AnnotationFileLoader` to load
-route definitions from class annotations. The specific details are left
-out here.
+route definitions from class annotations::
+
+    use Doctrine\Common\Annotations\AnnotationReader;
+    use Symfony\Bundle\FrameworkBundle\Routing\AnnotatedRouteControllerLoader;
+    use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\Routing\Loader\AnnotationDirectoryLoader;
+
+    $loader = new AnnotationDirectoryLoader(
+        new FileLocator(__DIR__.'/app/controllers/'),
+        new AnnotatedRouteControllerLoader(
+            new AnnotationReader()
+        )
+    );
+
+    $routes = $loader->load(__DIR__.'/app/controllers/');
+    // ...
 
 .. include:: /_includes/_annotation_loader_tip.rst.inc
 
@@ -372,7 +298,8 @@ automatically in the background if you want to use it. A basic example of the
         ['cache_dir' => __DIR__.'/cache'],
         $requestContext
     );
-    $router->match('/foo/bar');
+    $parameters = $router->match('/foo/bar');
+    $url = $router->generate('some_route', ['parameter' => 'value']);
 
 .. note::
 
@@ -380,161 +307,6 @@ automatically in the background if you want to use it. A basic example of the
     are saved in the ``cache_dir``. This means your script must have write
     permissions for that location.
 
-Unicode Routing Support
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The Routing component supports UTF-8 characters in route paths and requirements.
-Thanks to the ``utf8`` route option, you can make Symfony match and generate
-routes with UTF-8 characters:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class DefaultController extends AbstractController
-        {
-            /**
-             * @Route("/category/{name}", name="route1", options={"utf8": true})
-             */
-            public function category()
-            {
-                // ...
-            }
-
-    .. code-block:: yaml
-
-        route1:
-            path:     /category/{name}
-            defaults: { _controller: 'App\Controller\DefaultController::category' }
-            options:
-                utf8: true
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="route1" path="/category/{name}">
-                <default key="_controller">App\Controller\DefaultController::category</default>
-                <option key="utf8">true</option>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('route1', new Route('/category/{name}',
-            [
-                '_controller' => 'App\Controller\DefaultController::category',
-            ],
-            [],
-            [
-                'utf8' => true,
-            ]
-        ));
-
-        // ...
-
-        return $routes;
-
-In this route, the ``utf8`` option set to ``true`` makes Symfony consider the
-``.`` requirement to match any UTF-8 characters instead of just a single
-byte character. This means that so the following URLs would match:
-``/category/日本語``, ``/category/فارسی``, ``/category/한국어``, etc. In case you
-are wondering, this option also allows to include and match emojis in URLs.
-
-You can also include UTF-8 strings as routing requirements:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class DefaultController extends AbstractController
-        {
-            /**
-             * @Route(
-             *     "/category/{name}",
-             *     name="route2",
-             *     requirements={"default"="한국어"},
-             *     options={"utf8": true}
-             * )
-             */
-            public function default()
-            {
-                // ...
-            }
-
-    .. code-block:: yaml
-
-        route2:
-            path:     /default/{default}
-            defaults: { _controller: 'App\Controller\DefaultController::default' }
-            requirements:
-                default: "한국어"
-            options:
-                utf8: true
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="route2" path="/default/{default}">
-                <default key="_controller">App\Controller\DefaultController::default</default>
-                <requirement key="default">한국어</requirement>
-                <option key="utf8">true</option>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('route2', new Route('/default/{default}',
-            [
-                '_controller' => 'App\Controller\DefaultController::default',
-            ],
-            [
-                'default' => '한국어',
-            ],
-            [
-                'utf8' => true,
-            ]
-        ));
-
-        // ...
-
-        return $routes;
-
-.. tip::
-
-    In addition to UTF-8 characters, the Routing component also supports all
-    the `PCRE Unicode properties`_, which are escape sequences that match
-    generic character types. For example, ``\p{Lu}`` matches any uppercase
-    character in any language, ``\p{Greek}`` matches any Greek character,
-    ``\P{Han}`` matches any character not included in the Chinese Han script.
-
 Learn more
 ----------
 
@@ -546,6 +318,3 @@ Learn more
     /routing/*
     /controller
     /controller/*
-
-.. _Packagist: https://packagist.org/packages/symfony/routing
-.. _PCRE Unicode properties: http://php.net/manual/en/regexp.reference.unicode.php
diff --git a/components/security.rst b/components/security.rst
index 98808c33c52..ee6c1580472 100644
--- a/components/security.rst
+++ b/components/security.rst
@@ -18,12 +18,10 @@ Installation
 
     $ composer require symfony/security
 
-Alternatively, you can clone the `<https://github.com/symfony/security>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
-The Security component is divided into four smaller sub-components which can be
-used separately:
+The Security component is divided into several smaller sub-components which can
+be used separately:
 
 ``symfony/security-core``
     It provides all the common security features, from authentication to
@@ -36,6 +34,10 @@ used separately:
 ``symfony/security-csrf``
     It provides protection against `CSRF attacks`_.
 
+``symfony/security-guard``
+    It brings many layers of authentication together, allowing the creation
+    of complex authentication systems.
+
 .. seealso::
 
     This article explains how to use the Security features as an independent
@@ -55,5 +57,4 @@ Learn More
     /reference/configuration/security
     /reference/constraints/UserPassword
 
-.. _Packagist: https://packagist.org/packages/symfony/security
 .. _`CSRF attacks`: https://en.wikipedia.org/wiki/Cross-site_request_forgery
diff --git a/components/security/authentication.rst b/components/security/authentication.rst
index ee4e99b6529..849ea53a992 100644
--- a/components/security/authentication.rst
+++ b/components/security/authentication.rst
@@ -13,11 +13,11 @@ an *authenticated* token if the supplied credentials were found to be valid.
 The listener should then store the authenticated token using
 :class:`the token storage <Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface>`::
 
-    use Symfony\Component\Security\Http\Firewall\ListenerInterface;
-    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
+    use Symfony\Component\HttpKernel\Event\RequestEvent;
     use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
-    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
+    use Symfony\Component\Security\Http\Firewall\ListenerInterface;
 
     class SomeAuthenticationListener implements ListenerInterface
     {
@@ -38,7 +38,7 @@ The listener should then store the authenticated token using
 
         // ...
 
-        public function handle(GetResponseEvent $event)
+        public function handle(RequestEvent $event)
         {
             $request = $event->getRequest();
 
@@ -127,9 +127,9 @@ to create a hash of the password and returns an authenticated token if the
 password was valid::
 
     use Symfony\Component\Security\Core\Authentication\Provider\DaoAuthenticationProvider;
-    use Symfony\Component\Security\Core\User\UserChecker;
-    use Symfony\Component\Security\Core\User\InMemoryUserProvider;
     use Symfony\Component\Security\Core\Encoder\EncoderFactory;
+    use Symfony\Component\Security\Core\User\InMemoryUserProvider;
+    use Symfony\Component\Security\Core\User\UserChecker;
 
     $userProvider = new InMemoryUserProvider(
         [
@@ -276,14 +276,15 @@ Authentication Events
 
 The security component provides 4 related authentication events:
 
-===============================  ================================================  ==============================================================================
-Name                             Event Constant                                    Argument Passed to the Listener
-===============================  ================================================  ==============================================================================
-security.authentication.success  ``AuthenticationEvents::AUTHENTICATION_SUCCESS``  :class:`Symfony\\Component\\Security\\Core\\Event\\AuthenticationEvent`
-security.authentication.failure  ``AuthenticationEvents::AUTHENTICATION_FAILURE``  :class:`Symfony\\Component\\Security\\Core\\Event\\AuthenticationFailureEvent`
-security.interactive_login       ``SecurityEvents::INTERACTIVE_LOGIN``             :class:`Symfony\\Component\\Security\\Http\\Event\\InteractiveLoginEvent`
-security.switch_user             ``SecurityEvents::SWITCH_USER``                   :class:`Symfony\\Component\\Security\\Http\\Event\\SwitchUserEvent`
-===============================  ================================================  ==============================================================================
+===============================  ================================================================= ==============================================================================
+Name                             Event Constant                                                    Argument Passed to the Listener
+===============================  ================================================================= ==============================================================================
+security.authentication.success  ``AuthenticationEvents::AUTHENTICATION_SUCCESS``                  :class:`Symfony\\Component\\Security\\Core\\Event\\AuthenticationEvent`
+security.authentication.failure  ``AuthenticationEvents::AUTHENTICATION_FAILURE``                  :class:`Symfony\\Component\\Security\\Core\\Event\\AuthenticationFailureEvent`
+security.interactive_login       ``SecurityEvents::INTERACTIVE_LOGIN``                             :class:`Symfony\\Component\\Security\\Http\\Event\\InteractiveLoginEvent`
+security.switch_user             ``SecurityEvents::SWITCH_USER``                                   :class:`Symfony\\Component\\Security\\Http\\Event\\SwitchUserEvent`
+security.logout_on_change        ``Symfony\Component\Security\Http\Event\DeauthenticatedEvent``    :class:`Symfony\\Component\\Security\\Http\\Event\\DeauthenticatedEvent`
+===============================  ================================================================= ==============================================================================
 
 Authentication Success and Failure Events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -314,10 +315,16 @@ order to give your user a welcome flash message every time they log in.
 The ``security.switch_user`` event is triggered every time you activate
 the ``switch_user`` firewall listener.
 
+The ``Symfony\Component\Security\Http\Event\DeauthenticatedEvent`` event is triggered when a token has been deauthenticated
+because of a user change, it can help you doing some clean-up task when a logout has been triggered.
+
+.. versionadded:: 4.3
+
+    The ``Symfony\Component\Security\Http\Event\DeauthenticatedEvent`` event was introduced in Symfony 4.3.
+
 .. seealso::
 
     For more information on switching users, see
     :doc:`/security/impersonating_user`.
 
 .. _`CVE-2013-5750`: https://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form
-.. _`BasePasswordEncoder::checkPasswordLength`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php
diff --git a/components/security/authorization.rst b/components/security/authorization.rst
index 4bac0b42c74..52f9b8bacd4 100644
--- a/components/security/authorization.rst
+++ b/components/security/authorization.rst
@@ -19,7 +19,7 @@ by an instance of :class:`Symfony\\Component\\Security\\Core\\Authorization\\Acc
 An authorization decision will always be based on a few things:
 
 * The current token
-    For instance, the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoles`
+    For instance, the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoleNames`
     method may be used to retrieve the roles of the current user (e.g.
     ``ROLE_SUPER_ADMIN``), or a decision may be based on the class of the token.
 * A set of attributes
@@ -49,7 +49,7 @@ recognizes several strategies:
 ``unanimous``
     only grant access if none of the voters has denied access;
 
-.. code-block:: php
+Usage of the available options in detail::
 
     use Symfony\Component\Security\Core\Authorization\AccessDecisionManager;
 
@@ -101,9 +101,7 @@ The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\Authentica
 voter supports the attributes ``IS_AUTHENTICATED_FULLY``, ``IS_AUTHENTICATED_REMEMBERED``,
 and ``IS_AUTHENTICATED_ANONYMOUSLY`` and grants access based on the current
 level of authentication, i.e. is the user fully authenticated, or only based
-on a "remember-me" cookie, or even authenticated anonymously?
-
-.. code-block:: php
+on a "remember-me" cookie, or even authenticated anonymously?::
 
     use Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolver;
     use Symfony\Component\Security\Core\Authentication\Token\AnonymousToken;
@@ -127,7 +125,7 @@ RoleVoter
 The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleVoter`
 supports attributes starting with ``ROLE_`` and grants access to the user
 when the required ``ROLE_*`` attributes can all be found in the array of
-roles returned by the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoles`
+roles returned by the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoleNames`
 method::
 
     use Symfony\Component\Security\Core\Authorization\Voter\RoleVoter;
@@ -159,32 +157,53 @@ role::
 
     $roleHierarchyVoter = new RoleHierarchyVoter($roleHierarchy);
 
-.. note::
+ExpressionVoter
+~~~~~~~~~~~~~~~
 
-    When you make your own voter, you can use its constructor
-    to inject any dependencies it needs to come to a decision.
+The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\ExpressionVoter`
+grants access based on the evaluation of expressions created with the
+:doc:`ExpressionLanguage component </components/expression_language>`. These
+expressions have access to a number of
+:ref:`special security variables <security-expression-variables>`::
 
-Roles
------
+    use Symfony\Component\ExpressionLanguage\Expression;
+    use Symfony\Component\Security\Core\Authorization\Voter\ExpressionVoter;
+
+    // Symfony\Component\Security\Core\Authorization\ExpressionLanguage;
+    $expressionLanguage = ...;
 
-Roles are objects that give expression to a certain right the user has. The only
-requirement is that they must define a ``getRole()`` method that returns a
-string representation of the role itself. To do so, you can optionally extend
-from the default :class:`Symfony\\Component\\Security\\Core\\Role\\Role` class,
-which returns its first constructor argument in this method::
+    // instance of Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolverInterface
+    $trustResolver = ...;
+
+    // Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface
+    $authorizationChecker = ...;
+
+    $expressionVoter = new ExpressionVoter($expressionLanguage, $trustResolver, $authorizationChecker);
+
+    // instance of Symfony\Component\Security\Core\Authentication\Token\TokenInterface
+    $token = ...;
 
-    use Symfony\Component\Security\Core\Role\Role;
+    // any object
+    $object = ...;
 
-    $role = new Role('ROLE_ADMIN');
+    $expression = new Expression(
+        '"ROLE_ADMIN" in roles or (not is_anonymous() and user.isSuperAdmin())'
+    )
 
-    // shows 'ROLE_ADMIN'
-    var_dump($role->getRole());
+    $vote = $expressionVoter->vote($token, $object, [$expression]);
 
 .. note::
 
-    Most authentication tokens extend from :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\AbstractToken`,
-    which means that the roles given to its constructor will be
-    automatically converted from strings to these simple ``Role`` objects.
+    When you make your own voter, you can use its constructor to inject any
+    dependencies it needs to come to a decision.
+
+Roles
+-----
+
+Roles are strings that give expression to a certain right the user has (e.g.
+*"edit a blog post"*, *"create an invoice"*). You can freely choose those
+strings. The only requirement is that they must start with the ``ROLE_`` prefix
+(e.g. ``ROLE_POST_EDIT``, ``ROLE_INVOICE_CREATE``).
 
 Using the Decision Manager
 --------------------------
@@ -203,8 +222,8 @@ It uses an access map (which should be an instance of :class:`Symfony\\Component
 which contains request matchers and a corresponding set of attributes that
 are required for the current user to get access to the application::
 
-    use Symfony\Component\Security\Http\AccessMap;
     use Symfony\Component\HttpFoundation\RequestMatcher;
+    use Symfony\Component\Security\Http\AccessMap;
     use Symfony\Component\Security\Http\Firewall\AccessListener;
 
     $accessMap = new AccessMap();
diff --git a/components/security/firewall.rst b/components/security/firewall.rst
index eca13908727..17b7d03e0d2 100644
--- a/components/security/firewall.rst
+++ b/components/security/firewall.rst
@@ -52,9 +52,9 @@ ability to find out if the current request points to a secured area.
 The listeners are then asked if the current request can be used to authenticate
 the user::
 
-    use Symfony\Component\Security\Http\FirewallMap;
     use Symfony\Component\HttpFoundation\RequestMatcher;
     use Symfony\Component\Security\Http\Firewall\ExceptionListener;
+    use Symfony\Component\Security\Http\FirewallMap;
 
     $firewallMap = new FirewallMap();
 
@@ -70,8 +70,8 @@ the user::
 The firewall map will be given to the firewall as its first argument, together
 with the event dispatcher that is used by the :class:`Symfony\\Component\\HttpKernel\\HttpKernel`::
 
-    use Symfony\Component\Security\Http\Firewall;
     use Symfony\Component\HttpKernel\KernelEvents;
+    use Symfony\Component\Security\Http\Firewall;
 
     // the EventDispatcher used by the HttpKernel
     $dispatcher = ...;
diff --git a/components/serializer.rst b/components/serializer.rst
index 3a2de500aa6..4eba1055433 100644
--- a/components/serializer.rst
+++ b/components/serializer.rst
@@ -29,8 +29,6 @@ Installation
 
     $ composer require symfony/serializer
 
-Alternatively, you can clone the `<https://github.com/symfony/serializer>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 To use the ``ObjectNormalizer``, the :doc:`PropertyAccess component </components/property_access>`
@@ -41,18 +39,20 @@ Usage
 
 .. seealso::
 
-    This article explains how to use the Serializer features as an independent
-    component in any PHP application. Read the :doc:`/serializer` article to
-    learn about how to use it in Symfony applications.
+    This article explains the philosophy of the Serializer and gets you familiar
+    with the concepts of normalizers and encoders. The code examples assume
+    that you use the Serializer as an independent component. If you are using
+    the Serializer in a Symfony application, read :doc:`/serializer` after you
+    finish this article.
 
 To use the Serializer component, set up the
 :class:`Symfony\\Component\\Serializer\\Serializer` specifying which encoders
 and normalizer are going to be available::
 
-    use Symfony\Component\Serializer\Serializer;
-    use Symfony\Component\Serializer\Encoder\XmlEncoder;
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
+    use Symfony\Component\Serializer\Encoder\XmlEncoder;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
 
     $encoders = [new XmlEncoder(), new JsonEncoder()];
     $normalizers = [new ObjectNormalizer()];
@@ -212,6 +212,22 @@ The serializer can also be used to update an existing object::
 
 This is a common need when working with an ORM.
 
+The ``OBJECT_TO_POPULATE`` is only used for the top level object. If that object
+is the root of a tree structure, all child elements that exist in the
+normalized data will be re-created with new instances.
+
+When the ``AbstractObjectNormalizer::DEEP_OBJECT_TO_POPULATE`` option is set to
+true, existing children of the root ``OBJECT_TO_POPULATE`` are updated from the
+normalized data, instead of the denormalizer re-creating them. Note that
+``DEEP_OBJECT_TO_POPULATE`` only works for single child objects, but not for
+arrays of objects. Those will still be replaced when present in the normalized
+data.
+
+.. versionadded:: 4.3
+
+    The ``AbstractObjectNormalizer::DEEP_OBJECT_TO_POPULATE`` option was
+    introduced in Symfony 4.3.
+
 .. _component-serializer-attributes-groups:
 
 Attributes Groups
@@ -245,23 +261,30 @@ The definition of serialization can be specified using annotations, XML
 or YAML. The :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory`
 that will be used by the normalizer must be aware of the format to use.
 
-Initialize the :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory`
-like the following::
+The following code shows how to initialize the :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory`
+for each format:
+
+* Annotations in PHP files::
 
-    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
-    // For annotations
     use Doctrine\Common\Annotations\AnnotationReader;
+    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
     use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;
-    // For XML
-    // use Symfony\Component\Serializer\Mapping\Loader\XmlFileLoader;
-    // For YAML
-    // use Symfony\Component\Serializer\Mapping\Loader\YamlFileLoader;
 
     $classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
-    // For XML
-    // $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
-    // For YAML
-    // $classMetadataFactory = new ClassMetadataFactory(new YamlFileLoader('/path/to/your/definition.yaml'));
+
+* YAML files::
+
+    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
+    use Symfony\Component\Serializer\Mapping\Loader\YamlFileLoader;
+
+    $classMetadataFactory = new ClassMetadataFactory(new YamlFileLoader('/path/to/your/definition.yaml'));
+
+* XML files::
+
+    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
+    use Symfony\Component\Serializer\Mapping\Loader\XmlFileLoader;
+
+    $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
 
 .. _component-serializer-attributes-groups-annotations:
 
@@ -308,7 +331,7 @@ Then, create your groups definition:
         <serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
-                http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
+                https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
         >
             <class name="Acme\MyObj">
                 <attribute name="foo">
@@ -324,8 +347,8 @@ Then, create your groups definition:
 
 You are now able to serialize only attributes in the groups you want::
 
-    use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
 
     $obj = new MyObj();
     $obj->foo = 'foo';
@@ -334,7 +357,7 @@ You are now able to serialize only attributes in the groups you want::
     $normalizer = new ObjectNormalizer($classMetadataFactory);
     $serializer = new Serializer([$normalizer]);
 
-    $data = $serializer->normalize($obj, null, ['groups' => ['group1']]);
+    $data = $serializer->normalize($obj, null, ['groups' => 'group1']);
     // $data = ['foo' => 'foo'];
 
     $obj2 = $serializer->denormalize(
@@ -354,8 +377,8 @@ Selecting Specific Attributes
 
 It is also possible to serialize only a set of specific attributes::
 
-    use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
 
     class User
     {
@@ -392,26 +415,30 @@ As for groups, attributes can be selected during both the serialization and dese
 Ignoring Attributes
 -------------------
 
-.. note::
-
-    Using attribute groups instead of the :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setIgnoredAttributes`
-    method is considered best practice.
-
-As an option, there's a way to ignore attributes from the origin object. To remove
-those attributes use the
-:method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setIgnoredAttributes`
-method on the normalizer definition::
+As an option, there's a way to ignore attributes from the origin object.
+To remove those attributes provide an array via the ``ignored_attributes``
+key in the ``context`` parameter of the desired serializer method::
 
-    use Symfony\Component\Serializer\Serializer;
+    use Acme\Person;
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
+
+    $person = new Person();
+    $person->setName('foo');
+    $person->setAge(99);
 
     $normalizer = new ObjectNormalizer();
-    $normalizer->setIgnoredAttributes(['age']);
     $encoder = new JsonEncoder();
 
     $serializer = new Serializer([$normalizer], [$encoder]);
-    $serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsperson":false}
+    $serializer->serialize($person, 'json', ['ignored_attributes' => ['age']]); // Output: {"name":"foo"}
+
+.. deprecated:: 4.2
+
+    The :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setIgnoredAttributes`
+    method that was used as an alternative to the ``ignored_attributes`` option
+    was deprecated in Symfony 4.2.
 
 .. _component-serializer-converting-property-names-when-serializing-and-deserializing:
 
@@ -478,6 +505,12 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`::
     $companyCopy = $serializer->deserialize($json, Company::class, 'json');
     // Same data as $company
 
+.. note::
+
+    You can also implement
+    :class:`Symfony\\Component\\Serializer\\NameConverter\\AdvancedNameConverterInterface`
+    to access to the current class name, format and context.
+
 .. _using-camelized-method-names-for-underscored-attributes:
 
 CamelCase to snake_case
@@ -519,6 +552,80 @@ processes::
     $anne = $normalizer->denormalize(['first_name' => 'Anne'], 'Person');
     // Person object with firstName: 'Anne'
 
+Configure name conversion using metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using this component inside a Symfony application and the class metadata
+factory is enabled as explained in the :ref:`Attributes Groups section <component-serializer-attributes-groups>`,
+this is already set up and you only need to provide the configuration. Otherwise::
+
+    // ...
+    use Symfony\Component\Serializer\Encoder\JsonEncoder;
+    use Symfony\Component\Serializer\NameConverter\MetadataAwareNameConverter;
+    use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
+
+    $classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
+
+    $metadataAwareNameConverter = new MetadataAwareNameConverter($classMetadataFactory);
+
+    $serializer = new Serializer(
+        [new ObjectNormalizer($classMetadataFactory, $metadataAwareNameConverter)],
+        ['json' => new JsonEncoder()]
+    );
+
+Now configure your name conversion mapping. Consider an application that
+defines a ``Person`` entity with a ``firstName`` property:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        namespace App\Entity;
+
+        use Symfony\Component\Serializer\Annotation\SerializedName;
+
+        class Person
+        {
+            /**
+             * @SerializedName("customer_name")
+             */
+            private $firstName;
+
+            public function __construct($firstName)
+            {
+                $this->firstName = $firstName;
+            }
+
+            // ...
+        }
+
+    .. code-block:: yaml
+
+        App\Entity\Person:
+            attributes:
+                firstName:
+                    serialized_name: customer_name
+
+    .. code-block:: xml
+
+        <?xml version="1.0" ?>
+        <serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
+                https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
+        >
+            <class name="App\Entity\Person">
+                <attribute name="firstName" serialized-name="customer_name"/>
+            </class>
+        </serializer>
+
+This custom mapping is used to convert property names when serializing and
+deserializing objects::
+
+    $serialized = $serializer->serialize(new Person("Kévin"));
+    // {"customer_name": "Kévin"}
+
 Serializing Boolean Attributes
 ------------------------------
 
@@ -532,6 +639,12 @@ and ``remove``.
 Using Callbacks to Serialize Properties with Object Instances
 -------------------------------------------------------------
 
+.. deprecated:: 4.2
+
+    The :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setCallbacks`
+    method is deprecated since Symfony 4.2. Use the ``callbacks``
+    key of the context instead.
+
 When serializing, you can set a callback to format a specific object property::
 
     use App\Model\Person;
@@ -540,15 +653,19 @@ When serializing, you can set a callback to format a specific object property::
     use Symfony\Component\Serializer\Serializer;
 
     $encoder = new JsonEncoder();
-    $normalizer = new GetSetMethodNormalizer();
 
-    $callback = function ($dateTime) {
-        return $dateTime instanceof \DateTime
-            ? $dateTime->format(\DateTime::ISO8601)
-            : '';
+    // all callback parameters are optional (you can omit the ones you don't use)
+    $dateCallback = function ($innerObject, $outerObject, string $attributeName, string $format = null, array $context = []) {
+        return $innerObject instanceof \DateTime ? $innerObject->format(\DateTime::ISO8601) : '';
     };
 
-    $normalizer->setCallbacks(['createdAt' => $callback]);
+    $defaultContext = [
+        AbstractNormalizer::CALLBACKS => [
+            'createdAt' => $dateCallback,
+        ],
+    ];
+
+    $normalizer = new GetSetMethodNormalizer(null, null, null, null, null, $defaultContext);
 
     $serializer = new Serializer([$normalizer], [$encoder]);
 
@@ -560,6 +677,11 @@ When serializing, you can set a callback to format a specific object property::
     $serializer->serialize($person, 'json');
     // Output: {"name":"cordoval", "age": 34, "createdAt": "2014-03-22T09:43:12-0500"}
 
+.. deprecated:: 4.2
+
+    The :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setCallbacks` is deprecated since
+    Symfony 4.2, use the "callbacks" key of the context instead.
+
 .. _component-serializer-normalizers:
 
 Normalizers
@@ -574,7 +696,7 @@ There are several types of normalizers available:
     calling the constructor during the denormalization process.
 
     Objects are normalized to a map of property names and values (names are
-    generated removing the ``get``, ``set``, ``has`` or ``remove`` prefix from
+    generated removing the ``get``, ``set``, ``has``, ``is`` or ``remove`` prefix from
     the method name and lowercasing the first letter; e.g. ``getFirstName()`` ->
     ``firstName``).
 
@@ -613,7 +735,7 @@ There are several types of normalizers available:
 :class:`Symfony\\Component\\Serializer\\Normalizer\\DateTimeNormalizer`
     This normalizer converts :phpclass:`DateTimeInterface` objects (e.g.
     :phpclass:`DateTime` and :phpclass:`DateTimeImmutable`) into strings.
-    By default it uses the RFC3339_ format.
+    By default, it uses the `RFC3339`_ format.
 
 :class:`Symfony\\Component\\Serializer\\Normalizer\\DataUriNormalizer`
     This normalizer converts :phpclass:`SplFileInfo` objects into a data URI
@@ -621,17 +743,13 @@ There are several types of normalizers available:
 
 :class:`Symfony\\Component\\Serializer\\Normalizer\\DateIntervalNormalizer`
     This normalizer converts :phpclass:`DateInterval` objects into strings.
-    By default it uses the ``P%yY%mM%dDT%hH%iM%sS`` format.
+    By default, it uses the ``P%yY%mM%dDT%hH%iM%sS`` format.
 
 :class:`Symfony\\Component\\Serializer\\Normalizer\\ConstraintViolationListNormalizer`
     This normalizer converts objects that implement
     :class:`Symfony\\Component\\Validator\\ConstraintViolationListInterface`
     into a list of errors according to the `RFC 7807`_ standard.
 
-    .. versionadded:: 4.1
-
-        The ``ConstraintViolationListNormalizer`` was introduced in Symfony 4.1.
-
 .. _component-serializer-encoders:
 
 Encoders
@@ -645,9 +763,9 @@ for encoding (array to format) and
 
 You can add new encoders to a Serializer instance by using its second constructor argument::
 
-    use Symfony\Component\Serializer\Serializer;
-    use Symfony\Component\Serializer\Encoder\XmlEncoder;
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
+    use Symfony\Component\Serializer\Encoder\XmlEncoder;
+    use Symfony\Component\Serializer\Serializer;
 
     $encoders = [new XmlEncoder(), new JsonEncoder()];
     $serializer = new Serializer([], $encoders);
@@ -658,17 +776,17 @@ Built-in Encoders
 The Serializer component provides several built-in encoders:
 
 :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`
-    This class encodes and decodes data in JSON_.
+    This class encodes and decodes data in `JSON`_.
 
 :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`
-    This class encodes and decodes data in XML_.
+    This class encodes and decodes data in `XML`_.
 
 :class:`Symfony\\Component\\Serializer\\Encoder\\YamlEncoder`
-    This encoder encodes and decodes data in YAML_. This encoder requires the
+    This encoder encodes and decodes data in `YAML`_. This encoder requires the
     :doc:`Yaml Component </components/yaml>`.
 
 :class:`Symfony\\Component\\Serializer\\Encoder\\CsvEncoder`
-    This encoder encodes and decodes data in CSV_.
+    This encoder encodes and decodes data in `CSV`_.
 
 All these encoders are enabled by default when using the Serializer component
 in a Symfony application.
@@ -687,8 +805,9 @@ The ``CsvEncoder`` encodes to and decodes from CSV.
 You can pass the context key ``as_collection`` in order to have the results
 always as a collection.
 
-.. versionadded:: 4.1
-    The ``as_collection`` option was introduced in Symfony 4.1.
+.. deprecated:: 4.2
+
+    Relying on the default value ``false`` is deprecated since Symfony 4.2.
 
 The ``XmlEncoder``
 ~~~~~~~~~~~~~~~~~~
@@ -708,30 +827,33 @@ The ``XmlEncoder`` will encode this object like that::
         <bar>1</bar>
     </response>
 
-Be aware that this encoder will consider keys beginning with ``@`` as attributes::
+Be aware that this encoder will consider keys beginning with ``@`` as attributes, and will use
+the key  ``#comment`` for encoding XML comments::
 
     $encoder = new XmlEncoder();
-    $encoder->encode(['foo' => ['@bar' => 'value']], 'xml');
+    $encoder->encode([
+        'foo' => ['@bar' => 'value'],
+        'qux' => ['#comment' => 'A comment'],
+    ], 'xml');
     // will return:
     // <?xml version="1.0"?>
     // <response>
-    //     <foo bar="value" />
+    //     <foo bar="value"/>
+    //     <qux><!-- A comment --!><qux>
     // </response>
 
 You can pass the context key ``as_collection`` in order to have the results
 always as a collection.
 
-.. versionadded:: 4.1
-    The ``as_collection`` option was introduced in Symfony 4.1.
-
 .. tip::
 
     XML comments are ignored by default when decoding contents, but this
-    behavior can be changed with the optional ``$ignoredNodeTypes`` argument of
+    behavior can be changed with the optional ``$decoderIgnoredNodeTypes`` argument of
     the ``XmlEncoder`` class constructor.
 
-    .. versionadded:: 4.1
-        XML comments are ignored by default starting from Symfony 4.1.
+    Data with ``#comment`` keys are encoded to XML comments by default. This can be
+    changed with the optional ``$encoderIgnoredNodeTypes`` argument of the
+    ``XmlEncoder`` class constructor.
 
 The ``YamlEncoder``
 ~~~~~~~~~~~~~~~~~~~
@@ -739,6 +861,22 @@ The ``YamlEncoder``
 This encoder requires the :doc:`Yaml Component </components/yaml>` and
 transforms from and to Yaml.
 
+Skipping ``null`` Values
+------------------------
+
+By default, the Serializer will preserve properties containing a ``null`` value.
+You can change this behavior by setting the ``skip_null_values`` context option
+to ``true``::
+
+    $dummy = new class {
+        public $foo;
+        public $bar = 'notNull';
+    };
+
+    $normalizer = new ObjectNormalizer();
+    $result = $normalizer->normalize($dummy, 'json', ['skip_null_values' => true]);
+    // ['bar' => 'notNull']
+
 .. _component-serializer-handling-circular-references:
 
 Handling Circular References
@@ -814,25 +952,32 @@ when such a case is encountered::
 
     echo $serializer->serialize($organization, 'json'); // Throws a CircularReferenceException
 
-The ``setCircularReferenceLimit()`` method of this normalizer sets the number
-of times it will serialize the same object before considering it a circular
-reference. Its default value is ``1``.
+The key ``circular_reference_limit`` in the default context sets the number of
+times it will serialize the same object before considering it a circular
+reference. The default value is ``1``.
 
 Instead of throwing an exception, circular references can also be handled
 by custom callables. This is especially useful when serializing entities
 having unique identifiers::
 
     $encoder = new JsonEncoder();
-    $normalizer = new ObjectNormalizer();
-
-    $normalizer->setCircularReferenceHandler(function ($object) {
-        return $object->getName();
-    });
+    $defaultContext = [
+        AbstractNormalizer::CIRCULAR_REFERENCE_HANDLER => function ($object, $format, $context) {
+            return $object->getName();
+        },
+    ];
+    $normalizer = new ObjectNormalizer(null, null, null, null, null, null, $defaultContext);
 
     $serializer = new Serializer([$normalizer], [$encoder]);
     var_dump($serializer->serialize($org, 'json'));
     // {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"}]}
 
+.. deprecated:: 4.2
+
+    The :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setCircularReferenceHandler`
+    method is deprecated since Symfony 4.2. Use the ``circular_reference_handler``
+    key of the context instead.
+
 Handling Serialization Depth
 ----------------------------
 
@@ -870,10 +1015,10 @@ Here, we set it to 2 for the ``$child`` property:
 
     .. code-block:: php-annotations
 
-        use Symfony\Component\Serializer\Annotation\MaxDepth;
-
         namespace Acme;
 
+        use Symfony\Component\Serializer\Annotation\MaxDepth;
+
         class MyObj
         {
             /**
@@ -897,10 +1042,10 @@ Here, we set it to 2 for the ``$child`` property:
         <serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
-                http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
+                https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
         >
             <class name="Acme\MyObj">
-                <attribute name="child" max-depth="2" />
+                <attribute name="child" max-depth="2"/>
             </class>
         </serializer>
 
@@ -919,11 +1064,11 @@ because it is deeper than the configured maximum depth of 2::
     $result = [
         'foo' => 'level1',
         'child' => [
-                'foo' => 'level2',
-                'child' => [
-                        'child' => null,
-                    ],
+            'foo' => 'level2',
+            'child' => [
+                'child' => null,
             ],
+        ],
     ];
     */
 
@@ -932,11 +1077,11 @@ maximum depth is reached. This is especially useful when serializing entities
 having unique identifiers::
 
     use Doctrine\Common\Annotations\AnnotationReader;
-    use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Annotation\MaxDepth;
     use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
     use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
 
     class Foo
     {
@@ -960,10 +1105,16 @@ having unique identifiers::
     $level2->child = $level3;
 
     $classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
-    $normalizer = new ObjectNormalizer($classMetadataFactory);
-    $normalizer->setMaxDepthHandler(function ($foo) {
-        return '/foos/'.$foo->id;
-    });
+
+    // all callback parameters are optional (you can omit the ones you don't use)
+    $maxDepthHandler = function ($innerObject, $outerObject, string $attributeName, string $format = null, array $context = []) {
+        return '/foos/'.$innerObject->id;
+    };
+
+    $defaultContext = [
+        AbstractObjectNormalizer::MAX_DEPTH_HANDLER => $maxDepthHandler,
+    ];
+    $normalizer = new ObjectNormalizer($classMetadataFactory, null, null, null, null, null, $defaultContext);
 
     $serializer = new Serializer([$normalizer]);
 
@@ -978,8 +1129,11 @@ having unique identifiers::
     ];
     */
 
-.. versionadded:: 4.1
-    The ``setMaxDepthHandler()`` method was introduced in Symfony 4.1.
+.. deprecated:: 4.2
+
+    The :method:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer::setMaxDepthHandler`
+    method is deprecated since Symfony 4.2. Use the ``max_depth_handler``
+    key of the context instead.
 
 Handling Arrays
 ---------------
@@ -1008,9 +1162,7 @@ If you want to deserialize such a structure, you need to add the
 :class:`Symfony\\Component\\Serializer\\Normalizer\\ArrayDenormalizer`
 to the set of normalizers. By appending ``[]`` to the type parameter of the
 :method:`Symfony\\Component\\Serializer\\Serializer::deserialize` method,
-you indicate that you're expecting an array instead of a single object.
-
-.. code-block:: php
+you indicate that you're expecting an array instead of a single object::
 
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
     use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
@@ -1051,7 +1203,7 @@ The array keys beginning with ``@`` are considered XML attributes::
     // is encoded as follows:
     // <?xml version="1.0"?>
     // <response>
-    //     <foo bar="value" />
+    //     <foo bar="value"/>
     // </response>
 
 Use the special ``#`` key to define the data of a node::
@@ -1097,16 +1249,13 @@ These are the options available:
 Handling Constructor Arguments
 ------------------------------
 
-.. versionadded:: 4.1
-    The ``default_constructor_arguments`` option was introduced in Symfony 4.1.
-
 If the class constructor defines arguments, as usually happens with
 `Value Objects`_, the serializer won't be able to create the object if some
 arguments are missing. In those cases, use the ``default_constructor_arguments``
 context option::
 
-    use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
 
     class MyObj
     {
@@ -1144,12 +1293,12 @@ When using the component standalone, an implementation of :class:`Symfony\\Compo
 (usually an instance of :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`) must be passed as the 4th
 parameter of the ``ObjectNormalizer``::
 
+    namespace Acme;
+
     use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
-    use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
-
-    namespace Acme;
+    use Symfony\Component\Serializer\Serializer;
 
     class ObjectOuter
     {
@@ -1188,7 +1337,7 @@ parameter of the ``ObjectNormalizer``::
 
     $obj = $serializer->denormalize(
         ['inner' => ['foo' => 'foo', 'bar' => 'bar'], 'date' => '1988/01/21'],
-         'Acme\ObjectOuter'
+        'Acme\ObjectOuter'
     );
 
     dump($obj->getInner()->foo); // 'foo'
@@ -1225,8 +1374,8 @@ this is already set up and you only need to provide the configuration. Otherwise
 
     // ...
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
-    use Symfony\Component\Serializer\Mapping\ClassDiscriminatorMapping;
     use Symfony\Component\Serializer\Mapping\ClassDiscriminatorFromClassMetadata;
+    use Symfony\Component\Serializer\Mapping\ClassDiscriminatorMapping;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     use Symfony\Component\Serializer\Serializer;
 
@@ -1277,12 +1426,12 @@ and ``BitBucketCodeRepository`` classes:
         <serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
-                http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
+                https://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
         >
             <class name="App\CodeRepository">
                 <discriminator-map type-property="type">
-                    <mapping type="github" class="App\GitHubCodeRepository" />
-                    <mapping type="bitbucket" class="App\BitBucketCodeRepository" />
+                    <mapping type="github" class="App\GitHubCodeRepository"/>
+                    <mapping type="bitbucket" class="App\BitBucketCodeRepository"/>
                 </discriminator-map>
             </class>
         </serializer>
@@ -1316,7 +1465,7 @@ and return ``true`` when
 :method:`Symfony\\Component\\Serializer\\Normalizer\\CacheableSupportsMethodInterface::hasCacheableSupportsMethod`
 is called.
 
- .. note::
+.. note::
 
     All built-in :ref:`normalizers and denormalizers <component-serializer-normalizers>`
     as well the ones included in `API Platform`_ natively implement this interface.
@@ -1333,7 +1482,7 @@ Learn more
 .. seealso::
 
     Normalizers for the Symfony Serializer Component supporting popular web API formats
-    (JSON-LD, GraphQL, HAL and JSONAPI) are available as part of the `API Platform`_ project.
+    (JSON-LD, GraphQL, OpenAPI, HAL, JSON:API) are available as part of the `API Platform`_ project.
 
 .. seealso::
 
@@ -1343,7 +1492,6 @@ Learn more
 
 .. _`PSR-1 standard`: https://www.php-fig.org/psr/psr-1/
 .. _`JMS serializer`: https://github.com/schmittjoh/serializer
-.. _Packagist: https://packagist.org/packages/symfony/serializer
 .. _RFC3339: https://tools.ietf.org/html/rfc3339#section-5.8
 .. _JSON: http://www.json.org/
 .. _XML: https://www.w3.org/XML/
diff --git a/components/stopwatch.rst b/components/stopwatch.rst
index c792b0eb90f..a000bca1be8 100644
--- a/components/stopwatch.rst
+++ b/components/stopwatch.rst
@@ -14,14 +14,12 @@ Installation
 
     $ composer require symfony/stopwatch
 
-Alternatively, you can clone the `<https://github.com/symfony/stopwatch>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
 -----
 
-The Stopwatch component provides an easy and consistent way to measure execution
+The Stopwatch component provides a consistent way to measure execution
 time of certain parts of code so that you don't constantly have to parse
 microtime by yourself. Instead, use the
 :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class::
@@ -63,9 +61,8 @@ Symfony Profiler tool uses categories to nicely color-code different events.
 
 .. tip::
 
-    When you want to show events in the Symfony profiler, autowire
-    ``Symfony\Component\Stopwatch\Stopwatch`` into your service. Each category
-    is shown on a separate line.
+    Read :ref:`this article <profiler-timing-execution>` to learn more about
+    integrating the Stopwatch component into the Symfony profiler.
 
 Periods
 -------
@@ -122,5 +119,3 @@ method and specifying the id of the section to be reopened::
     $stopwatch->openSection('routing');
     $stopwatch->start('building_config_tree');
     $stopwatch->stopSection('routing');
-
-.. _Packagist: https://packagist.org/packages/symfony/stopwatch
diff --git a/components/templating.rst b/components/templating.rst
index 9639eb39719..ea6b8d11e83 100644
--- a/components/templating.rst
+++ b/components/templating.rst
@@ -20,8 +20,6 @@ Installation
 
     $ composer require symfony/templating
 
-Alternatively, you can clone the `<https://github.com/symfony/templating>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -41,9 +39,9 @@ template reference (:class:`Symfony\\Component\\Templating\\TemplateReferenceInt
 It also needs a template loader (:class:`Symfony\\Component\\Templating\\Loader\\LoaderInterface`)
 which uses the template reference to actually find and load the template::
 
+    use Symfony\Component\Templating\Loader\FilesystemLoader;
     use Symfony\Component\Templating\PhpEngine;
     use Symfony\Component\Templating\TemplateNameParser;
-    use Symfony\Component\Templating\Loader\FilesystemLoader;
 
     $filesystemLoader = new FilesystemLoader(__DIR__.'/views/%name%');
 
@@ -197,8 +195,8 @@ choose which one to use for the template, the
 method is used::
 
     use Acme\Templating\CustomEngine;
-    use Symfony\Component\Templating\PhpEngine;
     use Symfony\Component\Templating\DelegatingEngine;
+    use Symfony\Component\Templating\PhpEngine;
 
     $templating = new DelegatingEngine([
         new PhpEngine(...),
@@ -215,5 +213,3 @@ Learn More
     /components/templating/*
     /templating
     /templating/*
-
-.. _Packagist: https://packagist.org/packages/symfony/templating
diff --git a/components/translation.rst b/components/translation.rst
index 7b99002535e..fe7ab4c3d79 100644
--- a/components/translation.rst
+++ b/components/translation.rst
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/translation
 
-Alternatively, you can clone the `<https://github.com/symfony/translation>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 .. seealso::
@@ -162,12 +160,17 @@ Fallback Locales
 
 If the message is not located in the catalog of the specific locale, the
 translator will look into the catalog of one or more fallback locales. For
-example, assume you're trying to translate into the ``fr_FR`` locale:
+example, assume you're trying to translate into the ``es_AR`` locale:
+
+#. First, the translator looks for the translation in the ``es_AR``
+   (Argentinean Spanish) locale;
 
-#. First, the translator looks for the translation in the ``fr_FR`` locale;
+#. If it wasn't found, the translator looks for the translation in the parent
+   locale, which is automatically defined only for some locales. In this
+   example, the parent locale is ``es_419`` (Latin American Spanish);
 
-#. If it wasn't found, the translator looks for the translation in the ``fr``
-   locale;
+#. If it wasn't found, the translator looks for the translation in the ``es``
+   (Spanish) locale;
 
 #. If the translation still isn't found, the translator uses the one or more
    fallback locales set explicitly on the translator.
@@ -229,6 +232,5 @@ Learn More
     /translation/*
     /validation/translations
 
-.. _Packagist: https://packagist.org/packages/symfony/translation
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst
index 3d90d5861f9..98721a17dec 100644
--- a/components/translation/custom_formats.rst
+++ b/components/translation/custom_formats.rst
@@ -30,8 +30,8 @@ new class that implements the
 method will get a filename and parse it into an array. Then, it will
 create the catalog that will be returned::
 
-    use Symfony\Component\Translation\MessageCatalogue;
     use Symfony\Component\Translation\Loader\LoaderInterface;
+    use Symfony\Component\Translation\MessageCatalogue;
 
     class MyFormatLoader implements LoaderInterface
     {
@@ -80,8 +80,8 @@ must be created. To write the dump contents into a file, extending the
 :class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class
 will save a few lines::
 
-    use Symfony\Component\Translation\MessageCatalogue;
     use Symfony\Component\Translation\Dumper\FileDumper;
+    use Symfony\Component\Translation\MessageCatalogue;
 
     class MyFormatDumper extends FileDumper
     {
diff --git a/components/translation/usage.rst b/components/translation/usage.rst
index 6391a9db1a0..e9fa2a6bdcb 100644
--- a/components/translation/usage.rst
+++ b/components/translation/usage.rst
@@ -6,8 +6,8 @@ Using the Translator
 
 Imagine you want to translate the string *"Symfony is great"* into French::
 
-    use Symfony\Component\Translation\Translator;
     use Symfony\Component\Translation\Loader\ArrayLoader;
+    use Symfony\Component\Translation\Translator;
 
     $translator = new Translator('fr_FR');
     $translator->addLoader('array', new ArrayLoader());
@@ -21,79 +21,6 @@ In this example, the message *"Symfony is great!"* will be translated into
 the locale set in the constructor (``fr_FR``) if the message exists in one of
 the message catalogs.
 
-.. _component-translation-placeholders:
-
-Message Placeholders
---------------------
-
-Sometimes, a message containing a variable needs to be translated::
-
-    // ...
-    $translated = $translator->trans('Hello '.$name);
-
-    var_dump($translated);
-
-However, creating a translation for this string is impossible since the translator
-will try to look up the exact message, including the variable portions
-(e.g. *"Hello Ryan"* or *"Hello Fabien"*). Instead of writing a translation
-for every possible iteration of the ``$name`` variable, you can replace the
-variable with a "placeholder"::
-
-    // ...
-    $translated = $translator->trans(
-        'Hello %name%',
-        ['%name%' => $name]
-    );
-
-    var_dump($translated);
-
-Symfony will now look for a translation of the raw message (``Hello %name%``)
-and *then* replace the placeholders with their values. Creating a translation
-is done just as before:
-
-.. configuration-block::
-
-    .. code-block:: xml
-
-        <?xml version="1.0"?>
-        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
-            <file source-language="en" datatype="plaintext" original="file.ext">
-                <body>
-                    <trans-unit id="1">
-                        <source>Hello %name%</source>
-                        <target>Bonjour %name%</target>
-                    </trans-unit>
-                </body>
-            </file>
-        </xliff>
-
-    .. code-block:: php
-
-        return [
-            'Hello %name%' => 'Bonjour %name%',
-        ];
-
-    .. code-block:: yaml
-
-        'Hello %name%': Bonjour %name%
-
-.. note::
-
-    The placeholders can take on any form as the full message is reconstructed
-    using the PHP :phpfunction:`strtr function<strtr>`. But the ``%...%`` form
-    is recommended, to avoid problems when using Twig.
-
-As you've seen, creating a translation is a two-step process:
-
-#. Abstract the message that needs to be translated by processing it through
-   the ``Translator``.
-
-#. Create a translation for the message in each locale that you choose to
-   support.
-
-The second step is done by creating message catalogs that define the translations
-for any number of different locales.
-
 Creating Translations
 ---------------------
 
@@ -104,7 +31,7 @@ for the individual translation, and can be the message in the main locale (e.g.
 *"Symfony is great"*) of your application or a unique identifier (e.g.
 ``symfony.great`` - see the sidebar below).
 
-Translation files can be created in several different formats, XLIFF being the
+Translation files can be created in several formats, XLIFF being the
 recommended format. These files are parsed by one of the loader classes.
 
 .. configuration-block::
@@ -194,7 +121,7 @@ recommended format. These files are parsed by one of the loader classes.
                     'has' => [
                         'bundles' => 'Symfony has bundles',
                     ],
-                ),
+                ],
                 'user' => [
                     'login' => 'Login',
                 ],
@@ -222,141 +149,6 @@ recommended format. These files are parsed by one of the loader classes.
                 'user.login'          => 'Login',
             ];
 
-.. _component-translation-pluralization:
-
-Pluralization
--------------
-
-Message pluralization is a tough topic as the rules can be quite complex. For
-instance, here is the mathematical representation of the Russian pluralization
-rules::
-
-    (($number % 10 == 1) && ($number % 100 != 11))
-        ? 0
-        : ((($number % 10 >= 2)
-            && ($number % 10 <= 4)
-            && (($number % 100 < 10)
-            || ($number % 100 >= 20)))
-                ? 1
-                : 2
-    );
-
-As you can see, in Russian, you can have three different plural forms, each
-given an index of 0, 1 or 2. For each form, the plural is different, and
-so the translation is also different.
-
-When a translation has different forms due to pluralization, you can provide
-all the forms as a string separated by a pipe (``|``)::
-
-    'There is one apple|There are %count% apples'
-
-To translate pluralized messages, use the
-:method:`Symfony\\Component\\Translation\\Translator::transChoice` method::
-
-    // the %count% placeholder is assigned to the second argument...
-    $translator->transChoice(
-        'There is one apple|There are %count% apples',
-        10
-    );
-
-    // ...but you can define more placeholders if needed
-    $translator->transChoice(
-        'Hurry up %name%! There is one apple left.|There are %count% apples left.',
-        10,
-        // no need to include %count% here; Symfony does that for you
-        ['%name%' => $user->getName()]
-    );
-
-The second argument (``10`` in this example) is the *number* of objects being
-described and is used to determine which translation to use and also to populate
-the ``%count%`` placeholder.
-
-Based on the given number, the translator chooses the right plural form.
-In English, most words have a singular form when there is exactly one object
-and a plural form for all other numbers (0, 2, 3...). So, if ``count`` is
-``1``, the translator will use the first string (``There is one apple``)
-as the translation. Otherwise it will use ``There are %count% apples``.
-
-Here is the French translation:
-
-.. code-block:: text
-
-    'Il y a %count% pomme|Il y a %count% pommes'
-
-Even if the string looks similar (it is made of two sub-strings separated by a
-pipe), the French rules are different: the first form (no plural) is used when
-``count`` is ``0`` or ``1``. So, the translator will automatically use the
-first string (``Il y a %count% pomme``) when ``count`` is ``0`` or ``1``.
-
-Each locale has its own set of rules, with some having as many as six different
-plural forms with complex rules behind which numbers map to which plural form.
-The rules are quite simple for English and French, but for Russian, you'd
-may want a hint to know which rule matches which string. To help translators,
-you can optionally "tag" each string:
-
-.. code-block:: text
-
-    'one: There is one apple|some: There are %count% apples'
-
-    'none_or_one: Il y a %count% pomme|some: Il y a %count% pommes'
-
-The tags are really only hints for translators and don't affect the logic
-used to determine which plural form to use. The tags can be any descriptive
-string that ends with a colon (``:``). The tags also do not need to be the
-same in the original message as in the translated one.
-
-.. tip::
-
-    As tags are optional, the translator doesn't use them (the translator will
-    only get a string based on its position in the string).
-
-Explicit Interval Pluralization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The easiest way to pluralize a message is to let the Translator use internal
-logic to choose which string to use based on a given number. Sometimes, you'll
-need more control or want a different translation for specific cases (for
-``0``, or when the count is negative, for example). For such cases, you can
-use explicit math intervals:
-
-.. code-block:: text
-
-    '{0} There are no apples|{1} There is one apple|]1,19] There are %count% apples|[20,Inf[ There are many apples'
-
-The intervals follow the `ISO 31-11`_ notation. The above string specifies
-four different intervals: exactly ``0``, exactly ``1``, ``2-19``, and ``20``
-and higher.
-
-You can also mix explicit math rules and standard rules. In this case, if
-the count is not matched by a specific interval, the standard rules take
-effect after removing the explicit rules:
-
-.. code-block:: text
-
-    '{0} There are no apples|[20,Inf[ There are many apples|There is one apple|a_few: There are %count% apples'
-
-For example, for ``1`` apple, the standard rule ``There is one apple`` will
-be used. For ``2-19`` apples, the second standard rule
-``There are %count% apples`` will be selected.
-
-An :class:`Symfony\\Component\\Translation\\Interval` can represent a finite set
-of numbers:
-
-.. code-block:: text
-
-    {1,2,3,4}
-
-Or numbers between two other numbers:
-
-.. code-block:: text
-
-    [1, +Inf[
-    ]-1,2[
-
-The left delimiter can be ``[`` (inclusive) or ``]`` (exclusive). The right
-delimiter can be ``[`` (exclusive) or ``]`` (inclusive). Beside numbers, you
-can use ``-Inf`` and ``+Inf`` for the infinite.
-
 Forcing the Translator Locale
 -----------------------------
 
@@ -431,30 +223,30 @@ loaded/dumped when using this component inside a Symfony application:
 
 .. code-block:: xml
 
-    <?xml version="1.0" encoding="utf-8"?>
+    <?xml version="1.0" encoding="UTF-8"?>
     <xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0"
-           srcLang="fr-FR" trgLang="en-US">
-      <file id="messages.en_US">
-        <unit id="LCa0a2j" name="original-content">
-          <notes>
-            <note category="state">new</note>
-            <note category="approved">true</note>
-            <note category="section" priority="1">user login</note>
-          </notes>
-          <segment>
-            <source>original-content</source>
-            <target>translated-content</target>
-          </segment>
-        </unit>
-      </file>
+        srcLang="fr-FR" trgLang="en-US">
+        <file id="messages.en_US">
+            <unit id="LCa0a2j" name="original-content">
+                <notes>
+                    <note category="state">new</note>
+                    <note category="approved">true</note>
+                    <note category="section" priority="1">user login</note>
+                </notes>
+                <segment>
+                    <source>original-content</source>
+                    <target>translated-content</target>
+                </segment>
+            </unit>
+        </file>
     </xliff>
 
 When using the standalone Translation component, call the ``setMetadata()``
 method of the catalogue and pass the notes as arrays. This is for example the
 code needed to generate the previous XLIFF file::
 
-    use Symfony\Component\Translation\MessageCatalogue;
     use Symfony\Component\Translation\Dumper\XliffFileDumper;
+    use Symfony\Component\Translation\MessageCatalogue;
 
     $catalogue = new MessageCatalogue('en_US');
     $catalogue->add([
@@ -473,4 +265,3 @@ code needed to generate the previous XLIFF file::
     ]);
 
 .. _`L10n`: https://en.wikipedia.org/wiki/Internationalization_and_localization
-.. _`ISO 31-11`: https://en.wikipedia.org/wiki/Interval_(mathematics)#Notations_for_intervals
diff --git a/components/using_components.rst b/components/using_components.rst
index d63a0313363..0b77e4f6a4e 100644
--- a/components/using_components.rst
+++ b/components/using_components.rst
@@ -59,7 +59,7 @@ immediately::
 Now what?
 ---------
 
-Now that the component is installed and autoloaded, read the specific component's
+Now, the component is installed and autoloaded. Read the specific component's
 documentation to find out more about how to use it.
 
 And have fun!
diff --git a/components/validator.rst b/components/validator.rst
index 77b531fc5f8..9028f8d6874 100644
--- a/components/validator.rst
+++ b/components/validator.rst
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/validator
 
-Alternatively, you can clone the `<https://github.com/symfony/validator>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -36,9 +34,9 @@ The Validator component behavior is based on two concepts:
 The following example shows how to validate that a string is at least 10
 characters long::
 
-    use Symfony\Component\Validator\Validation;
     use Symfony\Component\Validator\Constraints\Length;
     use Symfony\Component\Validator\Constraints\NotBlank;
+    use Symfony\Component\Validator\Validation;
 
     $validator = Validation::createValidator();
     $violations = $validator->validate('Bernhard', [
@@ -91,4 +89,3 @@ Learn More
     /validation/*
 
 .. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303
-.. _Packagist: https://packagist.org/packages/symfony/validator
diff --git a/components/validator/metadata.rst b/components/validator/metadata.rst
index 77c4037cc48..f5df3fa68de 100755
--- a/components/validator/metadata.rst
+++ b/components/validator/metadata.rst
@@ -15,8 +15,8 @@ The following example shows how to validate that the ``$firstName`` property of
 the ``Author`` class has at least 3 characters::
 
     // ...
-    use Symfony\Component\Validator\Mapping\ClassMetadata;
     use Symfony\Component\Validator\Constraints as Assert;
+    use Symfony\Component\Validator\Mapping\ClassMetadata;
 
     class Author
     {
@@ -51,8 +51,8 @@ doesn't match the first name of the user. First, create a public method called
 Then, add the Validator component configuration to the class::
 
     // ...
-    use Symfony\Component\Validator\Mapping\ClassMetadata;
     use Symfony\Component\Validator\Constraints as Assert;
+    use Symfony\Component\Validator\Mapping\ClassMetadata;
 
     class Author
     {
@@ -85,8 +85,8 @@ validation logic::
 Then, add the Validator component configuration to the class::
 
     // ...
-    use Symfony\Component\Validator\Mapping\ClassMetadata;
     use Symfony\Component\Validator\Constraints as Assert;
+    use Symfony\Component\Validator\Mapping\ClassMetadata;
 
     class Author
     {
diff --git a/components/validator/resources.rst b/components/validator/resources.rst
index 69feb66243c..a7cf3678c9d 100644
--- a/components/validator/resources.rst
+++ b/components/validator/resources.rst
@@ -35,8 +35,8 @@ method of the validator builder::
 In this example, the validation metadata is retrieved executing the
 ``loadValidatorMetadata()`` method of the class::
 
-    use Symfony\Component\Validator\Mapping\ClassMetadata;
     use Symfony\Component\Validator\Constraints as Assert;
+    use Symfony\Component\Validator\Mapping\ClassMetadata;
 
     class User
     {
@@ -71,7 +71,7 @@ configure the locations of these files::
     use Symfony\Component\Validator\Validation;
 
     $validator = Validation::createValidatorBuilder()
-        ->addYamlMapping('config/validation.yaml')
+        ->addYamlMapping('validator/validation.yaml')
         ->getValidator();
 
 .. note::
@@ -100,8 +100,8 @@ prefixed classes included in doc block comments (``/** ... */``). For example::
     class User
     {
         /**
-        * @Assert\NotBlank
-        */
+         * @Assert\NotBlank
+         */
         protected $name;
     }
 
@@ -136,7 +136,7 @@ multiple mappings::
     $validator = Validation::createValidatorBuilder()
         ->enableAnnotationMapping()
         ->addMethodMapping('loadValidatorMetadata')
-        ->addXmlMapping('config/validation.xml')
+        ->addXmlMapping('validator/validation.xml')
         ->getValidator();
 
 Caching
@@ -192,5 +192,3 @@ You can set this custom implementation using
     Since you are using a custom metadata factory, you can't configure loaders
     and caches using the ``add*Mapping()`` methods anymore. You now have to
     inject them into your custom metadata factory yourself.
-
-.. _`Packagist`: https://packagist.org
diff --git a/components/var_dumper.rst b/components/var_dumper.rst
index 2378d6da7ec..1c48a021855 100644
--- a/components/var_dumper.rst
+++ b/components/var_dumper.rst
@@ -16,14 +16,12 @@ Installation
 
     $ composer require --dev symfony/var-dumper
 
-Alternatively, you can clone the `<https://github.com/symfony/var-dumper>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 .. note::
 
     If using it inside a Symfony application, make sure that the DebugBundle has
-    been installed (or run ``composer require symfony/debug-bundle`` to install it).
+    been installed (or run ``composer require --dev symfony/debug-bundle`` to install it).
 
 .. _components-var-dumper-dump:
 
@@ -64,6 +62,12 @@ current PHP SAPI:
   mechanism;
 * On other SAPIs, dumps are written as HTML in the regular output.
 
+.. tip::
+
+    You can also select the output format explicitly defining the
+    ``VAR_DUMPER_FORMAT`` environment variable and setting its value to either
+    ``html`` or ``cli``.
+
 .. note::
 
     If you want to catch the dump output as a string, please read the
@@ -88,17 +92,11 @@ current PHP SAPI:
     function. This function dumps the variables using ``dump()`` and
     immediately ends the execution of the script (using :phpfunction:`exit`).
 
-    .. versionadded:: 4.1
-        The ``dd()`` helper method was introduced in Symfony 4.1.
-
 .. _var-dumper-dump-server:
 
 The Dump Server
 ---------------
 
-.. versionadded:: 4.1
-    The dump server was introduced in Symfony 4.1.
-
 The ``dump()`` function outputs its contents in the same browser window or
 console terminal as your own application. Sometimes mixing the real output
 with the debug output can be confusing. That's why this component provides a
@@ -111,11 +109,11 @@ server, which outputs it to its own console or to an HTML file:
 .. code-block:: terminal
 
     # displays the dumped data in the console:
-    $ ./bin/console server:dump
+    $ php bin/console server:dump
       [OK] Server listening on tcp://0.0.0.0:9912
 
     # stores the dumped data in a file using the HTML format:
-    $ ./bin/console server:dump --format=html > dump.html
+    $ php bin/console server:dump --format=html > dump.html
 
 Inside a Symfony application, the output of the dump server is configured with
 the :ref:`dump_destination option <configuration-debug-dump_destination>` of the
@@ -137,10 +135,10 @@ the :ref:`dump_destination option <configuration-debug-dump_destination>` of the
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:debug="http://symfony.com/schema/dic/debug"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/debug http://symfony.com/schema/dic/debug/debug-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/debug https://symfony.com/schema/dic/debug/debug-1.0.xsd">
 
-            <debug:config dump-destination="tcp://%env(VAR_DUMPER_SERVER)%" />
+            <debug:config dump-destination="tcp://%env(VAR_DUMPER_SERVER)%"/>
         </container>
 
     .. code-block:: php
@@ -154,13 +152,13 @@ Outside a Symfony application, use the :class:`Symfony\\Component\\VarDumper\\Du
 
     require __DIR__.'/vendor/autoload.php';
 
-    use Symfony\Component\VarDumper\VarDumper;
     use Symfony\Component\VarDumper\Cloner\VarCloner;
     use Symfony\Component\VarDumper\Dumper\CliDumper;
     use Symfony\Component\VarDumper\Dumper\ContextProvider\CliContextProvider;
     use Symfony\Component\VarDumper\Dumper\ContextProvider\SourceContextProvider;
     use Symfony\Component\VarDumper\Dumper\HtmlDumper;
     use Symfony\Component\VarDumper\Dumper\ServerDumper;
+    use Symfony\Component\VarDumper\VarDumper;
 
     $cloner = new VarCloner();
     $fallbackDumper = \in_array(\PHP_SAPI, ['cli', 'phpdbg']) ? new CliDumper() : new HtmlDumper();
@@ -221,10 +219,10 @@ option. Read more about this and other options in
 
     If the dumped contents are complex, consider using the local search box to
     look for specific variables or values. First, click anywhere on the dumped
-    contents and then press :kbd:`Ctrl. + F` or :kbd:`Cmd. + F` to make the local
+    contents and then press ``Ctrl. + F`` or ``Cmd. + F`` to make the local
     search box appear. All the common shortcuts to navigate the search results
-    are supported (:kbd:`Ctrl. + G` or :kbd:`Cmd. + G`, :kbd:`F3`, etc.) When
-    finished, press :kbd:`Esc.` to hide the box again.
+    are supported (``Ctrl. + G`` or ``Cmd. + G``, ``F3``, etc.) When
+    finished, press ``Esc.`` to hide the box again.
 
 Using the VarDumper Component in your PHPUnit Test Suite
 --------------------------------------------------------
@@ -246,10 +244,11 @@ This will provide you with two new assertions:
 Example::
 
     use PHPUnit\Framework\TestCase;
+    use Symfony\Component\VarDumper\Test\VarDumperTestTrait;
 
     class ExampleTest extends TestCase
     {
-        use \Symfony\Component\VarDumper\Test\VarDumperTestTrait;
+        use VarDumperTestTrait;
 
         public function testWithDumpEquals()
         {
@@ -271,10 +270,6 @@ Example::
         }
     }
 
-.. versionadded:: 4.1
-    The possibility of passing non-string variables as the first argument of
-    ``assertDumpEquals()`` was introduced in Symfony 4.1.
-
 Dump Examples and Output
 ------------------------
 
@@ -411,5 +406,3 @@ Learn More
     :glob:
 
     var_dumper/*
-
-.. _Packagist: https://packagist.org/packages/symfony/var-dumper
diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst
index 34355da2f4c..c90d94e6cdb 100644
--- a/components/var_dumper/advanced.rst
+++ b/components/var_dumper/advanced.rst
@@ -15,10 +15,10 @@ By adding a handler, you can customize the `Cloners`_, `Dumpers`_ and `Casters`_
 as explained below. A simple implementation of a handler function might look
 like this::
 
-    use Symfony\Component\VarDumper\VarDumper;
     use Symfony\Component\VarDumper\Cloner\VarCloner;
     use Symfony\Component\VarDumper\Dumper\CliDumper;
     use Symfony\Component\VarDumper\Dumper\HtmlDumper;
+    use Symfony\Component\VarDumper\VarDumper;
 
     VarDumper::setHandler(function ($var) {
         $cloner = new VarCloner();
@@ -179,9 +179,16 @@ method. They also typically implement the
 them from re-implementing the logic required to walk through a
 :class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object's internal structure.
 
+The :class:`Symfony\\Component\\VarDumper\\Dumper\\HtmlDumper` uses a dark
+theme by default. Use the :method:`Symfony\\Component\\VarDumper\\Dumper\\HtmlDumper::setTheme`
+method to use a light theme::
+
+    // ...
+    $htmlDumper->setTheme('light');
+
 The :class:`Symfony\\Component\\VarDumper\\Dumper\\HtmlDumper` limits string
 length and nesting depth of the output to make it more readable. These options
-can be overriden by the third optional parameter of the
+can be overridden by the third optional parameter of the
 :method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`
 method::
 
@@ -208,23 +215,24 @@ bit field of ``Caster::EXCLUDE_*`` constants and influences the expected
 output produced by the different casters.
 
 If ``DUMP_STRING_LENGTH`` is set, then the length of a string is displayed
-next to its content:
-
-.. code-block:: php
+next to its content::
 
+    use Symfony\Component\VarDumper\Cloner\VarCloner;
     use Symfony\Component\VarDumper\Dumper\AbstractDumper;
     use Symfony\Component\VarDumper\Dumper\CliDumper;
 
+    $varCloner = new VarCloner();
     $var = ['test'];
+    
     $dumper = new CliDumper();
-    echo $dumper->dump($var, true);
+    echo $dumper->dump($varCloner->cloneVar($var), true);
 
     // array:1 [
     //   0 => "test"
     // ]
 
     $dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH);
-    echo $dumper->dump($var, true);
+    echo $dumper->dump($varCloner->cloneVar($var), true);
 
     // (added string length before the string)
     // array:1 [
@@ -232,23 +240,24 @@ next to its content:
     // ]
 
 If ``DUMP_LIGHT_ARRAY`` is set, then arrays are dumped in a shortened format
-similar to PHP's short array notation:
-
-.. code-block:: php
+similar to PHP's short array notation::
 
+    use Symfony\Component\VarDumper\Cloner\VarCloner;
     use Symfony\Component\VarDumper\Dumper\AbstractDumper;
     use Symfony\Component\VarDumper\Dumper\CliDumper;
 
+    $varCloner = new VarCloner();
     $var = ['test'];
+    
     $dumper = new CliDumper();
-    echo $dumper->dump($var, true);
+    echo $dumper->dump($varCloner->cloneVar($var), true);
 
     // array:1 [
     //   0 => "test"
     // ]
 
     $dumper = new CliDumper(null, null, AbstractDumper::DUMP_LIGHT_ARRAY);
-    echo $dumper->dump($var, true);
+    echo $dumper->dump($varCloner->cloneVar($var), true);
 
     // (no more array:1 prefix)
     // [
@@ -256,16 +265,17 @@ similar to PHP's short array notation:
     // ]
 
 If you would like to use both options, then you can combine them by
-using a the logical OR operator ``|``:
-
-.. code-block:: php
+using the logical OR operator ``|``::
 
+    use Symfony\Component\VarDumper\Cloner\VarCloner;
     use Symfony\Component\VarDumper\Dumper\AbstractDumper;
     use Symfony\Component\VarDumper\Dumper\CliDumper;
 
+    $varCloner = new VarCloner();
     $var = ['test'];
+    
     $dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH | AbstractDumper::DUMP_LIGHT_ARRAY);
-    echo $dumper->dump($var, true);
+    echo $dumper->dump($varCloner->cloneVar($var), true);
 
     // [
     //   0 => (4) "test"
diff --git a/components/var_exporter.rst b/components/var_exporter.rst
new file mode 100644
index 00000000000..6b403f79263
--- /dev/null
+++ b/components/var_exporter.rst
@@ -0,0 +1,132 @@
+.. index::
+   single: VarExporter
+   single: Components; VarExporter
+
+The VarExporter Component
+=========================
+
+    The VarExporter component exports any serializable PHP data structure to
+    plain PHP code and allows to instantiate and populate objects without
+    calling their constructors.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require --dev symfony/var-exporter
+
+.. include:: /components/require_autoload.rst.inc
+
+Exporting/Serializing Variables
+-------------------------------
+
+The main feature of this component is to serialize PHP data structures to plain
+PHP code, similar to PHP's :phpfunction:`var_export` function::
+
+    use Symfony\Component\VarExporter\VarExporter;
+
+    $exported = VarExporter::export($someVariable);
+    // store the $exported data in some file or cache system for later reuse
+    $data = file_put_contents('exported.php', $exported);
+
+    // later, regenerate the original variable when you need it
+    $regeneratedVariable = require 'exported.php';
+
+The reason to use this component instead of ``serialize()`` or ``igbinary`` is
+performance: thanks to `OPcache`_, the resulting code is significantly faster
+and more memory efficient than using ``unserialize()`` or ``igbinary_unserialize()``.
+
+In addition, there are some minor differences:
+
+* If the original variable defines them, all the semantics associated with
+  ``serialize()`` (such as ``__wakeup()``, ``__sleep()``, and ``Serializable``)
+  are preserved (``var_export()`` ignores them);
+* References involving ``SplObjectStorage``, ``ArrayObject`` or ``ArrayIterator``
+  instances are preserved;
+* Missing classes throw a ``ClassNotFoundException`` instead of being
+  unserialized to ``PHP_Incomplete_Class`` objects;
+* ``Reflection*``, ``IteratorIterator`` and ``RecursiveIteratorIterator``
+  classes throw an exception when being serialized.
+
+The exported data is a `PSR-2`_ compatible PHP file. Consider for example the
+following class hierarchy::
+
+    abstract class AbstractClass
+    {
+        protected $foo;
+        private $bar;
+
+        protected function setBar($bar)
+        {
+            $this->bar = $bar;
+        }
+    }
+
+    class ConcreteClass extends AbstractClass
+    {
+        public function __construct()
+        {
+            $this->foo = 123;
+            $this->setBar(234);
+        }
+    }
+
+When exporting the ``ConcreteClass`` data with VarExporter, the generated PHP
+file looks like this::
+
+    <?php
+    return \Symfony\Component\VarExporter\Internal\Hydrator::hydrate(
+        $o = [
+            clone (\Symfony\Component\VarExporter\Internal\Registry::$prototypes['Symfony\\Component\\VarExporter\\Tests\\ConcreteClass'] ?? \Symfony\Component\VarExporter\Internal\Registry::p('Symfony\\Component\\VarExporter\\Tests\\ConcreteClass')),
+        ],
+        null,
+        [
+            'Symfony\\Component\\VarExporter\\Tests\\AbstractClass' => [
+                'foo' => [
+                    123,
+                ],
+                'bar' => [
+                    234,
+                ],
+            ],
+        ],
+        $o[0],
+        []
+    );
+
+Instantiating PHP Classes
+-------------------------
+
+The other main feature provided by this component is an instantiator which can
+create objects and set their properties without calling their constructors or
+any other methods::
+
+    use Symfony\Component\VarExporter\Instantiator;
+
+    // creates an empty instance of Foo
+    $fooObject = Instantiator::instantiate(Foo::class);
+
+    // creates a Foo instance and sets one of its properties
+    $fooObject = Instantiator::instantiate(Foo::class, ['propertyName' => $propertyValue]);
+
+    // creates a Foo instance and sets a private property defined on its parent Bar class
+    $fooObject = Instantiator::instantiate(Foo::class, [], [
+        Bar::class => ['privateBarProperty' => $propertyValue],
+    ]);
+
+Instances of ``ArrayObject``, ``ArrayIterator`` and ``SplObjectHash`` can be
+created by using the special ``"\0"`` property name to define their internal value::
+
+    // Creates an SplObjectHash where $info1 is associated to $object1, etc.
+    $theObject = Instantiator::instantiate(SplObjectStorage::class, [
+        "\0" => [$object1, $info1, $object2, $info2...]
+    ]);
+
+    // creates an ArrayObject populated with $inputArray
+    $theObject = Instantiator::instantiate(ArrayObject::class, [
+        "\0" => [$inputArray]
+    ]);
+
+.. _`OPcache`: https://php.net/opcache
+.. _`PSR-2`: https://www.php-fig.org/psr/psr-2/
diff --git a/components/web_link.rst b/components/web_link.rst
index 9bc6e945a1d..634da8b81b7 100644
--- a/components/web_link.rst
+++ b/components/web_link.rst
@@ -5,8 +5,8 @@
 The WebLink Component
 ======================
 
-   The WebLink component provides tools to manage the ``Link`` HTTP header needed
-   for `Web Linking`_ when using `HTTP/2 Server Push`_ as well as `Resource Hints`_.
+    The WebLink component provides tools to manage the ``Link`` HTTP header needed
+    for `Web Linking`_ when using `HTTP/2 Server Push`_ as well as `Resource Hints`_.
 
 Installation
 ------------
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/web-link
 
-Alternatively, you can clone the `<https://github.com/symfony/web-link>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Usage
@@ -24,16 +22,16 @@ Usage
 
 The following example shows the component in action::
 
-   use Fig\Link\GenericLinkProvider;
-   use Fig\Link\Link;
-   use Symfony\Component\WebLink\HttpHeaderSerializer;
+    use Fig\Link\GenericLinkProvider;
+    use Fig\Link\Link;
+    use Symfony\Component\WebLink\HttpHeaderSerializer;
 
-   $linkProvider = (new GenericLinkProvider())
-       ->withLink(new Link('preload', '/bootstrap.min.css'));
+    $linkProvider = (new GenericLinkProvider())
+        ->withLink(new Link('preload', '/bootstrap.min.css'));
 
-   header('Link: '.(new HttpHeaderSerializer())->serialize($linkProvider->getLinks()));
+    header('Link: '.(new HttpHeaderSerializer())->serialize($linkProvider->getLinks()));
 
-   echo 'Hello';
+    echo 'Hello';
 
 Read the full :doc:`WebLink documentation </web_link>` to learn about all the
 features of the component and its integration with the Symfony framework.
diff --git a/components/workflow.rst b/components/workflow.rst
index e1fcbc145c9..f04571d19b4 100644
--- a/components/workflow.rst
+++ b/components/workflow.rst
@@ -15,8 +15,6 @@ Installation
 
     $ composer require symfony/workflow
 
-Alternatively, you can clone the `<https://github.com/symfony/workflow>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Creating a Workflow
@@ -34,28 +32,30 @@ a ``Definition`` and a way to write the states to the objects (i.e. an
 instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`).
 
 Consider the following example for a blog post. A post can have one of a number
-of predefined statuses (`draft`, `review`, `rejected`, `published`). In a workflow,
+of predefined statuses (`draft`, `reviewed`, `rejected`, `published`). In a workflow,
 these statuses are called **places**. You can define the workflow like this::
 
     use Symfony\Component\Workflow\DefinitionBuilder;
+    use Symfony\Component\Workflow\MarkingStore\MethodMarkingStore;
     use Symfony\Component\Workflow\Transition;
     use Symfony\Component\Workflow\Workflow;
-    use Symfony\Component\Workflow\MarkingStore\SingleStateMarkingStore;
 
     $definitionBuilder = new DefinitionBuilder();
-    $definition = $definitionBuilder->addPlaces(['draft', 'review', 'rejected', 'published'])
+    $definition = $definitionBuilder->addPlaces(['draft', 'reviewed', 'rejected', 'published'])
         // Transitions are defined with a unique name, an origin place and a destination place
-        ->addTransition(new Transition('to_review', 'draft', 'review'))
-        ->addTransition(new Transition('publish', 'review', 'published'))
-        ->addTransition(new Transition('reject', 'review', 'rejected'))
+        ->addTransition(new Transition('to_review', 'draft', 'reviewed'))
+        ->addTransition(new Transition('publish', 'reviewed', 'published'))
+        ->addTransition(new Transition('reject', 'reviewed', 'rejected'))
         ->build()
     ;
 
-    $marking = new SingleStateMarkingStore('currentState');
+    $singleState = true; // true if the subject can be in only one state at a given time
+    $property = 'currentState'; // subject property name where the state is stored
+    $marking = new MethodMarkingStore($singleState, $property);
     $workflow = new Workflow($definition, $marking);
 
-The ``Workflow`` can now help you to decide what actions are allowed
-on a blog post depending on what *place* it is in. This will keep your domain
+The ``Workflow`` can now help you to decide what *transitions* (actions) are allowed
+on a blog post depending on what *place* (state) it is in. This will keep your domain
 logic in one place and not spread all over your application.
 
 When you define multiple workflows you should consider using a ``Registry``,
@@ -63,37 +63,36 @@ which is an object that stores and provides access to different workflows.
 A registry will also help you to decide if a workflow supports the object you
 are trying to use it with::
 
-    use Symfony\Component\Workflow\Registry;
-    use Symfony\Component\Workflow\SupportStrategy\InstanceOfSupportStrategy;
     use Acme\Entity\BlogPost;
     use Acme\Entity\Newsletter;
+    use Symfony\Component\Workflow\Registry;
+    use Symfony\Component\Workflow\SupportStrategy\InstanceOfSupportStrategy;
 
-    $blogWorkflow = ...
+    $blogPostWorkflow = ...
     $newsletterWorkflow = ...
 
     $registry = new Registry();
-    $registry->addWorkflow($blogWorkflow, new InstanceOfSupportStrategy(BlogPost::class));
+    $registry->addWorkflow($blogPostWorkflow, new InstanceOfSupportStrategy(BlogPost::class));
     $registry->addWorkflow($newsletterWorkflow, new InstanceOfSupportStrategy(Newsletter::class));
 
-.. versionadded:: 4.1
-    The ``addWorkflow()`` method was introduced in Symfony 4.1. In previous
-    Symfony versions it was called ``add()``.
-
 Usage
 -----
 
-When you have configured a ``Registry`` with your workflows, you may use it as follows::
+When you have configured a ``Registry`` with your workflows,
+you can retrieve a workflow from it and use it as follows::
 
     // ...
-    $post = new BlogPost();
-    $workflow = $registry->get($post);
+    // Consider that $blogPost is in place "draft" by default
+    $blogPost = new BlogPost();
+    $workflow = $registry->get($blogPost);
 
-    $workflow->can($post, 'publish'); // False
-    $workflow->can($post, 'to_review'); // True
+    $workflow->can($blogPost, 'publish'); // False
+    $workflow->can($blogPost, 'to_review'); // True
 
-    $workflow->apply($post, 'to_review');
-    $workflow->can($post, 'publish'); // True
-    $workflow->getEnabledTransitions($post); // ['publish', 'reject']
+    $workflow->apply($blogPost, 'to_review'); // $blogPost is now in place "reviewed"
+
+    $workflow->can($blogPost, 'publish'); // True
+    $workflow->getEnabledTransitions($blogPost); // $blogPost can perform transition "publish" or "reject"
 
 Learn more
 ----------
@@ -103,5 +102,3 @@ Learn more
     :glob:
 
     /workflow/*
-
-.. _Packagist: https://packagist.org/packages/symfony/workflow
diff --git a/components/yaml.rst b/components/yaml.rst
index bbbd1fbba03..93e9f30e0fd 100644
--- a/components/yaml.rst
+++ b/components/yaml.rst
@@ -33,8 +33,6 @@ Installation
 
     $ composer require symfony/yaml
 
-Alternatively, you can clone the `<https://github.com/symfony/yaml>`_ repository.
-
 .. include:: /components/require_autoload.rst.inc
 
 Why?
@@ -190,7 +188,7 @@ representation to the inline one::
 Indentation
 ...........
 
-By default the YAML component will use 4 spaces for indentation. This can be
+By default, the YAML component will use 4 spaces for indentation. This can be
 changed using the third argument as follows::
 
     // uses 8 spaces for indentation
@@ -279,7 +277,7 @@ representation of the object as a map.
 Handling Invalid Types
 ~~~~~~~~~~~~~~~~~~~~~~
 
-By default the parser will encode invalid types as ``null``. You can make the
+By default, the parser will encode invalid types as ``null``. You can make the
 parser throw exceptions by using the ``PARSE_EXCEPTION_ON_INVALID_TYPE``
 flag::
 
@@ -291,14 +289,12 @@ Similarly you can use ``DUMP_EXCEPTION_ON_INVALID_TYPE`` when dumping::
     $data = new \stdClass(); // by default objects are invalid.
     Yaml::dump($data, 2, 4, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception
 
-    echo $yaml; // { foo: bar }
-
 Date Handling
 ~~~~~~~~~~~~~
 
-By default the YAML parser will convert unquoted strings which look like a
+By default, the YAML parser will convert unquoted strings which look like a
 date or a date-time into a Unix timestamp; for example ``2016-05-27`` or
-``2016-05-27T02:59:43.1Z`` (ISO-8601_)::
+``2016-05-27T02:59:43.1Z`` (`ISO-8601`_)::
 
     Yaml::parse('2016-05-27'); // 1464307200
 
@@ -311,7 +307,7 @@ flag::
 Dumping Multi-line Literal Blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In YAML multiple lines can be represented as literal blocks, by default the
+In YAML, multiple lines can be represented as literal blocks. By default, the
 dumper will encode multiple lines as an inline string::
 
     $string = ["string" => "Multiple\nLine\nString"];
@@ -394,7 +390,6 @@ First, install the Console component:
 Create a console application with ``lint:yaml`` as its only command::
 
     // lint.php
-
     use Symfony\Component\Console\Application;
     use Symfony\Component\Yaml\Command\LintCommand;
 
@@ -411,9 +406,15 @@ Then, execute the script for validating contents:
     # validates a single file
     $ php lint.php path/to/file.yaml
 
+    # or validates multiple files
+    $ php lint.php path/to/file1.yaml path/to/file2.yaml
+
     # or all the files in a directory
     $ php lint.php path/to/directory
 
+    # or all the files in multiple directories
+    $ php lint.php path/to/directory1 path/to/directory2
+
     # or contents passed to STDIN
     $ cat path/to/file.yaml | php lint.php
 
@@ -439,7 +440,6 @@ Learn More
 
     yaml/*
 
-.. _YAML: http://yaml.org/
-.. _Packagist: https://packagist.org/packages/symfony/yaml
+.. _`YAML`: http://yaml.org/
 .. _`YAML 1.2 version specification`: http://yaml.org/spec/1.2/spec.html
-.. _ISO-8601: http://www.iso.org/iso/iso8601
+.. _`ISO-8601`: http://www.iso.org/iso/iso8601
diff --git a/components/yaml/yaml_format.rst b/components/yaml/yaml_format.rst
index 78802213765..d5f29b3937a 100644
--- a/components/yaml/yaml_format.rst
+++ b/components/yaml/yaml_format.rst
@@ -149,7 +149,7 @@ Booleans in YAML are expressed with ``true`` and ``false``.
 Dates
 ~~~~~
 
-YAML uses the ISO-8601 standard to express dates:
+YAML uses the `ISO-8601`_ standard to express dates:
 
 .. code-block:: yaml
 
@@ -286,8 +286,8 @@ Comments can be added in YAML by prefixing them with a hash mark (``#``):
 
 .. note::
 
-    Comments are simply ignored by the YAML parser and do not need to be
-    indented according to the current level of nesting in a collection.
+    Comments are ignored by the YAML parser and do not need to be indented
+    according to the current level of nesting in a collection.
 
 Explicit Typing
 ---------------
@@ -310,8 +310,6 @@ The YAML specification defines some tags to set the type of any data explicitly:
             Pz7Y6OjuDg4J+fn5OTk6enp
             56enmleECcgggoBADs=
 
-.. _YAML: http://yaml.org/
-
 Unsupported YAML Features
 -------------------------
 
@@ -320,12 +318,13 @@ The following YAML features are not supported by the Symfony Yaml component:
 * Multi-documents (``---`` and ``...`` markers);
 * Complex mapping keys and complex values starting with ``?``;
 * Tagged values as keys;
-* The following tags and types: `!!set`, `!!omap`, `!!pairs`, `!!set`, `!!seq`,
-  `!!bool`, `!!int`, `!!merge`, `!!null`, `!!timestamp`, `!!value`, `!!yaml`;
+* The following tags and types: `!!set`, `!!omap`, `!!pairs`, `!!seq`,
+  `!!bool`, `!!int`, `!!merge`, `!!null`, `!!timestamp`, `!!value`, `!!yaml`;
 * Tags (``TAG`` directive; example: ``%TAG ! tag:example.com,2000:app/``)
   and tag references (example: ``!<tag:example.com,2000:app/foo>``);
 * Using sequence-like syntax for mapping elements (example: ``{foo, bar}``; use
   ``{foo: ~, bar: ~}`` instead).
 
+.. _`ISO-8601`: http://www.iso.org/iso/iso8601
 .. _`YAML website`: http://yaml.org/
 .. _`YAML specification`: http://www.yaml.org/spec/1.2/spec.html
diff --git a/configuration.rst b/configuration.rst
index b1fab7982c9..6314d0dbfb3 100644
--- a/configuration.rst
+++ b/configuration.rst
@@ -1,128 +1,145 @@
 .. index::
    single: Configuration
 
-Configuring Symfony (and Environments)
-======================================
+Configuring Symfony
+===================
 
-Symfony applications can install third-party packages (bundles, libraries, etc.)
-to bring in new features (:doc:`services </service_container>`) to your project.
-Each package can be customized via configuration files that live - by default -
-in the ``config/`` directory.
+Configuration Files
+-------------------
 
-Configuration: config/packages/
--------------------------------
+Symfony applications are configured with the files stored in the ``config/``
+directory, which has this default structure:
 
-The configuration for each package can be found in ``config/packages/``. For
-instance, the framework bundle is configured in ``config/packages/framework.yaml``:
+.. code-block:: text
 
-.. configuration-block::
+    your-project/
+    ├─ config/
+    │  ├─ packages/
+    │  ├─ bundles.php
+    │  ├─ routes.yaml
+    │  └─ services.yaml
+    ├─ ...
 
-    .. code-block:: yaml
+The ``routes.yaml`` file defines the :doc:`routing configuration </routing>`;
+the ``services.yaml`` file configures the services of the
+:doc:`service container </service_container>`; the ``bundles.php`` file enables/
+disables packages in your application.
 
-        # config/packages/framework.yaml
-        framework:
-            secret: '%env(APP_SECRET)%'
-            #default_locale: en
-            #csrf_protection: true
-            #http_method_override: true
+You'll be working most in the ``config/packages/`` directory. This directory
+stores the configuration of every package installed in your application.
+Packages (also called "bundles" in Symfony and "plugins/modules" in other
+projects) add ready-to-use features to your projects.
 
-            # Enables session support. Note that the session will ONLY be started if you read or write from it.
-            # Remove or comment this section to explicitly disable session support.
-            session:
-                handler_id: ~
+When using :ref:`Symfony Flex <symfony-flex>`, which is enabled by default in
+Symfony applications, packages update the ``bundles.php`` file and create new
+files in ``config/packages/`` automatically during their installation. For
+example, this is the default file created by the "API Platform" package:
 
-            #esi: true
-            #fragments: true
-            php_errors:
-                log: true
+.. code-block:: yaml
 
-    .. code-block:: xml
+    # config/packages/api_platform.yaml
+    api_platform:
+        mapping:
+            paths: ['%kernel.project_dir%/src/Entity']
 
-            <!-- config/packages/framework.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:framework="http://symfony.com/schema/dic/framework"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/framework http://symfony.com/schema/dic/framework/framework-1.0.xsd"
-            >
-                <framework:config secret="%env(APP_SECRET)%">
-                    <!--<framework:csrf-protection enabled="true“ />-->
-                    <!--<framework:esi enabled="true" />-->
-                    <!--<framework:fragments enabled="true" />-->
-
-                    <!-- Enables session support. Note that the session will ONLY be started if you read or write from it.
-                         Remove or comment this section to explicitly disable session support. -->
-                    <framework:session />
-
-                    <framework:php-errors log="true" />
-                </framework:config>
-            </container>
+Splitting the configuration into lots of small files is intimidating for some
+Symfony newcomers. However, you'll get used to them quickly and you rarely need
+to change these files after package installation
 
-    .. code-block:: php
+.. tip::
 
-        // config/packages/framework.php
-        $container->loadFromExtension('framework', [
-            'secret' => '%env(APP_SECRET)%',
-            //'default_locale' => 'en',
-            //'csrf_protection' => true,
-            //'http_method_override' => true,
-
-            // Enables session support. Note that the session will ONLY be started if you read or write from it.
-            // Remove or comment this section to explicitly disable session support.
-            'session' => [
-                'handler_id' => null,
-            ],
-            //'esi' => true,
-            //'fragments' => true,
-            'php_errors' => [
-                'log' => true,
-            ],
-        ]);
+    To learn about all the available configuration options, check out the
+    :doc:`Symfony Configuration Reference </reference/index>` or run the
+    ``config:dump-reference`` command.
 
-The top-level key (here ``framework``) references configuration for a specific
-bundle (:doc:`FrameworkBundle </reference/configuration/framework>` in this case).
+Configuration Formats
+~~~~~~~~~~~~~~~~~~~~~
 
-.. sidebar:: Configuration Formats
+Unlike other frameworks, Symfony doesn't impose you a specific format to
+configure your applications. Symfony lets you choose between YAML, XML and PHP
+and throughout the Symfony documentation, all configuration examples will be
+shown in these three formats.
 
-    Throughout the documentation, all configuration examples will be shown in
-    three formats (YAML, XML and PHP). YAML is used by default, but you can
-    choose whatever you like best. There is no performance difference:
+There isn't any practical difference between formats. In fact, Symfony
+transforms and caches all of them into PHP before running the application, so
+there's not even any performance difference between them.
 
-    * :doc:`/components/yaml/yaml_format`: Simple, clean and readable;
-    * *XML*: More powerful than YAML at times & supports IDE autocompletion;
-    * *PHP*: Very powerful but less readable than standard configuration formats.
+YAML is used by default when installing packages because it's concise and very
+readable. These are the main advantages and disadvantages of each format:
 
-Configuration Reference & Dumping
----------------------------------
+* **YAML**: simple, clean and readable, but not all IDEs support autocompletion
+  and validation for it. :doc:`Learn the YAML syntax </components/yaml/yaml_format>`;
+* **XML**:autocompleted/validated by most IDEs and is parsed natively by PHP,
+  but sometimes it generates too verbose configuration. `Learn the XML syntax`_;
+* **PHP**: very powerful and it allows to create dynamic configuration, but the
+  resulting configuration is less readable than the other formats.
 
-There are *two* ways to know *what* keys you can configure:
+Importing Configuration Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-#. Use the :doc:`Reference Section </reference/index>`;
-#. Use the ``config:dump-reference`` command.
+Symfony loads configuration files using the :doc:`Config component
+</components/config>`, which provides advanced features such as importing other
+configuration files, even if they use a different format:
 
-For example, if you want to configure something related to the framework bundle,
-you can see an example dump of all available configuration options by running:
+.. configuration-block::
 
-.. code-block:: terminal
+    .. code-block:: yaml
 
-    $ php bin/console config:dump-reference framework
+        # config/services.yaml
+        imports:
+            - { resource: 'legacy_config.php' }
+            # ignore_errors silently discards errors if the loaded file doesn't exist
+            - { resource: 'my_config_file.xml', ignore_errors: true }
+            # glob expressions are also supported to load multiple files
+            - { resource: '/etc/myapp/*.yaml' }
 
-.. index::
-   single: Environments; Introduction
+        # ...
 
-.. _page-creation-environments:
-.. _page-creation-prod-cache-clear:
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <imports>
+                <import resource="legacy_config.php"/>
+                <!-- ignore_errors silently discards errors if the loaded file doesn't exist -->
+                <import resource="my_config_file.yaml" ignore-errors="true"/>
+                <!-- glob expressions are also supported to load multiple files -->
+                <import resource="/etc/myapp/*.yaml"/>
+            </imports>
+
+            <!-- ... -->
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        $loader->import('legacy_config.xml');
+        // the third optional argument of import() is 'ignore_errors', which
+        // silently discards errors if the loaded file doesn't exist
+        $loader->import('my_config_file.yaml', null, true);
+        // glob expressions are also supported to load multiple files
+        $loader->import('/etc/myapp/*.yaml');
+
+        // ...
 
 .. _config-parameter-intro:
+.. _config-parameters-yml:
+.. _configuration-parameters:
 
-The parameters Key: Parameters (Variables)
-------------------------------------------
+Configuration Parameters
+------------------------
 
-The configuration has some special top-level keys. One of them is called
-``parameters``: it's used to define *variables* that can be referenced in *any*
-other configuration file. For example, when you install the *translation*
-package, a ``locale`` parameter is added  to ``config/services.yaml``:
+Sometimes the same configuration value is used in several configuration files.
+Instead of repeating it, you can define it as a "parameter", which is like a
+reusable configuration value. By convention, parameters are defined under the
+``parameters`` key in the ``config/services.yaml`` file:
 
 .. configuration-block::
 
@@ -130,7 +147,22 @@ package, a ``locale`` parameter is added  to ``config/services.yaml``:
 
         # config/services.yaml
         parameters:
-            locale: en
+            # the parameter name is an arbitrary string (the 'app.' prefix is recommended
+            # to better differentiate your parameters from Symfony parameters).
+            app.admin_email: 'something@example.com'
+
+            # boolean parameters
+            app.enable_v2_protocol: true
+
+            # array/collection parameters
+            app.supported_locales: ['en', 'es', 'fr']
+
+            # binary content parameters (encode the contents with base64_encode())
+            app.some_parameter: !!binary VGhpcyBpcyBhIEJlbGwgY2hhciAH
+
+            # PHP constants as parameter values
+            app.some_constant: !php/const GLOBAL_CONSTANT
+            app.another_constant: !php/const App\Entity\BlogPost::MAX_ITEMS
 
         # ...
 
@@ -142,12 +174,33 @@ package, a ``locale`` parameter is added  to ``config/services.yaml``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <parameters>
-                <parameter key="locale">en</parameter>
+                <!-- the parameter name is an arbitrary string (the 'app.' prefix is recommended
+                     to better differentiate your parameters from Symfony parameters). -->
+                <parameter key="app.admin_email">something@example.com</parameter>
+
+                <!-- boolean parameters -->
+                <parameter key="app.enable_v2_protocol">true</parameter>
+                <!-- if you prefer to store the boolean value as a string in the parameter -->
+                <parameter key="app.enable_v2_protocol" type="string">true</parameter>
+
+                <!-- array/collection parameters -->
+                <parameter key="app.supported_locales" type="collection">
+                    <parameter>en</parameter>
+                    <parameter>es</parameter>
+                    <parameter>fr</parameter>
+                </parameter>
+
+                <!-- binary content parameters (encode the contents with base64_encode()) -->
+                <parameter key="app.some_parameter" type="binary">VGhpcyBpcyBhIEJlbGwgY2hhciAH</parameter>
+
+                <!-- PHP constants as parameter values -->
+                <parameter key="app.some_constant" type="constant">GLOBAL_CONSTANT</parameter>
+                <parameter key="app.another_constant" type="constant">App\Entity\BlogPost::MAX_ITEMS</parameter>
             </parameters>
 
             <!-- ... -->
@@ -156,92 +209,432 @@ package, a ``locale`` parameter is added  to ``config/services.yaml``:
     .. code-block:: php
 
         // config/services.php
-        $container->setParameter('locale', 'en');
+        // the parameter name is an arbitrary string (the 'app.' prefix is recommended
+        // to better differentiate your parameters from Symfony parameters).
+        $container->setParameter('app.admin_email', 'something@example.com');
+
+        // boolean parameters
+        $container->setParameter('app.enable_v2_protocol', true);
+
+        // array/collection parameters
+        $container->setParameter('app.supported_locales', ['en', 'es', 'fr']);
+
+        // binary content parameters (use the PHP escape sequences)
+        $container->setParameter('app.some_parameter', 'This is a Bell char: \x07');
+
+        // PHP constants as parameter values
+        use App\Entity\BlogPost;
+
+        $container->setParameter('app.some_constant', GLOBAL_CONSTANT);
+        $container->setParameter('app.another_constant', BlogPost::MAX_ITEMS);
+
         // ...
 
-This parameter is then referenced in the framework config in
-``config/packages/translation.yaml``:
+.. caution::
+
+    When using XML configuration, the values between ``<parameter>`` tags are
+    not trimmed. This means that the value of the following parameter will be
+    ``'\n    something@example.com\n'``:
+
+    .. code-block:: xml
+
+        <parameter key="app.admin_email">
+            something@example.com
+        </parameter>
+
+Once defined, you can reference this parameter value from any other
+configuration file using a special syntax: wrap the parameter name in two ``%``
+(e.g. ``%app.admin_email%``):
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # config/packages/translation.yaml
-        framework:
+        # config/packages/some_package.yaml
+        some_package:
             # any string surrounded by two % is replaced by that parameter value
-            default_locale: '%locale%'
+            email_address: '%app.admin_email%'
 
             # ...
 
     .. code-block:: xml
 
-        <!-- config/packages/translation.xml -->
+        <!-- config/packages/some_package.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <!-- any string surrounded by two % is replaced by that parameter value -->
-            <framework:config default-locale="%locale%">
+            <some-package:config email-address="%app.admin_email%">
                 <!-- ... -->
-            </framework:config>
+            </some-package:config>
         </container>
 
     .. code-block:: php
 
-        // config/packages/translation.php
-        $container->loadFromExtension('framework', [
+        // config/packages/some_package.php
+        $container->loadFromExtension('some_package', [
             // any string surrounded by two % is replaced by that parameter value
-            'default_locale' => '%locale%',
+            'email_address' => '%app.admin_email%',
 
             // ...
         ]);
 
-You can define whatever parameter names you want under the ``parameters`` key of
-any configuration file. To reference a parameter, surround its name with two
-percent signs - e.g. ``%locale%``.
+.. note::
+
+    If some parameter value includes the ``%`` character, you need to escape it
+    by adding another ``%`` so Symfony doesn't consider it a reference to a
+    parameter name:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/services.yaml
+            parameters:
+                # Parsed as 'https://symfony.com/?foo=%s&amp;bar=%d'
+                url_pattern: 'https://symfony.com/?foo=%%s&amp;bar=%%d'
+
+        .. code-block:: xml
+
+            <!-- config/services.xml -->
+            <parameters>
+                <parameter key="url_pattern">http://symfony.com/?foo=%%s&amp;bar=%%d</parameter>
+            </parameters>
+
+        .. code-block:: php
+
+            // config/services.php
+            $container->setParameter('url_pattern', 'http://symfony.com/?foo=%%s&amp;bar=%%d');
+
+.. include:: /components/dependency_injection/_imports-parameters-note.rst.inc
+
+Configuration parameters are very common in Symfony applications. Some packages
+even define their own parameters (e.g. when installing the translation package,
+a new ``locale`` parameter is added to the ``config/services.yaml`` file).
+
+.. seealso::
+
+    Read the `Accessing Configuration Values`_ section of this article to learn
+    about how to use these configuration parameters in services and controllers.
+
+.. index::
+   single: Environments; Introduction
+
+.. _page-creation-environments:
+.. _page-creation-prod-cache-clear:
+.. _configuration-environments:
+
+Configuration Environments
+--------------------------
+
+You have just one application, but whether you realize it or not, you need it
+to behave differently at different times:
+
+* While **developing**, you want to log everything and expose nice debugging tools;
+* After deploying to **production**, you want that same application to be
+  optimized for speed and only log errors.
+
+The files stored in ``config/packages/`` are used by Symfony to configure the
+:doc:`application services </service_container>`. In other words, you can change
+the application behavior by changing which configuration files are loaded.
+That's the idea of Symfony's **configuration environments**.
+
+A typical Symfony application begins with three environments: ``dev`` (for local
+development), ``prod`` (for production servers) and ``test`` (for
+:doc:`automated tests </testing>`). When running the application, Symfony loads
+the configuration files in this order (the last files can override the values
+set in the previous ones):
+
+#. ``config/packages/*.yaml`` (and ``.xml`` and ``*.php`` files too);
+#. ``config/packages/<environment-name>/*.yaml`` (and ``.xml`` and ``*.php`` files too);
+#. ``config/packages/services.yaml`` (and ``services.xml`` and ``services.php`` files too);
+
+Take the ``framework`` package, installed by default, as an example:
+
+* First, ``config/packages/framework.yaml`` is loaded in all environments and
+  it configures the framework with some options;
+* In the **prod** environment, nothing extra will be set as there is no
+  ``config/packages/prod/framework.yaml`` file;
+* In the **dev** environment, there is no file either (
+  ``config/packages/dev/framework.yaml`` does not exist).
+* In the **test** environment, the ``config/packages/test/framework.yaml`` file
+  is loaded to override some of the settings previously configured in
+  ``config/packages/framework.yaml``.
+
+In reality, each environment differs only somewhat from others. This means that
+all environments share a large base of common configurations, which is put in
+files directly in the ``config/packages/`` directory.
 
 .. seealso::
 
-    You can also set parameters dynamically, like from environment variables.
-    See :doc:`/configuration/external_parameters`.
+    See the ``configureContainer()`` method of
+    :doc:`the Kernel class </configuration/front_controllers_and_kernel>` to
+    learn everything about the loading order of configuration files.
+
+.. _selecting-the-active-environment:
+
+Selecting the Active Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony applications come with a file called ``.env`` located at the project
+root directory. This file is used to define the value of environment variables
+and it's explained in detail :ref:`later in this article <config-dot-env>`.
+
+Open the ``.env`` file (or better, the ``.env.local`` file if you created one)
+and edit the value of the ``APP_ENV`` variable to change the environment in
+which the application runs. For example, to run the application in production:
+
+.. code-block:: bash
+
+    # .env (or .env.local)
+    APP_ENV=prod
+
+This value is used both for the web and for the console commands. However, you
+can override it for commands by setting the ``APP_ENV`` value before running them:
+
+.. code-block:: terminal
+
+    # Use the environment defined in the .env file
+    $ php bin/console command_name
+
+    # Ignore the .env file and run this command in production
+    $ APP_ENV=prod php bin/console command_name
+
+Creating a New Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For more information about parameters - including how to reference them from inside
-a controller - see :ref:`service-container-parameters`.
+The default three environments provided by Symfony are enough for most projects,
+but you can define your own environments too. For example, this is how you can
+define a ``staging`` environment where the client can test the project before
+going to production:
 
+#. Create a configuration directory with the same name as the environment (in
+   this case, ``config/packages/staging/``);
+#. Add the needed configuration files in ``config/packages/staging/`` to
+   define the behavior of the new environment. Symfony loads first the files in
+   ``config/packages/*.yaml``, so you must only configure the differences with
+   those files;
+#. Select the ``staging`` environment using the ``APP_ENV`` env var as explained
+   in the previous section.
+
+.. tip::
+
+    It's common for environments to be similar between each other, so you can
+    use `symbolic links`_ between ``config/packages/<environment-name>/``
+    directories to reuse the same configuration.
+
+.. _config-env-vars:
+
+Configuration Based on Environment Variables
+--------------------------------------------
+
+Using `environment variables`_ (or "env vars" for short) is a common practice to
+configure options that depend on where the application is run (e.g. the database
+credentials are usually different in production and in your local machine).
+
+Instead of defining those as regular options, you can define them as environment
+variables and reference them in the configuration files using the special syntax
+``%env(ENV_VAR_NAME)%``. The values of these options are resolved at runtime
+(only once per request, to not impact performance).
+
+This example shows how to configure the database connection using an env var:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/doctrine.yaml
+        doctrine:
+            dbal:
+                # by convention the env var names are always uppercase
+                url: '%env(DATABASE_URL)%'
+            # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/doctrine.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+
+            <doctrine:config>
+                <!-- by convention the env var names are always uppercase -->
+                <doctrine:dbal url="%env(DATABASE_URL)%"/>
+            </doctrine:config>
+
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/doctrine.php
+        $container->loadFromExtension('doctrine', [
+            'dbal' => [
+                // by convention the env var names are always uppercase
+                'url' => '%env(DATABASE_URL)%',
+            ]
+        ]);
+
+The next step is to define the value of those env vars in your shell, your web
+server, etc. This is explained in the following sections, but to protect your
+application from undefined env vars, you can give them a default value using the
+``.env`` file:
+
+.. code-block:: bash
+
+    # .env
+    DATABASE_URL=sqlite:///%kernel.project_dir%/var/data.db
+
+.. seealso::
+
+    The values of env vars can only be strings, but Symfony includes some
+    :doc:`env var processors </configuration/env_var_processors>` to transform
+    their contents (e.g. to turn a string value into an integer).
+
+In order to define the actual values of env vars, Symfony proposes different
+solutions depending if the application is running in production or in your local
+development machine.
+
+Independent from the way you set environmnet variables, you may need to run the
+``debug:container`` command with the ``--env-vars`` option to verify that they
+are defined and have the expected values:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:container --env-vars
+
+    ---------------- ----------------- ---------------------------------------------
+     Name             Default value     Real value
+    ---------------- ----------------- ---------------------------------------------
+     APP_SECRET       n/a               "471a62e2d601a8952deb186e44186cb3"
+     FOO              "[1, "2.5", 3]"   n/a
+     BAR              null              n/a
+    ---------------- ----------------- ---------------------------------------------
+
+    # you can also filter the list of env vars by name:
+    $ php bin/console debug:container --env-vars foo
+
+    # run this command to show all the details for a specific env var:
+    $ php bin/console debug:container --env-var=FOO
+
+.. versionadded:: 4.3
+
+    The option to debug environment variables was introduced in Symfony 4.3.
+
+.. _configuration-env-var-in-dev:
 .. _config-dot-env:
-.. _config-parameters-yml:
 
-The .env File & Environment Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configuring Environment Variables in Development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There is also a ``.env`` file which is loaded and its contents become environment
-variables. This is useful during development, or if setting environment variables
-is difficult for your deployment.
+Instead of defining env vars in your shell or your web server, Symfony proposes
+a convenient way of defining them in your local machine based on a file called
+``.env`` (with a leading dot) located at the root of your project.
 
-When you install packages, more environment variables are added to this file. But
-you can also add your own.
+The ``.env`` file is read and parsed on every request and its env vars are added
+to the ``$_ENV`` PHP variable. The existing env vars are never overwritten by
+the values defined in ``.env``, so you can combine both.
 
-Environment variables can be referenced in any other configuration files by using
-a special syntax. For example, if you install the ``doctrine`` package, then you
-will have an environment variable called ``DATABASE_URL`` in your ``.env`` file.
-This is referenced inside ``config/packages/doctrine.yaml``:
+This is for example the content of the ``.env`` file to define the value of the
+``DATABASE_URL`` env var shown earlier in this article:
 
-.. code-block:: yaml
+.. code-block:: bash
+
+    # .env
+    DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"
+
+In addition to your own env vars, this ``.env`` file also contains the env vars
+defined by the third-party packages installed in your application (they are
+added automatically by :ref:`Symfony Flex <symfony-flex>` when installing packages).
+
+.. _configuration-env-var-in-prod:
+
+Configuring Environment Variables in Production
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In production, the ``.env`` files are also parsed and loaded on each request so
+you can override the env vars already defined in the server. In order to improve
+performance, you can run the ``dump-env`` command (available when using
+:ref:`Symfony Flex <symfony-flex>` 1.2 or later).
+
+This command parses all the ``.env`` files once and compiles their contents into
+a new PHP-optimized file called  ``.env.local.php``. From that moment, Symfony
+will load the parsed file instead of parsing the ``.env`` files again:
 
-    # config/packages/doctrine.yaml
-    doctrine:
-        dbal:
-            url: '%env(DATABASE_URL)%'
+.. code-block:: terminal
+
+    $ composer dump-env prod
+
+.. tip::
+
+    Update your deployment tools/workflow to run the ``dump-env`` command after
+    each deploy to improve the application performance.
 
-            # The `resolve:` prefix replaces container params by their values inside the env variable:
-            # url: '%env(resolve:DATABASE_URL)%'
+.. _configuration-env-var-web-server:
 
-For more details about environment variables, see :ref:`config-env-vars`.
+Creating ``.env`` files is the easiest way of using env vars in Symfony
+applications. However, you can also configure real env vars in your servers and
+operating systems.
+
+.. tip::
+
+    SymfonyCloud, the cloud service optimized for Symfony applications, defines
+    some `utilities to manage env vars`_ in production.
+
+.. caution::
+
+    Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
+    or outputting the ``phpinfo()`` contents will display the values of the
+    environment variables, exposing sensitive information such as the database
+    credentials.
+
+    The values of the env vars are also exposed in the web interface of the
+    :doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
+    problem because the web profiler must **never** be enabled in production.
+
+Managing Multiple .env Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``.env`` file defines the default values for all env vars. However, it's
+common to override some of those values depending on the environment (e.g. to
+use a different database for tests) or depending on the machine (e.g. to use a
+different OAuth token on your local machine while developing).
+
+That's why you can define multiple ``.env`` files to override env vars. The
+following list shows the files loaded in all environments. The ``.env`` file is
+the only mandatory file and each file content overrides the previous one:
+
+* ``.env``: defines the default values of the env vars needed by the application;
+* ``.env.local``: defines machine-specific overrides for env vars on all
+  environments. This file is not committed to the repository, so these overrides
+  only apply to the machine which contains the file (your local computer,
+  production server, etc.);
+* ``.env.<environment>`` (e.g. ``.env.test``): overrides env vars only for some
+  environment but for all machines;
+* ``.env.<environment>.local`` (e.g. ``.env.test.local``): defines machine-specific
+  env vars overrides only for some environment. It's similar to ``.env.local``,
+  but the overrides only apply to some particular environment.
+
+.. note::
+
+    The real environment variables defined in the server always win over the
+    env vars created by the ``.env`` files.
+
+The ``.env`` and ``.env.<environment>`` files should be committed to the shared
+repository because they are the same for all developers and machines. However,
+the env files ending in ``.local`` (``.env.local`` and ``.env.<environment>.local``)
+**should not be committed** because only you will use them. In fact, the
+``.gitignore`` file that comes with Symfony prevents them from being committed.
 
 .. caution::
 
@@ -249,48 +642,154 @@ For more details about environment variables, see :ref:`config-env-vars`.
     involving a ``.env.dist`` file. For information about upgrading, see:
     :doc:`configuration/dot-env-changes`.
 
-The ``.env`` file is special, because it defines the values that usually change
-on each server. For example, the database credentials on your local development
-machine might be different from your workmates. The ``.env`` file should contain
-sensible, non-secret *default* values for all of your environment variables and
-*should* be commited to your repository.
+Accessing Configuration Values
+------------------------------
+
+Controllers and services can access all the configuration parameters. This
+includes both the :ref:`parameters defined by yourself <configuration-parameters>`
+and the parameters created by packages/bundles. Run the following command to see
+all the parameters that exist in your application:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:container --parameters
 
-To override these variables with machine-specific or sensitive values, create a
-``.env.local`` file. This file is **not committed to the shared repository** and
-is only stored on your machine. In fact, the ``.gitignore`` file that comes with
-Symfony prevents it from being committed.
+Parameters are injected in services as arguments to their constructors.
+:doc:`Service autowiring </service_container/autowiring>` doesn't work for
+parameters. Instead, inject them explicitly:
 
-You can also create a few other ``.env`` files that will be loaded:
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        parameters:
+            app.contents_dir: '...'
+
+        services:
+            App\Service\MessageGenerator:
+                arguments:
+                    $contentsDir: '%app.contents_dir%'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <parameters>
+                <parameter key="app.contents_dir">...</parameter>
+            </parameters>
+
+            <services>
+                <service id="App\Service\MessageGenerator">
+                    <argument key="$contentsDir">%app.contents_dir%</argument>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\Service\MessageGenerator;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        $container->setParameter('app.contents_dir', '...');
+
+        $container->getDefinition(MessageGenerator::class)
+            ->setArgument('$contentsDir', '%app.contents_dir%');
 
-* ``.env.{environment}``: e.g. ``.env.test`` will be loaded in the ``test`` environment
-  and committed to your repository.
+If you inject the same parameters over and over again, use instead the
+``services._defaults.bind`` option. The arguments defined in that option are
+injected automatically whenever a service constructor or controller action
+define an argument with that exact name. For example, to inject the value of the
+:ref:`kernel.project_dir parameter <configuration-kernel-project-directory>`
+whenever a service/controller defines a ``$projectDir`` argument, use this:
 
-* ``.env.{environment}.local``: e.g. ``.env.prod.local`` will be loaded in the
-  ``prod`` environment but will *not* be committed to your repository.
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            _defaults:
+                bind:
+                    # pass this value to any $projectDir argument for any service
+                    # that's created in this file (including controller arguments)
+                    $projectDir: '%kernel.project_dir%'
+
+            # ...
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
-If you decide to set real environment variables on production, the ``.env`` files
-*are* still loaded, but your real environment variables will override those values.
+            <services>
+                <defaults autowire="true" autoconfigure="true" public="false">
+                    <!-- pass this value to any $projectDir argument for any service
+                         that's created in this file (including controller arguments) -->
+                    <bind key="$projectDir">%kernel.project_dir%</bind>
+                </defaults>
 
-Environments & the Other Config Files
--------------------------------------
+                <!-- ... -->
+            </services>
+        </container>
 
-You have just *one* app, but whether you realize it or not, you need it to
-behave *differently* at different times:
+    .. code-block:: php
 
-* While **developing**, you want your app to log everything and expose nice
-  debugging tools;
+        // config/services.php
+        use App\Controller\LuckyController;
+        use Psr\Log\LoggerInterface;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        $container->register(LuckyController::class)
+            ->setPublic(true)
+            ->setBindings([
+                // pass this value to any $projectDir argument for any service
+                // that's created in this file (including controller arguments)
+                '$projectDir' => '%kernel.project_dir%',
+            ])
+        ;
 
-* After deploying to **production**, you want that *same* app to be optimized
-  for speed and only log errors.
+.. seealso::
 
-How can you make *one* application behave in two different ways? With
-*environments*.
+    Read the article about :ref:`binding arguments by name and/or type <services-binding>`
+    to learn more about this powerful feature.
 
-You've probably already been using the ``dev`` environment without even knowing
-it. After you deploy, you'll use the ``prod`` environment.
+Finally, if some service needs to access to lots of parameters, instead of
+injecting each of them individually, you can inject all the application
+parameters at once by type-hinting any of its constructor arguments with the
+:class:`Symfony\\Component\\DependencyInjection\\ParameterBag\\ContainerBagInterface`::
 
-To learn more about *how* to execute and control each environment, see
-:doc:`/configuration/environments`.
+    // src/Service/MessageGenerator.php
+    // ...
+
+    use Symfony\Component\DependencyInjection\ParameterBag\ContainerBagInterface;
+
+    class MessageGenerator
+    {
+        private $params;
+
+        public function __construct(ContainerBagInterface $params)
+        {
+            $this->params = $params;
+        }
+
+        public function someMethod()
+        {
+            // get any container parameter from $this->params, which stores all of them
+            $sender = $this->params->get('mailer_sender');
+            // ...
+        }
+    }
 
 Keep Going!
 -----------
@@ -305,10 +804,7 @@ part of Symfony individually by following the guides. Check out:
 * :doc:`/email`
 * :doc:`/logging`
 
-And the many other topics.
-
-Learn more
-----------
+And all the other topics related to configuration:
 
 .. toctree::
     :maxdepth: 1
@@ -316,4 +812,7 @@ Learn more
 
     configuration/*
 
-.. _`Incenteev Parameter Handler`: https://github.com/Incenteev/ParameterHandler
+.. _`Learn the XML syntax`: https://en.wikipedia.org/wiki/XML
+.. _`environment variables`: https://en.wikipedia.org/wiki/Environment_variable
+.. _`symbolic links`: https://en.wikipedia.org/wiki/Symbolic_link
+.. _`utilities to manage env vars`: https://symfony.com/doc/master/cloud/cookbooks/env.html
diff --git a/configuration/configuration_organization.rst b/configuration/configuration_organization.rst
deleted file mode 100644
index b3a06a89aae..00000000000
--- a/configuration/configuration_organization.rst
+++ /dev/null
@@ -1,180 +0,0 @@
-.. index::
-    single: Configuration
-
-How to Organize Configuration Files
-===================================
-
-The Symfony skeleton defines three :doc:`execution environments </configuration/environments>`
-called ``dev``, ``prod`` and ``test``. An environment represents a way
-to execute the same codebase with different configurations.
-
-In order to select the configuration file to load for each environment, Symfony
-executes the ``configureContainer()`` method of the ``Kernel`` class::
-
-    // src/Kernel.php
-    use Symfony\Component\Config\Loader\LoaderInterface;
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
-    use Symfony\Component\HttpKernel\Kernel as BaseKernel;
-
-    class Kernel extends BaseKernel
-    {
-        const CONFIG_EXTS = '.{php,xml,yaml,yml}';
-
-        // ...
-
-        public function configureContainer(ContainerBuilder $container, LoaderInterface $loader)
-        {
-            $confDir = $this->getProjectDir().'/config';
-            $loader->load($confDir.'/packages/*'.self::CONFIG_EXTS, 'glob');
-            if (is_dir($confDir.'/packages/'.$this->environment)) {
-                $loader->load($confDir.'/packages/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob');
-            }
-            $loader->load($confDir.'/services'.self::CONFIG_EXTS, 'glob');
-            $loader->load($confDir.'/services_'.$this->environment.self::CONFIG_EXTS, 'glob');
-        }
-    }
-
-For the ``dev`` environment, Symfony loads the following config files and
-directories and in this order:
-
-#. ``config/packages/*``
-#. ``config/packages/dev/*``
-#.  ``config/services.yaml``
-#. ``config/services_dev.yaml``
-
-Therefore, the configuration files of the default Symfony applications follow
-this structure:
-
-.. code-block:: text
-
-    your-project/
-    ├─ config/
-    │  ├─ packages/
-    │  │  ├─ dev/
-    │  │  │  ├─ framework.yaml
-    │  │  │  └─ ...
-    │  │  ├─ prod/
-    │  │  │  └─ ...
-    │  │  ├─ test/
-    │  │  │  └─ ...
-    │  │  ├─ framework.yaml
-    │  │  └─ ...
-    │  ├─ services.yaml
-    │  └─ services_dev.yaml
-    ├─ ...
-
-This default structure was chosen for its simplicity — one file per package and
-environment. But as any other Symfony feature, you can customize it to better
-suit your needs.
-
-Advanced Techniques
--------------------
-
-Symfony loads configuration files using the
-:doc:`Config component </components/config>`, which provides some
-advanced features.
-
-Mix and Match Configuration Formats
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Configuration files can import files defined with any other built-in configuration
-format (``.yaml`` or ``.yml``, ``.xml``, ``.php``, ``.ini``):
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        imports:
-            - { resource: 'my_config_file.xml' }
-            - { resource: 'legacy.php' }
-
-        # ...
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <imports>
-                <import resource="my_config_file.yaml" />
-                <import resource="legacy.php" />
-            </imports>
-
-            <!-- ... -->
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $loader->import('my_config_file.yaml');
-        $loader->import('legacy.xml');
-
-        // ...
-
-If you use any other configuration format, you have to define your own loader
-class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`.
-When the configuration values are dynamic, you can use the PHP configuration
-file to execute your own logic. In addition, you can define your own services
-to load configurations from databases or web services.
-
-Global Configuration Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Some system administrators may prefer to store sensitive parameters in files
-outside the project directory. Imagine that the database credentials for your
-website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. You
-can load files from outside the project folder by indicating the full file path
-when importing it from any other configuration file:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        imports:
-            - { resource: '/etc/sites/mysite.com/parameters.yaml', ignore_errors: true }
-
-        # ...
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <imports>
-                <import resource="/etc/sites/mysite.com/parameters.yaml" ignore-errors="true" />
-            </imports>
-
-            <!-- ... -->
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $loader->import('/etc/sites/mysite.com/parameters.yaml', null, true);
-
-        // ...
-
-.. tip::
-
-    The ``ignore_errors`` option (which is the third optional argument in the
-    loader's ``import()`` method) silently discards errors when the loaded file
-    doesn't exist. This is needed in this case because most of the time, local
-    developers won't have the same files that exist on the production servers.
-
-As you've seen, there are lots of ways to organize your configuration files. You
-can choose one of these or even create your own custom way of organizing the
-files. For even more customization, see ":doc:`/configuration/override_dir_structure`".
diff --git a/configuration/dot-env-changes.rst b/configuration/dot-env-changes.rst
index c0e1a3917d1..280a40c8d63 100644
--- a/configuration/dot-env-changes.rst
+++ b/configuration/dot-env-changes.rst
@@ -18,12 +18,12 @@ important changes:
 * A) The ``.env.dist`` file no longer exists. Its contents should be moved to your
   ``.env`` file (see the next point).
 
-* B) The ``.env`` file **is** now commited to your repository. It was previously ignored
+* B) The ``.env`` file **is** now committed to your repository. It was previously ignored
   via the ``.gitignore`` file (the updated recipe does not ignore this file). Because
   this file is committed, it should contain non-sensitive, default values. Basically,
   the ``.env.dist`` file was moved to ``.env``.
 
-* C) A ``.env.local`` file can now be created to *override* environment variables for
+* C) A ``.env.local`` file can now be created to *override* values in ``.env`` for
   your machine. This file is ignored in the new ``.gitignore``.
 
 * D) When testing, your ``.env`` file is now read, making it consistent with all
@@ -67,7 +67,7 @@ changes can be made to any Symfony 3.4 or higher app:
        + /.env.local
        + /.env.local.php
        + /.env.*.local
-    
+
        # ...
 
 #. Rename ``.env`` to ``.env.local`` and ``.env.dist`` to ``.env``:
@@ -79,18 +79,18 @@ changes can be made to any Symfony 3.4 or higher app:
        $ git mv .env.dist .env
 
        # Windows
-       $ mv .env .env.local
-       $ git mv .env.dist .env
+       C:\> move .env .env.local
+       C:\> git mv .env.dist .env
 
-    You can also update the `comment on the top of .env`_ to reflect the new changes.
+   You can also update the `comment on the top of .env`_ to reflect the new changes.
 
 #. If you're using PHPUnit, you will also need to `create a new .env.test`_ file
    and update your `phpunit.xml.dist file`_ so it loads the ``config/bootstrap.php``
    file.
 
-.. _`config/bootstrap.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/config/bootstrap.php
-.. _`public/index.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php
-.. _`index.php diff`: https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...f54d6a468405d0d8d27b0e790dc09a01e337777a#diff-473fca613b5bda15d87731036cb31586
+.. _`config/bootstrap.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.2/config/bootstrap.php
+.. _`public/index.php`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.2/public/index.php
+.. _`index.php diff`: https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-7d73eabd1e5eb7d969ddf9a7ce94f954
 .. _`bin/console`: https://github.com/symfony/recipes/blob/master/symfony/console/3.3/bin/console
 .. _`comment on the top of .env`: https://github.com/symfony/recipes/blob/master/symfony/flex/1.0/.env
 .. _`create a new .env.test`: https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/.env.test
diff --git a/configuration/env_var_processors.rst b/configuration/env_var_processors.rst
new file mode 100644
index 00000000000..67d9bca422e
--- /dev/null
+++ b/configuration/env_var_processors.rst
@@ -0,0 +1,670 @@
+.. index::
+    single: Environment Variable Processors; env vars
+
+.. _env-var-processors:
+
+Environment Variable Processors
+===============================
+
+:ref:`Using env vars to configure Symfony applications <config-env-vars>` is a
+common practice to make your applications truly dynamic.
+
+The main issue of env vars is that their values can only be strings and your
+application may need other data types (integer, boolean, etc.). Symfony solves
+this problem with "env var processors", which transform the original contents of
+the given environment variables. The following example uses the integer
+processor to turn the value of the ``HTTP_PORT`` env var into an integer:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            router:
+                http_port: '%env(int:HTTP_PORT)%'
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:router http-port="%env(int:HTTP_PORT)%"/>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        $container->loadFromExtension('framework', [
+            'router' => [
+                'http_port' => '%env(int:HTTP_PORT)%',
+            ],
+        ]);
+
+Built-In Environment Variable Processors
+----------------------------------------
+
+Symfony provides the following env var processors:
+
+``env(string:FOO)``
+    Casts ``FOO`` to a string:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(SECRET): 'some_secret'
+            framework:
+                secret: '%env(string:SECRET)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(SECRET)">some_secret</parameter>
+                </parameters>
+
+                <framework:config secret="%env(string:SECRET)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(SECRET)', 'some_secret');
+            $container->loadFromExtension('framework', [
+                'secret' => '%env(string:SECRET)%',
+            ]);
+
+``env(bool:FOO)``
+    Casts ``FOO`` to a bool:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(HTTP_METHOD_OVERRIDE): 'true'
+            framework:
+                http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(HTTP_METHOD_OVERRIDE)">true</parameter>
+                </parameters>
+
+                <framework:config http-methode-override="%env(bool:HTTP_METHOD_OVERRIDE)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(HTTP_METHOD_OVERRIDE)', 'true');
+            $container->loadFromExtension('framework', [
+                'http_method_override' => '%env(bool:HTTP_METHOD_OVERRIDE)%',
+            ]);
+
+``env(int:FOO)``
+    Casts ``FOO`` to an int.
+
+``env(float:FOO)``
+    Casts ``FOO`` to a float.
+
+``env(const:FOO)``
+    Finds the const value named in ``FOO``:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/security.yaml
+            parameters:
+                env(HEALTH_CHECK_METHOD): 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD'
+            security:
+                access_control:
+                    - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' }
+
+        .. code-block:: xml
+
+            <!-- config/packages/security.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:security="http://symfony.com/schema/dic/security"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(HEALTH_CHECK_METHOD)">Symfony\Component\HttpFoundation\Request::METHOD_HEAD</parameter>
+                </parameters>
+
+                <security:config>
+                    <rule path="^/health-check$" methods="%env(const:HEALTH_CHECK_METHOD)%"/>
+                </security:config>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/security.php
+            $container->setParameter('env(HEALTH_CHECK_METHOD)', 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD');
+            $container->loadFromExtension('security', [
+                'access_control' => [
+                    [
+                        'path' => '^/health-check$',
+                        'methods' => '%env(const:HEALTH_CHECK_METHOD)%',
+                    ],
+                ],
+            ]);
+
+``env(base64:FOO)``
+    Decodes the content of ``FOO``, which is a base64 encoded string.
+
+``env(json:FOO)``
+    Decodes the content of ``FOO``, which is a JSON encoded string. It returns
+    either an array or ``null``:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(TRUSTED_HOSTS): '["10.0.0.1", "10.0.0.2"]'
+            framework:
+                trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(TRUSTED_HOSTS)">["10.0.0.1", "10.0.0.2"]</parameter>
+                </parameters>
+
+                <framework:config trusted-hosts="%env(json:TRUSTED_HOSTS)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(TRUSTED_HOSTS)', '["10.0.0.1", "10.0.0.2"]');
+            $container->loadFromExtension('framework', [
+                'trusted_hosts' => '%env(json:TRUSTED_HOSTS)%',
+            ]);
+
+``env(resolve:FOO)``
+    Replaces the string ``FOO`` by the value of a config parameter with the
+    same name:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/sentry.yaml
+            parameters:
+                env(HOST): '10.0.0.1'
+                sentry_host: '%env(HOST)%'
+                env(SENTRY_DSN): 'http://%sentry_host%/project'
+            sentry:
+                dsn: '%env(resolve:SENTRY_DSN)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/sentry.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(HOST)">10.0.0.1</parameter>
+                    <parameter key="sentry_host">%env(HOST)%</parameter>
+                    <parameter key="env(SENTRY_DSN)">http://%sentry_host%/project</parameter>
+                </parameters>
+
+                <sentry:config dsn="%env(resolve:SENTRY_DSN)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/sentry.php
+            $container->setParameter('env(HOST)', '10.0.0.1');
+            $container->setParameter('sentry_host', '%env(HOST)%');
+            $container->setParameter('env(SENTRY_DSN)', 'http://%sentry_host%/project');
+            $container->loadFromExtension('sentry', [
+                'dsn' => '%env(resolve:SENTRY_DSN)%',
+            ]);
+
+``env(csv:FOO)``
+    Decodes the content of ``FOO``, which is a CSV-encoded string:
+
+    .. code-block:: yaml
+
+        parameters:
+            env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2"
+        framework:
+           trusted_hosts: '%env(csv:TRUSTED_HOSTS)%'
+
+``env(file:FOO)``
+    Returns the contents of a file whose path is the value of the ``FOO`` env var:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(AUTH_FILE): '../config/auth.json'
+            google:
+                auth: '%env(file:AUTH_FILE)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(AUTH_FILE)">../config/auth.json</parameter>
+                </parameters>
+
+                <google auth="%env(file:AUTH_FILE)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(AUTH_FILE)', '../config/auth.json');
+            $container->loadFromExtension('google', [
+                'auth' => '%env(file:AUTH_FILE)%',
+            ]);
+
+``env(require:FOO)``
+    ``require()`` the PHP file whose path is the value of the ``FOO``
+    env var and return the value returned from it.
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(PHP_FILE): '../config/.runtime-evaluated.php'
+            app:
+                auth: '%env(require:PHP_FILE)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(PHP_FILE)">../config/.runtime-evaluated.php</parameter>
+                </parameters>
+
+                <app auth="%env(require:PHP_FILE)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(PHP_FILE)', '../config/.runtime-evaluated.php');
+            $container->loadFromExtension('app', [
+                'auth' => '%env(require:AUTH_FILE)%',
+            ]);
+
+    .. versionadded:: 4.3
+
+        The ``require`` processor was introduced in Symfony 4.3.
+
+``env(trim:FOO)``
+    Trims the content of ``FOO`` env var, removing whitespaces from the beginning
+    and end of the string. This is especially useful in combination with the
+    ``file`` processor, as it'll remove newlines at the end of a file.
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(AUTH_FILE): '../config/auth.json'
+            google:
+                auth: '%env(trim:file:AUTH_FILE)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(AUTH_FILE)">../config/auth.json</parameter>
+                </parameters>
+
+                <google auth="%env(trim:file:AUTH_FILE)%"/>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(AUTH_FILE)', '../config/auth.json');
+            $container->loadFromExtension('google', [
+                'auth' => '%env(trim:file:AUTH_FILE)%',
+            ]);
+
+    .. versionadded:: 4.3
+
+        The ``trim`` processor was introduced in Symfony 4.3.
+
+``env(key:FOO:BAR)``
+    Retrieves the value associated with the key ``FOO`` from the array whose
+    contents are stored in the ``BAR`` env var:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/services.yaml
+            parameters:
+                env(SECRETS_FILE): '/opt/application/.secrets.json'
+                database_password: '%env(key:database_password:json:file:SECRETS_FILE)%'
+                # if SECRETS_FILE contents are: {"database_password": "secret"} it returns "secret"
+
+        .. code-block:: xml
+
+            <!-- config/services.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(SECRETS_FILE)">/opt/application/.secrets.json</parameter>
+                    <parameter key="database_password">%env(key:database_password:json:file:SECRETS_FILE)%</parameter>
+                </parameters>
+            </container>
+
+        .. code-block:: php
+
+            // config/services.php
+            $container->setParameter('env(SECRETS_FILE)', '/opt/application/.secrets.json');
+            $container->setParameter('database_password', '%env(key:database_password:json:file:SECRETS_FILE)%');
+
+``env(default:fallback_param:BAR)``
+    Retrieves the value of the parameter ``fallback_param`` when the ``BAR`` env
+    var is not available:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/services.yaml
+            parameters:
+                # if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
+                private_key: '%env(default:raw_key:file:PRIVATE_KEY)%'
+                raw_key: '%env(PRIVATE_KEY)%'
+
+        .. code-block:: xml
+
+            <!-- config/services.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                <parameters>
+                    <!-- if PRIVATE_KEY is not a valid file path, the content of raw_key is returned -->
+                    <parameter key="private_key">%env(default:raw_key:file:PRIVATE_KEY)%</parameter>
+                    <parameter key="raw_key">%env(PRIVATE_KEY)%</parameter>
+                </parameters>
+            </container>
+
+        .. code-block:: php
+
+            // config/services.php
+
+            // if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
+            $container->setParameter('private_key', '%env(default:raw_key:file:PRIVATE_KEY)%');
+            $container->setParameter('raw_key', '%env(PRIVATE_KEY)%');
+
+    When the fallback parameter is omitted (e.g. ``env(default::API_KEY)``), the
+    value returned is ``null``.
+
+    .. versionadded:: 4.3
+
+        The ``default`` processor was introduced in Symfony 4.3.
+
+``env(url:FOO)``
+    Parses an absolute URL and returns its components as an associative array.
+
+    .. code-block:: bash
+
+        # .env
+        MONGODB_URL="mongodb://db_user:db_password@127.0.0.1:27017/db_name"
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/mongodb.yaml
+            mongo_db_bundle:
+                clients:
+                    default:
+                        hosts:
+                            - { host: '%env(key:host:url:MONGODB_URL)%', port: '%env(key:port:url:MONGODB_URL)%' }
+                        username: '%env(key:user:url:MONGODB_URL)%'
+                        password: '%env(key:pass:url:MONGODB_URL)%'
+                connections:
+                    default:
+                        database_name: '%env(key:path:url:MONGODB_URL)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/mongodb.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <mongodb:config>
+                    <mongodb:client name="default" username="%env(key:user:url:MONGODB_URL)%" password="%env(key:pass:url:MONGODB_URL)%">
+                        <mongodb:host host="%env(key:host:url:MONGODB_URL)%" port="%env(key:port:url:MONGODB_URL)%"/>
+                    </mongodb:client>
+                    <mongodb:connections name="default" database_name="%env(key:path:url:MONGODB_URL)%"/>
+                </mongodb:config>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/mongodb.php
+            $container->loadFromExtension('mongodb', [
+                'clients' => [
+                    'default' => [
+                        'hosts' => [
+                            [
+                                'host' => '%env(key:host:url:MONGODB_URL)%',
+                                'port' => '%env(key:port:url:MONGODB_URL)%',
+                            ],
+                        ],
+                        'username' => '%env(key:user:url:MONGODB_URL)%',
+                        'password' => '%env(key:pass:url:MONGODB_URL)%',
+                    ],
+                ],
+                'connections' => [
+                    'default' => [
+                        'database_name' => '%env(key:path:url:MONGODB_URL)%',
+                    ],
+                ],
+            ]);
+
+    .. caution::
+
+        In order to ease extraction of the resource from the URL, the leading
+        ``/`` is trimmed from the ``path`` component.
+
+    .. versionadded:: 4.3
+
+        The ``url`` processor was introduced in Symfony 4.3.
+
+``env(query_string:FOO)``
+    Parses the query string part of the given URL and returns its components as
+    an associative array.
+
+    .. code-block:: bash
+
+        # .env
+        MONGODB_URL="mongodb://db_user:db_password@127.0.0.1:27017/db_name?timeout=3000"
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/mongodb.yaml
+            mongo_db_bundle:
+                clients:
+                    default:
+                        # ...
+                        connectTimeoutMS: '%env(int:key:timeout:query_string:MONGODB_URL)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/mongodb.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <mongodb:config>
+                    <mongodb:client name="default" connectTimeoutMS="%env(int:key:timeout:query_string:MONGODB_URL)%"/>
+                </mongodb:config>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/mongodb.php
+            $container->loadFromExtension('mongodb', [
+                'clients' => [
+                    'default' => [
+                        // ...
+                        'connectTimeoutMS' => '%env(int:key:timeout:query_string:MONGODB_URL)%',
+                    ],
+                ],
+            ]);
+
+    .. versionadded:: 4.3
+
+        The ``query_string`` processor was introduced in Symfony 4.3.
+
+It is also possible to combine any number of processors:
+
+.. code-block:: yaml
+
+    parameters:
+        env(AUTH_FILE): "%kernel.project_dir%/config/auth.json"
+    google:
+        # 1. gets the value of the AUTH_FILE env var
+        # 2. replaces the values of any config param to get the config path
+        # 3. gets the content of the file stored in that path
+        # 4. JSON-decodes the content of the file and returns it
+        auth: '%env(json:file:resolve:AUTH_FILE)%'
+
+Custom Environment Variable Processors
+--------------------------------------
+
+It's also possible to add your own processors for environment variables. First,
+create a class that implements
+:class:`Symfony\\Component\\DependencyInjection\\EnvVarProcessorInterface`::
+
+    use Symfony\Component\DependencyInjection\EnvVarProcessorInterface;
+
+    class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
+    {
+        public function getEnv($prefix, $name, \Closure $getEnv)
+        {
+            $env = $getEnv($name);
+
+            return strtolower($env);
+        }
+
+        public static function getProvidedTypes()
+        {
+            return [
+                'lowercase' => 'string',
+            ];
+        }
+    }
+
+To enable the new processor in the app, register it as a service and
+:doc:`tag it </service_container/tags>` with the ``container.env_var_processor``
+tag. If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
diff --git a/configuration/environments.rst b/configuration/environments.rst
deleted file mode 100644
index 70b7d9aaa3c..00000000000
--- a/configuration/environments.rst
+++ /dev/null
@@ -1,360 +0,0 @@
-.. index::
-    single: Environments
-
-How to Master and Create new Environments
-=========================================
-
-Every application is the combination of code and a set of configuration that
-dictates how that code should function. The configuration may define the database
-being used, if something should be cached or how verbose logging should be.
-
-In Symfony, the idea of "environments" is the idea that the same codebase can be
-run using multiple different configurations. For example, the ``dev`` environment
-should use configuration that makes development easy and friendly, while the
-``prod`` environment should use a set of configuration optimized for speed.
-
-.. index::
-   single: Environments; Configuration files
-
-Different Environments, different Configuration Files
------------------------------------------------------
-
-A typical Symfony application begins with three environments: ``dev``,
-``prod`` and ``test``. As mentioned, each environment represents a way to
-execute the same codebase with different configuration. It should be no
-surprise then that each environment loads its own individual configuration
-files. These different files are organized by environment:
-
-* for the ``dev`` environment: ``config/packages/dev/``
-* for the ``prod`` environment: ``config/packages/prod/``
-* for the ``test`` environment: ``config/packages/test/``
-
-In reality, each environment differs only somewhat from others. This means that
-all environments share a large base of common configurations. This configuration
-is put in files directly in the ``config/packages/`` directory.
-
-The location of these files is defined by the application's kernel::
-
-    // src/Kernel.php
-
-    // ...
-    class Kernel extends BaseKernel
-    {
-        // ...
-
-        protected function configureContainer(ContainerBuilder $container, LoaderInterface $loader)
-        {
-            // ...
-            $confDir = $this->getProjectDir().'/config';
-
-            // always load all files in /config/packages/
-            $loader->load($confDir.'/packages/*'.self::CONFIG_EXTS, 'glob');
-
-            // then, if available, load the files in the specific environment directory
-            if (is_dir($confDir.'/packages/'.$this->environment)) {
-                $loader->load($confDir.'/packages/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob');
-            }
-
-            // load a special services.(yaml/xml/php) and, if available, services_ENVIRONMENT.(yaml/xml/php) file
-            $loader->load($confDir.'/services'.self::CONFIG_EXTS, 'glob');
-            $loader->load($confDir.'/services_'.$this->environment.self::CONFIG_EXTS, 'glob');
-        }
-    }
-
-Take the framework package, installed by default, as an example:
-
-* Loaded in all environments, ``config/packages/framework.yaml`` configures the
-  framework with some ``secret`` setting;
-* In the **prod** environment, nothing extra will be set as there is no
-  ``config/packages/prod/`` directory;
-* The same applies to **dev**, as there is no
-  ``config/packages/dev/framework.yaml``. There are however other packages (e.g.
-  ``routing.yaml``) with special dev settings;
-* At last, during the **test** environment, the framework's test features are
-  enabled in ``config/packages/test/framework.yaml``.
-
-.. index::
-   single: Environments; Executing different environments
-
-Executing an Application in different Environments
---------------------------------------------------
-
-To execute the application in each environment, change the ``APP_ENV``
-environment variable. During development, this is done in ``.env`` or in ``.env.local``:
-
-.. code-block:: bash
-
-    # .env or .env.local
-    APP_ENV=dev
-
-    # or for test:
-    #APP_ENV=test
-
-Visit the ``http://localhost:8000/index.php`` page in your web browser to see
-your application in the configured environment.
-
-.. tip::
-
-    In production, you can use real environment variables via
-    your :ref:`web server configuration <configuration-env-var-in-prod>`.
-
-.. note::
-
-    The given URLs assume that your web server is configured to use the ``public/``
-    directory of the application as its root. Read more in :doc:`Installing Symfony </setup>`.
-
-If you open the file you just visited (``public/index.php``), you'll see that
-the environment variable is passed to the kernel::
-
-    // public/index.php
-
-    // ...
-    $kernel = new Kernel($_SERVER['APP_ENV'], $_SERVER['APP_DEBUG']);
-
-    // ...
-
-.. note::
-
-    The ``test`` environment is used when writing functional tests and is
-    usually not accessed in the browser directly via a front controller.
-
-.. index::
-   single: Configuration; Debug mode
-
-.. sidebar:: *Debug* Mode
-
-    Important, but unrelated to the topic of *environments* is the second
-    argument to the ``Kernel`` constructor. This specifies if the application
-    should run in "debug mode". Regardless of the environment, a Symfony
-    application can be run with debug mode set to ``true`` or ``false``
-    (respectively ``1`` or ``0`` for the ``APP_DEBUG`` variable defined in
-    ``.env``). This affects many things in the application, such as displaying
-    stacktraces on error pages or if cache files are dynamically rebuilt on
-    each request.  Though not a requirement, debug mode is generally set to
-    ``true`` for the ``dev`` and ``test`` environments and ``false`` for the
-    ``prod`` environment.
-
-    Internally, the value of the debug mode becomes the ``kernel.debug``
-    parameter used inside the :doc:`service container </service_container>`.
-    If you look inside the application configuration file, you'll see the
-    parameter used, for example, to turn Twig's debug mode on:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/twig.yaml
-            twig:
-                debug: '%kernel.debug%'
-
-        .. code-block:: xml
-
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/twig
-                    http://symfony.com/schema/dic/twig/twig-1.0.xsd">
-
-                <twig:config debug="%kernel.debug%" />
-
-            </container>
-
-        .. code-block:: php
-
-            $container->loadFromExtension('twig', [
-                'debug' => '%kernel.debug%',
-                // ...
-            ]);
-
-Selecting the Environment for Console Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, Symfony commands are executed in whatever environment is defined by
-the ``APP_ENV`` environment variable (usually configured in your ``.env`` file).
-
-Use the ``--env`` and ``--no-debug`` options to modify this behavior:
-
-.. code-block:: terminal
-
-    # 'dev' environment and debug enabled
-    $ php bin/console command_name
-
-    # 'prod' environment (debug is always disabled for 'prod')
-    $ php bin/console command_name --env=prod
-
-    # 'test' environment and debug disabled
-    $ php bin/console command_name --env=test --no-debug
-
-.. index::
-   single: Environments; Creating a new environment
-
-Creating a new Environment
---------------------------
-
-Since an environment is nothing more than a string that corresponds to a set of
-configuration, you can also create your own environments for specific purposes.
-
-Suppose, for example, that before deployment, you need to benchmark your
-application. One way to benchmark the application is to use near-production
-settings, but with Symfony's ``web_profiler`` enabled. This allows Symfony
-to record information about your application while benchmarking.
-
-The best way to accomplish this is via a new environment called, for example,
-``benchmark``. Start by creating a new configuration directory and a
-configuration file:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/benchmark/web_profiler.yaml
-        framework:
-            profiler: { only_exceptions: false }
-
-    .. code-block:: xml
-
-        <!-- config/packages/benchmark/web_profiler.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <framework:config>
-                <framework:profiler only-exceptions="false" />
-            </framework:config>
-
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/benchmark/web_profiler.php
-        $container->loadFromExtension('framework', [
-            'profiler' => ['only_exceptions' => false],
-        ]);
-
-And... you're finished! The application now supports a new environment called
-``benchmark``.
-
-Change the ``APP_ENV`` variable to ``benchmark`` to be able to access the new
-environment through your browser:
-
-.. code-block:: bash
-
-    # .env or .env.local
-    APP_ENV=benchmark
-
-.. sidebar:: Importing configuration
-
-    Besides loading files in the Kernel, you can also import files in the
-    configuration directly. For instance, to make sure the benchmark
-    environment is identical to the prod environment, you might want to load
-    all its configuration as well.
-
-    You can achieve this by using a special ``imports`` key:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/benchmark/other.yaml
-            imports:
-                - { resource: '../prod/' }
-
-                # other resources are possible as well, like importing other
-                # files or using globs:
-                #- { resource: '/etc/myapp/some_special_config.xml' }
-                #- { resource: '/etc/myapp/*.yaml' }
-
-        .. code-block:: xml
-
-            <!-- config/packages/benchmark/other.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:framework="http://symfony.com/schema/dic/symfony"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/symfony
-                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-                <imports>
-                    <import resource="../prod/"/>
-
-                    <!-- other resources are possible as well, like importing other
-                         files or using globs:
-                    <import resource="/etc/myapp/some_special_config.yaml"/>
-                    <import resource="/etc/myapp/*.xml"/>
-                    -->
-                </imports>
-
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/benchmark/other.php
-            $loader->import('../prod/');
-
-            // other resources are possible as well, like importing other
-            // files or using globs:
-            //$loader->import('/etc/myapp/some_special_config.yaml');
-            //$loader->import('/etc/myapp/*.php');
-
-.. index::
-   single: Environments; Cache directory
-
-Environments and the Cache Directory
-------------------------------------
-
-Symfony takes advantage of caching in many ways: the application configuration,
-routing configuration, Twig templates and more are cached to PHP objects
-stored in files on the filesystem.
-
-By default, these cached files are largely stored in the ``var/cache/`` directory.
-However, each environment caches its own set of files:
-
-.. code-block:: text
-
-    your-project/
-    ├─ var/
-    │  ├─ cache/
-    │  │  ├─ dev/   # cache directory for the *dev* environment
-    │  │  └─ prod/  # cache directory for the *prod* environment
-    │  ├─ ...
-
-Sometimes, when debugging, it may be helpful to inspect a cached file to
-understand how something is working. When doing so, remember to look in
-the directory of the environment you're using (most commonly ``dev/`` while
-developing and debugging). While it can vary, the ``var/cache/dev/`` directory
-includes the following:
-
-``appDevDebugProjectContainer.php``
-    The cached "service container" that represents the cached application
-    configuration.
-
-``appDevUrlGenerator.php``
-    The PHP class generated from the routing configuration and used when
-    generating URLs.
-
-``appDevUrlMatcher.php``
-    The PHP class used for route matching - look here to see the compiled regular
-    expression logic used to match incoming URLs to different routes.
-
-``twig/``
-    This directory contains all the cached Twig templates.
-
-.. note::
-
-    You can change the directory location and name. For more information
-    read the article :doc:`/configuration/override_dir_structure`.
-
-Going further
--------------
-
-Read the article on :doc:`/configuration/external_parameters`.
diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst
deleted file mode 100644
index 362f1e1b302..00000000000
--- a/configuration/external_parameters.rst
+++ /dev/null
@@ -1,522 +0,0 @@
-.. index::
-    single: Environments; External parameters
-
-How to Set external Parameters in the Service Container
-=======================================================
-
-In :doc:`/configuration`, you learned how to manage your application
-configuration. At times, it may benefit your application to store certain
-credentials outside of your project code. Database configuration is one such
-example. The flexibility of the Symfony service container allows you to easily
-do this.
-
-.. _config-env-vars:
-
-Environment Variables
----------------------
-
-You can reference environment variables by using special parameters named after
-the variables you want to use enclosed between ``env()``. Their actual values
-will be resolved at runtime (once per request), so that dumped containers can be
-reconfigured dynamically even after being compiled.
-
-For example, when installing the ``doctrine`` recipe, database configuration is
-put in a ``DATABASE_URL`` environment variable:
-
-.. code-block:: bash
-
-    # .env
-    DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"
-
-This variable is referenced in the service container configuration using
-``%env(DATABASE_URL)%``:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/doctrine.yaml
-        doctrine:
-            dbal:
-                url: '%env(DATABASE_URL)%'
-            # ...
-
-    .. code-block:: xml
-
-        <!-- config/packages/doctrine.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
-
-            <doctrine:config>
-                <doctrine:dbal
-                    url="%env(DATABASE_URL)%"
-                />
-            </doctrine:config>
-
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/doctrine.php
-        $container->loadFromExtension('doctrine', [
-            'dbal' => [
-                'url' => '%env(DATABASE_URL)%',
-            ]
-        ]);
-
-You can also give the ``env()`` parameters a default value: the default value
-will be used whenever the corresponding environment variable is *not* found:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            env(DATABASE_HOST): localhost
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="env(DATABASE_HOST)">localhost</parameter>
-            </parameters>
-         </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('env(DATABASE_HOST)', 'localhost');
-
-.. _configuration-env-var-in-prod:
-
-Configuring Environment Variables in Production
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-During development, you'll use the ``.env`` file to configure your environment
-variables. On your production server, it is recommended to configure these at
-the web server level. If you're using Apache or Nginx, you can use e.g. one of
-the following:
-
-.. configuration-block::
-
-    .. code-block:: apache
-
-        <VirtualHost *:80>
-            # ...
-
-            SetEnv DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name"
-        </VirtualHost>
-
-    .. code-block:: nginx
-
-        fastcgi_param DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name";
-
-.. caution::
-
-    Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
-    or outputting the ``phpinfo()`` contents will display the values of the
-    environment variables, exposing sensitive information such as the database
-    credentials.
-
-    The values of the env vars are also exposed in the web interface of the
-    :doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
-    problem because the web profiler must **never** be enabled in production.
-
-Environment Variable Processors
--------------------------------
-
-The values of environment variables are considered strings by default.
-However, your code may expect other data types, like integers or booleans.
-Symfony solves this problem with *processors*, which modify the contents of the
-given environment variables. The following example uses the integer processor to
-turn the value of the ``HTTP_PORT`` env var into an integer:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/framework.yaml
-        framework:
-            router:
-                http_port: env(int:HTTP_PORT)
-
-    .. code-block:: xml
-
-        <!-- config/packages/framework.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <framework:config>
-                <framework:router http-port="%env(int:HTTP_PORT)%" />
-            </framework:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/framework.php
-        $container->loadFromExtension('framework', [
-            'router' => [
-                'http_port' => '%env(int:HTTP_PORT)%',
-            ],
-        ]);
-
-Symfony provides the following env var processors:
-
-``env(string:FOO)``
-    Casts ``FOO`` to a string:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/framework.yaml
-            parameters:
-                env(SECRET): 'some_secret'
-            framework:
-                secret: '%env(string:SECRET)%'
-
-        .. code-block:: xml
-
-            <!-- config/packages/framework.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:framework="http://symfony.com/schema/dic/symfony"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/symfony
-                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(SECRET)">some_secret</parameter>
-                </parameters>
-
-                <framework:config secret="%env(string:SECRET)%" />
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/framework.php
-            $container->setParameter('env(SECRET)', 'some_secret');
-            $container->loadFromExtension('framework', [
-                'secret' => '%env(string:SECRET)%',
-            ]);
-
-``env(bool:FOO)``
-    Casts ``FOO`` to a bool:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/framework.yaml
-            parameters:
-                env(HTTP_METHOD_OVERRIDE): 'true'
-            framework:
-                http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'
-
-        .. code-block:: xml
-
-            <!-- config/packages/framework.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:framework="http://symfony.com/schema/dic/symfony"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/symfony
-                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(HTTP_METHOD_OVERRIDE)">true</parameter>
-                </parameters>
-
-                <framework:config http-methode-override="%env(bool:HTTP_METHOD_OVERRIDE)%" />
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/framework.php
-            $container->setParameter('env(HTTP_METHOD_OVERRIDE)', 'true');
-            $container->loadFromExtension('framework', [
-                'http_method_override' => '%env(bool:HTTP_METHOD_OVERRIDE)%',
-            ]);
-
-``env(int:FOO)``
-    Casts ``FOO`` to an int.
-
-``env(float:FOO)``
-    Casts ``FOO`` to a float.
-
-``env(const:FOO)``
-    Finds the const value named in ``FOO``:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/security.yaml
-            parameters:
-                env(HEALTH_CHECK_METHOD): 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD'
-            security:
-                access_control:
-                    - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' }
-
-        .. code-block:: xml
-
-            <!-- config/packages/security.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:security="http://symfony.com/schema/dic/security"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(HEALTH_CHECK_METHOD)">Symfony\Component\HttpFoundation\Request::METHOD_HEAD</parameter>
-                </parameters>
-
-                <security:config>
-                    <rule path="^/health-check$" methods="%env(const:HEALTH_CHECK_METHOD)%" />
-                </security:config>
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/security.php
-            $container->setParameter('env(HEALTH_CHECK_METHOD)', 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD');
-            $container->loadFromExtension('security', [
-                'access_control' => [
-                    [
-                        'path' => '^/health-check$',
-                        'methods' => '%env(const:HEALTH_CHECK_METHOD)%',
-                    ],
-                ],
-            ]);
-
-``env(base64:FOO)``
-    Decodes the content of ``FOO``, which is a base64 encoded string.
-
-``env(json:FOO)``
-    Decodes the content of ``FOO``, which is a JSON encoded string. It returns
-    either an array or ``null``:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/framework.yaml
-            parameters:
-                env(TRUSTED_HOSTS): '["10.0.0.1", "10.0.0.2"]'
-            framework:
-                trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
-
-        .. code-block:: xml
-
-            <!-- config/packages/framework.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:framework="http://symfony.com/schema/dic/symfony"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/symfony
-                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(TRUSTED_HOSTS)">["10.0.0.1", "10.0.0.2"]</parameter>
-                </parameters>
-
-                <framework:config trusted-hosts="%env(json:TRUSTED_HOSTS)%" />
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/framework.php
-            $container->setParameter('env(TRUSTED_HOSTS)', '["10.0.0.1", "10.0.0.2"]');
-            $container->loadFromExtension('framework', [
-                'trusted_hosts' => '%env(json:TRUSTED_HOSTS)%',
-            ]);
-
-``env(resolve:FOO)``
-    Replaces the string ``FOO`` by the value of a config parameter with the
-    same name:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/sentry.yaml
-            parameters:
-                env(HOST): '10.0.0.1'
-                env(SENTRY_DSN): 'http://%env(HOST)%/project'
-            sentry:
-                dsn: '%env(resolve:SENTRY_DSN)%'
-
-        .. code-block:: xml
-
-            <!-- config/packages/sentry.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(HOST)">10.0.0.1</parameter>
-                    <parameter key="env(SENTRY_DSN)">http://%env(HOST)%/project</parameter>
-                </parameters>
-
-                <sentry:config dsn="%env(resolve:SENTRY_DSN)%" />
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/sentry.php
-            $container->setParameter('env(HOST)', '10.0.0.1');
-            $container->setParameter('env(SENTRY_DSN)', 'http://%env(HOST)%/project');
-            $container->loadFromExtension('sentry', [
-                'dsn' => '%env(resolve:SENTRY_DSN)%',
-            ]);
-
-``env(csv:FOO)``
-    Decodes the content of ``FOO``, which is a CSV-encoded string:
-
-    .. code-block:: yaml
-
-        parameters:
-            env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2"
-        framework:
-           trusted_hosts: '%env(csv:TRUSTED_HOSTS)%'
-
-    .. versionadded:: 4.1
-        The ``csv`` processor was introduced in Symfony 4.1.
-
-``env(file:FOO)``
-    Returns the contents of a file whose path is the value of the ``FOO`` env var:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/framework.yaml
-            parameters:
-                env(AUTH_FILE): '../config/auth.json'
-            google:
-                auth: '%env(file:AUTH_FILE)%'
-
-        .. code-block:: xml
-
-            <!-- config/packages/framework.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:framework="http://symfony.com/schema/dic/symfony"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/symfony
-                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-                <parameters>
-                    <parameter key="env(AUTH_FILE)">../config/auth.json</parameter>
-                </parameters>
-
-                <google auth="%env(file:AUTH_FILE)%" />
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/framework.php
-            $container->setParameter('env(AUTH_FILE)', '../config/auth.json');
-            $container->loadFromExtension('google', [
-                'auth' => '%env(file:AUTH_FILE)%',
-            ]);
-
-It is also possible to combine any number of processors:
-
-.. code-block:: yaml
-
-    parameters:
-        env(AUTH_FILE): "%kernel.project_dir%/config/auth.json"
-    google:
-        # 1. gets the value of the AUTH_FILE env var
-        # 2. replaces the values of any config param to get the config path
-        # 3. gets the content of the file stored in that path
-        # 4. JSON-decodes the content of the file and returns it
-        auth: '%env(json:file:resolve:AUTH_FILE)%'
-
-Custom Environment Variable Processors
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It's also possible to add your own processors for environment variables. First,
-create a class that implements
-:class:`Symfony\\Component\\DependencyInjection\\EnvVarProcessorInterface`::
-
-    use Symfony\Component\DependencyInjection\EnvVarProcessorInterface;
-
-    class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
-    {
-        public function getEnv($prefix, $name, \Closure $getEnv)
-        {
-            $env = $getEnv($name);
-
-            return strtolower($env);
-        }
-
-        public static function getProvidedTypes()
-        {
-            return [
-                'lowercase' => 'string',
-            ];
-        }
-    }
-
-To enable the new processor in the app, register it as a service and
-:doc:`tag it </service_container/tags>` with the ``container.env_var_processor``
-tag. If you're using the
-:ref:`default services.yaml configuration <service-container-services-load-example>`,
-this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
-
-Constants
----------
-
-The container also has support for setting PHP constants as parameters.
-See :ref:`component-di-parameters-constants` for more details.
-
-Miscellaneous Configuration
----------------------------
-
-You can mix whatever configuration format you like (YAML, XML and PHP) in
-``config/packages/``.  Importing a PHP file gives you the flexibility to add
-whatever is needed in the container. For instance, you can create a
-``drupal.php`` file in which you set a database URL based on Drupal's database
-configuration::
-
-    // config/packages/drupal.php
-
-    // import Drupal's configuration
-    include_once('/path/to/drupal/sites/default/settings.php');
-
-    // set a app.database_url parameter
-    $container->setParameter('app.database_url', $db_url);
-
-.. _`SetEnv`: http://httpd.apache.org/docs/current/env.html
-.. _`fastcgi_param`: http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param
diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst
index 61ded2eb384..d986d7471b7 100644
--- a/configuration/front_controllers_and_kernel.rst
+++ b/configuration/front_controllers_and_kernel.rst
@@ -5,11 +5,11 @@
 Understanding how the Front Controller, Kernel and Environments Work together
 =============================================================================
 
-The section :doc:`/configuration/environments` explained the basics on how
-Symfony uses environments to run your application with different configuration
-settings. This section will explain a bit more in-depth what happens when your
-application is bootstrapped. To hook into this process, you need to understand
-three parts that work together:
+The :ref:`configuration environments <configuration-environments>` section
+explained the basics on how Symfony uses environments to run your application
+with different configuration settings. This section will explain a bit more
+in-depth what happens when your application is bootstrapped. To hook into this
+process, you need to understand three parts that work together:
 
 * `The Front Controller`_
 * `The Kernel Class`_
@@ -74,7 +74,7 @@ It then creates the service container before serving requests in its
 :method:`Symfony\\Component\\HttpKernel\\HttpKernelInterface::handle`
 method.
 
-The kernel used in Symfony apps extends from :class:`Symfony\\Component\\HttpKernel\\Kernel`
+The kernel used in Symfony applications extends from :class:`Symfony\\Component\\HttpKernel\\Kernel`
 and uses the :class:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait`.
 The ``Kernel`` class leaves some methods from :class:`Symfony\\Component\\HttpKernel\\KernelInterface`
 unimplemented and the ``MicroKernelTrait`` defines several abstract methods, so
@@ -101,9 +101,9 @@ This class uses the name of the environment - which is passed to the Kernel's
 method and is available via :method:`Symfony\\Component\\HttpKernel\\Kernel::getEnvironment` -
 to decide which bundles to enable. The logic for that is in ``registerBundles()``.
 
-You are, of course, free to create your own, alternative or additional
-``Kernel`` variants. All you need is to adapt your (or add a new) front
-controller to make use of the new kernel.
+You are free to create your own, alternative or additional ``Kernel`` variants.
+All you need is to adapt your (or add a new) front controller to make use of the
+new kernel.
 
 .. note::
 
@@ -120,6 +120,77 @@ controller to make use of the new kernel.
     But odds are high that you don't need to change things like this on the
     fly by having several ``Kernel`` implementations.
 
+.. index::
+   single: Configuration; Debug mode
+
+Debug Mode
+~~~~~~~~~~
+
+The second argument to the ``Kernel`` constructor specifies if the application
+should run in "debug mode". Regardless of the
+:ref:`configuration environment <configuration-environments>`, a Symfony
+application can be run with debug mode set to ``true`` or ``false``.
+
+This affects many things in the application, such as displaying stacktraces on
+error pages or if cache files are dynamically rebuilt on each request. Though
+not a requirement, debug mode is generally set to ``true`` for the ``dev`` and
+``test`` environments and ``false`` for the ``prod`` environment.
+
+Similar to :ref:`configuring the environment <selecting-the-active-environment>`
+you can also enable/disable the debug mode using :ref:`the .env file <config-dot-env>`:
+
+.. code-block:: bash
+
+    # .env
+    # set it to 1 to enable the debug mode
+    APP_DEBUG=0
+
+This value can be overridden for commands by passing the ``APP_DEBUG`` value
+before running them:
+
+.. code-block:: terminal
+
+    # Use the debug mode defined in the .env file
+    $ php bin/console command_name
+
+    # Ignore the .env file and enable the debug mode for this command
+    $ APP_DEBUG=1 php bin/console command_name
+
+Internally, the value of the debug mode becomes the ``kernel.debug``
+parameter used inside the :doc:`service container </service_container>`.
+If you look inside the application configuration file, you'll see the
+parameter used, for example, to turn Twig's debug mode on:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/twig.yaml
+        twig:
+            debug: '%kernel.debug%'
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <twig:config debug="%kernel.debug%"/>
+
+        </container>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('twig', [
+            'debug' => '%kernel.debug%',
+            // ...
+        ]);
+
 The Environments
 ----------------
 
@@ -128,9 +199,9 @@ As mentioned above, the ``Kernel`` has to implement another method -
 This method is responsible for loading the application's configuration from the
 right *environment*.
 
-Environments have been covered extensively :doc:`in the previous article
-</configuration/environments>`, and you probably remember that the Symfony uses
-by default three of them - ``dev``, ``prod`` and ``test``.
+:ref:`Configuration environments <configuration-environments>` allow to execute
+the same code using different configuration. Symfony provides three environments
+by default called ``dev``, ``prod`` and ``test``.
 
 More technically, these names are nothing more than strings passed from the
 front controller to the ``Kernel``'s constructor. This name can then be used in
@@ -138,9 +209,56 @@ the ``configureContainer()`` method to decide which configuration files to load.
 
 Symfony's default ``Kernel`` class implements this method by loading first the
 config files found on ``config/packages/*`` and then, the files found on
-``config/packages/ENVIRONMENT_NAME/``. You are, of course, free to implement
-this method differently if you need a more sophisticated way of loading your
-configuration.
+``config/packages/ENVIRONMENT_NAME/``. You are free to implement this method
+differently if you need a more sophisticated way of loading your configuration.
+
+.. index::
+   single: Environments; Cache directory
+
+Environments and the Cache Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony takes advantage of caching in many ways: the application configuration,
+routing configuration, Twig templates and more are cached to PHP objects
+stored in files on the filesystem.
+
+By default, these cached files are largely stored in the ``var/cache/`` directory.
+However, each environment caches its own set of files:
+
+.. code-block:: text
+
+    your-project/
+    ├─ var/
+    │  ├─ cache/
+    │  │  ├─ dev/   # cache directory for the *dev* environment
+    │  │  └─ prod/  # cache directory for the *prod* environment
+    │  ├─ ...
+
+Sometimes, when debugging, it may be helpful to inspect a cached file to
+understand how something is working. When doing so, remember to look in
+the directory of the environment you're using (most commonly ``dev/`` while
+developing and debugging). While it can vary, the ``var/cache/dev/`` directory
+includes the following:
+
+``appDevDebugProjectContainer.php``
+    The cached "service container" that represents the cached application
+    configuration.
+
+``appDevUrlGenerator.php``
+    The PHP class generated from the routing configuration and used when
+    generating URLs.
+
+``appDevUrlMatcher.php``
+    The PHP class used for route matching - look here to see the compiled regular
+    expression logic used to match incoming URLs to different routes.
+
+``twig/``
+    This directory contains all the cached Twig templates.
+
+.. note::
+
+    You can change the cache directory location and name. For more information
+    read the article :doc:`/configuration/override_dir_structure`.
 
-.. _front controller: https://en.wikipedia.org/wiki/Front_Controller_pattern
-.. _decorate: https://en.wikipedia.org/wiki/Decorator_pattern
+.. _`front controller`: https://en.wikipedia.org/wiki/Front_Controller_pattern
+.. _`decorate`: https://en.wikipedia.org/wiki/Decorator_pattern
diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst
index f6b5eedf1f6..4676c9a27e4 100644
--- a/configuration/micro_kernel_trait.rst
+++ b/configuration/micro_kernel_trait.rst
@@ -14,7 +14,7 @@ A Single-File Symfony Application
 Start with a completely empty directory and install these Symfony components
 via Composer:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     $ composer require symfony/config symfony/http-kernel \
       symfony/http-foundation symfony/routing \
@@ -72,11 +72,12 @@ Next, create an ``index.php`` file that defines the kernel class and executes it
     $response->send();
     $kernel->terminate($request, $response);
 
-That's it! To test it, you can start the built-in web server:
+That's it! To test it, start the :doc:`Symfony Local Web Server
+</setup/symfony_server>`:
 
 .. code-block:: terminal
 
-    $ php -S localhost:8000
+    $ symfony server:start
 
 Then see the JSON response in your browser:
 
@@ -220,11 +221,11 @@ because the configuration started to get bigger:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config secret="S0ME_SECRET">
-                <framework:profiler only-exceptions="false" />
+                <framework:profiler only-exceptions="false"/>
             </framework:config>
         </container>
 
@@ -282,7 +283,6 @@ Finally, you need a front controller to boot and run the application. Create a
 ``public/index.php``::
 
     // public/index.php
-
     use App\Kernel;
     use Doctrine\Common\Annotations\AnnotationRegistry;
     use Symfony\Component\HttpFoundation\Request;
@@ -323,12 +323,13 @@ this:
     ├─ composer.json
     └─ composer.lock
 
-As before you can use PHP built-in server:
+As before you can use the :doc:`Symfony Local Web Server
+</setup/symfony_server>`:
 
 .. code-block:: terminal
 
     cd public/
-    $ php -S localhost:8000 -t public/
+    $ symfony server:start
 
 Then see webpage in browser:
 
diff --git a/configuration/multiple_kernels.rst b/configuration/multiple_kernels.rst
index d5999b96c20..235305ce090 100644
--- a/configuration/multiple_kernels.rst
+++ b/configuration/multiple_kernels.rst
@@ -16,7 +16,7 @@ request to generate the response.
 
 This single kernel approach is a convenient default, but Symfony applications
 can define any number of kernels. Whereas
-:doc:`environments </configuration/environments>` execute the same application
+:ref:`environments <configuration-environments>` execute the same application
 with different configurations, kernels can execute different parts of the same
 application.
 
@@ -82,9 +82,9 @@ Kernel. Be sure to also change the location of the cache, logs and configuration
 files so they don't collide with the files from ``src/Kernel.php``::
 
     // src/ApiKernel.php
-    use Symfony\Component\HttpKernel\Kernel;
     use Symfony\Component\Config\Loader\LoaderInterface;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\HttpKernel\Kernel;
 
     class ApiKernel extends Kernel
     {
diff --git a/configuration/override_dir_structure.rst b/configuration/override_dir_structure.rst
index 2e6bb5d3e82..fbfa119cc14 100644
--- a/configuration/override_dir_structure.rst
+++ b/configuration/override_dir_structure.rst
@@ -4,9 +4,8 @@
 How to Override Symfony's default Directory Structure
 =====================================================
 
-Symfony automatically ships with a default directory structure. You can
-override this directory structure to create your own. The default
-directory structure is:
+Symfony applications have the following default directory structure, but you can
+override it to create your own structure:
 
 .. code-block:: text
 
@@ -28,10 +27,19 @@ directory structure is:
     │  └─ ...
     └─ vendor/
 
+.. _override-config-dir:
+
+Override the Configuration Directory
+------------------------------------
+
+The configuration directory is the only one which cannot be overridden in a
+Symfony application. Its location is hardcoded as the ``config/`` directory
+at your project root directory.
+
 .. _override-cache-dir:
 
-Override the ``cache`` Directory
---------------------------------
+Override the Cache Directory
+----------------------------
 
 You can change the default cache directory by overriding the ``getCacheDir()``
 method in the ``Kernel`` class of your application::
@@ -51,21 +59,21 @@ method in the ``Kernel`` class of your application::
 
 In this code, ``$this->environment`` is the current environment (i.e. ``dev``).
 In this case you have changed the location of the cache directory to
-``var/{environment}/cache``.
+``var/{environment}/cache/``.
 
 .. caution::
 
-    You should keep the ``cache`` directory different for each environment,
+    You should keep the cache directory different for each environment,
     otherwise some unexpected behavior may happen. Each environment generates
     its own cached configuration files, and so each needs its own directory to
     store those cache files.
 
 .. _override-logs-dir:
 
-Override the ``logs`` Directory
--------------------------------
+Override the Log Directory
+--------------------------
 
-Overriding the ``logs`` directory is the same as overriding the ``cache``
+Overriding the ``var/log/`` directory is the same as overriding the ``var/cache/``
 directory. The only difference is that you need to override the ``getLogDir()``
 method::
 
@@ -82,7 +90,7 @@ method::
         }
     }
 
-Here you have changed the location of the directory to ``var/{environment}/log``.
+Here you have changed the location of the directory to ``var/{environment}/log/``.
 
 .. _override-templates-dir:
 
@@ -110,9 +118,9 @@ own templates directory (or directories):
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <twig:path>%kernel.project_dir%/resources/views</twig:path>
@@ -154,9 +162,9 @@ configuration option to define your own translations directory (or directories):
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <framework:config>
                 <framework:translator>
@@ -180,19 +188,19 @@ configuration option to define your own translations directory (or directories):
 .. _override-web-dir:
 .. _override-the-web-directory:
 
-Override the ``public`` Directory
----------------------------------
+Override the Public Directory
+-----------------------------
 
-If you need to rename or move your ``public`` directory, the only thing you need
-to guarantee is that the path to the ``var`` directory is still correct in your
-``index.php`` front controller. If you simply renamed the directory, you're
-fine. But if you moved it in some way, you may need to modify these paths inside
-those files::
+If you need to rename or move your ``public/`` directory, the only thing you
+need to guarantee is that the path to the ``var/`` directory is still correct in
+your ``index.php`` front controller. If you renamed the directory, you're fine.
+But if you moved it in some way, you may need to modify these paths inside those
+files::
 
     require_once __DIR__.'/../path/to/vendor/autoload.php';
 
-You also need to change the ``extra.public-dir`` option in the
-``composer.json`` file:
+You also need to change the ``extra.public-dir`` option in the ``composer.json``
+file:
 
 .. code-block:: json
 
@@ -206,17 +214,17 @@ You also need to change the ``extra.public-dir`` option in the
 
 .. tip::
 
-    Some shared hosts have a ``public_html`` web directory root. Renaming
-    your web directory from ``public`` to ``public_html`` is one way to make
+    Some shared hosts have a ``public_html/`` web directory root. Renaming
+    your web directory from ``public/`` to ``public_html/`` is one way to make
     your Symfony project work on your shared host. Another way is to deploy
     your application to a directory outside of your web root, delete your
-    ``public_html`` directory, and then replace it with a symbolic link to
-    the ``public`` dir in your project.
+    ``public_html/`` directory, and then replace it with a symbolic link to
+    the ``public/`` dir in your project.
 
-Override the ``vendor`` Directory
----------------------------------
+Override the Vendor Directory
+-----------------------------
 
-To override the ``vendor`` directory, you need to define the ``vendor-dir``
+To override the ``vendor/`` directory, you need to define the ``vendor-dir``
 option in your ``composer.json`` file like this:
 
 .. code-block:: json
@@ -230,6 +238,6 @@ option in your ``composer.json`` file like this:
 
 .. tip::
 
-    This modification can be of interest if you are working in a virtual environment
-    and cannot use NFS - for example, if you're running a Symfony application using
-    Vagrant/VirtualBox in a guest operating system.
+    This modification can be of interest if you are working in a virtual
+    environment and cannot use NFS - for example, if you're running a Symfony
+    application using Vagrant/VirtualBox in a guest operating system.
diff --git a/configuration/using_parameters_in_dic.rst b/configuration/using_parameters_in_dic.rst
index 9a45d0e4eca..758bb68d39a 100644
--- a/configuration/using_parameters_in_dic.rst
+++ b/configuration/using_parameters_in_dic.rst
@@ -53,15 +53,15 @@ Now, examine the results to see this closely:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:my-bundle="http://example.org/schema/dic/my_bundle">
 
-            <my-bundle:config logging="true" />
+            <my-bundle:config logging="true"/>
             <!-- true, as expected -->
 
-            <my-bundle:config logging="%kernel.debug%" />
+            <my-bundle:config logging="%kernel.debug%"/>
             <!-- true/false (depends on 2nd parameter of Kernel),
                  as expected, because %kernel.debug% inside configuration
                  gets evaluated before being passed to the extension -->
 
-            <my-bundle:config />
+            <my-bundle:config/>
             <!-- passes the string "%kernel.debug%".
                  Which is always considered as true.
                  The Configurator does not know anything about
@@ -109,10 +109,9 @@ be injected with this parameter via the extension as follows::
 
         public function getConfigTreeBuilder()
         {
-            $treeBuilder = new TreeBuilder();
-            $rootNode = $treeBuilder->root('my_bundle');
+            $treeBuilder = new TreeBuilder('my_bundle');
 
-            $rootNode
+            $treeBuilder->getRootNode()
                 ->children()
                     // ...
                     ->booleanNode('logging')->defaultValue($this->debug)->end()
@@ -144,5 +143,5 @@ And set it in the constructor of ``Configuration`` via the ``Extension`` class::
 .. tip::
 
     There are some instances of ``%kernel.debug%`` usage within a
-    ``Configurator`` class for example in TwigBundle. However this is because
+    ``Configurator`` class for example in TwigBundle. However, this is because
     the default parameter value is set by the Extension class.
diff --git a/console.rst b/console.rst
index cf449547fd7..7e8e65c0f1c 100644
--- a/console.rst
+++ b/console.rst
@@ -52,8 +52,7 @@ want a command to create a user::
 Configuring the Command
 -----------------------
 
-First of all, you must configure the name of the command in the ``configure()``
-method. Then you can optionally define a help message and the
+You can optionally define a description, help message and the
 :doc:`input options and arguments </console/input>`::
 
     // ...
@@ -92,7 +91,7 @@ available in the ``configure()`` method::
             parent::__construct();
         }
 
-        public function configure()
+        protected function configure()
         {
             $this
                 // ...
@@ -149,10 +148,6 @@ the console::
         $output->write('create a user.');
     }
 
-.. versionadded:: 4.1
-    The support of PHP iterators in the ``write()`` and ``writeln()`` methods
-    was introduced in Symfony 4.1.
-
 Now, try executing the command:
 
 .. code-block:: terminal
@@ -169,9 +164,6 @@ Now, try executing the command:
 Output Sections
 ~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.1
-    Output sections were introduced in Symfony 4.1.
-
 The regular console output can be divided into multiple independent regions
 called "output sections". Create one or more of these sections when you need to
 clear and overwrite the output information.
@@ -269,8 +261,8 @@ as a service, you can use normal dependency injection. Imagine you have a
 ``App\Service\UserManager`` service that you want to access::
 
     // ...
-    use Symfony\Component\Console\Command\Command;
     use App\Service\UserManager;
+    use Symfony\Component\Console\Command\Command;
 
     class CreateUserCommand extends Command
     {
diff --git a/console/coloring.rst b/console/coloring.rst
index a12cb29af96..774a2ab96fa 100644
--- a/console/coloring.rst
+++ b/console/coloring.rst
@@ -74,8 +74,26 @@ You can also set these colors and options directly inside the tag name::
     or use the :method:`Symfony\\Component\\Console\\Formatter\\OutputFormatter::escape`
     method to escape all the tags included in the given string.
 
-.. _Cmder: http://cmder.net/
+Displaying Clickable Links
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The feature to display clickable links was introduced in Symfony 4.3.
+
+Commands can use the special ``<href>`` tag to display links similar to the
+``<a>`` elements of web pages::
+
+    $output->writeln('<href=https://symfony.com>Symfony Homepage</>');
+
+If your terminal belongs to the `list of terminal emulators that support links`_
+you can click on the *"Symfony Homepage"* text to open its URL in your default
+browser. Otherwise, you'll see *"Symfony Homepage"* as regular text and the URL
+will be lost.
+
+.. _Cmder: https://cmder.net/
 .. _ConEmu: https://conemu.github.io/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases
 .. _Mintty: https://mintty.github.io/
 .. _Hyper: https://hyper.is/
+.. _`list of terminal emulators that support links`: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
diff --git a/console/command_in_controller.rst b/console/command_in_controller.rst
index 08e934bbec4..6559ae15c0a 100644
--- a/console/command_in_controller.rst
+++ b/console/command_in_controller.rst
@@ -21,7 +21,7 @@ their code. Instead, you can execute the command directly.
     overhead.
 
 Imagine you want to send spooled Swift Mailer messages by
-:doc:`using the swiftmailer:spool:send command </email/spool>`.
+:doc:`using the swiftmailer:spool:send command </email>`.
 Run this command from inside your controller via::
 
     // src/Controller/SpoolController.php
@@ -42,11 +42,11 @@ Run this command from inside your controller via::
             $application->setAutoExit(false);
 
             $input = new ArrayInput([
-               'command' => 'swiftmailer:spool:send',
-               // (optional) define the value of command arguments
-               'fooArgument' => 'barValue',
-               // (optional) pass options to the command
-               '--message-limit' => $messages,
+                'command' => 'swiftmailer:spool:send',
+                // (optional) define the value of command arguments
+                'fooArgument' => 'barValue',
+                // (optional) pass options to the command
+                '--message-limit' => $messages,
             ]);
 
             // You can use NullOutput() if you don't need the output
diff --git a/console/commands_as_services.rst b/console/commands_as_services.rst
index 1e4f0a111fb..000dffeca48 100644
--- a/console/commands_as_services.rst
+++ b/console/commands_as_services.rst
@@ -13,12 +13,6 @@ recommended setup.
     You can also manually register your command as a service by configuring the service
     and :doc:`tagging it </service_container/tags>` with ``console.command``.
 
-In either case, if your class extends :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\ContainerAwareCommand`,
-you can access public services via ``$this->getContainer()->get('SERVICE_ID')``.
-
-But if your class is registered as a service, you can instead access services by
-using normal :ref:`dependency injection <services-constructor-injection>`.
-
 For example, suppose you want to log something from within your command::
 
     namespace App\Command;
@@ -30,6 +24,7 @@ For example, suppose you want to log something from within your command::
 
     class SunshineCommand extends Command
     {
+        protected static $defaultName = 'app:sunshine';
         private $logger;
 
         public function __construct(LoggerInterface $logger)
@@ -43,7 +38,6 @@ For example, suppose you want to log something from within your command::
         protected function configure()
         {
             $this
-                ->setName('app:sunshine')
                 ->setDescription('Good morning!');
         }
 
@@ -66,6 +60,13 @@ works! You can call the ``app:sunshine`` command and start logging.
     work (e.g. making database queries), as that code will be run, even if you're using
     the console to execute a different command.
 
+.. note::
+
+    In previous Symfony versions, you could make the command class extend from
+    :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\ContainerAwareCommand` to
+    get services via ``$this->getContainer()->get('SERVICE_ID')``. This is
+    deprecated in Symfony 4.2 and it won't work in future Symfony versions.
+
 .. _console-command-service-lazy-loading:
 
 Lazy Loading
@@ -99,11 +100,11 @@ Or set the ``command`` attribute on the ``console.command`` tag in your service
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Command\SunshineCommand">
-                     <tag name="console.command" command="app:sunshine" />
+                    <tag name="console.command" command="app:sunshine"/>
                 </service>
             </services>
         </container>
@@ -112,7 +113,7 @@ Or set the ``command`` attribute on the ``console.command`` tag in your service
 
         // config/services.php
         use App\Command\SunshineCommand;
-        //...
+        // ...
 
         $container
             ->register(SunshineCommand::class)
diff --git a/console/hide_commands.rst b/console/hide_commands.rst
index 827f93a0a4a..814888fe660 100644
--- a/console/hide_commands.rst
+++ b/console/hide_commands.rst
@@ -18,10 +18,11 @@ In those cases, you can define the command as **hidden** by setting the
 
     class LegacyCommand extends Command
     {
+        protected static $defaultName = 'app:legacy';
+
         protected function configure()
         {
             $this
-                ->setName('app:legacy')
                 ->setHidden(true)
                 // ...
             ;
diff --git a/console/input.rst b/console/input.rst
index 71dc5209bba..e1c4c48af06 100644
--- a/console/input.rst
+++ b/console/input.rst
@@ -119,7 +119,7 @@ Using Command Options
 Unlike arguments, options are not ordered (meaning you can specify them in any
 order) and are specified with two dashes (e.g. ``--yell``). Options are
 *always* optional, and can be setup to accept a value (e.g. ``--dir=src``) or
-simply as a boolean flag without a value (e.g.  ``--yell``).
+as a boolean flag without a value (e.g.  ``--yell``).
 
 For example, add a new option to the command that can be used to specify
 how many times in a row the message should be printed::
@@ -166,8 +166,8 @@ flag:
 
 .. tip::
 
-     You can also declare a one-letter shortcut that you can call with a single
-     dash, like ``-i``::
+    You can also declare a one-letter shortcut that you can call with a single
+    dash, like ``-i``::
 
         $this
             // ...
diff --git a/console/request_context.rst b/console/request_context.rst
deleted file mode 100644
index b8ffb907c6b..00000000000
--- a/console/request_context.rst
+++ /dev/null
@@ -1,99 +0,0 @@
-.. index::
-   single: Console; Generating URLs
-
-How to Generate URLs from the Console
-=====================================
-
-Unfortunately, the command line context does not know about your VirtualHost
-or domain name. This means that if you generate absolute URLs within a
-console command you'll probably end up with something like ``http://localhost/foo/bar``
-which is not very useful.
-
-To fix this, you need to configure the "request context", which is a fancy
-way of saying that you need to configure your environment so that it knows
-what URL it should use when generating URLs.
-
-There are two ways of configuring the request context: at the application level
-and per Command.
-
-Configuring the Request Context Globally
-----------------------------------------
-
-To configure the Request Context - which is used by the URL Generator - you can
-redefine the parameters it uses as default values to change the default host
-(``localhost``) and scheme (``http``). You can also configure the base path (both for
-the URL generator and the assets) if Symfony is not running in the root directory.
-
-Note that this does not impact URLs generated via normal web requests, since those
-will override the defaults.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            router.request_context.host: 'example.org'
-            router.request_context.scheme: 'https'
-            router.request_context.base_url: 'my/path'
-            asset.request_context.base_path: '%router.request_context.base_url%'
-            asset.request_context.secure: true
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8"?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-
-            <parameters>
-                <parameter key="router.request_context.host">example.org</parameter>
-                <parameter key="router.request_context.scheme">https</parameter>
-                <parameter key="router.request_context.base_url">my/path</parameter>
-                <parameter key="asset.request_context.base_path">%router.request_context.base_url%</parameter>
-                <parameter key="asset.request_context.secure">true</parameter>
-            </parameters>
-
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('router.request_context.host', 'example.org');
-        $container->setParameter('router.request_context.scheme', 'https');
-        $container->setParameter('router.request_context.base_url', 'my/path');
-        $container->setParameter('asset.request_context.base_path', $container->getParameter('router.request_context.base_url'));
-        $container->setParameter('asset.request_context.secure', true);
-
-Configuring the Request Context per Command
--------------------------------------------
-
-To change it only in one command you can fetch the Request Context from the
-router service and override its settings::
-
-    // src/Command/DemoCommand.php
-    use Symfony\Component\Routing\RouterInterface;
-    // ...
-
-    class DemoCommand extends Command
-    {
-        private $router;
-
-        public function __construct(RouterInterface $router)
-        {
-            parent::__construct();
-
-            $this->router = $router;
-        }
-
-        protected function execute(InputInterface $input, OutputInterface $output)
-        {
-            $context = $this->router->getContext();
-            $context->setHost('example.com');
-            $context->setScheme('https');
-            $context->setBaseUrl('my/path');
-
-            $url = $this->router->generate('route-name', ['param-name' => 'param-value']);
-            // ...
-        }
-    }
diff --git a/console/style.rst b/console/style.rst
index e866ecc1e16..88e605f0146 100644
--- a/console/style.rst
+++ b/console/style.rst
@@ -13,11 +13,11 @@ Consider for example the code used to display the title of the following command
     // src/Command/GreetCommand.php
     namespace App\Command;
 
-    use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
+    use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
 
-    class GreetCommand extends ContainerAwareCommand
+    class GreetCommand extends Command
     {
         // ...
 
@@ -53,12 +53,12 @@ title of the command::
     // src/Command/GreetCommand.php
     namespace App\Command;
 
-    use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
-    use Symfony\Component\Console\Style\SymfonyStyle;
+    use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
+    use Symfony\Component\Console\Style\SymfonyStyle;
 
-    class GreetCommand extends ContainerAwareCommand
+    class GreetCommand extends Command
     {
         // ...
 
@@ -226,7 +226,7 @@ User Input Methods
 
         $io->ask('What is your name?');
 
-    You can pass the default value as the second argument so the user can simply
+    You can pass the default value as the second argument so the user can
     hit the <Enter> key to select that value::
 
         $io->ask('Where are you from?', 'United States');
@@ -248,7 +248,9 @@ User Input Methods
 
         $io->askHidden('What is your password?');
 
-        // validates the given answer
+    In case you need to validate the given value, pass a callback validator as
+    the second argument::
+
         $io->askHidden('What is your password?', function ($password) {
             if (empty($password)) {
                 throw new \RuntimeException('Password cannot be empty.');
@@ -262,7 +264,7 @@ User Input Methods
 
         $io->confirm('Restart the web server?');
 
-    You can pass the default value as the second argument so the user can simply
+    You can pass the default value as the second argument so the user can
     hit the <Enter> key to select that value::
 
         $io->confirm('Restart the web server?', true);
@@ -273,7 +275,7 @@ User Input Methods
 
         $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3']);
 
-    You can pass the default value as the third argument so the user can simply
+    You can pass the default value as the third argument so the user can
     hit the <Enter> key to select that value::
 
         $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3'], 'queue1');
@@ -352,23 +354,26 @@ Then, instantiate this custom class instead of the default ``SymfonyStyle`` in
 your commands. Thanks to the ``StyleInterface`` you won't need to change the code
 of your commands to change their appearance::
 
+    // src/Command/GreetCommand.php
     namespace App\Console;
 
     use App\Console\CustomStyle;
+    use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
 
-    class GreetCommand extends ContainerAwareCommand
+    class GreetCommand extends Command
     {
         // ...
 
         protected function execute(InputInterface $input, OutputInterface $output)
         {
             // Before
-            // $io = new SymfonyStyle($input, $output);
+            $io = new SymfonyStyle($input, $output);
 
             // After
             $io = new CustomStyle($input, $output);
+
             // ...
         }
     }
diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst
index dbfe6b0e52c..a631073afec 100644
--- a/contributing/code/bc.rst
+++ b/contributing/code/bc.rst
@@ -22,7 +22,7 @@ method signature.
 
 Also, not every BC break has the same impact on application code. While some BC
 breaks require you to make significant changes to your classes or your
-architecture, others are fixed as easily as changing the name of a method.
+architecture, others are fixed by changing the name of a method.
 
 That's why we created this page for you. The section "Using Symfony Code" will
 tell you how you can ensure that your application won't break completely when
@@ -94,7 +94,7 @@ public methods and properties.
 .. caution::
 
     Classes, properties and methods that bear the tag ``@internal`` as well as
-    the classes located in the various ``*\\Tests\\`` namespaces are an
+    the classes located in the various ``*\Tests\`` namespaces are an
     exception to this rule. They are meant for internal use only and should
     not be accessed by your own code.
 
@@ -445,9 +445,4 @@ Turn static into non static                         No
 
 .. [9] Allowed for the ``void`` return type.
 
-.. _Semantic Versioning: https://semver.org/
-.. _scalar type: https://php.net/manual/en/function.is-scalar.php
-.. _boolean values: https://php.net/manual/en/function.boolval.php
-.. _string values: https://php.net/manual/en/function.strval.php
-.. _integer values: https://php.net/manual/en/function.intval.php
-.. _float values: https://php.net/manual/en/function.floatval.php
+.. _`Semantic Versioning`: https://semver.org/
diff --git a/contributing/code/bugs.rst b/contributing/code/bugs.rst
index 5f0ac3f585d..3b024945271 100644
--- a/contributing/code/bugs.rst
+++ b/contributing/code/bugs.rst
@@ -26,7 +26,7 @@ If your problem definitely looks like a bug, report it using the official bug
 * Describe the steps needed to reproduce the bug with short code examples
   (providing a unit test that illustrates the bug is best);
 
-* If the bug you experienced is not obvious or affects more than one layer,
+* If the bug you experienced is not simple or affects more than one layer,
   providing a simple failing unit test may not be sufficient. In this case,
   please :doc:`provide a reproducer </contributing/code/reproducer>`;
 
@@ -42,11 +42,10 @@ If your problem definitely looks like a bug, report it using the official bug
   **Be wary that stack traces may contain sensitive information, and if it is
   the case, be sure to redact them prior to posting your stack trace.**
 
-* *(optional)* Attach a :doc:`patch <patches>`.
+* *(optional)* Attach a :doc:`patch <pull_requests>`.
 
 .. _`Stack Overflow`: https://stackoverflow.com/questions/tagged/symfony
 .. _IRC channel: https://symfony.com/irc
 .. _the Symfony Slack: https://symfony.com/slack-invite
 .. _tracker: https://github.com/symfony/symfony/issues
-.. _Symfony Standard Edition: https://github.com/symfony/symfony-standard/
 .. _<details> HTML tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst
index b90cbb565da..d3622b57ade 100644
--- a/contributing/code/conventions.rst
+++ b/contributing/code/conventions.rst
@@ -79,31 +79,46 @@ must be used instead (where ``XXX`` is the name of the related thing):
 
 .. _contributing-code-conventions-deprecations:
 
-Deprecations
-------------
+Deprecating Code
+----------------
 
 From time to time, some classes and/or methods are deprecated in the
 framework; that happens when a feature implementation cannot be changed
 because of backward compatibility issues, but we still want to propose a
-"better" alternative. In that case, the old implementation can simply be
-**deprecated**.
+"better" alternative. In that case, the old implementation can be **deprecated**.
+
+Deprecations must only be introduced on the next minor version of the impacted
+component (or bundle, or bridge, or contract).
+They can exceptionally be introduced on previous supported versions if they are critical.
+
+A new class (or interface, or trait) cannot be introduced as deprecated, or
+contain deprecated methods.
+
+A new method cannot be introduced as deprecated.
 
 A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to
 relevant classes, methods, properties, ...::
 
     /**
-     * @deprecated since version 2.8, to be removed in 3.0. Use XXX instead.
+     * @deprecated since Symfony 2.8.
+     */
+
+The deprecation message must indicate the version in which the feature was deprecated,
+and whenever possible, how it was replaced::
+
+    /**
+     * @deprecated since Symfony 2.8, use Replacement instead.
      */
 
-The deprecation message should indicate the version when the class/method was
-deprecated, the version when it will be removed, and whenever possible, how
-the feature was replaced.
+When the replacement is in another namespace than the deprecated class, its FQCN must be used::
+
+    /**
+     * @deprecated since Symfony 2.8, use A\B\Replacement instead.
+     */
 
-A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with
-the migration starting one or two minor versions before the version where the
-feature will be removed (depending on the criticality of the removal)::
+A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration::
 
-    @trigger_error('XXX() is deprecated since version 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);
+    @trigger_error(sprintf('The "%s" class is deprecated since Symfony 2.8, use "%s" instead.', Deprecated::class, Replacement::class), E_USER_DEPRECATED);
 
 Without the `@-silencing operator`_, users would need to opt-out from deprecation
 notices. Silencing swaps this behavior and allows users to opt-in when they are
@@ -114,19 +129,58 @@ the Web Debug Toolbar or by the PHPUnit bridge).
 
 When deprecating a whole class the ``trigger_error()`` call should be placed
 between the namespace and the use declarations, like in this example from
-`ArrayParserCache`_::
+`ServiceRouterLoader`_::
 
-    namespace Symfony\Component\ExpressionLanguage\ParserCache;
+    namespace Symfony\Component\Routing\Loader\DependencyInjection;
 
-    @trigger_error('The '.__NAMESPACE__.'\ArrayParserCache class is deprecated since version 3.2 and will be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.', E_USER_DEPRECATED);
+    use Symfony\Component\Routing\Loader\ContainerLoader;
 
-    use Symfony\Component\ExpressionLanguage\ParsedExpression;
+    @trigger_error(sprintf('The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class), E_USER_DEPRECATED);
 
     /**
-     * @author Adrien Brault <adrien.brault@gmail.com>
-     *
-     * @deprecated ArrayParserCache class is deprecated since version 3.2 and will be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.
+     * @deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead.
      */
-    class ArrayParserCache implements ParserCacheInterface
+    class ServiceRouterLoader extends ObjectRouteLoader
+
+.. _`ServiceRouterLoader`: https://github.com/symfony/symfony/blob/4.4/src/Symfony/Component/Routing/Loader/DependencyInjection/ServiceRouterLoader.php
+
+The deprecation must be added to the ``CHANGELOG.md`` file of the impacted component::
+
+    4.4.0
+    -----
+
+    * Deprecated the `Deprecated` class, use `Replacement` instead.
+
+It must also be added to the ``UPGRADE.md`` file of the targeted minor version
+(``UPGRADE-4.4.md`` in our example)::
+
+    DependencyInjection
+    -------------------
+
+    * Deprecated the `Deprecated` class, use `Replacement` instead.
+
+Finally, its consequences must be added to the ``UPGRADE.md`` file of the next major version
+(``UPGRADE-5.0.md`` in our example)::
+
+    DependencyInjection
+    -------------------
+
+    * Removed the `Deprecated` class, use `Replacement` instead.
+
+All these tasks are mandatory and must be done in the same pull request.
+
+Removing Deprecated Code
+------------------------
+
+Removing deprecated code can only be done once every 2 years, on the next major version of the
+impacted component (``master`` branch).
+
+When removing deprecated code, the consequences of the deprecation must be added to the ``CHANGELOG.md`` file
+of the impacted component::
+
+    5.0.0
+    -----
+
+    * Removed the `Deprecated` class, use `Replacement` instead.
 
-.. _`ArrayParserCache`: https://github.com/symfony/symfony/blob/3.2/src/Symfony/Component/ExpressionLanguage/ParserCache/ArrayParserCache.php
+This task is mandatory and must be done in the same pull request.
diff --git a/contributing/code/core_team.rst b/contributing/code/core_team.rst
index 0c5c37427f2..5a9596fc80f 100644
--- a/contributing/code/core_team.rst
+++ b/contributing/code/core_team.rst
@@ -29,12 +29,7 @@ The Symfony Core groups, in descending order of priority, are as follows:
 
 2. **Mergers Team**
 
-* Merge pull requests for the component or components on which they have been
-  granted privileges.
-
-3. **Deciders Team**
-
-* Decide to merge or reject a pull request.
+* Merge pull requests on the main Symfony repository.
 
 In addition, there are other groups created to manage specific topics:
 
@@ -43,6 +38,10 @@ In addition, there are other groups created to manage specific topics:
 * Manage the whole security process (triaging reported vulnerabilities, fixing
   the reported issues, coordinating the release of security fixes, etc.)
 
+**Recipes Team**
+
+* Manage the recipes in the main and contrib recipe repositories.
+
 **Documentation Team**
 
 * Manage the whole `symfony-docs repository`_.
@@ -50,62 +49,36 @@ In addition, there are other groups created to manage specific topics:
 Active Core Members
 ~~~~~~~~~~~~~~~~~~~
 
-.. role:: leader
-.. role:: merger
-.. role:: decider
-
 * **Project Leader**:
 
   * **Fabien Potencier** (`fabpot`_).
 
 * **Mergers Team** (``@symfony/mergers`` on GitHub):
 
-  * **Tobias Schultze** (`Tobion`_) can merge into the Routing_,
-    OptionsResolver_ and PropertyAccess_ components;
-
-  * **Nicolas Grekas** (`nicolas-grekas`_) can merge into the Cache_, Debug_,
-    Process_, PropertyAccess_, VarDumper_ components, PhpUnitBridge_ and
-    the DebugBundle_;
-
-  * **Christophe Coevoet** (`stof`_) can merge into all components, bridges and
-    bundles;
-
-  * **Kévin Dunglas** (`dunglas`_) can merge into the PropertyInfo_, the Serializer_
-    and the WebLink_ components;
-
-  * **Jakub Zalas** (`jakzal`_) can merge into the DomCrawler_ and Intl_
-    components;
-
-  * **Christian Flothmann** (`xabbuh`_) can merge into the Yaml_ component;
-
-  * **Javier Eguiluz** (`javiereguiluz`_) can merge into the WebProfilerBundle_;
-
-  * **Grégoire Pineau** (`lyrixx`_) can merge into the Workflow_ component;
-
-  * **Ryan Weaver** (`weaverryan`_) can merge into the Security_ component and
-    the SecurityBundle_;
-
-  * **Robin Chalas** (`chalasr`_) can merge into the Console_ and Security_
-    components and the SecurityBundle_;
-
-  * **Maxime Steinhausser** (`ogizanagi`_) can merge into Config_, Console_,
-    Form_, Serializer_, DependencyInjection_, and HttpKernel_ components;
-
-  * **Tobias Nyholm** (`Nyholm`_) manages the official and contrib recipes
-    repositories;
-
-  * **Samuel Rozé** (`sroze`_) can merge into the Messenger_ component.
-
-* **Deciders Team** (``@symfony/deciders`` on GitHub):
-
-  * **Jordi Boggiano** (`seldaek`_);
-  * **Lukas Kahwe Smith** (`lsmith77`_).
+  * **Nicolas Grekas** (`nicolas-grekas`_);
+  * **Christophe Coevoet** (`stof`_);
+  * **Christian Flothmann** (`xabbuh`_);
+  * **Tobias Schultze** (`Tobion`_);
+  * **Kévin Dunglas** (`dunglas`_);
+  * **Jakub Zalas** (`jakzal`_);
+  * **Javier Eguiluz** (`javiereguiluz`_);
+  * **Grégoire Pineau** (`lyrixx`_);
+  * **Ryan Weaver** (`weaverryan`_);
+  * **Robin Chalas** (`chalasr`_);
+  * **Maxime Steinhausser** (`ogizanagi`_);
+  * **Samuel Rozé** (`sroze`_);
+  * **Yonel Ceruto** (`yceruto`_).
 
 * **Security Team** (``@symfony/security`` on GitHub):
 
   * **Fabien Potencier** (`fabpot`_);
   * **Michael Cullum** (`michaelcullum`_).
 
+* **Recipes Team**:
+
+  * **Fabien Potencier** (`fabpot`_);
+  * **Tobias Nyholm** (`Nyholm`_).
+
 * **Documentation Team** (``@symfony/team-symfony-docs`` on GitHub):
 
   * **Fabien Potencier** (`fabpot`_);
@@ -114,6 +87,7 @@ Active Core Members
   * **Wouter De Jong** (`wouterj`_);
   * **Jules Pietri** (`HeahDude`_);
   * **Javier Eguiluz** (`javiereguiluz`_).
+  * **Oskar Stark** (`OskarStark`_).
 
 Former Core Members
 ~~~~~~~~~~~~~~~~~~~
@@ -123,7 +97,8 @@ Symfony contributions:
 
 * **Bernhard Schussek** (`webmozart`_);
 * **Abdellatif AitBoudad** (`aitboudad`_);
-* **Romain Neutron**.
+* **Romain Neutron**;
+* **Jordi Boggiano** (`Seldaek`_).
 
 Core Membership Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -170,11 +145,11 @@ A pull request **can be merged** if:
 
 * It is a minor change [1]_;
 
-* Enough time was given for peer reviews (at least 2 days for "regular"
-  pull requests, and 4 days for pull requests with "a significant impact");
+* Enough time was given for peer reviews;
 
-* At least the component's **Merger** or two other Core members voted ``+1``
-  and no Core member voted ``-1``.
+* At least two **Merger Team** members voted ``+1`` (only one if the submitter
+  is part of the Merger team) and no Core member voted ``-1`` (via Github
+  reviews or as comments).
 
 Pull Request Merging Process
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -199,54 +174,15 @@ discretion of the **Project Leader**.
 .. [1] Minor changes comprise typos, DocBlock fixes, code standards
        violations, and minor CSS, JavaScript and HTML modifications.
 
-.. _PhpUnitBridge: https://github.com/symfony/phpunit-bridge
-.. _BrowserKit: https://github.com/symfony/browser-kit
-.. _Cache: https://github.com/symfony/cache
-.. _Config: https://github.com/symfony/config
-.. _Console: https://github.com/symfony/console
-.. _Debug: https://github.com/symfony/debug
-.. _DebugBundle: https://github.com/symfony/debug-bundle
-.. _DependencyInjection: https://github.com/symfony/dependency-injection
-.. _DoctrineBridge: https://github.com/symfony/doctrine-bridge
-.. _EventDispatcher: https://github.com/symfony/event-dispatcher
-.. _DomCrawler: https://github.com/symfony/dom-crawler
-.. _Form: https://github.com/symfony/form
-.. _HttpFoundation: https://github.com/symfony/http-foundation
-.. _HttpKernel: https://github.com/symfony/http-kernel
-.. _Icu: https://github.com/symfony/icu
-.. _Intl: https://github.com/symfony/intl
-.. _LDAP: https://github.com/symfony/ldap
-.. _Locale: https://github.com/symfony/locale
-.. _Messenger: https://github.com/symfony/messenger
-.. _MonologBridge: https://github.com/symfony/monolog-bridge
-.. _OptionsResolver: https://github.com/symfony/options-resolver
-.. _Process: https://github.com/symfony/process
-.. _PropertyAccess: https://github.com/symfony/property-access
-.. _PropertyInfo: https://github.com/symfony/property-info
-.. _Routing: https://github.com/symfony/routing
-.. _Serializer: https://github.com/symfony/serializer
-.. _Translation: https://github.com/symfony/translation
-.. _Security: https://github.com/symfony/security
-.. _SecurityBundle: https://github.com/symfony/security-bundle
-.. _Stopwatch: https://github.com/symfony/stopwatch
-.. _TwigBridge: https://github.com/symfony/twig-bridge
-.. _Validator: https://github.com/symfony/validator
-.. _VarDumper: https://github.com/symfony/var-dumper
-.. _Workflow: https://github.com/symfony/workflow
-.. _Yaml: https://github.com/symfony/yaml
-.. _WebProfilerBundle: https://github.com/symfony/web-profiler-bundle
-.. _WebLink: https://github.com/symfony/web-link
 .. _`symfony-docs repository`: https://github.com/symfony/symfony-docs
 .. _`fabpot`: https://github.com/fabpot/
 .. _`webmozart`: https://github.com/webmozart/
 .. _`Tobion`: https://github.com/Tobion/
-.. _`romainneutron`: https://github.com/romainneutron/
 .. _`nicolas-grekas`: https://github.com/nicolas-grekas/
 .. _`stof`: https://github.com/stof/
 .. _`dunglas`: https://github.com/dunglas/
 .. _`jakzal`: https://github.com/jakzal/
 .. _`Seldaek`: https://github.com/Seldaek/
-.. _`lsmith77`: https://github.com/lsmith77/
 .. _`weaverryan`: https://github.com/weaverryan/
 .. _`aitboudad`: https://github.com/aitboudad/
 .. _`xabbuh`: https://github.com/xabbuh/
@@ -256,6 +192,8 @@ discretion of the **Project Leader**.
 .. _`ogizanagi`: https://github.com/ogizanagi/
 .. _`Nyholm`: https://github.com/Nyholm
 .. _`sroze`: https://github.com/sroze
+.. _`yceruto`: https://github.com/yceruto
 .. _`michaelcullum`: https://github.com/michaelcullum
 .. _`wouterj`: https://github.com/wouterj
 .. _`HeahDude`: https://github.com/HeahDude
+.. _`OskarStark`: https://github.com/OskarStark
diff --git a/contributing/code/experimental.rst b/contributing/code/experimental.rst
index 9081cf5184c..998f112ba7b 100644
--- a/contributing/code/experimental.rst
+++ b/contributing/code/experimental.rst
@@ -5,8 +5,8 @@ All Symfony features benefit from our :doc:`Backward Compatibility Promise
 </contributing/code/bc>` to give developers the confidence to upgrade to new
 versions safely and more often.
 
-But sometimes, a new feature is controversial. Or finding a good API is not
-easy. In such cases, we prefer to gather feedback from real-world usage, adapt
+But sometimes, a new feature is controversial or you cannot find a convincing API.
+In such cases, we prefer to gather feedback from real-world usage, adapt
 the API, or remove it altogether. Doing so is not possible with a no BC-break
 approach.
 
diff --git a/contributing/code/index.rst b/contributing/code/index.rst
index 49608caeeb6..0bb29d6abc4 100644
--- a/contributing/code/index.rst
+++ b/contributing/code/index.rst
@@ -6,7 +6,7 @@ Contributing Code
 
     bugs
     reproducer
-    patches
+    pull_requests
     maintenance
     core_team
     security
diff --git a/contributing/code/maintenance.rst b/contributing/code/maintenance.rst
index bc16a6cf805..de643e98af6 100644
--- a/contributing/code/maintenance.rst
+++ b/contributing/code/maintenance.rst
@@ -23,8 +23,8 @@ Besides bug fixes, other minor changes can be accepted in a patch version:
   issues (any such patches must come with numbers that show a significant
   improvement on real-world code);
 
-* **Newer versions of PHP/HHVM**: Fixes that add support for newer versions of
-  PHP or HHVM are acceptable if they don't break the unit test suite;
+* **Newer versions of PHP**: Fixes that add support for newer versions of
+  PHP are acceptable if they don't break the unit test suite;
 
 * **Newer versions of popular OSes**: Fixes that add support for newer versions
   of popular OSes (Linux, MacOS and Windows) are acceptable if they don't break
diff --git a/contributing/code/patches.rst b/contributing/code/pull_requests.rst
similarity index 72%
rename from contributing/code/patches.rst
rename to contributing/code/pull_requests.rst
index 9eb76d4b570..6957c5d043d 100644
--- a/contributing/code/patches.rst
+++ b/contributing/code/pull_requests.rst
@@ -1,10 +1,21 @@
-Submitting a Patch
+Proposing a Change
 ==================
 
-Patches are the best way to provide a bug fix or to propose enhancements to
-Symfony.
+A pull request, "PR" for short, is the best way to provide a bug fix or to
+propose enhancements to Symfony.
 
-Step 1: Setup your Environment
+Step 1: Check existing Issues and Pull Requests
+-----------------------------------------------
+
+Before working on a change, check to see if someone else also raised the topic
+or maybe even started working on a PR by `searching on GitHub`_.
+
+If you are unsure or if you have any questions during this entire process,
+please ask your questions on the #contribs channel on `Symfony Slack`_.
+
+.. _step-1-setup-your-environment:
+
+Step 2: Setup your Environment
 ------------------------------
 
 Install the Software Stack
@@ -90,20 +101,27 @@ Check that the current Tests Pass
 Now that Symfony is installed, check that all unit tests pass for your
 environment as explained in the dedicated :doc:`document <tests>`.
 
-Step 2: Work on your Patch
---------------------------
+.. tip::
+
+    If tests are failing, check on `Travis-CI`_ if the same test is
+    failing there as well. In that case you do not need to be concerned
+    about the test failing locally.
+
+.. _step-2-work-on-your-patch:
+
+Step 3: Work on your Pull Request
+---------------------------------
 
 The License
 ~~~~~~~~~~~
 
-Before you start, you must know that all the patches you are going to submit
-must be released under the *MIT license*, unless explicitly specified in your
-commits.
+Before you start, you should be aware that all the code you are going to submit
+must be released under the *MIT license*.
 
 Choose the right Branch
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Before working on a patch, you must determine on which branch you need to
+Before working on a PR, you must determine on which branch you need to
 work:
 
 * ``3.4``, if you are fixing a bug for an existing feature or want to make a
@@ -111,33 +129,39 @@ work:
   </contributing/code/maintenance>` (you may have to choose a higher branch if
   the feature you are fixing was introduced in a later version);
 
- * ``master``, if you are adding a new feature.
+* ``master``, if you are adding a new feature.
+
+  The only exception is when a new :doc:`major Symfony version </contributing/community/releases>`
+  (4.0, 5.0, etc.) comes out every two years. Because of the
+  :ref:`special development process <major-version-development>` of those versions,
+  you need to use the previous minor version for the features (e.g. use ``3.4``
+  instead of ``4.0``, use ``4.4`` instead of ``5.0``, etc.)
 
 .. note::
 
     All bug fixes merged into maintenance branches are also merged into more
-    recent branches on a regular basis. For instance, if you submit a patch
-    for the ``3.4`` branch, the patch will also be applied by the core team on
+    recent branches on a regular basis. For instance, if you submit a PR
+    for the ``3.4`` branch, the PR will also be applied by the core team on
     the ``master`` branch.
 
 Create a Topic Branch
 ~~~~~~~~~~~~~~~~~~~~~
 
-Each time you want to work on a patch for a bug or on an enhancement, create a
+Each time you want to work on a PR for a bug or on an enhancement, create a
 topic branch:
 
 .. code-block:: terminal
 
     $ git checkout -b BRANCH_NAME master
 
-Or, if you want to provide a bugfix for the ``3.4`` branch, first track the remote
+Or, if you want to provide a bug fix for the ``3.4`` branch, first track the remote
 ``3.4`` branch locally:
 
 .. code-block:: terminal
 
     $ git checkout -t origin/3.4
 
-Then create a new branch off the ``3.4`` branch to work on the bugfix:
+Then create a new branch off the ``3.4`` branch to work on the bug fix:
 
 .. code-block:: terminal
 
@@ -167,8 +191,10 @@ uses, and replaces them by symbolic links to the ones in the Git repository.
 Before running the ``link`` command, be sure that the dependencies of the project you
 want to debug are installed by running ``composer install`` inside it.
 
-Work on your Patch
-~~~~~~~~~~~~~~~~~~
+.. _work-on-your-patch:
+
+Work on your Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Work on the code as much as you want and commit as much as you want; but keep
 in mind the following:
@@ -181,7 +207,7 @@ in mind the following:
   actually works;
 
 * Try hard to not break backward compatibility (if you must do so, try to
-  provide a compatibility layer to support the old way) -- patches that break
+  provide a compatibility layer to support the old way) -- PRs that break
   backward compatibility have less chance to be merged;
 
 * Do atomic and logically separate commits (use the power of ``git rebase`` to
@@ -199,7 +225,7 @@ in mind the following:
     as defined in `PSR-1`_ and `PSR-2`_.
 
     A status is posted below the pull request description with a summary
-    of any problems it detects or any Travis CI build failures.
+    of any problems it detects or any `Travis-CI`_ build failures.
 
 .. tip::
 
@@ -210,10 +236,12 @@ in mind the following:
     verb (``fixed ...``, ``added ...``, ...) to start the summary and don't
     add a period at the end.
 
-Prepare your Patch for Submission
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _prepare-your-patch-for-submission:
+
+Prepare your Pull Request for Submission
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When your patch is not about a bug fix (when you add a new feature or change
+When your PR is not about a bug fix (when you add a new feature or change
 an existing one for instance), it must also include the following:
 
 * An explanation of the changes in the relevant ``CHANGELOG`` file(s) (the
@@ -223,16 +251,20 @@ an existing one for instance), it must also include the following:
   ``UPGRADE`` file(s) if the changes break backward compatibility or if you
   deprecate something that will ultimately break backward compatibility.
 
-Step 3: Submit your Patch
--------------------------
+.. _step-4-submit-your-patch:
+
+Step 4: Submit your Pull Request
+--------------------------------
 
-Whenever you feel that your patch is ready for submission, follow the
+Whenever you feel that your PR is ready for submission, follow the
 following steps.
 
-Rebase your Patch
-~~~~~~~~~~~~~~~~~
+.. _rebase-your-patch:
 
-Before submitting your patch, update your branch (needed if it takes you a
+Rebase your Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before submitting your PR, update your branch (needed if it takes you a
 while to finish your changes):
 
 .. code-block:: terminal
@@ -246,7 +278,7 @@ while to finish your changes):
 .. tip::
 
     Replace ``master`` with the branch you selected previously (e.g. ``3.4``)
-    if you are working on a bugfix
+    if you are working on a bug fix.
 
 When doing the ``rebase`` command, you might have to fix merge conflicts.
 ``git status`` will show you the *unmerged* files. Resolve all the conflicts,
@@ -273,7 +305,7 @@ You can now make a pull request on the ``symfony/symfony`` GitHub repository.
 .. tip::
 
     Take care to point your pull request towards ``symfony:3.4`` if you want
-    the core team to pull a bugfix based on the ``3.4`` branch.
+    the core team to pull a bug fix based on the ``3.4`` branch.
 
 To ease the core team work, always include the modified components in your
 pull request message, like in:
@@ -296,10 +328,10 @@ Some answers to the questions trigger some more requirements:
 * If you answer yes to "New feature?", you must submit a pull request to the
   documentation and reference it under the "Doc PR" section;
 
-* If you answer yes to "BC breaks?", the patch must contain updates to the
+* If you answer yes to "BC breaks?", the PR must contain updates to the
   relevant ``CHANGELOG`` and ``UPGRADE`` files;
 
-* If you answer yes to "Deprecations?", the patch must contain updates to the
+* If you answer yes to "Deprecations?", the PR must contain updates to the
   relevant ``CHANGELOG`` and ``UPGRADE`` files;
 
 * If you answer no to "Tests pass", you must add an item to a todo-list with
@@ -326,9 +358,10 @@ because you want early feedback on your work, add an item to todo-list:
     - [ ] gather feedback for my changes
 
 As long as you have items in the todo-list, please prefix the pull request
-title with "[WIP]".
+title with "[WIP]". If you do not yet want to trigger the automated tests,
+you can also set the PR to `draft status`_.
 
-In the pull request description, give as much details as possible about your
+In the pull request description, give as much detail as possible about your
 changes (don't hesitate to give code examples to illustrate your points). If
 your pull request is about adding a new feature or modifying an existing one,
 explain the rationale for the changes. The pull request description helps the
@@ -339,11 +372,29 @@ commit message).
 In addition to this "code" pull request, you must also send a pull request to
 the `documentation repository`_ to update the documentation when appropriate.
 
-Rework your Patch
-~~~~~~~~~~~~~~~~~
+Step 5: Receiving Feedback
+--------------------------
+
+We ask all contributors to follow some
+:doc:`best practices </contributing/community/reviews>`
+to ensure a constructive feedback process.
+
+If you think someone fails to keep this advice in mind and you want another
+perspective, please join the #contribs channel on `Symfony Slack`_. If you
+receive feedback you find abusive please contact the
+:doc:`CARE team </contributing/code_of_conduct/care_team>`.
+
+The :doc:`core team </contributing/code/core_team>` is responsible for deciding
+which PR gets merged, so their feedback is the most relevant. So do not feel
+pressured to refactor your code immediately when someone provides feedback.
+
+.. _rework-your-patch:
+
+Rework your Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Based on the feedback on the pull request, you might need to rework your
-patch. Before re-submitting the patch, rebase with ``upstream/master`` or
+PR. Before re-submitting the PR, rebase with ``upstream/master`` or
 ``upstream/3.4``, don't merge; and force the push to the origin:
 
 .. code-block:: terminal
@@ -364,13 +415,13 @@ before merging.
 
 .. _ProGit: https://git-scm.com/book
 .. _GitHub: https://github.com/join
-.. _`GitHub's Documentation`: https://help.github.com/articles/ignoring-files
+.. _`GitHub's documentation`: https://help.github.com/articles/ignoring-files
 .. _Symfony repository: https://github.com/symfony/symfony
-.. _dev mailing-list: https://groups.google.com/group/symfony-devs
-.. _travis-ci.org: https://travis-ci.org/
-.. _`travis-ci.org status icon`: https://about.travis-ci.com/docs/user/status-images/
-.. _`travis-ci.org Getting Started Guide`: https://about.travis-ci.com/docs/user/getting-started/
 .. _`documentation repository`: https://github.com/symfony/symfony-docs
 .. _`fabbot`: https://fabbot.io
 .. _`PSR-1`: https://www.php-fig.org/psr/psr-1/
 .. _`PSR-2`: https://www.php-fig.org/psr/psr-2/
+.. _`searching on GitHub`: https://github.com/symfony/symfony/issues?q=+is%3Aopen+
+.. _`Symfony Slack`: https://symfony.com/slack-invite
+.. _`Travis-CI`: https://travis-ci.org/symfony/symfony
+.. _`draft status`: https://help.github.com/en/articles/about-pull-requests#draft-pull-requests
diff --git a/contributing/code/reproducer.rst b/contributing/code/reproducer.rst
index be6514c842c..771bd69eeac 100644
--- a/contributing/code/reproducer.rst
+++ b/contributing/code/reproducer.rst
@@ -2,11 +2,11 @@ Creating a Bug Reproducer
 =========================
 
 The main Symfony code repository receives thousands of issues reports per year.
-Some of those issues are so obvious or easy to understand, that Symfony Core
-developers can fix them without any other information. However, other issues are
-much harder to understand because developers can't easily reproduce them in their
-computers. That's when we'll ask you to create a "bug reproducer", which is the
-minimum amount of code needed to make the bug appear when executed.
+Some of those issues are easy to understand and the Symfony Core developers can
+fix them without any other information. However, other issues are much harder to
+understand because developers can't reproduce them in their computers. That's
+when we'll ask you to create a "bug reproducer", which is the minimum amount of
+code needed to make the bug appear when executed.
 
 Reproducing Simple Bugs
 -----------------------
diff --git a/contributing/code/security.rst b/contributing/code/security.rst
index a751763c8c9..e9f4dcdabf1 100644
--- a/contributing/code/security.rst
+++ b/contributing/code/security.rst
@@ -1,9 +1,9 @@
 Security Issues
 ===============
 
-This document explains how Symfony security issues are handled by the Symfony
-core team (Symfony being the code hosted on the main ``symfony/symfony`` `Git
-repository`_).
+This document explains how Symfony security issues are handled by the
+Symfony core team (Symfony being the code hosted on the main ``symfony/symfony``
+`Git repository`_).
 
 Reporting a Security Issue
 --------------------------
@@ -38,7 +38,8 @@ confirmed, the core team works on a solution following these steps:
 #. Publish the post on the official Symfony `blog`_ (it must also be added to
    the "`Security Advisories`_" category);
 #. Update the public `security advisories database`_ maintained by the
-   FriendsOfPHP organization and which is used by the ``security:check`` command.
+   FriendsOfPHP organization and which is used by
+   :ref:`the check:security command <security-checker>`.
 
 .. note::
 
@@ -78,7 +79,7 @@ projects. The process works as follows:
    date for a joint release (there is no guarantee that all releases will
    be at the same time but we will try hard to make them at about the same
    time). When the issue is not known to be exploited in the wild, a period
-   of two weeks seems like a reasonable amount of time.
+   of two weeks is considered a reasonable amount of time.
 
 The list of downstream projects participating in this process is kept as small
 as possible in order to better manage the flow of confidential information
@@ -150,7 +151,7 @@ score for Affected Projects is capped at 4.*
 Score Totals
 ~~~~~~~~~~~~
 
-* Attack Complexity: 1 - 4
+* Attack Complexity: 1 - 5
 * Impact: 1 - 6
 * Affected Projects: 1 - 4
 
@@ -169,15 +170,14 @@ Security Advisories
 .. tip::
 
     You can check your Symfony application for known security vulnerabilities
-    using the ``security:check`` command (see :doc:`/security/security_checker`).
+    using :ref:`the check:security command <security-checker>`.
 
 Check the `Security Advisories`_ blog category for a list of all security
 vulnerabilities that were fixed in Symfony releases, starting from Symfony
 1.0.0.
 
-.. _Git repository: https://github.com/symfony/symfony
+.. _`Git repository`: https://github.com/symfony/symfony
 .. _blog: https://symfony.com/blog/
-.. _Security Advisories: https://symfony.com/blog/category/security-advisories
 .. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
 .. _`mitre.org`: https://cveform.mitre.org/
 .. _`Security Advisories`: https://symfony.com/blog/category/security-advisories
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
index 8b28f2d64a7..e81d195ab71 100644
--- a/contributing/code/standards.rst
+++ b/contributing/code/standards.rst
@@ -27,11 +27,7 @@ Symfony Coding Standards in Detail
 ----------------------------------
 
 If you want to learn about the Symfony coding standards in detail, here's a
-short example containing most features described below:
-
-.. code-block:: html+php
-
-    <?php
+short example containing most features described below::
 
     /*
      * This file is part of the Symfony package.
@@ -71,7 +67,7 @@ short example containing most features described below:
          */
         public function someDeprecatedMethod()
         {
-            @trigger_error(sprintf('The %s() method is deprecated since version 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
+            @trigger_error(sprintf('The %s() method is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
 
             return Baz::someMethod();
         }
@@ -213,7 +209,7 @@ Naming Conventions
 
 * Prefix all abstract classes with ``Abstract`` except PHPUnit ``*TestCase``.
   Please note some early Symfony classes do not follow this convention and
-  have not been renamed for backward compatibility reasons. However all new
+  have not been renamed for backward compatibility reasons. However, all new
   abstract classes must follow this naming convention;
 
 * Suffix interfaces with ``Interface``;
@@ -272,7 +268,7 @@ Documentation
 * When adding a new class or when making significant changes to an existing class,
   an ``@author`` tag with personal contact information may be added, or expanded.
   Please note it is possible to have the personal contact information updated or
-  removed per request to the doc:`core team </contributing/code/core_team>`.
+  removed per request to the :doc:`core team </contributing/code/core_team>`.
 
 License
 ~~~~~~~
@@ -280,7 +276,7 @@ License
 * Symfony is released under the MIT license, and the license block has to be
   present at the top of every PHP file, before the namespace.
 
-.. _`PHP CS Fixer tool`: http://cs.sensiolabs.org/
+.. _`PHP CS Fixer tool`: https://cs.symfony.com/
 .. _`PSR-0`: https://www.php-fig.org/psr/psr-0/
 .. _`PSR-1`: https://www.php-fig.org/psr/psr-1/
 .. _`PSR-2`: https://www.php-fig.org/psr/psr-2/
diff --git a/contributing/code/tests.rst b/contributing/code/tests.rst
index 968ad1c95cf..75c72e0128d 100644
--- a/contributing/code/tests.rst
+++ b/contributing/code/tests.rst
@@ -4,11 +4,11 @@ Running Symfony Tests
 =====================
 
 The Symfony project uses a third-party service which automatically runs tests
-for any submitted :doc:`patch <patches>`. If the new code breaks any test,
+for any submitted :doc:`patch <pull_requests>`. If the new code breaks any test,
 the pull request will show an error message with a link to the full error details.
 
 In any case, it's a good practice to run tests locally before submitting a
-:doc:`patch <patches>` for inclusion, to check that you have not broken anything.
+:doc:`patch <pull_requests>` for inclusion, to check that you have not broken anything.
 
 .. _phpunit:
 .. _dependencies_optional:
@@ -18,7 +18,7 @@ Before Running the Tests
 
 To run the Symfony test suite, install the external dependencies used during the
 tests, such as Doctrine, Twig and Monolog. To do so,
-:doc:`install Composer </setup/composer>` and execute the following:
+`install Composer`_ and execute the following:
 
 .. code-block:: terminal
 
@@ -54,6 +54,7 @@ what's going on and if the tests are broken because of the new code.
     On Windows, install the `Cmder`_, `ConEmu`_, `ANSICON`_ or `Mintty`_ free applications
     to see colored test results.
 
+.. _`install Composer`: https://getcomposer.org/download/
 .. _Cmder: http://cmder.net/
 .. _ConEmu: https://conemu.github.io/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases
diff --git a/contributing/code_of_conduct/care_team.rst b/contributing/code_of_conduct/care_team.rst
index 04b7fdbad82..b452de35895 100644
--- a/contributing/code_of_conduct/care_team.rst
+++ b/contributing/code_of_conduct/care_team.rst
@@ -4,22 +4,24 @@ CARE Team
 Our Pledge
 ----------
 
-In the interest of fostering an open and welcoming environment, the CoC Active Response Ensurers, or CARE,
-pledge to ensure that the spirit of the :doc:`Code of Conduct </contributing/code_of_conduct/index>`
+In the interest of fostering an open and welcoming environment, the "Code of
+Conduct Active Response Ensurers", or CARE team, pledge to ensure that the
+spirit of the :doc:`Code of Conduct </contributing/code_of_conduct/index>`
 is respected. Our main priority is to ensure the safety of our community members.
-The second goal is to help educate the community as a whole to be aware of the CoC
-and how to help implement its spirit throughout the community. In case these goals
-conflict, we will prioritize safety of community members over all other goals.
+The second goal is to help educate the community as a whole to be aware of the
+Code of Conduct and how to help implement its spirit throughout the community.
+In case these goals conflict, we will prioritize safety of community members
+over all other goals.
 
-If you think there is or has been a violation to the code of conduct please contact
+If you think there is or has been a violation to the Code of Conduct please contact
 the CARE team or if you prefer contact only individual members of the CARE team.
 
 Members
 -------
 
-Here are all the members of the Code of Conduct CARE team (in alphabetic order).
-You can contact any of them directly using the contact details below or you can
-also contact all of them at once by emailing **coc@symfony.com**:
+Here are all the members of the CARE team (in alphabetic order). You can contact
+any of them directly using the contact details below or you can also contact all
+of them at once by emailing **care@symfony.com**:
 
 * **Emilie Lorenzo**
 
@@ -46,3 +48,12 @@ The :doc:`Symfony project leader </contributing/code/core_team>` appoints the CA
 team with candidates they see fit. The CARE team will consist of at least
 3 people. The team should be representing as many demographics as possible,
 ideally from different employers.
+
+CARE Team Transparency Reports
+------------------------------
+
+The CARE team publishes a transparency report at the end of each year:
+
+* `Symfony Code of Conduct Transparency Report 2018`_.
+
+.. _`Symfony Code of Conduct Transparency Report 2018`: https://symfony.com/blog/symfony-code-of-conduct-transparency-report-2018
diff --git a/contributing/code_of_conduct/concrete_example_document.rst b/contributing/code_of_conduct/concrete_example_document.rst
index 6f1277a625a..ddd1c9b84c8 100644
--- a/contributing/code_of_conduct/concrete_example_document.rst
+++ b/contributing/code_of_conduct/concrete_example_document.rst
@@ -2,7 +2,7 @@ Code of Conduct: Concrete Example Document
 ==========================================
 
 This is a living document that serves to give concrete examples of
-unwanted behaviour. These examples have all taken place somewhere in the
+unwanted behavior. These examples have all taken place somewhere in the
 PHP community in the past, and are clear code of conduct violations
 according to the Symfony code of conduct.
 
diff --git a/contributing/code_of_conduct/reporting_guidelines.rst b/contributing/code_of_conduct/reporting_guidelines.rst
index 1766d025e4d..63c4e820ce6 100644
--- a/contributing/code_of_conduct/reporting_guidelines.rst
+++ b/contributing/code_of_conduct/reporting_guidelines.rst
@@ -69,7 +69,7 @@ let them know what action (if any) we'll be taking. We'll take into account feed
 from the reporter on the appropriateness of our response, but our response will be
 determined by what will be best for community safety.
 
-The CARE team keeps a private record of all incidents. By default all reports
+The CARE team keeps a private record of all incidents. By default, all reports
 are shared with the entire CARE team unless the reporter specifically asks
 to exclude specific CARE team members, in which case these CARE team
 members will not be included in any communication on the incidents as well as records
diff --git a/contributing/community/index.rst b/contributing/community/index.rst
index 70cb60c740e..4a5aab91265 100644
--- a/contributing/community/index.rst
+++ b/contributing/community/index.rst
@@ -9,4 +9,3 @@ Community
     reviews
     mentoring
     speaker-mentoring
-    other
diff --git a/contributing/community/other.rst b/contributing/community/other.rst
deleted file mode 100644
index 2196ccb925c..00000000000
--- a/contributing/community/other.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-Other Resources
-===============
-
-In order to follow what is happening in the community you might find helpful
-these additional resources:
-
-* List of open `pull requests`_
-* List of recent `commits`_
-* List of open `bugs and enhancements`_
-* List of open source `bundles`_
-
-.. _pull requests:         https://github.com/symfony/symfony/pulls
-.. _commits:               https://github.com/symfony/symfony/commits/master
-.. _bugs and enhancements: https://github.com/symfony/symfony/issues
-.. _bundles:               https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories
diff --git a/contributing/community/releases.rst b/contributing/community/releases.rst
index 74e6d963d3b..d2336e21e86 100644
--- a/contributing/community/releases.rst
+++ b/contributing/community/releases.rst
@@ -8,13 +8,13 @@ Symfony releases follow the `semantic versioning`_ strategy and they are
 published through a *time-based model*:
 
 * A new **Symfony patch version** (e.g. 2.8.15, 4.1.7) comes out roughly every
-  month. It only contains bug fixes, so you can safely upgrade your apps;
+  month. It only contains bug fixes, so you can safely upgrade your applications;
 * A new **Symfony minor version** (e.g. 2.8, 3.2, 4.1) comes out every *six months*:
   one in *May* and one in *November*. It contains bug fixes and new features, but
-  it doesn't include any breaking change, so you can safely upgrade your apps;
+  it doesn't include any breaking change, so you can safely upgrade your applications;
 * A new **Symfony major version** (e.g. 3.0, 4.0) comes out every *two years*.
   It can contain breaking changes, so you may need to do some changes in your
-  apps before upgrading.
+  applications before upgrading.
 
 .. tip::
 
@@ -84,6 +84,23 @@ adds a new preferred one along side. Read the
 :ref:`conventions <contributing-code-conventions-deprecations>` document to
 learn more about how deprecations are handled in Symfony.
 
+.. _major-version-development:
+
+This deprecation policy also requires a custom development process for major
+versions (4.0, 5.0, 6.0, etc.) In those cases, Symfony develops at the same time
+two versions: the new major one (e.g. 4.0) and the latest version of the
+previous branch (e.g. 3.4).
+
+Both versions have the same new features, but they differ in the deprecated
+features. The oldest version (3.4 in this example) contains all the deprecated
+features whereas the new version (4.0 in this example) removes all of them.
+
+This allows you to upgrade your projects to the latest minor version (e.g. 3.4),
+see all the deprecation messages and fix them. Once you have fixed all those
+deprecations, you can upgrade to the new major version (e.g. 4.0) without
+effort, because it contains the same features (the only difference are the
+deprecated features, which your project no longer uses).
+
 Rationale
 ---------
 
diff --git a/contributing/community/review-comments.rst b/contributing/community/review-comments.rst
index fa1f26dcf2d..cb5b1c7084f 100644
--- a/contributing/community/review-comments.rst
+++ b/contributing/community/review-comments.rst
@@ -38,7 +38,7 @@ Tone of Voice
 We don't expect you to be completely formal, or to even write error-free
 English. Just remember this: don't swear, and be respectful to others.
 
-Don't reply in anger or with an aggressive tone. You're angry, we understand
+Don't reply in anger or with an aggressive tone. If you're angry, we understand
 that, but swearing/cursing and name calling doesn't really encourage anyone to
 help you. Take a deep breath, count to 10 and try to *clearly* explain what problems
 you encounter.
@@ -91,34 +91,34 @@ Don't use hyperbole ("always", "never", "endlessly", "nothing", "worst", "horrib
 **Don't:** *"I don't like how you wrote this code"* - there is no clear explanation why you
 don't like how it's written.
 
-**Better:** *"I find it hard to read this code as there many nested if statements, can you make it more
-readable? By encapsulating some of it's details or maybe adding some comments to explain the overall logic."* -
+**Better:** *"I find it hard to read this code as there are many nested if statements, can you make it more
+readable? By encapsulating some of the details or maybe adding some comments to explain the overall logic."* -
 You explain why you find the code hard to read *and* give some suggestions for improvement.
 
 If a piece of code is in fact wrong, explain why:
 
-* ``This code doesn't comply with Symfony's CS rules. Please see [...] for details``.
+* "This code doesn't comply with Symfony's CS rules. Please see [...] for details."
 
-* ``Symfony 3 still uses PHP 5 and doesn't allow the usage scalar type-hints.``.
+* "Symfony 3 still uses PHP 5 and doesn't allow the usage of scalar type-hints."
 
-* ``I think the code is less readable now`` - careful here, be sure explain why you think
+* "I think the code is less readable now." - careful here, be sure explain why you think
   the code is less readable, and maybe give some suggestions?
 
 **Examples of valid reasons to reject:**
 
-    * We tried that in the past (link to the relevant PR) but we needed to revert it for XXX reason.
+* "We tried that in the past (link to the relevant PR) but we needed to revert it for XXX reason."
 
-    * That change would introduce too many merge conflicts when merging up Symfony branches.
-      In the past we've always rejected changes like this.
+* "That change would introduce too many merge conflicts when merging up Symfony branches.
+  In the past we've always rejected changes like this."
 
-    * I profiled this change and it hurts performance significantly (if you don't profile, it's an opinion, so we can ignore)
+* "I profiled this change and it hurts performance significantly" - if you don't profile, it's an opinion, so we can ignore
 
-    * Code doesn't match Symfony's CS rules (e.g. use ``[]`` instead of ``array()``)
+* "Code doesn't match Symfony's CS rules (e.g. use ``[]`` instead of ``array()``)"
 
-    * We only provide integration with very popular projects (e.g. we integrate Bootstrap but not your own CSS framework)
+* "We only provide integration with very popular projects (e.g. we integrate Bootstrap but not your own CSS framework)"
 
-    * This would require adding lots of code and making lots of changes for a feature that doesn't look so important.
-      That could hurt maintaining in the future.
+* "This would require adding lots of code and making lots of changes for a feature that doesn't look so important.
+  That could hurt maintaining in the future."
 
 Asking for Changes
 ------------------
@@ -149,6 +149,17 @@ you don't have to use "Please" all the time. But it wouldn't hurt.
 It may not seem like much, but saying "Thank you" does make others feel
 more welcome.
 
+
+Preventing Escalations
+----------------------
+
+Sometimes when people receive feedback they may get defensive.
+In that case, it is better to try to approach the discussion in
+a different way, to not escalate further.
+
+If you want someone to mediate, please join the #contribs channel on `Symfony Slack`_,
+to have a safe environment and keep working together on the common goals.
+
 Using Humor
 -----------
 
@@ -176,3 +187,5 @@ But don't say it "just because", if your apology is not really meant
 you *will* lose credibility and respect from other developers.
 
 *Do unto others as you would have them do unto you.*
+
+.. _`Symfony Slack`: https://symfony.com/slack-invite
diff --git a/contributing/community/reviews.rst b/contributing/community/reviews.rst
index 2d4a5f125fa..06cc404d821 100644
--- a/contributing/community/reviews.rst
+++ b/contributing/community/reviews.rst
@@ -6,6 +6,13 @@ ready to contribute code or patches, reviewing issues and pull requests (PRs)
 can be a great start to get involved and give back. In fact, people who "triage"
 issues are the backbone to Symfony's success!
 
+.. note::
+
+    Communicating in a way where your words come across as intended can be
+    difficult. Please read through the
+    :doc:`Respectful Review Comments </contributing/community/review-comments>`
+    guidelines.
+
 Why Reviewing Is Important
 --------------------------
 
@@ -17,7 +24,7 @@ On the `Symfony issue tracker`_, you can find many items in a `Needs Review`_
 status:
 
 * **Bug Reports**: Bug reports need to be checked for completeness.
-  Is any important information missing? Can the bug be *easily* reproduced?
+  Is any important information missing? Can the bug be reproduced?
 
 * **Pull Requests**: Pull requests contain code that fixes a bug or implements
   new functionality. Reviews of pull requests ensure that they are implemented
@@ -38,7 +45,7 @@ next step.
 Create a GitHub Account
 -----------------------
 
-Symfony uses GitHub_ to manage bug reports and pull requests. If you want to
+Symfony uses `GitHub`_ to manage bug reports and pull requests. If you want to
 do reviews, you need to `create a GitHub account`_ and log in.
 
 The Bug Report Review Process
@@ -51,16 +58,16 @@ The steps for the review are:
 
 #. **Is the Report Complete?**
 
-   Good bug reports contain a link to a fork of the `Symfony Standard Edition`_
-   (the "reproduction project") that reproduces the bug. If it doesn't, the
-   report should at least contain enough information and code samples to
-   reproduce the bug.
+   Good bug reports contain a link to a project (the "reproduction project")
+   created with the `Symfony skeleton`_ or the `Symfony website skeleton`_
+   that reproduces the bug. If it doesn't, the report should at least contain
+   enough information and code samples to reproduce the bug.
 
 #. **Reproduce the Bug**
 
    Download the reproduction project and test whether the bug can be reproduced
    on your system. If the reporter did not provide a reproduction project,
-   create one by forking_ the `Symfony Standard Edition`_.
+   create one based on one `Symfony skeleton`_ (or the `Symfony website skeleton`_).
 
 #. **Update the Issue Status**
 
@@ -89,7 +96,7 @@ The steps for the review are:
 
         Thank you @weaverryan for creating this bug report! This indeed looks
         like a bug. I reproduced the bug in the "kernel-bug" branch of
-        https://github.com/webmozart/symfony-standard.
+        https://github.com/webmozart/some-project.
 
         Status: Reviewed
 
@@ -127,9 +134,9 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
 #. **Reproduce the Problem**
 
    Read the issue that the pull request is supposed to fix. Reproduce the
-   problem on a clean `Symfony Standard Edition`_ project and try to understand
-   why it exists. If the linked issue already contains such a project, install
-   it and run it on your system.
+   problem on a new project created with the `Symfony skeleton`_ (or the
+   `Symfony website skeleton`_) and try to understand why it exists. If the
+   linked issue already contains such a project, install it and run it on your system.
 
 #. **Review the Code**
 
@@ -139,7 +146,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
    * Does the PR stay within scope to address *only* that issue?
    * Does the PR contain automated tests? Do those tests cover all relevant
      edge cases?
-   * Does the PR contain sufficient comments to easily understand its code?
+   * Does the PR contain sufficient comments to understand its code?
    * Does the code break backward compatibility? If yes, does the PR header say
      so?
    * Does the PR contain deprecations? If yes, does the PR header say so? Does
@@ -204,13 +211,11 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
 
 .. _GitHub: https://github.com
 .. _Symfony issue tracker: https://github.com/symfony/symfony/issues
-.. _Symfony Standard Edition: https://github.com/symfony/symfony-standard
+.. _`Symfony skeleton`: https://github.com/symfony/skeleton
+.. _`Symfony website skeleton`: https://github.com/symfony/website-skeleton
 .. _create a GitHub account: https://help.github.com/articles/signing-up-for-a-new-github-account/
-.. _forking: https://help.github.com/articles/fork-a-repo/
 .. _bug reports in need of review: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22Bug%22+label%3A%22Status%3A+Needs+Review%22+
 .. _PRs in need of review: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Apr+label%3A%22Status%3A+Needs+Review%22+
-.. _Contribution Guidelines: https://github.com/symfony/symfony/blob/master/CONTRIBUTING.md
-.. _Symfony's Release Schedule: https://symfony.com/doc/current/contributing/community/releases.html#schedule
 .. _Symfony Roadmap: https://symfony.com/roadmap
 .. _Carson Bot: https://github.com/carsonbot/carsonbot
 .. _`Needs Review`: https://github.com/symfony/symfony/labels/Status%3A%20Needs%20Review
diff --git a/contributing/diversity/governance.rst b/contributing/diversity/governance.rst
index 0a58e564669..7e27f139b05 100644
--- a/contributing/diversity/governance.rst
+++ b/contributing/diversity/governance.rst
@@ -13,9 +13,9 @@ Guidance
 --------
 
 The project leader, Fabien Potencier, is responsible for publicly appointing
-five (5) key players of the initiative to provide guidance and drive it forward,
-but also retains the right to revoke any of the key players at any time. These
-guiding key players should:
+five (5) members of the initiative to provide guidance and drive it forward,
+but also retains the right to revoke any of the appointed members at any time.
+This guidance team should:
 
 * Be committed to the initiative's cause and have joined because they want to
   help the initiative to deliver its purpose most effectively for the
@@ -24,21 +24,30 @@ guiding key players should:
 * Be committed to good governance and want to contribute to the initiative's
   continued improvement.
 
+The current guidance team is composed of the following people (in alphabetical
+order):
+
+* **Lukas Kahwe Smith** (`lsmith77`_);
+* **Michelle Sanver** (`michellesanver`_);
+* **Nicolas Grekas** (`nicolas-grekas`_);
+* **Timo Bakx** (`TimoBakx`_);
+* **Zan Baldwin** (`zanbaldwin`_).
+
 Veto
 ~~~~
 
 The project leader (Fabien Potencier) will have the right to veto any actionable
-item, regardless of the vote of the initiative's key players. The project leader
-may, at their discretion, also appoint other people from among the initiative's
-key players to also have the right to veto - in such a case these people are
-expected to use appropriate judgement to know when to use a "no" vote or a veto.
-Any single veto will reject an actionable item.
+item, regardless of the vote of the initiative's guidance team. The project
+leader may, at their discretion, also appoint other people from among the
+initiative's guidance team to also have the right to veto - in such a case these
+people are expected to use appropriate judgement to know when to use a "no" vote
+or a veto. Any single veto will reject an actionable item.
 
 The purpose of having members with the right to veto is to prevent a "people's
 majority" from overruling the core interests of the Symfony project. This will
-encourage communication between proposing members, the initiative's key players
-and the Core Team to create realistic proposals, and in return any veto will
-come with a full explanation (not just a justification).
+encourage communication between proposing members, the initiative's guidance
+team and the Core Team to create realistic proposals, and in return any veto
+will come with a full explanation (not just a justification).
 
 Advice Process
 ~~~~~~~~~~~~~~
@@ -48,20 +57,37 @@ the community (advice, general consensus, or non-binding poll) should be
 requested from the wider community - this will aim to include both those who
 will be meaningfully affected and those with meaningful expertise in the matter
 at hand.
-This feedback will enable the key players to have the confidence to vote for the
-best possible decision according to the information they have available, knowing
-that the responsibility they accept for said vote is justified.
+This feedback will enable the guidance team to have the confidence to vote for
+the best possible decision according to the information they have available,
+knowing that the responsibility they accept for said vote is justified.
 
 Voting
 ~~~~~~
 
-Key players have the right to vote on proposals for actionable items.
+The guidance team have the right to vote on proposals for actionable items.
 The quorum of "yes" or "no" votes required for a decision to be considered valid
-is at least 75% of active, appointed key players - to abstain from voting means
-that vote will not be counted towards the quorum.
-For an actionable item to pass, approval from greater than 50% of the voting key
-players is required. Use or management of finances/donations require at least a
-two-thirds majority to pass.
+is at least 75% of active, appointed members of the guidance team - to abstain
+from voting means that vote will not be counted towards the quorum.
+For an actionable item to pass, approval from greater than 50% of the voting
+guidance team members is required. Use or management of finances/donations
+require at least a two-thirds majority to pass.
+
+For transparency and ease-of-understanding, this means only the following
+combinations of votes will result in an actionable item passing:
+
++-----+---------+---------+
+| For | Against | Abstain |
++=====+=========+=========+
+| 5   | 0       | 0       |
++-----+---------+---------+
+| 4   | 1       | 0       |
++-----+---------+---------+
+| 3   | 2       | 0       |
++-----+---------+---------+
+| 4   | 0       | 1       |
++-----+---------+---------+
+| 3   | 1       | 1       |
++-----+---------+---------+
 
 Guidance Principles
 -------------------
@@ -69,37 +95,37 @@ Guidance Principles
 Purpose
 ~~~~~~~
 
-The initiative should be led by an effective team of key players that provide
+The initiative should be led by an effective guidance team that provides
 strategic guidance in line with the initiative's aims and values, including a
-shared understanding with fellow key players to ensure that these are being
-delivered effectively and sustainably.
+shared understanding with fellow initiative members to ensure that these are
+being delivered effectively and sustainably.
 
 Integrity
 ~~~~~~~~~
 
-Key players should act with integrity: adopting values which help achieve the
-initiative's purposes, even where difficult or unpopular decisions are required.
-Key players should undertake their duties, aware of the importance of confidence
-and trust in the initiative from the wider community, and ultimately
-acknowledges shared responsibility for the reputation of the Symfony project
-like the Core Team.
+The guidance team should act with integrity: adopting values which help achieve
+the initiative's purposes, even where difficult or unpopular decisions are
+required. Guidance team members should undertake their duties, aware of the
+importance of confidence and trust in the initiative from the wider community,
+and ultimately acknowledges shared responsibility for the reputation of the
+Symfony project like the Core Team.
 
 Decision-making Effectiveness
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Key players should work as an effective team, using the appropriate balance of
-skills, experience, backgrounds and knowledge to make sure its decision-making
-processes are informed and equitable. Risk assessment and management systems
-should be set up and monitored.
+Guidance members should work as an effective team, using the appropriate balance
+of skills, experience, backgrounds and knowledge to make sure its
+decision-making processes are informed and equitable. Risk assessment and
+management systems should be set up and monitored.
 
 Openness and Accountability
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The behaviour and conduct of the initiative's key players sets the tone for the
-rest of the community. Key players should lead by example to create a culture
-that enables members to feel it is safe to suggest, question and challenge -
-rather than avoid - difficult ideas and topics. Key players guide the initiative
-in being transparent, accountable and open.
+The behavior and conduct of the initiative's guidance team sets the tone for
+the rest of the community. The guidance team should lead by example to create a
+culture that enables members to feel it is safe to suggest, question and
+challenge - rather than avoid - difficult ideas and topics. The team should
+guide the initiative in being transparent, accountable and open.
 
 Adaptability
 ~~~~~~~~~~~~
@@ -107,5 +133,11 @@ Adaptability
 The initiative should establish processes that do not require any one person to
 hold specific positions while being adaptable to accommodate unforeseen needs of
 the community, especially as membership and involvement grows over time (changes
-to key player appointment will have to be approved by the current system, which
-is Fabien Potencier).
+to guidance team member appointment will have to be approved by the current
+system, which is Fabien Potencier).
+
+.. _`lsmith77`: https://github.com/lsmith77/
+.. _`michellesanver`: https://github.com/michellesanver/
+.. _`nicolas-grekas`: https://github.com/nicolas-grekas/
+.. _`TimoBakx`: https://github.com/TimoBakx/
+.. _`zanbaldwin`: https://github.com/zanbaldwin/
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
index 2464b5b9e66..d7d19a193c3 100644
--- a/contributing/documentation/format.rst
+++ b/contributing/documentation/format.rst
@@ -131,7 +131,7 @@ If you want to modify that title, use this alternative syntax:
 
 .. code-block:: rst
 
-    :doc:`Spooling Email </email/spool>`
+    :doc:`Doctrine Associations </doctrine/associations>`
 
 .. note::
 
@@ -168,42 +168,51 @@ of the linked resource (``namespace``, ``class`` or ``method``):
 
     :phpfunction:`iterator_to_array`
 
-New Features or Behavior Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+New Features, Behavior Changes or Deprecations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you're documenting a brand new feature or a change that's been made in
-Symfony, you should precede your description of the change with a
-``.. versionadded:: 2.X`` directive and a short description:
+If you are documenting a brand new feature, a change or a deprecation that's
+been made in Symfony, you should precede your description of the change with
+the corresponding directive and a short description:
+
+For a new feature or a behavior change use the ``.. versionadded:: 4.x``
+directive:
 
 .. code-block:: rst
 
-    .. versionadded:: 2.7
+    .. versionadded:: 4.2
+
+        Named autowiring aliases have been introduced in Symfony 4.2.
+
+If you are documenting a behavior change, it may be helpful to *briefly*
+describe how the behavior has changed:
+
+.. code-block:: rst
 
-        The ``askHiddenResponse()`` method was introduced in Symfony 2.7.
+    .. versionadded:: 4.2
 
-    You can also ask a question and hide the response. This is particularly [...]
+       Support for ICU MessageFormat was introduced in Symfony 4.2. Prior to this,
+       pluralization was managed by the ``transChoice`` method.
 
-If you're documenting a behavior change, it may be helpful to *briefly* describe
-how the behavior has changed:
+For a deprecation use the ``.. deprecated:: 4.x`` directive:
 
 .. code-block:: rst
 
-    .. versionadded:: 2.7
+    .. deprecated:: 4.2
 
-        The ``include()`` function is a new Twig feature that's available in
-        Symfony 2.7. Prior, the ``{% include %}`` tag was used.
+        Not passing the root node name to ``TreeBuilder`` was deprecated in Symfony 4.2.
 
-Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
+Whenever a new major version of Symfony is released (e.g. 5.0, 6.0, etc),
 a new branch of the documentation is created from the ``master`` branch.
-At this point, all the ``versionadded`` tags for Symfony versions that have
-reached end-of-maintenance will be removed. For example, if Symfony 2.5 were
-released today, and 2.2 had recently reached its end-of-maintenance, the 2.2
-``versionadded`` tags would be removed from the new ``2.5`` branch.
+At this point, all the ``versionadded`` and ``deprecated`` tags for Symfony
+versions that have a lower major version will be removed. For example, if
+Symfony 5.0 were released today, 4.0 to 4.4 ``versionadded`` and ``deprecated``
+tags would be removed from the new ``5.0`` branch.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _Sphinx: http://sphinx-doc.org/
+.. _Sphinx: https://www.sphinx-doc.org/
 .. _`Symfony documentation`: https://github.com/symfony/symfony-docs
-.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html
+.. _`reStructuredText Primer`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 .. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
-.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/
+.. _`Sphinx Markup Constructs`: https://www.sphinx-doc.org/en/1.7/markup/index.html
 .. _`supported languages`: http://pygments.org/languages/
diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst
index d4ccfe74310..f16f4e32cc7 100644
--- a/contributing/documentation/index.rst
+++ b/contributing/documentation/index.rst
@@ -5,21 +5,21 @@ These short articles explain everything you need to contribute to the Symfony
 documentation:
 
 :doc:`The Contribution Process </contributing/documentation/overview>`
-  Explains the steps to follow to contribute fixes and new contents. It's the
-  same contribution process followed by most open source projects, so you may
-  already know everything that is needed.
+    Explains the steps to follow to contribute fixes and new contents. It's the
+    same contribution process followed by most open source projects, so you may
+    already know everything that is needed.
 
 :doc:`Documentation Formats </contributing/documentation/format>`
-  Explains the technical details of the reStructuredText format that is used to
-  write the docs. Skip it if you are already familiar with this format.
+    Explains the technical details of the reStructuredText format that is used to
+    write the docs. Skip it if you are already familiar with this format.
 
 :doc:`Documentation Standards </contributing/documentation/standards>`
-  Explains how to write docs and code examples to match the style and tone of
-  the rest of the existing documentation.
+    Explains how to write docs and code examples to match the style and tone of
+    the rest of the existing documentation.
 
 :doc:`License </contributing/documentation/license>`
-  Explains the details of the Creative Commons BY-SA 3.0 license used for the
-  Symfony Documentation.
+    Explains the details of the Creative Commons BY-SA 3.0 license used for the
+    Symfony Documentation.
 
 .. toctree::
     :hidden:
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
index e0fd5eac618..19dd6d030ce 100644
--- a/contributing/documentation/overview.rst
+++ b/contributing/documentation/overview.rst
@@ -65,9 +65,9 @@ Let's imagine that you want to improve the Setup guide. In order to make your
 changes, follow these steps:
 
 **Step 1.** Go to the official Symfony documentation repository located at
-`github.com/symfony/symfony-docs`_ and click on the **Fork** button to `fork the
-repository`_ to your personal account. This is only needed the first time you
-contribute to Symfony.
+`github.com/symfony/symfony-docs`_ and click on the **Fork** button to
+`fork the repository`_ to your personal account. This is only needed the first
+time you contribute to Symfony.
 
 **Step 2.** **Clone** the forked repository to your local machine (this example
 uses the ``projects/symfony-docs/`` directory to store the documentation; change
@@ -249,8 +249,22 @@ GitHub, click on the **Show all checks** link and finally, click on the
 Build the Documentation Locally
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Alternatively you can build the documentation on your own computer for testing
-purposes following these steps:
+If you have Docker installed on your machine, run these commands to build the
+docs:
+
+.. code-block:: terminal
+
+    # build the image...
+    $ docker build . -t symfony-docs
+
+    # ...and start the local web server
+    # (if it's already in use, change the '8080' port by any other port)
+    $ docker run --rm -p 8080:80 symfony-docs
+
+You can now read the docs at ``http://127.0.0.1:8080`` (if you use a virtual
+machine, browse its IP instead of localhost; e.g. ``http://192.168.99.100:8080``).
+
+If you don't use Docker, follow these steps to build the docs locally:
 
 #. Install `pip`_ as explained in the `pip installation`_ article;
 
@@ -325,7 +339,6 @@ definitely don't want you to waste your time!
 .. _`Symfony Documentation Contributors`: https://symfony.com/contributors/doc
 .. _`SymfonyConnect`: https://connect.symfony.com/
 .. _`Symfony Documentation Badge`: https://connect.symfony.com/badge/36/symfony-documentation-contributor
-.. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
 .. _`SymfonyCloud`: https://symfony.com/cloud
 .. _`roadmap`: https://symfony.com/roadmap
 .. _`pip`: https://pip.pypa.io/en/stable/
diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
index 5fc84d4b5fa..0cfad8880ed 100644
--- a/contributing/documentation/standards.rst
+++ b/contributing/documentation/standards.rst
@@ -135,7 +135,7 @@ Files and Directories
 * When referencing file extensions explicitly, you should include a leading dot
   for every extension (e.g. "XML files use the ``.xml`` extension").
 * When you list a Symfony file/directory hierarchy, use ``your-project/`` as the
-  top level directory. E.g.
+  top-level directory. E.g.
 
   .. code-block:: text
 
@@ -173,6 +173,24 @@ In addition, documentation follows these rules:
   * his or hers, use theirs
   * himself or herself, use themselves
 
+* **Avoid belittling words**: People read documentation because they know very
+  little about a specific topic or are even completely new to it. Things that
+  seem "obvious" or "simple" for the person documenting it, can be the exact
+  opposite for the reader. To make sure everybody feels comfortable when reading
+  the documentation, try to avoid words like:
+
+  * basically
+  * clearly
+  * easy/easily
+  * just
+  * logically
+  * merely
+  * obviously
+  * of course
+  * quick/quickly
+  * simply
+  * trivial
+
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
 .. _`Twig Coding Standards`: https://twig.symfony.com/doc/2.x/coding_standards.html
 .. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
diff --git a/contributing/map.rst.inc b/contributing/map.rst.inc
index a0cdd23cdd0..b9c9311a6cb 100644
--- a/contributing/map.rst.inc
+++ b/contributing/map.rst.inc
@@ -8,8 +8,8 @@
 * **Code**
 
   * :doc:`Bugs </contributing/code/bugs>`
-  * :doc:`Patches </contributing/code/patches>`
-  * :doc:`Reviewing Issues and Patches </contributing/community/reviews>`
+  * :doc:`Pull Requests </contributing/code/pull_requests>`
+  * :doc:`Reviewing Issues and Pull Requests </contributing/community/reviews>`
   * :doc:`Maintenance </contributing/code/maintenance>`
   * :doc:`The Core Team </contributing/code/core_team>`
   * :doc:`Security </contributing/code/security>`
@@ -32,7 +32,6 @@
   * :doc:`Release Process </contributing/community/releases>`
   * :doc:`Respectful Review comments </contributing/community/review-comments>`
   * :doc:`Community Reviews </contributing/community/reviews>`
-  * :doc:`Other Resources </contributing/community/other>`
 
 * **Diversity**
 
diff --git a/controller.rst b/controller.rst
index bd15d13a7eb..2513b5d3faf 100644
--- a/controller.rst
+++ b/controller.rst
@@ -7,8 +7,8 @@ Controller
 A controller is a PHP function you create that reads information from the
 ``Request`` object and creates and returns a ``Response`` object. The response could
 be an HTML page, JSON, XML, a file download, a redirect, a 404 error or anything
-else you can dream up. The controller executes whatever arbitrary logic
-*your application* needs to render the content of a page.
+else. The controller executes whatever arbitrary logic *your application* needs
+to render the content of a page.
 
 .. tip::
 
@@ -21,7 +21,7 @@ else you can dream up. The controller executes whatever arbitrary logic
 A Simple Controller
 -------------------
 
-While a controller can be any PHP callable (a function, method on an object,
+While a controller can be any PHP callable (function, method on an object,
 or a ``Closure``), a controller is usually a method inside a controller
 class::
 
@@ -46,7 +46,7 @@ class::
         }
     }
 
-The controller is the ``number()`` method, which lives inside a
+The controller is the ``number()`` method, which lives inside the
 controller class ``LuckyController``.
 
 This controller is pretty straightforward:
@@ -91,9 +91,9 @@ For more information on routing, see :doc:`/routing`.
 The Base Controller Class & Services
 ------------------------------------
 
-To make life nicer, Symfony comes with an optional base controller class called
+To aid development, Symfony comes with an optional base controller class called
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`.
-You can extend it to get access to some `helper methods`_.
+It can be extended to gain access to helper methods.
 
 Add the ``use`` statement atop your controller class and then modify
 ``LuckyController`` to extend it:
@@ -125,6 +125,8 @@ method is just a helper method that generates the URL for a given route::
 
     $url = $this->generateUrl('app_lucky_number', ['max' => 10]);
 
+.. _controller-redirect:
+
 Redirecting
 ~~~~~~~~~~~
 
@@ -195,7 +197,7 @@ any other "work" you can think of.
 If you need a service in a controller, type-hint an argument with its class
 (or interface) name. Symfony will automatically pass you the service you need::
 
-    use Psr\Log\LoggerInterface
+    use Psr\Log\LoggerInterface;
     // ...
 
     /**
@@ -243,7 +245,7 @@ the argument by its name:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
@@ -276,10 +278,6 @@ the argument by its name:
 Like with all services, you can also use regular :ref:`constructor injection <services-constructor-injection>`
 in your controllers.
 
-.. versionadded:: 4.1
-    The ability to bind scalar values to controller arguments was introduced in
-    Symfony 4.1. Previously you could only bind services.
-
 For more information about services, see the :doc:`/service_container` article.
 
 Generating Controllers
@@ -293,6 +291,7 @@ new controller class:
     $ php bin/console make:controller BrandNewController
 
     created: src/Controller/BrandNewController.php
+    created: templates/brandnew/index.html.twig
 
 If you want to generate an entire CRUD from a Doctrine :doc:`entity </doctrine>`,
 use:
@@ -301,7 +300,17 @@ use:
 
     $ php bin/console make:crud Product
 
+    created: src/Controller/ProductController.php
+    created: src/Form/ProductType.php
+    created: templates/product/_delete_form.html.twig
+    created: templates/product/_form.html.twig
+    created: templates/product/edit.html.twig
+    created: templates/product/index.html.twig
+    created: templates/product/new.html.twig
+    created: templates/product/show.html.twig
+
 .. versionadded:: 1.2
+
     The ``make:crud`` command was introduced in MakerBundle 1.2.
 
 .. index::
@@ -357,8 +366,8 @@ The Request object as a Controller Argument
 -------------------------------------------
 
 What if you need to read query parameters, grab a request header or get access
-to an uploaded file? All of that information is stored in Symfony's ``Request``
-object. To get it in your controller, add it as an argument and
+to an uploaded file? That information is stored in Symfony's ``Request``
+object. To access it in your controller, add it as an argument and
 **type-hint it with the Request class**::
 
     use Symfony\Component\HttpFoundation\Request;
@@ -409,16 +418,13 @@ To get the session, add an argument and type-hint it with
 
 Stored attributes remain in the session for the remainder of that user's session.
 
-.. tip::
-
-    Every ``SessionInterface`` implementation is supported. If you have your
-    own implementation, type-hint this in the argument instead.
-
 For more info, see :doc:`/session`.
 
 .. index::
    single: Session; Flash messages
 
+.. _flash-messages:
+
 Flash Messages
 ~~~~~~~~~~~~~~
 
@@ -461,14 +467,23 @@ read any flash messages from the session using ``app.flashes()``:
 
     {# templates/base.html.twig #}
 
-    {# you can read and display just one flash message type... #}
+    {# read and display just one flash message type #}
     {% for message in app.flashes('notice') %}
         <div class="flash-notice">
             {{ message }}
         </div>
     {% endfor %}
 
-    {# ...or you can read and display every flash message available #}
+    {# read and display several types of flash messages #}
+    {% for label, messages in app.flashes(['success', 'warning']) %}
+        {% for message in messages %}
+            <div class="flash-{{ label }}">
+                {{ message }}
+            </div>
+        {% endfor %}
+    {% endfor %}
+
+    {# read and display all flash messages #}
     {% for label, messages in app.flashes %}
         {% for message in messages %}
             <div class="flash-{{ label }}">
@@ -528,13 +543,13 @@ the ``Request`` class::
 The ``Request`` class has several public properties and methods that return any
 information you need about the request.
 
-Like the ``Request``, the ``Response`` object has also a public ``headers`` property.
-This is a :class:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag` that has
-some nice methods for getting and setting response headers. The header names are
-normalized so that using ``Content-Type`` is equivalent to ``content-type`` or even
-``content_type``.
+Like the ``Request``, the ``Response`` object has a public ``headers`` property.
+This object is of the type :class:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag`
+and provides methods for getting and setting response headers. The header names are
+normalized. As a result, the name ``Content-Type`` is equivalent to
+the name ``content-type`` or ``content_type``.
 
-The only requirement for a controller is to return a ``Response`` object::
+In Symfony, a controller is required to return a ``Response`` object::
 
     use Symfony\Component\HttpFoundation\Response;
 
@@ -545,15 +560,29 @@ The only requirement for a controller is to return a ``Response`` object::
     $response = new Response('<style> ... </style>');
     $response->headers->set('Content-Type', 'text/css');
 
-There are special classes that make certain kinds of responses easier. Some of these
-are mentioned below. To learn more about the ``Request`` and ``Response`` (and special
-``Response`` classes), see the :ref:`HttpFoundation component documentation <component-http-foundation-request>`.
+To facilitate this, different response objects are included to address different
+response types.  Some of these are mentioned below. To learn more about the
+``Request`` and ``Response`` (and different ``Response`` classes), see the
+:ref:`HttpFoundation component documentation <component-http-foundation-request>`.
+
+Accessing Configuration Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To get the value of any :ref:`configuration parameter <configuration-parameters>`
+from a controller, use the ``getParameter()`` helper method::
+
+    // ...
+    public function index()
+    {
+        $contentsDir = $this->getParameter('kernel.project_dir').'/contents';
+        // ...
+    }
 
 Returning JSON Response
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 To return JSON from a controller, use the ``json()`` helper method. This returns a
-special ``JsonResponse`` object that encodes the data automatically::
+``JsonResponse`` object that encodes the data automatically::
 
     // ...
     public function index()
@@ -603,13 +632,16 @@ The ``file()`` helper provides some arguments to configure its behavior::
 Final Thoughts
 --------------
 
-Whenever you create a page, you'll ultimately need to write some code that
-contains the logic for that page. In Symfony, this is called a controller,
-and it's a PHP function where you can do anything in order to return the
-final ``Response`` object that will be returned to the user.
+In Symfony, a controller is usually a class method which is used to accept
+requests, and return a ``Response`` object. When mapped with a URL, a controller
+becomes accessible and its response can be viewed.
 
-To make life easier, you'll probably extend the base ``AbstractController`` class because
-this gives access to shortcut methods (like ``render()`` and ``redirectToRoute()``).
+To facilitate the development of controllers, Symfony provides an
+``AbstractController``.  It can be used to extend the controller class allowing
+access to some frequently used utilities such as ``render()`` and
+``redirectToRoute()``. The ``AbstractController`` also provides the
+``createNotFoundException()`` utility which is used to return a page not found
+response.
 
 In other articles, you'll learn how to use specific services from inside your controller
 that will help you persist and fetch objects from a database, process form submissions,
@@ -634,6 +666,5 @@ Learn more about Controllers
 
     controller/*
 
-.. _`helper methods`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
 .. _`Symfony Maker`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html
 .. _`unvalidated redirects security vulnerability`: https://www.owasp.org/index.php/Open_redirect
diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst
index 5765cfb7469..0ac95a12ad6 100644
--- a/controller/argument_value_resolver.rst
+++ b/controller/argument_value_resolver.rst
@@ -12,10 +12,13 @@ in order to be recognized. This is done via the
 creating and registering custom argument value resolvers, you can extend this
 functionality.
 
-Functionality Shipped with the HttpKernel
------------------------------------------
+.. _functionality-shipped-with-the-httpkernel:
 
-Symfony ships with five value resolvers in the HttpKernel component:
+Built-In Value Resolvers
+------------------------
+
+Symfony ships with the following value resolvers in the
+:doc:`HttpKernel component </components/http_kernel>`:
 
 :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver\\RequestAttributeValueResolver`
     Attempts to find a request attribute that matches the name of the argument.
@@ -42,6 +45,30 @@ Symfony ships with five value resolvers in the HttpKernel component:
     argument list. When the action is called, the last (variadic) argument will
     contain all the values of this array.
 
+In addition, some components and official bundles provide other value resolvers:
+
+:class:`Symfony\\Component\\Security\\Http\\Controller\\UserValueResolver`
+    Injects the object that represents the current logged in user if type-hinted
+    with ``UserInterface``. Default value can be set to ``null`` in case
+    the controller can be accessed by anonymous users. It requires installing
+    the :doc:`Security component </components/security>`.
+
+:class:`Symfony\\Bundle\\SecurityBundle\\SecurityUserValueResolver`
+    Injects the object that represents the current logged in user if type-hinted
+    with ``UserInterface``. Default value can be set to ``null`` in case
+    the controller can be accessed by anonymous users. It requires installing
+    the `SecurityBundle`_.
+
+.. deprecated:: 4.1
+
+    The ``SecurityUserValueResolver`` was deprecated in Symfony 4.1 in favor of
+    :class:`Symfony\\Component\\Security\\Http\\Controller\\UserValueResolver`.
+
+``Psr7ServerRequestResolver``
+    Injects a `PSR-7`_ compliant version of the current request if type-hinted
+    with ``RequestInterface``, ``MessageInterface`` or ``ServerRequestInterface``.
+    It requires installing the `SensioFrameworkExtraBundle`_.
+
 Adding a Custom Value Resolver
 ------------------------------
 
@@ -85,10 +112,10 @@ type-hinted method arguments:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:sensio-framework-extra="http://symfony.com/schema/dic/symfony_extra"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <sensio-framework-extra:config>
-                <request converters="true" auto-convert="false" />
+                <request converters="true" auto-convert="false"/>
             </sensio-framework-extra:config>
         </container>
 
@@ -190,15 +217,15 @@ and adding a priority.
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... be sure autowiring is enabled -->
-                <defaults autowire="true" />
+                <defaults autowire="true"/>
                 <!-- ... -->
 
                 <service id="App\ArgumentResolver\UserValueResolver">
-                    <tag name="controller.argument_value_resolver" priority="50" />
+                    <tag name="controller.argument_value_resolver" priority="50"/>
                 </service>
             </services>
 
@@ -233,3 +260,6 @@ subrequests.
 
 .. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`yield`: http://php.net/manual/en/language.generators.syntax.php
+.. _`SecurityBundle`: https://github.com/symfony/security-bundle
+.. _`PSR-7`: https://www.php-fig.org/psr/psr-7/
+.. _`SensioFrameworkExtraBundle`: https://github.com/sensiolabs/SensioFrameworkExtraBundle
diff --git a/controller/error_pages.rst b/controller/error_pages.rst
index 7fa444003be..a4026b75a66 100644
--- a/controller/error_pages.rst
+++ b/controller/error_pages.rst
@@ -17,7 +17,7 @@ customize error pages, so run this command to make sure the bundle is installed:
 
     $ composer require twig
 
-In the :doc:`development environment </configuration/environments>`,
+In the :ref:`development environment <configuration-environments>`,
 Symfony catches all the exceptions and displays a special **exception page**
 with lots of debug information to help you discover the root problem:
 
@@ -150,7 +150,7 @@ Fortunately, the default ``ExceptionController`` allows you to preview your
 *error* pages during development.
 
 To use this feature, you need to load some special routes provided by TwigBundle
-(if the application uses :doc:`Symfony Flex </setup/flex>` they are loaded
+(if the application uses :ref:`Symfony Flex <symfony-flex>` they are loaded
 automatically when installing Twig support):
 
 .. configuration-block::
@@ -169,24 +169,21 @@ automatically when installing Twig support):
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <import resource="@TwigBundle/Resources/config/routing/errors.xml"
-                prefix="/_error" />
+            <import resource="@TwigBundle/Resources/config/routing/errors.xml" prefix="/_error"/>
         </routes>
 
     .. code-block:: php
 
         // config/routes/dev/twig.php
-        use Symfony\Component\Routing\RouteCollection;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->addCollection(
-            $loader->import('@TwigBundle/Resources/config/routing/errors.xml')
-        );
-        $routes->addPrefix("/_error");
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->import('@TwigBundle/Resources/config/routing/errors.xml')
+                ->prefix('/_error')
+            ;
+        };
 
 With this route added, you can use URLs like these to preview the *error* page
 for a given status code as HTML or for a given status code and format.
@@ -216,7 +213,7 @@ configuration option to point to it:
 
         # config/packages/twig.yaml
         twig:
-            exception_controller: App\Controller\ExceptionController::showException
+            exception_controller: App\Controller\ExceptionController::showAction
 
     .. code-block:: xml
 
@@ -226,12 +223,12 @@ configuration option to point to it:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
-                <twig:exception-controller>App\Controller\ExceptionController::showException</twig:exception-controller>
+                <twig:exception-controller>App\Controller\ExceptionController::showAction</twig:exception-controller>
             </twig:config>
 
         </container>
@@ -240,7 +237,7 @@ configuration option to point to it:
 
         // config/packages/twig.php
         $container->loadFromExtension('twig', [
-            'exception_controller' => 'App\Controller\ExceptionController::showException',
+            'exception_controller' => 'App\Controller\ExceptionController::showAction',
             // ...
         ]);
 
@@ -292,11 +289,11 @@ In that case, you might want to override one or both of the ``showAction()`` and
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <services>
                     <!-- ... be sure autowiring is enabled -->
-                    <defaults autowire="true" />
+                    <defaults autowire="true"/>
                     <!-- ... -->
 
                     <service id="App\Controller\CustomExceptionController" public="true">
@@ -342,7 +339,7 @@ error pages.
 .. note::
 
     If your listener calls ``setResponse()`` on the
-    :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`,
+    :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`,
     event, propagation will be stopped and the response will be sent to
     the client.
 
@@ -360,6 +357,3 @@ time and again, you can have just one (or several) listeners deal with them.
     out and other things.
 
 .. _`TwigBundle`: https://github.com/symfony/twig-bundle
-.. _`WebfactoryExceptionsBundle`: https://github.com/webfactory/exceptions-bundle
-.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard/
-.. _`ExceptionListener`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Http/Firewall/ExceptionListener.php
diff --git a/controller/forwarding.rst b/controller/forwarding.rst
index b8fb3bf8c63..74a6ffedeed 100644
--- a/controller/forwarding.rst
+++ b/controller/forwarding.rst
@@ -5,10 +5,13 @@ How to Forward Requests to another Controller
 =============================================
 
 Though not very common, you can also forward to another controller internally
-with the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController::forward`
-method. Instead of redirecting the user's browser, this makes an "internal"
-sub-request and calls the defined controller. The ``forward()`` method returns
-the :class:`Symfony\\Component\\HttpFoundation\\Response` object that is returned
+with the ``forward()`` method provided by the
+:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`
+class.
+
+Instead of redirecting the user's browser, this makes an "internal" sub-request
+and calls the defined controller. The ``forward()`` method returns the
+:class:`Symfony\\Component\\HttpFoundation\\Response` object that is returned
 from *that* controller::
 
     public function index($name)
diff --git a/controller/service.rst b/controller/service.rst
index 8fbb6db9a2f..a9098e16b86 100644
--- a/controller/service.rst
+++ b/controller/service.rst
@@ -26,13 +26,12 @@ a service like: ``App\Controller\HelloController::index``:
     .. code-block:: php-annotations
 
         // src/Controller/HelloController.php
-
         use Symfony\Component\Routing\Annotation\Route;
 
         class HelloController
         {
             /**
-             * @Route("/hello", name="hello")
+             * @Route("/hello", name="hello", methods={"GET"})
              */
             public function index()
             {
@@ -45,7 +44,8 @@ a service like: ``App\Controller\HelloController::index``:
         # config/routes.yaml
         hello:
             path:     /hello
-            defaults: { _controller: App\Controller\HelloController::index }
+            controller: App\Controller\HelloController::index
+            methods: GET
 
     .. code-block:: xml
 
@@ -54,29 +54,81 @@ a service like: ``App\Controller\HelloController::index``:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="hello" path="/hello">
-                <default key="_controller">App\Controller\HelloController::index</default>
-            </route>
+            <route id="hello" path="/hello" controller="App\Controller\HelloController::index" methods="GET"/>
 
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        $collection->add('hello', new Route('/hello', [
-            '_controller' => 'App\Controller\HelloController::index',
-        ]));
+        use App\Controller\HelloController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('hello', '/hello')
+                ->controller([HelloController::class, 'index'])
+                ->methods(['GET'])
+            ;
+        };
 
 .. _controller-service-invoke:
 
 Invokable Controllers
 ---------------------
 
-If your controller implements the ``__invoke()`` method - popular with the
-Action-Domain-Response (ADR) pattern, you can refer to the service id
-without the method (``App\Controller\HelloController`` for example).
+Controllers can also define a single action using the ``__invoke()`` method,
+which is a common practice when following the `ADR pattern`_
+(Action-Domain-Responder):
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/Hello.php
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        /**
+         * @Route("/hello/{name}", name="hello")
+         */
+        class Hello
+        {
+            public function __invoke($name = 'World')
+            {
+                return new Response(sprintf('Hello %s!', $name));
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        hello:
+            path:     /hello/{name}
+            defaults: { _controller: app.hello_controller }
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="hello" path="/hello/{name}">
+                <default key="_controller">app.hello_controller</default>
+            </route>
+
+        </routes>
+
+    .. code-block:: php
+
+        // app/config/routing.php
+        $collection->add('hello', new Route('/hello', [
+            '_controller' => 'app.hello_controller',
+        ]));
 
 Alternatives to base Controller Methods
 ---------------------------------------
@@ -132,6 +184,6 @@ If you want to know what type-hints to use for each service, see the
 ``getSubscribedServices()`` method in `AbstractController`_.
 
 .. _`Controller class source code`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
-.. _`base Controller class`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
 .. _`ControllerTrait`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
 .. _`AbstractController`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/AbstractController.php
+.. _`ADR pattern`: https://en.wikipedia.org/wiki/Action%E2%80%93domain%E2%80%93responder
diff --git a/controller/soap_web_service.rst b/controller/soap_web_service.rst
index 902d3d9a796..42679a7ca14 100644
--- a/controller/soap_web_service.rst
+++ b/controller/soap_web_service.rst
@@ -59,10 +59,10 @@ can be retrieved via ``/soap?wsdl``::
 
     namespace App\Controller;
 
+    use App\Service\HelloService;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Routing\Annotation\Route;
-    use App\Service\HelloService;
 
     class HelloServiceController extends AbstractController
     {
@@ -120,17 +120,17 @@ An example WSDL is below.
 
         <types>
             <xsd:schema targetNamespace="urn:hellowsdl">
-                <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/" />
-                <xsd:import namespace="http://schemas.xmlsoap.org/wsdl/" />
+                <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
+                <xsd:import namespace="http://schemas.xmlsoap.org/wsdl/"/>
             </xsd:schema>
         </types>
 
         <message name="helloRequest">
-            <part name="name" type="xsd:string" />
+            <part name="name" type="xsd:string"/>
         </message>
 
         <message name="helloResponse">
-            <part name="return" type="xsd:string" />
+            <part name="return" type="xsd:string"/>
         </message>
 
         <portType name="hellowsdlPortType">
@@ -160,7 +160,7 @@ An example WSDL is below.
 
         <service name="hellowsdl">
             <port name="hellowsdlPort" binding="tns:hellowsdlBinding">
-                <soap:address location="http://example.com/index.php/soap" />
+                <soap:address location="http://example.com/index.php/soap"/>
             </port>
         </service>
     </definitions>
diff --git a/controller/upload_file.rst b/controller/upload_file.rst
index 6b0368d1b59..ce63d2bd449 100644
--- a/controller/upload_file.rst
+++ b/controller/upload_file.rst
@@ -12,14 +12,13 @@ How to Upload Files
     integrated with Doctrine ORM, MongoDB ODM, PHPCR ODM and Propel.
 
 Imagine that you have a ``Product`` entity in your application and you want to
-add a PDF brochure for each product. To do so, add a new property called ``brochure``
-in the ``Product`` entity::
+add a PDF brochure for each product. To do so, add a new property called
+``brochureFilename`` in the ``Product`` entity::
 
     // src/Entity/Product.php
     namespace App\Entity;
 
     use Doctrine\ORM\Mapping as ORM;
-    use Symfony\Component\Validator\Constraints as Assert;
 
     class Product
     {
@@ -27,38 +26,40 @@ in the ``Product`` entity::
 
         /**
          * @ORM\Column(type="string")
-         *
-         * @Assert\NotBlank(message="Please, upload the product brochure as a PDF file.")
-         * @Assert\File(mimeTypes={ "application/pdf" })
          */
-        private $brochure;
+        private $brochureFilename;
 
-        public function getBrochure()
+        public function getBrochureFilename()
         {
-            return $this->brochure;
+            return $this->brochureFilename;
         }
 
-        public function setBrochure($brochure)
+        public function setBrochureFilename($brochureFilename)
         {
-            $this->brochure = $brochure;
+            $this->brochureFilename = $brochureFilename;
 
             return $this;
         }
     }
 
-Note that the type of the ``brochure`` column is ``string`` instead of ``binary``
-or ``blob`` because it just stores the PDF file name instead of the file contents.
+Note that the type of the ``brochureFilename`` column is ``string`` instead of
+``binary`` or ``blob`` because it only stores the PDF file name instead of the
+file contents.
 
-Then, add a new ``brochure`` field to the form that manages the ``Product`` entity::
+The next step is to add a new field to the form that manages the ``Product``
+entity. This must be a ``FileType`` field so the browsers can display the file
+upload widget. The trick to make it work is to add the form field as "unmapped",
+so Symfony doesn't try to get/set its value from the related entity::
 
     // src/Form/ProductType.php
     namespace App\Form;
 
     use App\Entity\Product;
     use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\FileType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\FileType;
+    use Symfony\Component\Validator\Constraints\File;
 
     class ProductType extends AbstractType
     {
@@ -66,7 +67,29 @@ Then, add a new ``brochure`` field to the form that manages the ``Product`` enti
         {
             $builder
                 // ...
-                ->add('brochure', FileType::class, ['label' => 'Brochure (PDF file)'])
+                ->add('brochure', FileType::class, [
+                    'label' => 'Brochure (PDF file)',
+
+                    // unmapped means that this field is not associated to any entity property
+                    'mapped' => false,
+
+                    // make it optional so you don't have to re-upload the PDF file
+                    // everytime you edit the Product details
+                    'required' => false,
+
+                    // unmapped fields can't define their validation using annotations
+                    // in the associated entity, so you can use the PHP constraint classes
+                    'constraints' => [
+                        new File([
+                            'maxSize' => '1024k',
+                            'mimeTypes' => [
+                                'application/pdf',
+                                'application/x-pdf',
+                            ],
+                            'mimeTypesMessage' => 'Please upload a valid PDF document',
+                        ])
+                    ],
+                ])
                 // ...
             ;
         }
@@ -99,12 +122,13 @@ Finally, you need to update the code of the controller that handles the form::
     // src/Controller/ProductController.php
     namespace App\Controller;
 
+    use App\Entity\Product;
+    use App\Form\ProductType;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpFoundation\File\Exception\FileException;
+    use Symfony\Component\HttpFoundation\File\UploadedFile;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\Routing\Annotation\Route;
-    use App\Entity\Product;
-    use App\Form\ProductType;
 
     class ProductController extends AbstractController
     {
@@ -118,26 +142,32 @@ Finally, you need to update the code of the controller that handles the form::
             $form->handleRequest($request);
 
             if ($form->isSubmitted() && $form->isValid()) {
-                // $file stores the uploaded PDF file
-                /** @var Symfony\Component\HttpFoundation\File\UploadedFile $file */
-                $file = $product->getBrochure();
-
-                $fileName = $this->generateUniqueFileName().'.'.$file->guessExtension();
-
-                // Move the file to the directory where brochures are stored
-                try {
-                    $file->move(
-                        $this->getParameter('brochures_directory'),
-                        $fileName
-                    );
-                } catch (FileException $e) {
-                    // ... handle exception if something happens during file upload
+                /** @var UploadedFile $brochureFile */
+                $brochureFile = $form['brochure']->getData();
+
+                // this condition is needed because the 'brochure' field is not required
+                // so the PDF file must be processed only when a file is uploaded
+                if ($brochureFile) {
+                    $originalFilename = pathinfo($brochureFile->getClientOriginalName(), PATHINFO_FILENAME);
+                    // this is needed to safely include the file name as part of the URL
+                    $safeFilename = transliterator_transliterate('Any-Latin; Latin-ASCII; [^A-Za-z0-9_] remove; Lower()', $originalFilename);
+                    $newFilename = $safeFilename.'-'.uniqid().'.'.$brochureFile->guessExtension();
+
+                    // Move the file to the directory where brochures are stored
+                    try {
+                        $brochureFile->move(
+                            $this->getParameter('brochures_directory'),
+                            $newFilename
+                        );
+                    } catch (FileException $e) {
+                        // ... handle exception if something happens during file upload
+                    }
+
+                    // updates the 'brochureFilename' property to store the PDF file name
+                    // instead of its contents
+                    $product->setBrochureFilename($newFilename);
                 }
 
-                // updates the 'brochure' property to store the PDF file name
-                // instead of its contents
-                $product->setBrochure($fileName);
-
                 // ... persist the $product variable or any other work
 
                 return $this->redirect($this->generateUrl('app_product_list'));
@@ -147,16 +177,6 @@ Finally, you need to update the code of the controller that handles the form::
                 'form' => $form->createView(),
             ]);
         }
-
-        /**
-         * @return string
-         */
-        private function generateUniqueFileName()
-        {
-            // md5() reduces the similarity of the file names generated by
-            // uniqid(), which is based on timestamps
-            return md5(uniqid());
-        }
     }
 
 Now, create the ``brochures_directory`` parameter that was used in the
@@ -172,9 +192,6 @@ controller to specify the directory in which the brochures should be stored:
 
 There are some important things to consider in the code of the above controller:
 
-#. When the form is uploaded, the ``brochure`` property contains the whole PDF
-   file contents. Since this property stores just the file name, you must set
-   its new value before persisting the changes of the entity;
 #. In Symfony applications, uploaded files are objects of the
    :class:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile` class. This class
    provides methods for the most common operations when dealing with uploaded files;
@@ -189,7 +206,8 @@ There are some important things to consider in the code of the above controller:
    use the :method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::guessExtension`
    method to let Symfony guess the right extension according to the file MIME type;
 
-.. versionadded:: 4.1
+.. deprecated:: 4.1
+
     The :method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientSize`
     method was deprecated in Symfony 4.1 and will be removed in Symfony 5.0.
     Use ``getSize()`` instead.
@@ -198,7 +216,7 @@ You can use the following code to link to the PDF brochure of a product:
 
 .. code-block:: html+twig
 
-    <a href="{{ asset('uploads/brochures/' ~ product.brochure) }}">View brochure (PDF)</a>
+    <a href="{{ asset('uploads/brochures/' ~ product.brochureFilename) }}">View brochure (PDF)</a>
 
 .. tip::
 
@@ -211,8 +229,8 @@ You can use the following code to link to the PDF brochure of a product:
         use Symfony\Component\HttpFoundation\File\File;
         // ...
 
-        $product->setBrochure(
-            new File($this->getParameter('brochures_directory').'/'.$product->getBrochure())
+        $product->setBrochureFilename(
+            new File($this->getParameter('brochures_directory').'/'.$product->getBrochureFilename())
         );
 
 Creating an Uploader Service
@@ -238,7 +256,9 @@ logic to a separate service::
 
         public function upload(UploadedFile $file)
         {
-            $fileName = md5(uniqid()).'.'.$file->guessExtension();
+            $originalFilename = pathinfo($file->getClientOriginalName(), PATHINFO_FILENAME);
+            $safeFilename = transliterator_transliterate('Any-Latin; Latin-ASCII; [^A-Za-z0-9_] remove; Lower()', $originalFilename);
+            $fileName = $safeFilename.'-'.uniqid().'.'.$file->guessExtension();
 
             try {
                 $file->move($this->getTargetDirectory(), $fileName);
@@ -267,9 +287,6 @@ logic to a separate service::
     :class:`Symfony\\Component\\HttpFoundation\\File\\Exception\\NoTmpDirFileException`,
     and :class:`Symfony\\Component\\HttpFoundation\\File\\Exception\\PartialFileException`.
 
-    .. versionadded:: 4.1
-        The detailed exception classes were introduced in Symfony 4.1.
-
 Then, define a service for this class:
 
 .. configuration-block::
@@ -291,7 +308,7 @@ Then, define a service for this class:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
             <!-- ... -->
 
             <service id="App\FileUploader">
@@ -310,8 +327,8 @@ Then, define a service for this class:
 Now you're ready to use this service in the controller::
 
     // src/Controller/ProductController.php
-    use Symfony\Component\HttpFoundation\Request;
     use App\Service\FileUploader;
+    use Symfony\Component\HttpFoundation\Request;
 
     // ...
     public function new(Request $request, FileUploader $fileUploader)
@@ -319,10 +336,12 @@ Now you're ready to use this service in the controller::
         // ...
 
         if ($form->isSubmitted() && $form->isValid()) {
-            $file = $product->getBrochure();
-            $fileName = $fileUploader->upload($file);
-
-            $product->setBrochure($fileName);
+            /** @var UploadedFile $brochureFile */
+            $brochureFile = $form['brochure']->getData();
+            if ($brochureFile) {
+                $brochureFileName = $fileUploader->upload($brochureFile);
+                $product->setBrochureFilename($brochureFileName);
+            }
 
             // ...
         }
@@ -333,149 +352,16 @@ Now you're ready to use this service in the controller::
 Using a Doctrine Listener
 -------------------------
 
-If you are using Doctrine to store the Product entity, you can create a
-:doc:`Doctrine listener </doctrine/event_listeners_subscribers>` to
-automatically upload the file when persisting the entity::
-
-    // src/EventListener/BrochureUploadListener.php
-    namespace App\EventListener;
-
-    use Symfony\Component\HttpFoundation\File\UploadedFile;
-    use Symfony\Component\HttpFoundation\File\File;
-    use Doctrine\ORM\Event\LifecycleEventArgs;
-    use Doctrine\ORM\Event\PreUpdateEventArgs;
-    use App\Entity\Product;
-    use App\Service\FileUploader;
-
-    class BrochureUploadListener
-    {
-        private $uploader;
-
-        public function __construct(FileUploader $uploader)
-        {
-            $this->uploader = $uploader;
-        }
-
-        public function prePersist(LifecycleEventArgs $args)
-        {
-            $entity = $args->getEntity();
-
-            $this->uploadFile($entity);
-        }
-
-        public function preUpdate(PreUpdateEventArgs $args)
-        {
-            $entity = $args->getEntity();
-
-            $this->uploadFile($entity);
-        }
-
-        private function uploadFile($entity)
-        {
-            // upload only works for Product entities
-            if (!$entity instanceof Product) {
-                return;
-            }
-
-            $file = $entity->getBrochure();
-
-            // only upload new files
-            if ($file instanceof UploadedFile) {
-                $fileName = $this->uploader->upload($file);
-                $entity->setBrochure($fileName);
-            } elseif ($file instanceof File) {
-                // prevents the full file path being saved on updates
-                // as the path is set on the postLoad listener
-                $entity->setBrochure($file->getFilename());
-            }
-        }
-    }
-
-Now, register this class as a Doctrine listener:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        services:
-            _defaults:
-                # ... be sure autowiring is enabled
-                autowire: true
-            # ...
-
-            App\EventListener\BrochureUploadListener:
-                tags:
-                    - { name: doctrine.event_listener, event: prePersist }
-                    - { name: doctrine.event_listener, event: preUpdate }
-
-    .. code-block:: xml
+The previous versions of this article explained how to handle file uploads using
+:doc:`Doctrine listeners </doctrine/event_listeners_subscribers>`. However, this
+is no longer recommended, because Doctrine events shouldn't be used for your
+domain logic.
 
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <!-- ... be sure autowiring is enabled -->
-                <defaults autowire="true" />
-                <!-- ... -->
-
-                <service id="App\EventListener\BrochureUploaderListener">
-                    <tag name="doctrine.event_listener" event="prePersist"/>
-                    <tag name="doctrine.event_listener" event="preUpdate"/>
-                </service>
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        use App\EventListener\BrochureUploaderListener;
-
-        $container->autowire(BrochureUploaderListener::class)
-            ->addTag('doctrine.event_listener', [
-                'event' => 'prePersist',
-            ])
-            ->addTag('doctrine.event_listener', [
-                'event' => 'preUpdate',
-            ])
-        ;
-
-This listener is now automatically executed when persisting a new Product
-entity. This way, you can remove everything related to uploading from the
-controller.
-
-.. tip::
-
-    This listener can also create the ``File`` instance based on the path when
-    fetching entities from the database::
-
-        // ...
-        use Symfony\Component\HttpFoundation\File\File;
-
-        // ...
-        class BrochureUploadListener
-        {
-            // ...
-
-            public function postLoad(LifecycleEventArgs $args)
-            {
-                $entity = $args->getEntity();
-
-                if (!$entity instanceof Product) {
-                    return;
-                }
-
-                if ($fileName = $entity->getBrochure()) {
-                    $entity->setBrochure(new File($this->uploader->getTargetDirectory().'/'.$fileName));
-                }
-            }
-        }
+Moreover, Doctrine listeners are often dependent on internal Doctrine behavior
+which may change in future versions. Also, they can introduce performance issues
+unawarely (because your listener persists entities which cause other entities to
+be changed and persisted).
 
-    After adding these lines, configure the listener to also listen for the
-    ``postLoad`` event.
+As an alternative, you can use :doc:`Symfony events, listeners and subscribers </event_dispatcher>`.
 
 .. _`VichUploaderBundle`: https://github.com/dustin10/VichUploaderBundle
diff --git a/create_framework/dependency_injection.rst b/create_framework/dependency_injection.rst
index 2dbb759abed..27991a50915 100644
--- a/create_framework/dependency_injection.rst
+++ b/create_framework/dependency_injection.rst
@@ -66,15 +66,15 @@ framework more configurable, but at the same time, it introduces a lot of
 issues:
 
 * We are not able to register custom listeners anymore as the dispatcher is
-  not available outside the Framework class (an easy workaround could be the
+  not available outside the Framework class (a workaround could be the
   adding of a ``Framework::getEventDispatcher()`` method);
 
 * We have lost the flexibility we had before; you cannot change the
   implementation of the ``UrlMatcher`` or of the ``ControllerResolver``
   anymore;
 
-* Related to the previous point, we cannot test our framework easily anymore
-  as it's impossible to mock internal objects;
+* Related to the previous point, we cannot test our framework without much
+  effort anymore as it's impossible to mock internal objects;
 
 * We cannot change the charset passed to ``ResponseListener`` anymore (a
   workaround could be to pass it as a constructor argument).
@@ -97,13 +97,13 @@ container:
 Create a new file to host the dependency injection container configuration::
 
     // example.com/src/container.php
+    use Simplex\Framework;
     use Symfony\Component\DependencyInjection;
     use Symfony\Component\DependencyInjection\Reference;
+    use Symfony\Component\EventDispatcher;
     use Symfony\Component\HttpFoundation;
     use Symfony\Component\HttpKernel;
     use Symfony\Component\Routing;
-    use Symfony\Component\EventDispatcher;
-    use Simplex\Framework;
 
     $containerBuilder = new DependencyInjection\ContainerBuilder();
     $containerBuilder->register('context', Routing\RequestContext::class);
@@ -234,7 +234,7 @@ And the related change in the front controller::
 
     $container->setParameter('routes', include __DIR__.'/../src/app.php');
 
-We have obviously barely scratched the surface of what you can do with the
+We have barely scratched the surface of what you can do with the
 container: from class names as parameters, to overriding existing object
 definitions, from shared service support to dumping a container to a plain PHP class,
 and much more. The Symfony dependency injection container is really powerful
@@ -253,4 +253,3 @@ internally.
 Have fun!
 
 .. _`Pimple`: https://github.com/silexphp/Pimple
-.. _`Application`: https://github.com/silexphp/Silex/blob/master/src/Silex/Application.php
diff --git a/create_framework/event_dispatcher.rst b/create_framework/event_dispatcher.rst
index b0d8aa99848..fd655a93ebf 100644
--- a/create_framework/event_dispatcher.rst
+++ b/create_framework/event_dispatcher.rst
@@ -3,8 +3,7 @@ The EventDispatcher Component
 
 Our framework is still missing a major characteristic of any good framework:
 *extensibility*. Being extensible means that the developer should be able to
-easily hook into the framework life cycle to modify the way the request is
-handled.
+hook into the framework life cycle to modify the way the request is handled.
 
 What kind of hooks are we talking about? Authentication or caching for
 instance. To be flexible, hooks must be plug-and-play; the ones you "register"
@@ -77,7 +76,7 @@ the Response instance::
             }
 
             // dispatch a response event
-            $this->dispatcher->dispatch('response', new ResponseEvent($response, $request));
+            $this->dispatcher->dispatch(new ResponseEvent($response, $request), 'response');
 
             return $response;
         }
@@ -91,7 +90,7 @@ now dispatched::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\EventDispatcher\Event;
+    use Symfony\Contracts\EventDispatcher\Event;
 
     class ResponseEvent extends Event
     {
@@ -302,4 +301,4 @@ is not about creating a generic framework, but one that is tailored to your
 needs. Stop whenever you see fit, and further evolve the code from there.
 
 .. _`WSGI`: https://www.python.org/dev/peps/pep-0333/#middleware-components-that-play-both-sides
-.. _`Rack`: http://rack.rubyforge.org/
+.. _`Rack`: https://github.com/rack/rack
diff --git a/create_framework/front_controller.rst b/create_framework/front_controller.rst
index 23dc9b8c82b..39286ba8c16 100644
--- a/create_framework/front_controller.rst
+++ b/create_framework/front_controller.rst
@@ -61,8 +61,8 @@ which name is exposed to the end user via the URL
 (``http://127.0.0.1:4321/bye.php``): there is a direct mapping between the PHP
 script name and the client URL. This is because the dispatching of the request
 is done by the web server directly. It might be a good idea to move this
-dispatching to our code for better flexibility. This can be achieved by
-routing all client requests to a single PHP script.
+dispatching to our code for better flexibility. This can be achieved by routing
+all client requests to a single PHP script.
 
 .. tip::
 
@@ -153,12 +153,12 @@ web root directory:
 Now, configure your web server root directory to point to ``web/`` and all
 other files won't be accessible from the client anymore.
 
-To test your changes in a browser (``http://localhost:4321/hello?name=Fabien``), run
-the PHP built-in server:
+To test your changes in a browser (``http://localhost:4321/hello?name=Fabien``),
+run the :doc:`Symfony Local Web Server </setup/symfony_server>`:
 
 .. code-block:: terminal
 
-    $ php -S 127.0.0.1:4321 -t web/ web/front.php
+    $ symfony server:start --port=4321 --passthru=front.php
 
 .. note::
 
@@ -220,7 +220,7 @@ We have the first version of our framework::
 
     $response->send();
 
-Adding a new page is a two step process: add an entry in the map and create a
+Adding a new page is a two-step process: add an entry in the map and create a
 PHP template in ``src/pages/``. From a template, get the Request data via the
 ``$request`` variable and tweak the Response headers via the ``$response``
 variable.
diff --git a/create_framework/http_foundation.rst b/create_framework/http_foundation.rst
index 672f40599ce..28d3f33dec3 100644
--- a/create_framework/http_foundation.rst
+++ b/create_framework/http_foundation.rst
@@ -9,10 +9,9 @@ top of the Symfony components is better than creating a framework from scratch.
 
 .. note::
 
-    We won't talk about the obvious and traditional benefits of using a
-    framework when working on big applications with more than a few
-    developers; the Internet has already plenty of good resources on that
-    topic.
+    We won't talk about the traditional benefits of using a framework when
+    working on big applications with more than a few developers; the Internet
+    has already plenty of good resources on that topic.
 
 Even if the "application" we wrote in the previous chapter was simple enough,
 it suffers from a few problems::
@@ -52,7 +51,7 @@ As you can see for yourself, the simple code we had written first is not that
 simple anymore if we want to avoid PHP warnings/notices and make the code
 more secure.
 
-Beyond security, this code is not even easily testable. Even if there is not
+Beyond security, this code can be complex to test. Even if there is not
 much to test, it strikes me that writing unit tests for the simplest possible
 snippet of PHP code is not natural and feels ugly. Here is a tentative PHPUnit
 unit test for the above code::
@@ -78,7 +77,7 @@ unit test for the above code::
 
     If our application were just slightly bigger, we would have been able to
     find even more problems. If you are curious about them, read the
-    :doc:`/introduction/from_flat_php_to_symfony2` chapter of the book.
+    :doc:`/introduction/from_flat_php_to_symfony` chapter of the book.
 
 At this point, if you are not convinced that security and testing are indeed
 two very good reasons to stop writing code the old way and adopt a framework
@@ -87,9 +86,9 @@ reading this book now and go back to whatever code you were working on before.
 
 .. note::
 
-    Of course, using a framework should give you more than just security and
-    testability, but the more important thing to keep in mind is that the
-    framework you choose must allow you to write better code faster.
+    Using a framework should give you more than just security and testability,
+    but the more important thing to keep in mind is that the framework you
+    choose must allow you to write better code faster.
 
 Going OOP with the HttpFoundation Component
 -------------------------------------------
@@ -126,10 +125,10 @@ containing the new requirement.
 .. sidebar:: Class Autoloading
 
     When installing a new dependency, Composer also generates a
-    ``vendor/autoload.php`` file that allows any class to be easily
-    `autoloaded`_. Without autoloading, you would need to require the file
-    where a class is defined before being able to use it. But thanks to
-    `PSR-4`_, we can just let Composer and PHP do the hard work for us.
+    ``vendor/autoload.php`` file that allows any class to be `autoloaded`_.
+    Without autoloading, you would need to require the file where a class
+    is defined before being able to use it. But thanks to `PSR-4`_,
+    we can just let Composer and PHP do the hard work for us.
 
 Now, let's rewrite our application by using the ``Request`` and the
 ``Response`` classes::
@@ -285,8 +284,8 @@ the wheel.
 
 I've almost forgot to talk about one added benefit: using the HttpFoundation
 component is the start of better interoperability between all frameworks and
-`applications using it`_ (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `ezPublish
-5`_, `Laravel`_ and `more`_).
+`applications using it`_ (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `Laravel`_
+and `ezPublish 5`_,  and `more`_).
 
 .. _`Twig`: https://twig.symfony.com/
 .. _`HTTP specification`: https://tools.ietf.org/wg/httpbis/
@@ -297,8 +296,6 @@ component is the start of better interoperability between all frameworks and
 .. _`phpBB 3`: https://www.phpbb.com/
 .. _`ezPublish 5`: https://ez.no/
 .. _`Laravel`: https://laravel.com/
-.. _`Midgard CMS`: http://www.midgard-project.org/
-.. _`Zikula`: https://zikula.org/
 .. _`autoloaded`: https://php.net/autoload
 .. _`PSR-4`: https://www.php-fig.org/psr/psr-4/
 .. _`more`: https://symfony.com/components/HttpFoundation
diff --git a/create_framework/http_kernel_controller_resolver.rst b/create_framework/http_kernel_controller_resolver.rst
index f9148c974c0..5b998ed2dab 100644
--- a/create_framework/http_kernel_controller_resolver.rst
+++ b/create_framework/http_kernel_controller_resolver.rst
@@ -25,10 +25,10 @@ Update the route definition accordingly::
     $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', [
         'year' => null,
         '_controller' => [new LeapYearController(), 'index'],
-    )));
+    ]));
 
 The move is pretty straightforward and makes a lot of sense as soon as you
-create more pages but you might have noticed a non-desirable side-effect...
+create more pages but you might have noticed a non-desirable side effect...
 The ``LeapYearController`` class is *always* instantiated, even if the
 requested URL does not match the ``leap_year`` route. This is bad for one main
 reason: performance wise, all controllers for all routes must now be
@@ -162,8 +162,8 @@ Let's conclude with the new version of our framework::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\Routing;
     use Symfony\Component\HttpKernel;
+    use Symfony\Component\Routing;
 
     function render_template(Request $request)
     {
@@ -203,4 +203,3 @@ Think about it once more: our framework is more robust and more flexible than
 ever and it still has less than 50 lines of code.
 
 .. _`reflection`: https://php.net/reflection
-.. _`FrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
diff --git a/create_framework/http_kernel_httpkernel_class.rst b/create_framework/http_kernel_httpkernel_class.rst
index 717b66f4113..f9f8f16932f 100644
--- a/create_framework/http_kernel_httpkernel_class.rst
+++ b/create_framework/http_kernel_httpkernel_class.rst
@@ -4,7 +4,7 @@ The HttpKernel Component: The HttpKernel Class
 If you were to use our framework right now, you would probably have to add
 support for custom error messages. We do have 404 and 500 error support but
 the responses are hardcoded in the framework itself. Making them customizable
-is easy enough though: dispatch a new event and listen to it. Doing it right
+is straightforward though: dispatch a new event and listen to it. Doing it right
 means that the listener has to call a regular controller. But what if the
 error controller throws an exception? You will end up in an infinite loop.
 There should be an easier way, right?
@@ -91,8 +91,8 @@ The error controller reads as follows::
     // example.com/src/Calendar/Controller/ErrorController.php
     namespace Calendar\Controller;
 
-    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Debug\Exception\FlattenException;
+    use Symfony\Component\HttpFoundation\Response;
 
     class ErrorController
     {
@@ -104,8 +104,8 @@ The error controller reads as follows::
         }
     }
 
-Voilà! Clean and customizable error management without efforts. And
-if your ``ErrorController`` throws an exception, HttpKernel will handle it nicely.
+*Voilà!* Clean and customizable error management without efforts. And if your
+``ErrorController`` throws an exception, HttpKernel will handle it nicely.
 
 In chapter two, we talked about the ``Response::prepare()`` method, which
 ensures that a Response is compliant with the HTTP specification. It is
@@ -114,8 +114,8 @@ client; that's what the ``ResponseListener`` does::
 
     $dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
 
-This one was easy too! Let's take another one: do you want out of the box
-support for streamed responses? Subscribe to ``StreamedResponseListener``::
+If you want out of the box support for streamed responses, subscribe
+to ``StreamedResponseListener``::
 
     $dispatcher->addSubscriber(new HttpKernel\EventListener\StreamedResponseListener());
 
@@ -153,12 +153,12 @@ only if needed::
     namespace Simplex;
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-    use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\ViewEvent;
 
     class StringResponseListener implements EventSubscriberInterface
     {
-        public function onView(GetResponseForControllerResultEvent $event)
+        public function onView(ViewEvent $event)
         {
             $response = $event->getControllerResult();
 
diff --git a/create_framework/http_kernel_httpkernelinterface.rst b/create_framework/http_kernel_httpkernelinterface.rst
index bf5fe5d3132..fccf5d408c0 100644
--- a/create_framework/http_kernel_httpkernelinterface.rst
+++ b/create_framework/http_kernel_httpkernelinterface.rst
@@ -46,7 +46,7 @@ Update your framework so that it implements this interface::
         }
     }
 
-Even if this change looks trivial, it brings us a lot! Let's talk about one of
+Even if this change looks not too complex, it brings us a lot! Let's talk about one of
 the most impressive one: transparent :doc:`HTTP caching </http_cache>` support.
 
 The ``HttpCache`` class implements a fully-featured reverse proxy, written in
@@ -55,7 +55,7 @@ PHP; it implements ``HttpKernelInterface`` and wraps another
 
     // example.com/web/front.php
 
-    // ..
+    // ...
 
     $framework = new Simplex\Framework($dispatcher, $matcher, $controllerResolver, $argumentResolver);
     $framework = new HttpKernel\HttpCache\HttpCache(
@@ -90,11 +90,10 @@ to cache a response for 10 seconds, use the ``Response::setTtl()`` method::
 
 .. tip::
 
-    If, like me, you are running your framework from the command line by
-    simulating requests (``Request::create('/is_leap_year/2012')``), you can
-    debug Response instances by dumping their string representation
-    (``echo $response;``) as it displays all headers as well as the response
-    content.
+    If you are running your framework from the command line by simulating
+    requests (``Request::create('/is_leap_year/2012')``), you can debug Response
+    instances by dumping their string representation (``echo $response;``) as it
+    displays all headers as well as the response content.
 
 To validate that it works correctly, add a random number to the response
 content and check that the number only changes every 10 seconds::
@@ -113,9 +112,9 @@ expiration and the validation models of the HTTP specification. If you are not
 comfortable with these concepts, read the `HTTP caching`_ chapter of the
 Symfony documentation.
 
-The Response class contains methods that let you configure the
-HTTP cache. One of the most powerful is ``setCache()`` as it
-abstracts the most frequently used caching strategies into a single array::
+The Response class contains methods that let you configure the HTTP cache. One
+of the most powerful is ``setCache()`` as it abstracts the most frequently used
+caching strategies into a single array::
 
     $date = date_create_from_format('Y-m-d H:i:s', '2005-10-15 10:00:00');
 
@@ -135,8 +134,8 @@ abstracts the most frequently used caching strategies into a single array::
     $response->setSharedMaxAge(10);
 
 When using the validation model, the ``isNotModified()`` method allows you to
-cut on the response time by short-circuiting the response generation as
-early as possible::
+cut on the response time by short-circuiting the response generation as early as
+possible::
 
     $response->setETag('whatever_you_compute_as_an_etag');
 
@@ -158,7 +157,7 @@ page as being the content of a sub-request call:
 
     This is the content of your page
 
-    Is 2012 a leap year? <esi:include src="/leapyear/2012" />
+    Is 2012 a leap year? <esi:include src="/leapyear/2012"/>
 
     Some other content
 
diff --git a/create_framework/introduction.rst b/create_framework/introduction.rst
index 82aaf864ea3..363538529d8 100644
--- a/create_framework/introduction.rst
+++ b/create_framework/introduction.rst
@@ -38,8 +38,8 @@ you can use as is or as a start for your very own. It will start with a simple
 framework and more features will be added with time. Eventually, you will have
 a fully-featured full-stack web framework.
 
-And each step will be the occasion to learn more about some of the
-Symfony Components.
+And each step will be the occasion to learn more about some of the Symfony
+Components.
 
 Many modern web frameworks advertize themselves as being MVC frameworks. This
 tutorial won't talk about the MVC pattern, as the Symfony Components are able to
@@ -87,7 +87,7 @@ Dependency Management
 
 To install the Symfony Components that you need for your framework, you are going
 to use `Composer`_, a project dependency manager for PHP. If you don't have it
-yet, :doc:`download and install Composer </setup/composer>` now.
+yet, `download and install Composer`_ now.
 
 Our Project
 -----------
@@ -101,17 +101,17 @@ start with the simplest web application we can think of in PHP::
 
     printf('Hello %s', $name);
 
-You can use the PHP built-in server to test this great application in a browser
-(``http://localhost:4321/index.php?name=Fabien``):
+You can use the :doc:`Symfony Local Web Server </setup/symfony_server>` to test
+this great application in a browser
+(``http://localhost:8000/index.php?name=Fabien``):
 
 .. code-block:: terminal
 
-    $ php -S 127.0.0.1:4321
-
-Otherwise, you can always use your own server (Apache, Nginx, etc.).
+    $ symfony server:start
 
 In the :doc:`next chapter </create_framework/http_foundation>`, we are going to
 introduce the HttpFoundation Component and see what it brings us.
 
 .. _`Symfony`: https://symfony.com/
 .. _`Composer`: http://packagist.org/about-composer
+.. _`download and install Composer`: https://getcomposer.org/download/
diff --git a/create_framework/routing.rst b/create_framework/routing.rst
index 56fa2465d92..b196d2cb965 100644
--- a/create_framework/routing.rst
+++ b/create_framework/routing.rst
@@ -80,8 +80,8 @@ of default values for route attributes (``['name' => 'World']``).
 Based on the information stored in the ``RouteCollection`` instance, a
 ``UrlMatcher`` instance can match URL paths::
 
-    use Symfony\Component\Routing\RequestContext;
     use Symfony\Component\Routing\Matcher\UrlMatcher;
+    use Symfony\Component\Routing\RequestContext;
 
     $context = new RequestContext();
     $context->fromRequest($request);
@@ -93,27 +93,27 @@ The ``match()`` method takes a request path and returns an array of attributes
 (notice that the matched route is automatically stored under the special
 ``_route`` attribute)::
 
-    print_r($matcher->match('/bye'));
-    /* Gives:
-    array (
-      '_route' => 'bye',
-    );
+    $matcher->match('/bye');
+    /* Result:
+    [
+        '_route' => 'bye',
+    ];
     */
 
-    print_r($matcher->match('/hello/Fabien'));
-    /* Gives:
-    array (
-      'name' => 'Fabien',
-      '_route' => 'hello',
-    );
+    $matcher->match('/hello/Fabien');
+    /* Result:
+    [
+        'name' => 'Fabien',
+        '_route' => 'hello',
+    ];
     */
 
-    print_r($matcher->match('/hello'));
-    /* Gives:
-    array (
-      'name' => 'World',
-      '_route' => 'hello',
-    );
+    $matcher->match('/hello');
+    /* Result:
+    [
+        'name' => 'World',
+        '_route' => 'hello',
+    ];
     */
 
 .. note::
@@ -165,23 +165,23 @@ There are a few new things in the code:
 
 * Request attributes are extracted to keep our templates simple::
 
-      <!-- example.com/src/pages/hello.php -->
-      Hello <?= htmlspecialchars($name, ENT_QUOTES, 'UTF-8') ?>
+    // example.com/src/pages/hello.php
+    Hello <?= htmlspecialchars($name, ENT_QUOTES, 'UTF-8') ?>
 
 * Route configuration has been moved to its own file::
 
-      // example.com/src/app.php
-      use Symfony\Component\Routing;
+    // example.com/src/app.php
+    use Symfony\Component\Routing;
 
-      $routes = new Routing\RouteCollection();
-      $routes->add('hello', new Routing\Route('/hello/{name}', ['name' => 'World']));
-      $routes->add('bye', new Routing\Route('/bye'));
+    $routes = new Routing\RouteCollection();
+    $routes->add('hello', new Routing\Route('/hello/{name}', ['name' => 'World']));
+    $routes->add('bye', new Routing\Route('/bye'));
 
-      return $routes;
+    return $routes;
 
-  We now have a clear separation between the configuration (everything
-  specific to our application in ``app.php``) and the framework (the generic
-  code that powers our application in ``front.php``).
+We now have a clear separation between the configuration (everything
+specific to our application in ``app.php``) and the framework (the generic
+code that powers our application in ``front.php``).
 
 With less than 30 lines of code, we have a new framework, more powerful and
 more flexible than the previous one. Enjoy!
@@ -189,8 +189,7 @@ more flexible than the previous one. Enjoy!
 Using the Routing component has one big additional benefit: the ability to
 generate URLs based on Route definitions. When using both URL matching and URL
 generation in your code, changing the URL patterns should have no other
-impact. Want to know how to use the generator? Calling the ``generate`` method
-is all it takes::
+impact. You can use the generator this way::
 
     use Symfony\Component\Routing;
 
@@ -217,6 +216,11 @@ generate absolute URLs::
     highly optimized URL matcher class that can replace the default
     ``UrlMatcher``::
 
-        $dumper = new Routing\Matcher\Dumper\PhpMatcherDumper($routes);
+        use Symfony\Component\Routing\Matcher\CompiledUrlMatcher;
+        use Symfony\Component\Routing\Matcher\Dumper\CompiledUrlMatcherDumper;
+
+        // $compiledRoutes is a plain PHP array that describes all routes in a performant data format
+        // you can (and should) cache it, typically by exporting it to a PHP file
+        $compiledRoutes = (new CompiledUrlMatcherDumper($routes))->getCompiledRoutes();
 
-        echo $dumper->dump();
+        $matcher = new CompiledUrlMatcher($compiledRoutes, $context);
diff --git a/create_framework/separation_of_concerns.rst b/create_framework/separation_of_concerns.rst
index cf971869c73..e1e46f3ebe3 100644
--- a/create_framework/separation_of_concerns.rst
+++ b/create_framework/separation_of_concerns.rst
@@ -13,7 +13,7 @@ simple principle: the logic is about creating the Response associated with a
 Request.
 
 Let's create our very own namespace for our framework: ``Simplex``. Move the
-request handling logic into its own ``Simplex\\Framework`` class::
+request handling logic into its own ``Simplex\Framework`` class::
 
     // example.com/src/Simplex/Framework.php
     namespace Simplex;
@@ -100,9 +100,9 @@ Move the controller to ``Calendar\Controller\LeapYearController``::
     // example.com/src/Calendar/Controller/LeapYearController.php
     namespace Calendar\Controller;
 
+    use Calendar\Model\LeapYear;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
-    use Calendar\Model\LeapYear;
 
     class LeapYearController
     {
@@ -138,7 +138,7 @@ Don't forget to update the ``example.com/src/app.php`` file accordingly::
 
     $routes->add('leap_year', new Routing\Route('/is_leap_year/{year}', [
         'year' => null,
-        '_controller' => 'Calendar\Controller\LeapYearController::indexAction',
+        '_controller' => 'Calendar\Controller\LeapYearController::index',
     ]));
 
 To sum up, here is the new file layout:
@@ -163,7 +163,7 @@ To sum up, here is the new file layout:
         └── front.php
 
 That's it! Our application has now four different layers and each of them has
-a well defined goal:
+a well-defined goal:
 
 * ``web/front.php``: The front controller; the only exposed PHP code that
   makes the interface with the client (it gets the Request and sends the
@@ -171,7 +171,7 @@ a well defined goal:
   our application;
 
 * ``src/Simplex``: The reusable framework code that abstracts the handling of
-  incoming Requests (by the way, it makes your controllers/templates easily
+  incoming Requests (by the way, it makes your controllers/templates better
   testable -- more about that later on);
 
 * ``src/Calendar``: Our application specific code (the controllers and the
diff --git a/create_framework/templating.rst b/create_framework/templating.rst
index f21564ce7b7..566779d5eaf 100644
--- a/create_framework/templating.rst
+++ b/create_framework/templating.rst
@@ -69,8 +69,8 @@ the ``_controller`` route attribute::
         $response = new Response('An error occurred', 500);
     }
 
-A route can now be associated with any controller and within a
-controller, you can still use the ``render_template()`` to render a template::
+A route can now be associated with any controller and within a controller, you
+can still use the ``render_template()`` to render a template::
 
     $routes->add('hello', new Routing\Route('/hello/{name}', [
         'name' => 'World',
@@ -142,8 +142,8 @@ framework does not need to be modified in any way, create a new
 ``app.php`` file::
 
     // example.com/src/app.php
-    use Symfony\Component\Routing;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Routing;
 
     function is_leap_year($year = null) {
         if (null === $year) {
diff --git a/create_framework/unit_testing.rst b/create_framework/unit_testing.rst
index 054dca776ef..69c235cfd3a 100644
--- a/create_framework/unit_testing.rst
+++ b/create_framework/unit_testing.rst
@@ -16,7 +16,7 @@ using `PHPUnit`_. Create a PHPUnit configuration file in
     <?xml version="1.0" encoding="UTF-8"?>
     <phpunit
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-        xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/5.1/phpunit.xsd"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/5.1/phpunit.xsd"
         backupGlobals="false"
         colors="true"
         bootstrap="vendor/autoload.php"
@@ -50,20 +50,20 @@ resolver. Modify the framework to make use of them::
 
     // ...
 
-    use Symfony\Component\Routing\Matcher\UrlMatcherInterface;
-    use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
     use Symfony\Component\HttpKernel\Controller\ArgumentResolverInterface;
+    use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
+    use Symfony\Component\Routing\Matcher\UrlMatcherInterface;
 
     class Framework
     {
         protected $matcher;
-        protected $resolver;
+        protected $controllerResolver;
         protected $argumentResolver;
 
         public function __construct(UrlMatcherInterface $matcher, ControllerResolverInterface $resolver, ArgumentResolverInterface $argumentResolver)
         {
             $this->matcher = $matcher;
-            $this->resolver = $resolver;
+            $this->controllerResolver = $resolver;
             $this->argumentResolver = $argumentResolver;
         }
 
@@ -135,8 +135,7 @@ Execute this test by running ``phpunit`` in the ``example.com`` directory:
 After the test ran, you should see a green bar. If not, you have a bug
 either in the test or in the framework code!
 
-Adding a unit test for any exception thrown in a controller means expecting a
-response code of 500::
+Adding a unit test for any exception thrown in a controller::
 
     public function testErrorHandling()
     {
@@ -151,8 +150,8 @@ Last, but not the least, let's write a test for when we actually have a proper
 Response::
 
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\HttpKernel\Controller\ControllerResolver;
     use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
+    use Symfony\Component\HttpKernel\Controller\ControllerResolver;
     // ...
 
     public function testControllerResponse()
diff --git a/deployment.rst b/deployment.rst
index 9bfdc06e17b..b0ab569c87f 100644
--- a/deployment.rst
+++ b/deployment.rst
@@ -63,8 +63,8 @@ manually taking other steps (see `Common Post-Deployment Tasks`_).
 Using Platforms as a Service
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using a Platform as a Service (PaaS) can be a great way to deploy your Symfony app
-quickly and easily. There are many PaaS - below are a few that work well with Symfony:
+Using a Platform as a Service (PaaS) can be a great way to deploy your Symfony
+app quickly. There are many PaaS - below are a few that work well with Symfony:
 
 * `Symfony Cloud`_
 * `Heroku`_
@@ -118,8 +118,8 @@ you'll need to do:
 A) Check Requirements
 ~~~~~~~~~~~~~~~~~~~~~
 
-Use the :doc:`Symfony Requirements Checker </reference/requirements>` to check
-if your server meets the technical requirements to run Symfony applications.
+Use the ``check:requirements`` command to check if your server meets the
+:ref:`technical requirements for running Symfony applications <symfony-tech-requirements>`.
 
 .. _b-configure-your-app-config-parameters-yml-file:
 
@@ -146,7 +146,6 @@ most natural in your hosting environment.
 
     .. code-block:: terminal
 
-        $ composer remove symfony/dotenv
         $ composer require symfony/dotenv
 
 C) Install/Update your Vendors
@@ -170,8 +169,8 @@ as you normally do:
 .. caution::
 
     If you get a "class not found" error during this step, you may need to
-    run ``export APP_ENV=prod`` (or ``export SYMFONY_ENV=prod`` if you're not
-    using :doc:`Symfony Flex </setup/flex>`) before running this command so
+    run ``export APP_ENV=prod`` (or ``export SYMFONY_ENV=prod`` if you're not
+    using :ref:`Symfony Flex <symfony-flex>`) before running this command so
     that the ``post-install-cmd`` scripts run in the ``prod`` environment.
 
 D) Clear your Symfony Cache
@@ -181,7 +180,7 @@ Make sure you clear and warm-up your Symfony cache:
 
 .. code-block:: terminal
 
-    $ php bin/console cache:clear --env=prod --no-debug
+    $ APP_ENV=prod APP_DEBUG=0 php bin/console cache:clear
 
 E) Other Things!
 ~~~~~~~~~~~~~~~~
@@ -190,7 +189,7 @@ There may be lots of other things that you need to do, depending on your
 setup:
 
 * Running any database migrations
-* Clearing your APC cache
+* Clearing your APCu cache
 * Add/edit CRON jobs
 * :ref:`Building and minifying your assets <how-do-i-deploy-my-encore-assets>` with Webpack Encore
 * Pushing assets to a CDN
@@ -218,28 +217,15 @@ Troubleshooting
 Deployments not Using the ``composer.json`` File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Symfony applications provide a ``kernel.project_dir`` parameter and a related
-:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method.
-You can use this method to perform operations with file paths relative to your
-project's root directory. The logic to find that project root directory is based
-on the location of the main ``composer.json`` file.
-
-If your deployment method doesn't use Composer, you may have removed the
-``composer.json`` file and the application won't work on the production server.
-The solution is to override the ``getProjectDir()`` method in the application
-kernel and return your project's root directory::
-
-    // src/Kernel.php
-    // ...
-    class Kernel extends BaseKernel
-    {
-        // ...
-
-        public function getProjectDir()
-        {
-            return __DIR__.'/..';
-        }
-    }
+The :ref:`project root directory <configuration-kernel-project-directory>`
+(whose value is used via the ``kernel.project_dir`` parameter and the
+:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method) is
+calculated automatically by Symfony as the directory where the main
+``composer.json`` file is stored.
+
+In deployments not using the ``composer.json`` file, you'll need to override the
+:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method
+:ref:`as explained in this section <configuration-kernel-project-directory>`.
 
 Learn More
 ----------
@@ -262,7 +248,7 @@ Learn More
 .. _`Deployer`: http://deployer.org/
 .. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging
 .. _`Heroku`: https://devcenter.heroku.com/articles/getting-started-with-symfony
-.. _`platform.sh`: https://docs.platform.sh/frameworks/symfony.html
+.. _`Platform.sh`: https://docs.platform.sh/frameworks/symfony.html
 .. _`Azure`: https://azure.microsoft.com/en-us/develop/php/
 .. _`fortrabbit`: https://help.fortrabbit.com/install-symfony
 .. _`EasyDeployBundle`: https://github.com/EasyCorp/easy-deploy-bundle
diff --git a/deployment/heroku.rst b/deployment/heroku.rst
index a7527805bd2..1e2e1635c55 100644
--- a/deployment/heroku.rst
+++ b/deployment/heroku.rst
@@ -7,6 +7,6 @@ Deploying to Heroku
 ===================
 
 To deploy to Heroku, see their official documentation:
-`Getting Started with Symfony on Heroku`_.
+`Deploying Symfony 4 Apps on Heroku`_.
 
-.. _`Getting Started with Symfony on Heroku`: https://devcenter.heroku.com/articles/getting-started-with-symfony
+.. _`Deploying Symfony 4 Apps on Heroku`: https://devcenter.heroku.com/articles/deploying-symfony4
diff --git a/deployment/proxies.rst b/deployment/proxies.rst
index d61d1c3a8d3..6e54ce5b612 100644
--- a/deployment/proxies.rst
+++ b/deployment/proxies.rst
@@ -22,9 +22,7 @@ Solution: setTrustedProxies()
 -----------------------------
 
 To fix this, you need to tell Symfony which reverse proxy IP addresses to trust
-and what headers your reverse proxy uses to send information:
-
-.. code-block:: php
+and what headers your reverse proxy uses to send information::
 
     // public/index.php
 
@@ -61,9 +59,7 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
    other than your load balancers. For AWS, this can be done with `security groups`_.
 
 #. Once you've guaranteed that traffic will only come from your trusted reverse
-   proxies, configure Symfony to *always* trust incoming request:
-
-   .. code-block:: php
+   proxies, configure Symfony to *always* trust incoming request::
 
        // public/index.php
 
@@ -80,5 +76,21 @@ That's it! It's critical that you prevent traffic from all non-trusted sources.
 If you allow outside traffic, they could "spoof" their true IP address and
 other information.
 
+Custom Headers When Using a Reverse Proxy
+-----------------------------------------
+
+Some reverse proxies (like `CloudFront`_ with ``CloudFront-Forwarded-Proto``) may force you to use a custom header.
+For instance you have ``Custom-Forwarded-Proto`` instead of ``X-Forwarded-Proto``.
+
+In this case, you'll need to set the header ``X-Forwarded-Proto`` with the value of
+``Custom-Forwarded-Proto`` early enough in your application, i.e. before handling the request::
+
+    // public/index.php
+
+    // ...
+    $_SERVER['HEADER_X_FORWARDED_PROTO'] = $_SERVER['HEADER_CUSTOM_FORWARDED_PROTO'];
+    // ...
+    $response = $kernel->handle($request);
+
 .. _`security groups`: http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html
-.. _`RFC 7239`: http://tools.ietf.org/html/rfc7239
+.. _`CloudFront`: https://en.wikipedia.org/wiki/Amazon_CloudFront
diff --git a/doctrine.rst b/doctrine.rst
index 0283fb9dfbd..9cedaa2c984 100644
--- a/doctrine.rst
+++ b/doctrine.rst
@@ -29,7 +29,7 @@ which will help generate some code:
 .. code-block:: terminal
 
     $ composer require symfony/orm-pack
-    $ composer require symfony/maker-bundle --dev
+    $ composer require --dev symfony/maker-bundle
 
 Configuring the Database
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -50,10 +50,10 @@ The database connection information is stored as an environment variable called
 .. caution::
 
     If the username, password, host or database name contain any character considered
-    special in a URI (such as ``!``, ``@``, ``$``, ``#``, ``/``), you must encode them.
-    See `RFC 3986`_ for the full list of reserved characters or use the
-    :phpfunction:`urlencode` function to encode them. In this case you need to remove
-    the ``resolve:`` prefix in ``config/packages/doctrine.yaml`` to avoid errors:
+    special in a URI (such as ``+``, ``@``, ``$``, ``#``, ``/``, ``:``, ``*``, ``!``),
+    you must encode them. See `RFC 3986`_ for the full list of reserved characters or
+    use the :phpfunction:`urlencode` function to encode them. In this case you need to
+    remove the ``resolve:`` prefix in ``config/packages/doctrine.yaml`` to avoid errors:
     ``url: '%env(resolve:DATABASE_URL)%'``
 
 Now that your connection parameters are setup, Doctrine can create the ``db_name``
@@ -117,6 +117,7 @@ need. The command will ask you some questions - answer them like done below:
     (press enter again to finish)
 
 .. versionadded:: 1.3
+
     The interactive behavior of the ``make:entity`` command was introduced
     in MakerBundle 1.3.
 
@@ -162,6 +163,13 @@ Woh! You now have a new ``src/Entity/Product.php`` file::
     Confused why the price is an integer? Don't worry: this is just an example.
     But, storing prices as integers (e.g. 100 = $1 USD) can avoid rounding issues.
 
+.. note::
+
+    If you are using an SQLite database, you'll see the following error:
+    *PDOException: SQLSTATE[HY000]: General error: 1 Cannot add a NOT NULL
+    column with default value NULL*. Add a ``nullable=true`` option to the
+    ``description`` property to fix the problem.
+
 .. caution::
 
     There is a `limit of 767 bytes for the index key prefix`_ when using
@@ -234,9 +242,9 @@ your production database up-to-date.
 Migrations & Adding more Fields
 -------------------------------
 
-But what if you need to add a new field property to ``Product``, like a ``description``?
-You can edit the class to add the new property. But, you can also use ``make:entity``
-again:
+But what if you need to add a new field property to ``Product``, like a
+``description``? You can edit the class to add the new property. But, you can
+also use ``make:entity`` again:
 
 .. code-block:: terminal
 
@@ -332,25 +340,25 @@ to experiment:
     $ php bin/console make:controller ProductController
 
 Inside the controller, you can create a new ``Product`` object, set data on it,
-and save it!
-
-.. code-block:: php
+and save it::
 
     // src/Controller/ProductController.php
     namespace App\Controller;
 
     // ...
     use App\Entity\Product;
+    use Doctrine\ORM\EntityManagerInterface;
+    use Symfony\Component\HttpFoundation\Response;
 
     class ProductController extends AbstractController
     {
         /**
-         * @Route("/product", name="product")
+         * @Route("/product", name="create_product")
          */
-        public function index()
+        public function createProduct(): Response
         {
             // you can fetch the EntityManager via $this->getDoctrine()
-            // or you can add an argument to your action: index(EntityManagerInterface $entityManager)
+            // or you can add an argument to the action: createProduct(EntityManagerInterface $entityManager)
             $entityManager = $this->getDoctrine()->getManager();
 
             $product = new Product();
@@ -386,17 +394,17 @@ Take a look at the previous example in more detail:
 
 .. _doctrine-entity-manager:
 
-* **line 16** The ``$this->getDoctrine()->getManager()`` method gets Doctrine's
+* **line 18** The ``$this->getDoctrine()->getManager()`` method gets Doctrine's
   *entity manager* object, which is the most important object in Doctrine. It's
   responsible for saving objects to, and fetching objects from, the database.
 
-* **lines 18-21** In this section, you instantiate and work with the ``$product``
+* **lines 20-23** In this section, you instantiate and work with the ``$product``
   object like any other normal PHP object.
 
-* **line 24** The ``persist($product)`` call tells Doctrine to "manage" the
+* **line 26** The ``persist($product)`` call tells Doctrine to "manage" the
   ``$product`` object. This does **not** cause a query to be made to the database.
 
-* **line 27** When the ``flush()`` method is called, Doctrine looks through
+* **line 29** When the ``flush()`` method is called, Doctrine looks through
   all of the objects that it's managing to see if they need to be persisted
   to the database. In this example, the ``$product`` object's data doesn't
   exist in the database, so the entity manager executes an ``INSERT`` query,
@@ -410,6 +418,78 @@ Take a look at the previous example in more detail:
 Whether you're creating or updating objects, the workflow is always the same: Doctrine
 is smart enough to know if it should INSERT or UPDATE your entity.
 
+.. _automatic_object_validation:
+
+Validating Objects
+------------------
+
+:doc:`The Symfony validator </validation>` reuses Doctrine metadata to perform
+some basic validation tasks::
+
+    // src/Controller/ProductController.php
+    namespace App\Controller;
+
+    use App\Entity\Product;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Validator\Validator\ValidatorInterface;
+    // ...
+
+    class ProductController extends AbstractController
+    {
+        /**
+         * @Route("/product", name="create_product")
+         */
+        public function createProduct(ValidatorInterface $validator): Response
+        {
+            $product = new Product();
+            // This will trigger an error: the column isn't nullable in the database
+            $product->setName(null);
+            // This will trigger a type mismatch error: an integer is expected
+            $product->setPrice('1999');
+
+            // ...
+
+            $errors = $validator->validate($product);
+            if (count($errors) > 0) {
+                return new Response((string) $errors, 400);
+            }
+
+            // ...
+        }
+    }
+
+Although the ``Product`` entity doesn't define any explicit
+:doc:`validation configuration </validation>`, Symfony introspects the Doctrine
+mapping configuration to infer some validation rules. For example, given that
+the ``name`` property can't be ``null`` in the database, a
+:doc:`NotNull constraint </reference/constraints/NotNull>` is added automatically
+to the property (if it doesn't contain that constraint already).
+
+The following table summarizes the mapping between Doctrine metadata and
+the corresponding validation constraints added automatically by Symfony:
+
+==================  =========================================================  =====
+Doctrine attribute  Validation constraint                                      Notes
+==================  =========================================================  =====
+``nullable=false``  :doc:`NotNull </reference/constraints/NotNull>`            Requires installing the :doc:`PropertyInfo component </components/property_info>`
+``type``            :doc:`Type </reference/constraints/Type>`                  Requires installing the :doc:`PropertyInfo component </components/property_info>`
+``unique=true``     :doc:`UniqueEntity </reference/constraints/UniqueEntity>`
+``length``          :doc:`Length </reference/constraints/Length>`
+==================  =========================================================  =====
+
+Because :doc:`the Form component </forms>` as well as `API Platform`_ internally
+use the Validator component, all your forms and web APIs will also automatically
+benefit from these automatic validation constraints.
+
+This automatic validation is a nice feature to improve your productivity, but it
+doesn't replace the validation configuration entirely. You still need to add
+some :doc:`validation constraints </reference/constraints>` to ensure that data
+provided by the user is correct.
+
+.. versionadded:: 4.3
+
+    The automatic validation has been added in Symfony 4.3.
+
 Fetching Objects from the Database
 ----------------------------------
 
@@ -504,9 +584,7 @@ for you automatically! First, install the bundle in case you don't have it:
 Now, simplify your controller::
 
     // src/Controller/ProductController.php
-
     use App\Entity\Product;
-    // ...
 
     /**
      * @Route("/product/{id}", name="product_show")
@@ -593,11 +671,11 @@ But what if you need a more complex query? When you generated your entity with
 
     use App\Entity\Product;
     use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
-    use Symfony\Bridge\Doctrine\RegistryInterface;
+    use Doctrine\Common\Persistence\ManagerRegistry;
 
     class ProductRepository extends ServiceEntityRepository
     {
-        public function __construct(RegistryInterface $registry)
+        public function __construct(ManagerRegistry $registry)
         {
             parent::__construct($registry, Product::class);
         }
@@ -615,7 +693,7 @@ a new method for this to your repository::
     // ...
     class ProductRepository extends ServiceEntityRepository
     {
-        public function __construct(RegistryInterface $registry)
+        public function __construct(ManagerRegistry $registry)
         {
             parent::__construct($registry, Product::class);
         }
@@ -729,7 +807,7 @@ data into your project (i.e. "fixture data"). Install it with:
 
 .. code-block:: terminal
 
-    $ composer require doctrine/doctrine-fixtures-bundle --dev
+    $ composer require --dev doctrine/doctrine-fixtures-bundle
 
 Then, use the ``make:fixtures`` command to generate an empty fixture class:
 
@@ -799,7 +877,6 @@ Learn more
 .. _`Doctrine's Mapping Types documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html
 .. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html
 .. _`Doctrine Query Language`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html
-.. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping
 .. _`Reserved SQL keywords documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words
 .. _`DoctrineMongoDBBundle`: https://symfony.com/doc/current/bundles/DoctrineMongoDBBundle/index.html
 .. _`DoctrineFixturesBundle`: https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html
@@ -810,3 +887,4 @@ Learn more
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`limit of 767 bytes for the index key prefix`: https://dev.mysql.com/doc/refman/5.6/en/innodb-restrictions.html
 .. _`Doctrine screencast series`: https://symfonycasts.com/screencast/symfony-doctrine
+.. _`API Platform`: https://api-platform.com/docs/core/validation/
diff --git a/doctrine/associations.rst b/doctrine/associations.rst
index 24bad95a950..62eaec04955 100644
--- a/doctrine/associations.rst
+++ b/doctrine/associations.rst
@@ -188,7 +188,7 @@ the ``Product`` entity (and getter & setter methods):
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="App\Entity\Product">
                 <!-- ... -->
@@ -196,7 +196,7 @@ the ``Product`` entity (and getter & setter methods):
                     field="category"
                     target-entity="App\Entity\Category"
                     inversed-by="products">
-                    <join-column nullable="false" />
+                    <join-column nullable="false"/>
                 </many-to-one>
             </entity>
         </doctrine-mapping>
@@ -264,14 +264,14 @@ class that will hold these objects:
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="App\Entity\Category">
                 <!-- ... -->
                 <one-to-many
                     field="products"
                     target-entity="App\Entity\Product"
-                    mapped-by="category" />
+                    mapped-by="category"/>
 
                 <!--
                     don't forget to init the collection in
@@ -398,7 +398,7 @@ you.
 .. image:: /_images/doctrine/mapping_relations_proxy.png
     :align: center
 
-What's important is the fact that you have easy access to the product's related
+What's important is the fact that you have access to the product's related
 category, but the category data isn't actually retrieved until you ask for
 the category (i.e. it's "lazily loaded").
 
@@ -450,6 +450,8 @@ by adding JOINs.
     all at once (via a *join*), Doctrine will return the *true* ``Category``
     object, since nothing needs to be lazily loaded.
 
+.. _doctrine-associations-join-query:
+
 Joining Related Records
 -----------------------
 
diff --git a/doctrine/custom_dql_functions.rst b/doctrine/custom_dql_functions.rst
index 7f83fa4b307..77e7c4f92bc 100644
--- a/doctrine/custom_dql_functions.rst
+++ b/doctrine/custom_dql_functions.rst
@@ -33,9 +33,9 @@ In Symfony, you can register your custom DQL functions as follows:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:orm>
@@ -53,10 +53,10 @@ In Symfony, you can register your custom DQL functions as follows:
     .. code-block:: php
 
         // config/packages/doctrine.php
-        use App\DQL\StringFunction;
-        use App\DQL\SecondStringFunction;
-        use App\DQL\NumericFunction;
         use App\DQL\DatetimeFunction;
+        use App\DQL\NumericFunction;
+        use App\DQL\SecondStringFunction;
+        use App\DQL\StringFunction;
 
         $container->loadFromExtension('doctrine', [
             'orm' => [
@@ -105,9 +105,9 @@ In Symfony, you can register your custom DQL functions as follows:
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
                     http://symfony.com/schema/dic/doctrine
-                    http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                    https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
                 <doctrine:config>
                     <doctrine:orm>
diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst
index 3d8ea18a627..b584ab479e3 100644
--- a/doctrine/dbal.rst
+++ b/doctrine/dbal.rst
@@ -13,8 +13,9 @@ How to Use Doctrine DBAL
 
 The `Doctrine`_ Database Abstraction Layer (DBAL) is an abstraction layer that
 sits on top of `PDO`_ and offers an intuitive and flexible API for communicating
-with the most popular relational databases. In other words, the DBAL library
-makes it easy to execute queries and perform other database actions.
+with the most popular relational databases. The DBAL library allows you to write
+queries independently of your ORM models, e.g. for building reports or direct
+data manipulations.
 
 .. tip::
 
@@ -82,14 +83,14 @@ mapping types, read Doctrine's `Custom Mapping Types`_ section of their document
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:dbal>
-                    <doctrine:type name="custom_first" class="App\Type\CustomFirst" />
-                    <doctrine:type name="custom_second" class="App\Type\CustomSecond" />
+                    <doctrine:type name="custom_first" class="App\Type\CustomFirst"/>
+                    <doctrine:type name="custom_second" class="App\Type\CustomSecond"/>
                 </doctrine:dbal>
             </doctrine:config>
         </container>
@@ -126,8 +127,8 @@ mapping type:
         # config/packages/doctrine.yaml
         doctrine:
             dbal:
-               mapping_types:
-                  enum: string
+                mapping_types:
+                    enum: string
 
     .. code-block:: xml
 
@@ -136,13 +137,13 @@ mapping type:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:dbal>
-                     <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
+                    <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
                 </doctrine:dbal>
             </doctrine:config>
         </container>
@@ -152,9 +153,9 @@ mapping type:
         // config/packages/doctrine.php
         $container->loadFromExtension('doctrine', [
             'dbal' => [
-               'mapping_types' => [
-                  'enum'  => 'string',
-               ],
+                'mapping_types' => [
+                    'enum'  => 'string',
+                ],
             ],
         ]);
 
diff --git a/doctrine/event_listeners_subscribers.rst b/doctrine/event_listeners_subscribers.rst
index 04b934ec80e..de27feecb26 100644
--- a/doctrine/event_listeners_subscribers.rst
+++ b/doctrine/event_listeners_subscribers.rst
@@ -16,9 +16,17 @@ whenever an object in your database is saved.
 
 Doctrine defines two types of objects that can listen to Doctrine events:
 listeners and subscribers. Both are very similar, but listeners are a bit
-more straightforward. For more, see `The Event System`_ on Doctrine's website.
+more straightforward. For more, see `The Event System`_ on Doctrine's documentation.
 
-The Doctrine website also explains all existing events that can be listened to.
+Before using them, keep in mind that Doctrine events are intended for
+persistence hooks (i.e. *"save also this when saving that"*). They should not be
+used for domain logic, such as logging changes, setting ``updatedAt`` and
+``createdAt`` properties, etc.
+
+.. seealso::
+
+    This article covers listeners and subscribers for Doctrine ORM. If you are
+    using ODM for MongoDB, read the `DoctrineMongoDBBundle documentation`_.
 
 Configuring the Listener/Subscriber
 -----------------------------------
@@ -55,13 +63,13 @@ managers that use this connection.
                 <!-- ... -->
 
                 <service id="App\EventListener\SearchIndexer">
-                    <tag name="doctrine.event_listener" event="postPersist" />
+                    <tag name="doctrine.event_listener" event="postPersist"/>
                 </service>
                 <service id="App\EventListener\SearchIndexer2">
-                    <tag name="doctrine.event_listener" event="postPersist" connection="default" />
+                    <tag name="doctrine.event_listener" event="postPersist" connection="default"/>
                 </service>
                 <service id="App\EventListener\SearchIndexerSubscriber">
-                    <tag name="doctrine.event_subscriber" connection="default" />
+                    <tag name="doctrine.event_subscriber" connection="default"/>
                 </service>
             </services>
         </container>
@@ -95,9 +103,9 @@ a ``postPersist()`` method, which will be called when the event is dispatched::
     // src/EventListener/SearchIndexer.php
     namespace App\EventListener;
 
+    use App\Entity\Product;
     // for Doctrine < 2.4: use Doctrine\ORM\Event\LifecycleEventArgs;
     use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
-    use App\Entity\Product;
 
     class SearchIndexer
     {
@@ -140,10 +148,10 @@ interface and have an event method for each event it subscribes to::
     // src/EventListener/SearchIndexerSubscriber.php
     namespace App\EventListener;
 
+    use App\Entity\Product;
     use Doctrine\Common\EventSubscriber;
     // for Doctrine < 2.4: use Doctrine\ORM\Event\LifecycleEventArgs;
     use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
-    use App\Entity\Product;
     use Doctrine\ORM\Events;
 
     class SearchIndexerSubscriber implements EventSubscriber
@@ -188,57 +196,16 @@ interface and have an event method for each event it subscribes to::
 
 For a full reference, see chapter `The Event System`_ in the Doctrine documentation.
 
-Lazy loading for Event Listeners
---------------------------------
-
-One subtle difference between listeners and subscribers is that Symfony can load
-entity listeners lazily. This means that your listener class will only be fetched
-from the service container (and thus be instantiated) once the event it is linked
-to actually fires.
-
-Lazy loading might give you a slight performance improvement when your listener
-runs for events that rarely fire. Also, it can help you when you run into
-*circular dependency issues* that may occur when your listener service in turn
-depends on the DBAL connection.
-
-To mark a listener service as lazily loaded, just add the ``lazy`` attribute
-to the tag like so:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        services:
-            App\EventListener\SearchIndexer:
-                tags:
-                    - { name: doctrine.event_listener, event: postPersist, lazy: true }
-
-    .. code-block:: xml
-
-        <?xml version="1.0" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
-
-            <services>
-                <service id="App\EventListener\SearchIndexer" autowire="true">
-                    <tag name="doctrine.event_listener" event="postPersist" lazy="true" />
-                </service>
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        use App\EventListener\SearchIndexer;
-
-        $container
-            ->autowire(SearchIndexer::class)
-            ->addTag('doctrine.event_listener', ['event' => 'postPersist', 'lazy' => 'true'])
-        ;
+Performance Considerations
+--------------------------
 
-.. note::
+One important difference between listeners and subscribers is that Symfony loads
+entity listeners lazily. This means that the listener classes are only fetched
+from the service container (and instantiated) if the related event is actually
+fired.
 
-    Marking an event listener as ``lazy`` has nothing to do with lazy service
-    definitions which are described :doc:`in their own article </service_container/lazy_services>`
+That's why it is preferable to use entity listeners instead of subscribers
+whenever possible.
 
 Priorities for Event Listeners
 ------------------------------
@@ -271,10 +238,10 @@ numbers mean that listeners are invoked earlier.
 
             <services>
                 <service id="App\EventListener\MyHighPriorityListener" autowire="true">
-                    <tag name="doctrine.event_listener" event="postPersist" priority="10" />
+                    <tag name="doctrine.event_listener" event="postPersist" priority="10"/>
                 </service>
                 <service id="App\EventListener\MyLowPriorityListener" autowire="true">
-                    <tag name="doctrine.event_listener" event="postPersist" priority="1" />
+                    <tag name="doctrine.event_listener" event="postPersist" priority="1"/>
                 </service>
             </services>
         </container>
@@ -282,8 +249,8 @@ numbers mean that listeners are invoked earlier.
     .. code-block:: php
 
         // config/services.php
-        use AppBundle\EventListener\MyHighPriorityListener;
-        use AppBundle\EventListener\MyLowPriorityListener;
+        use App\EventListener\MyHighPriorityListener;
+        use App\EventListener\MyLowPriorityListener;
 
         $container
             ->autowire(MyHighPriorityListener::class)
@@ -297,3 +264,4 @@ numbers mean that listeners are invoked earlier.
 
 .. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
 .. _`the DoctrineBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineBundle/entity-listeners.html
+.. _`DoctrineMongoDBBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineMongoDBBundle/index.html
diff --git a/doctrine/lifecycle_callbacks.rst b/doctrine/lifecycle_callbacks.rst
index 42344c8098d..9b62ae16f74 100644
--- a/doctrine/lifecycle_callbacks.rst
+++ b/doctrine/lifecycle_callbacks.rst
@@ -15,6 +15,9 @@ callbacks. This is not necessary if you're using YAML or XML for your mapping.
 
 .. code-block:: php-annotations
 
+    // src/Entity/Product.php
+    use Doctrine\ORM\Mapping as ORM;
+
     /**
      * @ORM\Entity()
      * @ORM\HasLifecycleCallbacks()
@@ -33,6 +36,7 @@ the current date, only when the entity is first persisted (i.e. inserted):
     .. code-block:: php-annotations
 
         // src/Entity/Product.php
+        use Doctrine\ORM\Mapping as ORM;
 
         /**
          * @ORM\PrePersist
@@ -58,12 +62,12 @@ the current date, only when the entity is first persisted (i.e. inserted):
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="App\Entity\Product">
                 <!-- ... -->
                 <lifecycle-callbacks>
-                    <lifecycle-callback type="prePersist" method="setCreatedAtValue" />
+                    <lifecycle-callback type="prePersist" method="setCreatedAtValue"/>
                 </lifecycle-callbacks>
             </entity>
         </doctrine-mapping>
diff --git a/doctrine/multiple_entity_managers.rst b/doctrine/multiple_entity_managers.rst
index 84867cde69f..4c73ef6f741 100644
--- a/doctrine/multiple_entity_managers.rst
+++ b/doctrine/multiple_entity_managers.rst
@@ -76,9 +76,9 @@ The following configuration code shows how you can configure two entity managers
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:dbal default-connection="default">
diff --git a/doctrine/pdo_session_storage.rst b/doctrine/pdo_session_storage.rst
index e53eb161804..ee6efc80de9 100644
--- a/doctrine/pdo_session_storage.rst
+++ b/doctrine/pdo_session_storage.rst
@@ -28,7 +28,7 @@ To use it, first register a new handler service:
 
                     # If you're using Doctrine & want to re-use that connection, then:
                     # comment-out the above 2 lines and uncomment the line below
-                    # - !service { class: PDO, factory: 'database_connection:getWrappedConnection' }
+                    # - !service { class: PDO, factory: ['@database_connection', 'getWrappedConnection'] }
                     # If you get transaction issues (e.g. after login) uncomment the line below
                     # - { lock_mode: 1 }
 
@@ -40,8 +40,8 @@ To use it, first register a new handler service:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <services>
                 <service id="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler" public="false">
@@ -68,8 +68,8 @@ To use it, first register a new handler service:
 
 .. tip::
 
-    Configure the database credentials as
-    :doc:`parameters defined with environment variables </configuration/external_parameters>`
+    Configure the database credentials
+    :ref:`using environment variables in the config file <config-env-vars>`
     to make your application more secure.
 
 Next, tell Symfony to use your service as the session handler:
@@ -133,7 +133,7 @@ a second array argument to ``PdoSessionHandler``:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler" public="false">
@@ -150,7 +150,6 @@ a second array argument to ``PdoSessionHandler``:
     .. code-block:: php
 
         // config/services.php
-
         use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
         // ...
 
@@ -220,7 +219,7 @@ MySQL
         `sess_data` BLOB NOT NULL,
         `sess_time` INTEGER UNSIGNED NOT NULL,
         `sess_lifetime` MEDIUMINT NOT NULL
-    ) COLLATE utf8_bin, ENGINE = InnoDB;
+    ) COLLATE utf8mb4_bin, ENGINE = InnoDB;
 
 .. note::
 
diff --git a/doctrine/registration_form.rst b/doctrine/registration_form.rst
index 9b6fbea28fb..ff3ee4d4be2 100644
--- a/doctrine/registration_form.rst
+++ b/doctrine/registration_form.rst
@@ -21,7 +21,7 @@ Make sure MakerBundle is installed:
 
 .. code-block:: terminal
 
-    $ composer require symfony/maker-bundle --dev
+    $ composer require --dev symfony/maker-bundle
 
 If you need any other dependencies, MakerBundle will tell you when you run each
 command.
@@ -50,6 +50,7 @@ To easiest way to build your registration form is by using the ``make:registrati
 command:
 
 .. versionadded:: 1.11
+
     The ``make:registration-form`` was introduced in MakerBundle 1.11.0.
 
 .. code-block:: terminal
@@ -76,8 +77,8 @@ The form class for the registration form will look something like this::
     use Symfony\Component\Form\Extension\Core\Type\PasswordType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Validator\Constraints\NotBlank;
     use Symfony\Component\Validator\Constraints\Length;
+    use Symfony\Component\Validator\Constraints\NotBlank;
 
     class RegistrationFormType extends AbstractType
     {
@@ -96,7 +97,7 @@ The form class for the registration form will look something like this::
                         new Length([
                             'min' => 6,
                             'minMessage' => 'Your password should be at least {{ limit }} characters',
-                            'max' => 4096
+                            'max' => 4096,
                         ]),
                     ],
                 ])
@@ -170,7 +171,7 @@ saves the user::
 
                 // do anything else you need here, like send an email
 
-                return $this->redirect('app_homepage');
+                return $this->redirectToRoute('app_homepage');
             }
 
             return $this->render('registration/register.html.twig', [
@@ -184,7 +185,7 @@ register.html.twig
 
 The template renders the form:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {% extends 'base.html.twig' %}
 
@@ -214,22 +215,22 @@ To do this, add a ``termsAccepted`` field to your form, but set its
 
     // src/Form/UserType.php
     // ...
-    use Symfony\Component\Validator\Constraints\IsTrue;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
     use Symfony\Component\Form\Extension\Core\Type\EmailType;
+    use Symfony\Component\Validator\Constraints\IsTrue;
 
     class UserType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
-                ->add('email', EmailType::class);
+                ->add('email', EmailType::class)
                 // ...
                 ->add('termsAccepted', CheckboxType::class, [
                     'mapped' => false,
                     'constraints' => new IsTrue(),
                 ])
-            );
+            ;
         }
     }
 
diff --git a/doctrine/resolve_target_entity.rst b/doctrine/resolve_target_entity.rst
index d6ec5c3ccac..a60dfe3e604 100644
--- a/doctrine/resolve_target_entity.rst
+++ b/doctrine/resolve_target_entity.rst
@@ -40,12 +40,11 @@ brevity) to explain how to set up and use the ``ResolveTargetEntityListener``.
 A Customer entity::
 
     // src/Entity/Customer.php
-
     namespace App\Entity;
 
-    use Doctrine\ORM\Mapping as ORM;
     use Acme\CustomerBundle\Entity\Customer as BaseCustomer;
     use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;
+    use Doctrine\ORM\Mapping as ORM;
 
     /**
      * @ORM\Entity
@@ -60,11 +59,10 @@ A Customer entity::
 An Invoice entity::
 
     // src/Acme/InvoiceBundle/Entity/Invoice.php
-
     namespace Acme\InvoiceBundle\Entity;
 
-    use Doctrine\ORM\Mapping AS ORM;
     use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;
+    use Doctrine\ORM\Mapping as ORM;
 
     /**
      * Represents an Invoice.
@@ -84,7 +82,6 @@ An Invoice entity::
 An InvoiceSubjectInterface::
 
     // src/Acme/InvoiceBundle/Model/InvoiceSubjectInterface.php
-
     namespace Acme\InvoiceBundle\Model;
 
     /**
@@ -128,9 +125,9 @@ about the replacement:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:orm>
diff --git a/doctrine/reverse_engineering.rst b/doctrine/reverse_engineering.rst
index ae446e33140..6b84cb17709 100644
--- a/doctrine/reverse_engineering.rst
+++ b/doctrine/reverse_engineering.rst
@@ -56,7 +56,7 @@ table fields.
 
 .. code-block:: terminal
 
-    $ php bin/console doctrine:mapping:import 'App\Entity' annotation --path=src/Entity
+    $ php bin/console doctrine:mapping:import "App\Entity" annotation --path=src/Entity
 
 This command line tool asks Doctrine to introspect the database and generate
 new PHP classes with annotation metadata into ``src/Entity``. This generates two
@@ -68,7 +68,7 @@ files: ``BlogPost.php`` and ``BlogComment.php``.
 
     .. code-block:: terminal
 
-        $ php bin/console doctrine:mapping:import 'App\Entity' xml --path=config/doctrine
+        $ php bin/console doctrine:mapping:import "App\Entity" xml --path=config/doctrine
 
     In this case, make sure to adapt your mapping configuration accordingly:
 
@@ -94,7 +94,7 @@ The generated PHP classes now have properties and annotation metadata, but they
 do *not* have any getter or setter methods. If you generated XML or YAML metadata,
 you don't even have the PHP classes!
 
-To generate the missing getter/setter methods (or to *create* the classes if neceesary),
+To generate the missing getter/setter methods (or to *create* the classes if necessary),
 run:
 
 .. code-block:: terminal
@@ -111,5 +111,4 @@ run:
 
 The generated entities are now ready to be used. Have fun!
 
-.. _`Doctrine tools documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/tools.html#reverse-engineering
-.. _`doctrine/doctrine#729`: https://github.com/doctrine/DoctrineBundle/issues/729
+.. _`Doctrine tools documentation`: https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/tools.html#reverse-engineering
diff --git a/email.rst b/email.rst
index f588eee0993..5cef4971914 100644
--- a/email.rst
+++ b/email.rst
@@ -1,8 +1,13 @@
 .. index::
    single: Emails
 
-How to Send an Email
-====================
+Swift Mailer
+============
+
+.. note::
+
+    In Symfony 4.3, the :doc:`Mailer </mailer>` component was introduced and can
+    be used instead of Swift Mailer.
 
 Symfony provides a mailer feature based on the popular `Swift Mailer`_ library
 via the `SwiftMailerBundle`_. This mailer supports sending messages with your
@@ -12,7 +17,7 @@ own mail servers as well as using popular email providers like `Mandrill`_,
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the Swift Mailer based mailer before using it:
 
 .. code-block:: terminal
@@ -39,10 +44,15 @@ environment variable in the ``.env`` file:
     # use this to disable email delivery
     MAILER_URL=null://localhost
 
-    # use this to configure a traditional SMTP server (make sure to URL-encode the
-    # values of the username and password if they contain non-alphanumeric characters
-    # such as '+', '@', ':' and '*', which are reserved in URLs)
-    MAILER_URL=smtp://localhost:25?encryption=ssl&auth_mode=login&username=&password=
+    # use this to configure a traditional SMTP server
+    MAILER_URL=smtp://localhost:465?encryption=ssl&auth_mode=login&username=&password=
+
+.. caution::
+
+    If the username, password or host contain any character considered special in a
+    URI (such as ``+``, ``@``, ``$``, ``#``, ``/``, ``:``, ``*``, ``!``), you must
+    encode them. See `RFC 3986`_ for the full list of reserved characters or use the
+    :phpfunction:`urlencode` function to encode them.
 
 Refer to the :doc:`SwiftMailer configuration reference </reference/configuration/swiftmailer>`
 for the detailed explanation of all the available config options.
@@ -68,16 +78,16 @@ sending an email is pretty straightforward::
                 ),
                 'text/html'
             )
-            /*
-             * If you also want to include a plaintext version of the message
+
+            // you can remove the following code if you don't define a text version for your emails
             ->addPart(
                 $this->renderView(
+                    // templates/emails/registration.txt.twig
                     'emails/registration.txt.twig',
                     ['name' => $name]
                 ),
                 'text/plain'
             )
-            */
         ;
 
         $mailer->send($message);
@@ -89,7 +99,7 @@ To keep things decoupled, the email body has been stored in a template and
 rendered with the ``renderView()`` method. The ``registration.html.twig``
 template might look something like this:
 
-.. code-block:: html+jinja
+.. code-block:: html+twig
 
     {# templates/emails/registration.html.twig #}
     <h3>You did it! You registered!</h3>
@@ -122,9 +132,9 @@ setting up a regular SMTP server. To do that, update the ``MAILER_URL`` of your
     # username is your full Gmail or Google Apps email address
     MAILER_URL=gmail://username:password@localhost
 
-The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport,
-``ssl`` encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app
-uses other encryption or auth mode, you must override those values
+The ``gmail`` transport is a shortcut that uses the ``smtp`` transport, ``ssl``
+encryption, ``login`` auth mode and ``smtp.gmail.com`` host. If your app uses
+other encryption or auth mode, you must override those values
 (:doc:`see mailer config reference </reference/configuration/swiftmailer>`):
 
 .. code-block:: bash
@@ -134,7 +144,7 @@ uses other encryption or auth mode, you must override those values
 
 If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
 and use it as the value of the mailer password. You must also ensure that you
-`allow less secure apps to access your Gmail account`_.
+`allow less secure applications to access your Gmail account`_.
 
 Using Cloud Services to Send Emails
 -----------------------------------
@@ -153,16 +163,499 @@ file. For example, for `Amazon SES`_ (Simple Email Service):
 Use the same technique for other mail services, as most of the time there is
 nothing more to it than configuring an SMTP endpoint.
 
-Learn more
-----------
+How to Work with Emails during Development
+------------------------------------------
+
+When developing an application which sends email, you will often
+not want to actually send the email to the specified recipient during
+development. If you are using the SwiftmailerBundle with Symfony, you
+can achieve this through configuration settings without having to make
+any changes to your application's code at all. There are two main choices
+when it comes to handling email during development: (a) disabling the
+sending of email altogether or (b) sending all email to a specific
+address (with optional exceptions).
+
+Disabling Sending
+~~~~~~~~~~~~~~~~~
+
+You can disable sending email by setting the ``disable_delivery`` option to
+``true``, which is the default value used by Symfony in the ``test`` environment
+(email messages will continue to be sent in the other environments):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/test/swiftmailer.yaml
+        swiftmailer:
+            disable_delivery: true
+
+    .. code-block:: xml
+
+        <!-- config/packages/test/swiftmailer.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config disable-delivery="true"/>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/test/swiftmailer.php
+        $container->loadFromExtension('swiftmailer', [
+            'disable_delivery' => "true",
+        ]);
+
+.. _sending-to-a-specified-address:
+
+Sending to a Specified Address(es)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also choose to have all email sent to a specific address or a list of addresses, instead
+of the address actually specified when sending the message. This can be done
+via the ``delivery_addresses`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/dev/swiftmailer.yaml
+        swiftmailer:
+            delivery_addresses: ['dev@example.com']
+
+    .. code-block:: xml
+
+        <!-- config/packages/dev/swiftmailer.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer
+                https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config>
+                <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
+            </swiftmailer:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/dev/swiftmailer.php
+        $container->loadFromExtension('swiftmailer', [
+            'delivery_addresses' => ['dev@example.com'],
+        ]);
+
+Now, suppose you're sending an email to ``recipient@example.com`` in a controller::
+
+    public function index($name, \Swift_Mailer $mailer)
+    {
+        $message = (new \Swift_Message('Hello Email'))
+            ->setFrom('send@example.com')
+            ->setTo('recipient@example.com')
+            ->setBody(
+                $this->renderView(
+                    // templates/hello/email.txt.twig
+                    'hello/email.txt.twig',
+                    ['name' => $name]
+                )
+            )
+        ;
+        $mailer->send($message);
+
+        return $this->render(...);
+    }
+
+In the ``dev`` environment, the email will instead be sent to ``dev@example.com``.
+Swift Mailer will add an extra header to the email, ``X-Swift-To``, containing
+the replaced address, so you can still see who it would have been sent to.
+
+.. note::
+
+    In addition to the ``to`` addresses, this will also stop the email being
+    sent to any ``CC`` and ``BCC`` addresses set for it. Swift Mailer will add
+    additional headers to the email with the overridden addresses in them.
+    These are ``X-Swift-Cc`` and ``X-Swift-Bcc`` for the ``CC`` and ``BCC``
+    addresses respectively.
+
+.. _sending-to-a-specified-address-but-with-exceptions:
+
+Sending to a Specified Address but with Exceptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose you want to have all email redirected to a specific address,
+(like in the above scenario to ``dev@example.com``). But then you may want
+email sent to some specific email addresses to go through after all, and
+not be redirected (even if it is in the dev environment). This can be done
+by adding the ``delivery_whitelist`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/dev/swiftmailer.yaml
+        swiftmailer:
+            delivery_addresses: ['dev@example.com']
+            delivery_whitelist:
+                # all email addresses matching these regexes will be delivered
+                # like normal, as well as being sent to dev@example.com
+                - '/@specialdomain\.com$/'
+                - '/^admin@mydomain\.com$/'
+
+    .. code-block:: xml
+
+        <!-- config/packages/dev/swiftmailer.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer
+                https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config>
+                <!-- all email addresses matching these regexes will be delivered
+                     like normal, as well as being sent to dev@example.com -->
+                <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
+                <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
+                <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
+            </swiftmailer:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/dev/swiftmailer.php
+        $container->loadFromExtension('swiftmailer', [
+            'delivery_addresses' => ["dev@example.com"],
+            'delivery_whitelist' => [
+                // all email addresses matching these regexes will be delivered
+                // like normal, as well as being sent to dev@example.com
+                '/@specialdomain\.com$/',
+                '/^admin@mydomain\.com$/',
+            ],
+        ]);
+
+In the above example all email messages will be redirected to ``dev@example.com``
+and messages sent to the ``admin@mydomain.com`` address or to any email address
+belonging to the domain ``specialdomain.com`` will also be delivered as normal.
+
+.. caution::
+
+    The ``delivery_whitelist`` option is ignored unless the ``delivery_addresses`` option is defined.
+
+Viewing from the Web Debug Toolbar
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can view any email sent during a single response when you are in the
+``dev`` environment using the web debug toolbar. The email icon in the toolbar
+will show how many emails were sent. If you click it, a report will open
+showing the details of the sent emails.
+
+If you're sending an email and then immediately redirecting to another page,
+the web debug toolbar will not display an email icon or a report on the next
+page.
+
+Instead, you can set the ``intercept_redirects`` option to ``true`` in the
+``dev`` environment, which will cause the redirect to stop and allow you to open
+the report with details of the sent emails.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/dev/web_profiler.yaml
+        web_profiler:
+            intercept_redirects: true
+
+    .. code-block:: xml
+
+        <!-- config/packages/dev/web_profiler.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:webprofiler="http://symfony.com/schema/dic/webprofiler"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/webprofiler
+                https://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd">
+
+            <webprofiler:config
+                intercept-redirects="true"
+            />
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/dev/web_profiler.php
+        $container->loadFromExtension('web_profiler', [
+            'intercept_redirects' => 'true',
+        ]);
+
+.. tip::
+
+    Alternatively, you can open the profiler after the redirect and search
+    by the submit URL used on the previous request (e.g. ``/contact/handle``).
+    The profiler's search feature allows you to load the profiler information
+    for any past requests.
+
+.. tip::
+
+    In addition to the features provided by Symfony, there are applications that
+    can help you test emails during application development, like `MailCatcher`_
+    and `MailHog`_.
+
+How to Spool Emails
+-------------------
+
+The default behavior of the Symfony mailer is to send the email messages
+immediately. You may, however, want to avoid the performance hit of the
+communication to the email server, which could cause the user to wait for the
+next page to load while the email is sending. This can be avoided by choosing to
+"spool" the emails instead of sending them directly.
+
+This makes the mailer to not attempt to send the email message but instead save
+it somewhere such as a file. Another process can then read from the spool and
+take care of sending the emails in the spool. Currently only spooling to file or
+memory is supported.
+
+.. _email-spool-memory:
+
+Spool Using Memory
+~~~~~~~~~~~~~~~~~~
+
+When you use spooling to store the emails to memory, they will get sent right
+before the kernel terminates. This means the email only gets sent if the whole
+request got executed without any unhandled exception or any errors. To configure
+this spool, use the following configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/swiftmailer.yaml
+        swiftmailer:
+            # ...
+            spool: { type: memory }
+
+    .. code-block:: xml
+
+        <!-- config/packages/swiftmailer.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config>
+                <swiftmailer:spool type="memory"/>
+            </swiftmailer:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/swiftmailer.php
+        $container->loadFromExtension('swiftmailer', [
+            // ...
+            'spool' => ['type' => 'memory'],
+        ]);
+
+.. _spool-using-a-file:
+
+Spool Using Files
+~~~~~~~~~~~~~~~~~
+
+When you use the filesystem for spooling, Symfony creates a folder in the given
+path for each mail service (e.g. "default" for the default service). This folder
+will contain files for each email in the spool. So make sure this directory is
+writable by Symfony (or your webserver/php)!
+
+In order to use the spool with files, use the following configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/swiftmailer.yaml
+        swiftmailer:
+            # ...
+            spool:
+                type: file
+                path: /path/to/spooldir
+
+    .. code-block:: xml
+
+        <!-- config/packages/swiftmailer.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <swiftmailer:config>
+                <swiftmailer:spool
+                    type="file"
+                    path="/path/to/spooldir"
+                />
+            </swiftmailer:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/swiftmailer.php
+        $container->loadFromExtension('swiftmailer', [
+            // ...
+
+            'spool' => [
+                'type' => 'file',
+                'path' => '/path/to/spooldir',
+            ],
+        ]);
+
+.. tip::
+
+    If you want to store the spool somewhere with your project directory,
+    remember that you can use the ``%kernel.project_dir%`` parameter to reference
+    the project's root:
+
+    .. code-block:: yaml
+
+        path: '%kernel.project_dir%/var/spool'
+
+Now, when your app sends an email, it will not actually be sent but instead
+added to the spool. Sending the messages from the spool is done separately.
+There is a console command to send the messages in the spool:
+
+.. code-block:: terminal
+
+    $ APP_ENV=prod php bin/console swiftmailer:spool:send
+
+It has an option to limit the number of messages to be sent:
+
+.. code-block:: terminal
+
+    $ APP_ENV=prod php bin/console swiftmailer:spool:send --message-limit=10
+
+You can also set the time limit in seconds:
+
+.. code-block:: terminal
+
+    $ APP_ENV=prod php bin/console swiftmailer:spool:send --time-limit=10
+
+In practice you will not want to run this manually. Instead, the console command
+should be triggered by a cron job or scheduled task and run at a regular
+interval.
+
+.. caution::
+
+    When you create a message with SwiftMailer, it generates a ``Swift_Message``
+    class. If the ``swiftmailer`` service is lazy loaded, it generates instead a
+    proxy class named ``Swift_Message_<someRandomCharacters>``.
+
+    If you use the memory spool, this change is transparent and has no impact.
+    But when using the filesystem spool, the message class is serialized in
+    a file with the randomized class name. The problem is that this random
+    class name changes on every cache clear. So if you send a mail and then you
+    clear the cache, the message will not be unserializable.
+
+    On the next execution of ``swiftmailer:spool:send`` an error will raise because
+    the class ``Swift_Message_<someRandomCharacters>`` doesn't exist (anymore).
+
+    The solutions are either to use the memory spool or to load the
+    ``swiftmailer`` service without the ``lazy`` option (see :doc:`/service_container/lazy_services`).
+
+How to Test that an Email is Sent in a Functional Test
+------------------------------------------------------
+
+Sending emails with Symfony is pretty straightforward thanks to the
+SwiftmailerBundle, which leverages the power of the `Swift Mailer`_ library.
+
+To functionally test that an email was sent, and even assert the email subject,
+content or any other headers, you can use :doc:`the Symfony Profiler </profiler>`.
+
+Start with a controller action that sends an email::
+
+    public function sendEmail($name, \Swift_Mailer $mailer)
+    {
+        $message = (new \Swift_Message('Hello Email'))
+            ->setFrom('send@example.com')
+            ->setTo('recipient@example.com')
+            ->setBody('You should see me from the profiler!')
+        ;
+
+        $mailer->send($message);
+
+        // ...
+    }
+
+In your functional test, use the ``swiftmailer`` collector on the profiler
+to get information about the messages sent on the previous request::
+
+    // tests/Controller/MailControllerTest.php
+    namespace App\Tests\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+
+    class MailControllerTest extends WebTestCase
+    {
+        public function testMailIsSentAndContentIsOk()
+        {
+            $client = static::createClient();
+
+            // enables the profiler for the next request (it does nothing if the profiler is not available)
+            $client->enableProfiler();
+
+            $crawler = $client->request('POST', '/path/to/above/action');
+
+            $mailCollector = $client->getProfile()->getCollector('swiftmailer');
+
+            // checks that an email was sent
+            $this->assertSame(1, $mailCollector->getMessageCount());
+
+            $collectedMessages = $mailCollector->getMessages();
+            $message = $collectedMessages[0];
+
+            // Asserting email data
+            $this->assertInstanceOf('Swift_Message', $message);
+            $this->assertSame('Hello Email', $message->getSubject());
+            $this->assertSame('send@example.com', key($message->getFrom()));
+            $this->assertSame('recipient@example.com', key($message->getTo()));
+            $this->assertSame(
+                'You should see me from the profiler!',
+                $message->getBody()
+            );
+        }
+    }
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+Problem: The Collector Object Is ``null``
+.........................................
+
+The email collector is only available when the profiler is enabled and collects
+information, as explained in :doc:`/testing/profiling`.
 
-.. toctree::
-    :maxdepth: 1
+Problem: The Collector Doesn't Contain the Email
+................................................
 
-    email/dev_environment
-    email/spool
-    email/testing
+If a redirection is performed after sending the email (for example when you send
+an email after a form is processed and before redirecting to another page), make
+sure that the test client doesn't follow the redirects, as explained in
+:doc:`/testing`. Otherwise, the collector will contain the information of the
+redirected page and the email won't be accessible.
 
+.. _`MailCatcher`: https://github.com/sj26/mailcatcher
+.. _`MailHog`: https://github.com/mailhog/MailHog
 .. _`Swift Mailer`: http://swiftmailer.org/
 .. _`SwiftMailerBundle`: https://github.com/symfony/swiftmailer-bundle
 .. _`Creating Messages`: https://swiftmailer.symfony.com/docs/messages.html
@@ -170,4 +663,5 @@ Learn more
 .. _`SendGrid`: https://sendgrid.com/
 .. _`Amazon SES`: http://aws.amazon.com/ses/
 .. _`generate an App password`: https://support.google.com/accounts/answer/185833
-.. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255
+.. _`allow less secure applications to access your Gmail account`: https://support.google.com/accounts/answer/6010255
+.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt
diff --git a/email/dev_environment.rst b/email/dev_environment.rst
deleted file mode 100644
index 15c440dbe22..00000000000
--- a/email/dev_environment.rst
+++ /dev/null
@@ -1,252 +0,0 @@
-.. index::
-   single: Emails; In development
-
-How to Work with Emails during Development
-==========================================
-
-When developing an application which sends email, you will often
-not want to actually send the email to the specified recipient during
-development. If you are using the default Symfony mailer, you
-can achieve this through configuration settings without having to
-make any changes to your application's code at all. There are two main
-choices when it comes to handling email during development: (a) disabling the
-sending of email altogether or (b) sending all email to a specific
-address (with optional exceptions).
-
-Disabling Sending
------------------
-
-You can disable sending email by setting the ``disable_delivery`` option to
-``true``, which is the default value used by Symfony in the ``test`` environment
-(email messages will continue to be sent in the other environments):
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/test/swiftmailer.yaml
-        swiftmailer:
-            disable_delivery: true
-
-    .. code-block:: xml
-
-        <!-- config/packages/test/swiftmailer.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
-            <swiftmailer:config disable-delivery="true" />
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/test/swiftmailer.php
-        $container->loadFromExtension('swiftmailer', [
-            'disable_delivery' => "true",
-        ]);
-
-.. _sending-to-a-specified-address:
-
-Sending to a Specified Address(es)
-----------------------------------
-
-You can also choose to have all email sent to a specific address or a list of addresses, instead
-of the address actually specified when sending the message. This can be done
-via the ``delivery_addresses`` option:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/dev/swiftmailer.yaml
-        swiftmailer:
-            delivery_addresses: ['dev@example.com']
-
-    .. code-block:: xml
-
-        <!-- config/packages/dev/swiftmailer.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer
-                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
-            <swiftmailer:config>
-                <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
-            </swiftmailer:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/dev/swiftmailer.php
-        $container->loadFromExtension('swiftmailer', [
-            'delivery_addresses' => ['dev@example.com'],
-        ]);
-
-Now, suppose you're sending an email to ``recipient@example.com`` in a controller::
-
-    public function index($name, \Swift_Mailer $mailer)
-    {
-        $message = (new \Swift_Message('Hello Email'))
-            ->setFrom('send@example.com')
-            ->setTo('recipient@example.com')
-            ->setBody(
-                $this->renderView(
-                    'HelloBundle:Hello:email.txt.twig',
-                    ['name' => $name]
-                )
-            )
-        ;
-        $mailer->send($message);
-
-        return $this->render(...);
-    }
-
-In the ``dev`` environment, the email will instead be sent to ``dev@example.com``.
-Swift Mailer will add an extra header to the email, ``X-Swift-To``, containing
-the replaced address, so you can still see who it would have been sent to.
-
-.. note::
-
-    In addition to the ``to`` addresses, this will also stop the email being
-    sent to any ``CC`` and ``BCC`` addresses set for it. Swift Mailer will add
-    additional headers to the email with the overridden addresses in them.
-    These are ``X-Swift-Cc`` and ``X-Swift-Bcc`` for the ``CC`` and ``BCC``
-    addresses respectively.
-
-.. _sending-to-a-specified-address-but-with-exceptions:
-
-Sending to a Specified Address but with Exceptions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Suppose you want to have all email redirected to a specific address,
-(like in the above scenario to ``dev@example.com``). But then you may want
-email sent to some specific email addresses to go through after all, and
-not be redirected (even if it is in the dev environment). This can be done
-by adding the ``delivery_whitelist`` option:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/dev/swiftmailer.yaml
-        swiftmailer:
-            delivery_addresses: ['dev@example.com']
-            delivery_whitelist:
-               # all email addresses matching these regexes will be delivered
-               # like normal, as well as being sent to dev@example.com
-               - '/@specialdomain\.com$/'
-               - '/^admin@mydomain\.com$/'
-
-    .. code-block:: xml
-
-        <!-- config/packages/dev/swiftmailer.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer
-                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
-            <swiftmailer:config>
-                <!-- all email addresses matching these regexes will be delivered
-                     like normal, as well as being sent to dev@example.com -->
-                <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
-                <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
-                <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
-            </swiftmailer:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/dev/swiftmailer.php
-        $container->loadFromExtension('swiftmailer', [
-            'delivery_addresses' => ["dev@example.com"],
-            'delivery_whitelist' => [
-                // all email addresses matching these regexes will be delivered
-                // like normal, as well as being sent to dev@example.com
-                '/@specialdomain\.com$/',
-                '/^admin@mydomain\.com$/',
-            ],
-        ]);
-
-In the above example all email messages will be redirected to ``dev@example.com``
-and messages sent to the ``admin@mydomain.com`` address or to any email address
-belonging to the domain ``specialdomain.com`` will also be delivered as normal.
-
-.. caution::
-
-    The ``delivery_whitelist`` option is ignored unless the ``delivery_addresses`` option is defined.
-
-Viewing from the Web Debug Toolbar
-----------------------------------
-
-You can view any email sent during a single response when you are in the
-``dev`` environment using the web debug toolbar. The email icon in the toolbar
-will show how many emails were sent. If you click it, a report will open
-showing the details of the sent emails.
-
-If you're sending an email and then immediately redirecting to another page,
-the web debug toolbar will not display an email icon or a report on the next
-page.
-
-Instead, you can set the ``intercept_redirects`` option to ``true`` in the
-``dev`` environment, which will cause the redirect to stop and allow you to open
-the report with details of the sent emails.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/dev/web_profiler.yaml
-        web_profiler:
-            intercept_redirects: true
-
-    .. code-block:: xml
-
-        <!-- config/packages/dev/web_profiler.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:webprofiler="http://symfony.com/schema/dic/webprofiler"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/webprofiler
-                http://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd">
-
-            <webprofiler:config
-                intercept-redirects="true"
-            />
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/dev/web_profiler.php
-        $container->loadFromExtension('web_profiler', [
-            'intercept_redirects' => 'true',
-        ]);
-
-.. tip::
-
-    Alternatively, you can open the profiler after the redirect and search
-    by the submit URL used on the previous request (e.g. ``/contact/handle``).
-    The profiler's search feature allows you to load the profiler information
-    for any past requests.
-
-.. tip::
-
-    In addition to the features provided by Symfony, there are applications that
-    can help you test emails during application development, like `MailCatcher`_
-    and `MailHog`_.
-
-.. _`MailCatcher`: https://github.com/sj26/mailcatcher
-.. _`MailHog`: https://github.com/mailhog/MailHog
diff --git a/email/spool.rst b/email/spool.rst
deleted file mode 100644
index 695242a1d52..00000000000
--- a/email/spool.rst
+++ /dev/null
@@ -1,164 +0,0 @@
-.. index::
-   single: Emails; Spooling
-
-How to Spool Emails
-===================
-
-The default behavior of the Symfony mailer is to send the email messages
-immediately. You may, however, want to avoid the performance hit of the
-communication to the email server, which could cause the user to wait for the
-next page to load while the email is sending. This can be avoided by choosing to
-"spool" the emails instead of sending them directly.
-
-This makes the mailer to not attempt to send the email message but instead save
-it somewhere such as a file. Another process can then read from the spool and
-take care of sending the emails in the spool. Currently only spooling to file or
-memory is supported.
-
-.. _email-spool-memory:
-
-Spool Using Memory
-------------------
-
-When you use spooling to store the emails to memory, they will get sent right
-before the kernel terminates. This means the email only gets sent if the whole
-request got executed without any unhandled exception or any errors. To configure
-this spool, use the following configuration:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/swiftmailer.yaml
-        swiftmailer:
-            # ...
-            spool: { type: memory }
-
-    .. code-block:: xml
-
-        <!-- config/packages/swiftmailer.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
-            <swiftmailer:config>
-                <swiftmailer:spool type="memory" />
-            </swiftmailer:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/swiftmailer.php
-        $container->loadFromExtension('swiftmailer', [
-             // ...
-            'spool' => ['type' => 'memory'],
-        ]);
-
-.. _spool-using-a-file:
-
-Spool Using Files
-------------------
-
-When you use the filesystem for spooling, Symfony creates a folder in the given
-path for each mail service (e.g. "default" for the default service). This folder
-will contain files for each email in the spool. So make sure this directory is
-writable by Symfony (or your webserver/php)!
-
-In order to use the spool with files, use the following configuration:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/swiftmailer.yaml
-        swiftmailer:
-            # ...
-            spool:
-                type: file
-                path: /path/to/spooldir
-
-    .. code-block:: xml
-
-        <!-- config/packages/swiftmailer.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
-
-            <swiftmailer:config>
-                <swiftmailer:spool
-                    type="file"
-                    path="/path/to/spooldir"
-                />
-            </swiftmailer:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/swiftmailer.php
-        $container->loadFromExtension('swiftmailer', [
-             // ...
-
-            'spool' => [
-                'type' => 'file',
-                'path' => '/path/to/spooldir',
-            ],
-        ]);
-
-.. tip::
-
-    If you want to store the spool somewhere with your project directory,
-    remember that you can use the ``%kernel.project_dir%`` parameter to reference
-    the project's root:
-
-    .. code-block:: yaml
-
-        path: '%kernel.project_dir%/var/spool'
-
-Now, when your app sends an email, it will not actually be sent but instead
-added to the spool. Sending the messages from the spool is done separately.
-There is a console command to send the messages in the spool:
-
-.. code-block:: terminal
-
-    $ php bin/console swiftmailer:spool:send --env=prod
-
-It has an option to limit the number of messages to be sent:
-
-.. code-block:: terminal
-
-    $ php bin/console swiftmailer:spool:send --message-limit=10 --env=prod
-
-You can also set the time limit in seconds:
-
-.. code-block:: terminal
-
-    $ php bin/console swiftmailer:spool:send --time-limit=10 --env=prod
-
-You will most likely not want to run this command manually in reality. Instead, the
-console command should be triggered by a cron job or scheduled task and run
-at a regular interval.
-
-.. caution::
-
-    When you create a message with SwiftMailer, it generates a ``Swift_Message``
-    class. If the ``swiftmailer`` service is lazy loaded, it generates instead a
-    proxy class named ``Swift_Message_<someRandomCharacters>``.
-
-    If you use the memory spool, this change is transparent and has no impact.
-    But when using the filesystem spool, the message class is serialized in
-    a file with the randomized class name. The problem is that this random
-    class name changes on every cache clear. So if you send a mail and then you
-    clear the cache, the message will not be unserializable.
-
-    On the next execution of ``swiftmailer:spool:send`` an error will raise because
-    the class ``Swift_Message_<someRandomCharacters>`` doesn't exist (anymore).
-
-    The solutions are either to use the memory spool or to load the
-    ``swiftmailer`` service without the ``lazy`` option (see :doc:`/service_container/lazy_services`).
diff --git a/email/testing.rst b/email/testing.rst
deleted file mode 100644
index 1da89c7315b..00000000000
--- a/email/testing.rst
+++ /dev/null
@@ -1,85 +0,0 @@
-.. index::
-   single: Emails; Testing
-
-How to Test that an Email is Sent in a Functional Test
-======================================================
-
-Sending emails with Symfony is pretty straightforward thanks to the
-SwiftmailerBundle, which leverages the power of the `Swift Mailer`_ library.
-
-To functionally test that an email was sent, and even assert the email subject,
-content or any other headers, you can use :doc:`the Symfony Profiler </profiler>`.
-
-Start with a simple controller action that sends an email::
-
-    public function sendEmail($name, \Swift_Mailer $mailer)
-    {
-        $message = (new \Swift_Message('Hello Email'))
-            ->setFrom('send@example.com')
-            ->setTo('recipient@example.com')
-            ->setBody('You should see me from the profiler!')
-        ;
-
-        $mailer->send($message);
-
-        return $this->render(...);
-    }
-
-In your functional test, use the ``swiftmailer`` collector on the profiler
-to get information about the messages sent on the previous request::
-
-    // tests/Controller/MailControllerTest.php
-    namespace App\Tests\Controller;
-
-    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
-
-    class MailControllerTest extends WebTestCase
-    {
-        public function testMailIsSentAndContentIsOk()
-        {
-            $client = static::createClient();
-
-            // enables the profiler for the next request (it does nothing if the profiler is not available)
-            $client->enableProfiler();
-
-            $crawler = $client->request('POST', '/path/to/above/action');
-
-            $mailCollector = $client->getProfile()->getCollector('swiftmailer');
-
-            // checks that an email was sent
-            $this->assertSame(1, $mailCollector->getMessageCount());
-
-            $collectedMessages = $mailCollector->getMessages();
-            $message = $collectedMessages[0];
-
-            // Asserting email data
-            $this->assertInstanceOf('Swift_Message', $message);
-            $this->assertSame('Hello Email', $message->getSubject());
-            $this->assertSame('send@example.com', key($message->getFrom()));
-            $this->assertSame('recipient@example.com', key($message->getTo()));
-            $this->assertSame(
-                'You should see me from the profiler!',
-                $message->getBody()
-            );
-        }
-    }
-
-Troubleshooting
----------------
-
-Problem: The Collector Object Is ``null``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The email collector is only available when the profiler is enabled and collects
-information, as explained in :doc:`/testing/profiling`.
-
-Problem: The Collector Doesn't Contain the Email
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If a redirection is performed after sending the email (for example when you send
-an email after a form is processed and before redirecting to another page), make
-sure that the test client doesn't follow the redirects, as explained in
-:doc:`/testing`. Otherwise, the collector will contain the information of the
-redirected page and the email won't be accessible.
-
-.. _`Swift Mailer`: http://swiftmailer.org/
diff --git a/event_dispatcher.rst b/event_dispatcher.rst
index 276f9d7fec4..9ba1850d58d 100644
--- a/event_dispatcher.rst
+++ b/event_dispatcher.rst
@@ -26,13 +26,13 @@ The most common way to listen to an event is to register an **event listener**::
     // src/EventListener/ExceptionListener.php
     namespace App\EventListener;
 
-    use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\ExceptionEvent;
     use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
 
     class ExceptionListener
     {
-        public function onKernelException(GetResponseForExceptionEvent $event)
+        public function onKernelException(ExceptionEvent $event)
         {
             // You get the exception object from the received event
             $exception = $event->getException();
@@ -63,10 +63,16 @@ The most common way to listen to an event is to register an **event listener**::
 .. tip::
 
     Each event receives a slightly different type of ``$event`` object. For
-    the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`.
+    the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`.
     Check out the :doc:`Symfony events reference </reference/events>` to see
     what type of object each event provides.
 
+.. versionadded:: 4.3
+
+    The :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent` class was
+    introduced in Symfony 4.3. In previous versions it was called
+    ``Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent``.
+
 Now that the class is created, you need to register it as a service and
 notify Symfony that it is a "listener" on the ``kernel.exception`` event by
 using a special "tag":
@@ -88,11 +94,11 @@ using a special "tag":
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\EventListener\ExceptionListener">
-                    <tag name="kernel.event_listener" event="kernel.exception" />
+                    <tag name="kernel.event_listener" event="kernel.exception"/>
                 </service>
             </services>
         </container>
@@ -119,10 +125,6 @@ listener class:
    method (which makes event listeners invokable);
 #. If the ``_invoke()`` method is not defined either, throw an exception.
 
-.. versionadded:: 4.1
-    The support of the ``__invoke()`` method to create invokable event listeners
-    was introduced in Symfony 4.1.
-
 .. note::
 
     There is an optional attribute for the ``kernel.event_listener`` tag called
@@ -155,7 +157,7 @@ listen to the same ``kernel.exception`` event::
     namespace App\EventSubscriber;
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-    use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
+    use Symfony\Component\HttpKernel\Event\ExceptionEvent;
     use Symfony\Component\HttpKernel\KernelEvents;
 
     class ExceptionSubscriber implements EventSubscriberInterface
@@ -164,25 +166,25 @@ listen to the same ``kernel.exception`` event::
         {
             // return the subscribed events, their methods and priorities
             return [
-               KernelEvents::EXCEPTION => [
-                   ['processException', 10],
-                   ['logException', 0],
-                   ['notifyException', -10],
-               ]
+                KernelEvents::EXCEPTION => [
+                    ['processException', 10],
+                    ['logException', 0],
+                    ['notifyException', -10],
+                ],
             ];
         }
 
-        public function processException(GetResponseForExceptionEvent $event)
+        public function processException(ExceptionEvent $event)
         {
             // ...
         }
 
-        public function logException(GetResponseForExceptionEvent $event)
+        public function logException(ExceptionEvent $event)
         {
             // ...
         }
 
-        public function notifyException(GetResponseForExceptionEvent $event)
+        public function notifyException(ExceptionEvent $event)
         {
             // ...
         }
@@ -211,11 +213,11 @@ or a "sub request"::
     // src/EventListener/RequestListener.php
     namespace App\EventListener;
 
-    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+    use Symfony\Component\HttpKernel\Event\RequestEvent;
 
     class RequestListener
     {
-        public function onKernelRequest(GetResponseEvent $event)
+        public function onKernelRequest(RequestEvent $event)
         {
             if (!$event->isMasterRequest()) {
                 // don't do anything if it's not the master request
diff --git a/event_dispatcher/before_after_filters.rst b/event_dispatcher/before_after_filters.rst
index 1353a2d8595..4202918ba92 100644
--- a/event_dispatcher/before_after_filters.rst
+++ b/event_dispatcher/before_after_filters.rst
@@ -52,7 +52,7 @@ First, define some token configuration as parameters:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <parameters>
                 <parameter key="tokens" type="collection">
@@ -114,9 +114,9 @@ event subscribers, you can learn more about them at :doc:`/event_dispatcher`::
     namespace App\EventSubscriber;
 
     use App\Controller\TokenAuthenticatedController;
-    use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
-    use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpKernel\Event\ControllerEvent;
+    use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
     use Symfony\Component\HttpKernel\KernelEvents;
 
     class TokenSubscriber implements EventSubscriberInterface
@@ -128,7 +128,7 @@ event subscribers, you can learn more about them at :doc:`/event_dispatcher`::
             $this->tokens = $tokens;
         }
 
-        public function onKernelController(FilterControllerEvent $event)
+        public function onKernelController(ControllerEvent $event)
         {
             $controller = $event->getController();
 
@@ -188,7 +188,7 @@ For example, take the ``TokenSubscriber`` from the previous example and first
 record the authentication token inside the request attributes. This will
 serve as a basic flag that this request underwent token authentication::
 
-    public function onKernelController(FilterControllerEvent $event)
+    public function onKernelController(ControllerEvent $event)
     {
         // ...
 
@@ -208,9 +208,9 @@ This will look for the ``auth_token`` flag on the request object and set a custo
 header on the response if it's found::
 
     // add the new use statement at the top of your file
-    use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
+    use Symfony\Component\HttpKernel\Event\ResponseEvent;
 
-    public function onKernelResponse(FilterResponseEvent $event)
+    public function onKernelResponse(ResponseEvent $event)
     {
         // check to see if onKernelController marked this as a token "auth'ed" request
         if (!$token = $event->getRequest()->attributes->get('auth_token')) {
diff --git a/event_dispatcher/method_behavior.rst b/event_dispatcher/method_behavior.rst
index b7d16962bd9..7d93d074353 100644
--- a/event_dispatcher/method_behavior.rst
+++ b/event_dispatcher/method_behavior.rst
@@ -19,7 +19,7 @@ method::
         {
             // dispatch an event before the method
             $event = new BeforeSendMailEvent($subject, $message);
-            $this->dispatcher->dispatch('mailer.pre_send', $event);
+            $this->dispatcher->dispatch($event, 'mailer.pre_send');
 
             // get $foo and $bar from the event, they may have been modified
             $subject = $event->getSubject();
@@ -30,7 +30,7 @@ method::
 
             // do something after the method
             $event = new AfterSendMailEvent($returnValue);
-            $this->dispatcher->dispatch('mailer.post_send', $event);
+            $this->dispatcher->dispatch($event, 'mailer.post_send');
 
             return $event->getReturnValue();
         }
@@ -44,7 +44,7 @@ events. For example, ``BeforeSendMailEvent`` might look like this::
     // src/Event/BeforeSendMailEvent.php
     namespace App\Event;
 
-    use Symfony\Component\EventDispatcher\Event;
+    use Symfony\Contracts\EventDispatcher\Event;
 
     class BeforeSendMailEvent extends Event
     {
@@ -83,7 +83,7 @@ And the ``AfterSendMailEvent`` even like this::
     // src/Event/AfterSendMailEvent.php
     namespace App\Event;
 
-    use Symfony\Component\EventDispatcher\Event;
+    use Symfony\Contracts\EventDispatcher\Event;
 
     class AfterSendMailEvent extends Event
     {
@@ -114,8 +114,8 @@ could listen to the ``mailer.post_send`` event and change the method's return va
     // src/EventSubscriber/MailPostSendSubscriber.php
     namespace App\EventSubscriber;
 
-    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use App\Event\AfterSendMailEvent;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
     class MailPostSendSubscriber implements EventSubscriberInterface
     {
diff --git a/form/action_method.rst b/form/action_method.rst
deleted file mode 100644
index 64067720898..00000000000
--- a/form/action_method.rst
+++ /dev/null
@@ -1,132 +0,0 @@
-.. index::
-    single: Forms; Changing the action and method
-
-How to Change the Action and Method of a Form
-=============================================
-
-By default, a form will be submitted via an HTTP POST request to the same
-URL under which the form was rendered. Sometimes you want to change these
-parameters. You can do so in a few different ways.
-
-If you use the :class:`Symfony\\Component\\Form\\FormBuilder` to build your
-form, you can use ``setAction()`` and ``setMethod()``:
-
-.. configuration-block::
-
-    .. code-block:: php-symfony
-
-        // src/Controller/DefaultController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Form\Extension\Core\Type\DateType;
-        use Symfony\Component\Form\Extension\Core\Type\SubmitType;
-        use Symfony\Component\Form\Extension\Core\Type\TextType;
-
-        class DefaultController extends AbstractController
-        {
-            public function new()
-            {
-                // ...
-
-                $form = $this->createFormBuilder($task)
-                    ->setAction($this->generateUrl('target_route'))
-                    ->setMethod('GET')
-                    ->add('task', TextType::class)
-                    ->add('dueDate', DateType::class)
-                    ->add('save', SubmitType::class)
-                    ->getForm();
-
-                // ...
-            }
-        }
-
-    .. code-block:: php-standalone
-
-        use Symfony\Component\Form\Forms;
-        use Symfony\Component\Form\Extension\Core\Type\DateType;
-        use Symfony\Component\Form\Extension\Core\Type\FormType;
-        use Symfony\Component\Form\Extension\Core\Type\SubmitType;
-        use Symfony\Component\Form\Extension\Core\Type\TextType;
-
-        // ...
-
-        $formFactoryBuilder = Forms::createFormFactoryBuilder();
-
-        // Form factory builder configuration ...
-
-        $formFactory = $formFactoryBuilder->getFormFactory();
-
-        $form = $formFactory->createBuilder(FormType::class, $task)
-            ->setAction('...')
-            ->setMethod('GET')
-            ->add('task', TextType::class)
-            ->add('dueDate', DateType::class)
-            ->add('save', SubmitType::class)
-            ->getForm();
-
-.. note::
-
-    This example assumes that you've created a route called ``target_route``
-    that points to the controller that processes the form.
-
-When using a form type class, you can pass the action and method as form
-options:
-
-.. configuration-block::
-
-    .. code-block:: php-symfony
-
-        // src/Controller/DefaultController.php
-        namespace App\Controller;
-
-        use App\Form\TaskType;
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-
-        class DefaultController extends AbstractController
-        {
-            public function new()
-            {
-                // ...
-
-                $form = $this->createForm(TaskType::class, $task, [
-                    'action' => $this->generateUrl('target_route'),
-                    'method' => 'GET',
-                ]);
-
-                // ...
-            }
-        }
-
-    .. code-block:: php-standalone
-
-        use App\Form\TaskType;
-        use Symfony\Component\Form\Forms;
-
-        $formFactoryBuilder = Forms::createFormFactoryBuilder();
-
-        // Form factory builder configuration ...
-
-        $formFactory = $formFactoryBuilder->getFormFactory();
-
-        $form = $formFactory->create(TaskType::class, $task, [
-            'action' => '...',
-            'method' => 'GET',
-        ]);
-
-Finally, you can override the action and method in the template by passing them
-to the ``form()`` or the ``form_start()`` helper functions:
-
-.. code-block:: html+twig
-
-    {# templates/default/new.html.twig #}
-    {{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}
-
-.. note::
-
-    If the form's method is not GET or POST, but PUT, PATCH or DELETE, Symfony
-    will insert a hidden field with the name ``_method`` that stores this method.
-    The form will be submitted in a normal POST request, but Symfony's router
-    is capable of detecting the ``_method`` parameter and will interpret it as
-    a PUT, PATCH or DELETE request. See the :ref:`configuration-framework-http_method_override`
-    option.
diff --git a/form/bootstrap4.rst b/form/bootstrap4.rst
index ce2e7ca860d..330ed2a165e 100644
--- a/form/bootstrap4.rst
+++ b/form/bootstrap4.rst
@@ -42,9 +42,9 @@ configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <twig:form-theme>bootstrap_4_layout.html.twig</twig:form-theme>
@@ -66,7 +66,7 @@ configuration:
 If you prefer to apply the Bootstrap styles on a form to form basis, include the
 ``form_theme`` tag in the templates where those forms are used:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {# ... #}
     {# this tag only applies to the forms defined in this template #}
@@ -95,7 +95,7 @@ Bootstrap 4 has a feature called "`custom forms`_". You can enable that on your
 Symfony Form ``RadioType`` and ``CheckboxType`` by adding a class called ``radio-custom``
 and ``checkbox-custom`` respectively.
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ form_row(form.myRadio, {label_attr: {class: 'radio-custom'} }) }}
     {{ form_row(form.myCheckbox, {label_attr: {class: 'checkbox-custom'} }) }}
@@ -111,6 +111,5 @@ Form errors are rendered **inside** the ``<label>`` element to make sure there
 is a strong connection between the error and its ``<input>``, as required by the
 `WCAG 2.0 standard`_.
 
-.. _`their documentation`: https://getbootstrap.com/docs/4.1/
 .. _`WCAG 2.0 standard`: https://www.w3.org/TR/WCAG20/
 .. _`custom forms`: https://getbootstrap.com/docs/4.1/components/forms/#custom-forms
diff --git a/form/create_custom_field_type.rst b/form/create_custom_field_type.rst
index cbe88040737..cc9ffe65df1 100644
--- a/form/create_custom_field_type.rst
+++ b/form/create_custom_field_type.rst
@@ -4,27 +4,37 @@
 How to Create a Custom Form Field Type
 ======================================
 
-Symfony comes with a bunch of core field types available for building forms.
-However there are situations where you may want to create a custom form field
-type for a specific purpose. This article assumes you need a field definition
-that holds a shipping option, based on the existing choice field. This section
-explains how the field is defined and how you can customize its layout.
-
-Defining the Field Type
------------------------
-
-In order to create the custom field type, first you have to create the class
-representing the field. In this situation the class holding the field type
-will be called ``ShippingType`` and the file will be stored in the default location
-for form fields, which is ``App\Form\Type``. Make sure the field extends
-:class:`Symfony\\Component\\Form\\AbstractType`::
+Symfony comes with :doc:`tens of form types </reference/forms/types>` (called
+"form fields" in other projects) ready to use in your applications. However,
+it's common to create custom form types to solve specific purposes in your
+projects.
+
+Creating Form Types Based on Symfony Built-in Types
+---------------------------------------------------
+
+The easiest way to create a form type is to base it on one of the
+:doc:`existing form types </reference/forms/types>`. Imagine that your project
+displays a list of "shipping options" as a ``<select>`` HTML element. This can
+be implemented with a :doc:`ChoiceType </reference/forms/types/choice>` where the
+``choices`` option is set to the list of available shipping options.
+
+However, if you use the same form type in several forms, repeating the list of
+``choices`` everytime you use it quickly becomes boring. In this example, a
+better solution is to create a custom form type based on ``ChoiceType``. The
+custom type looks and behaves like a ``ChoiceType`` but the list of choices is
+already populated with the shipping options so you don't need to define them.
+
+Form types are PHP classes that implement :class:`Symfony\\Component\\Form\\FormTypeInterface`,
+but you should instead extend from :class:`Symfony\\Component\\Form\\AbstractType`,
+which already implements that interface and provides some utilities.
+By convention they are stored in the ``src/Form/Type/`` directory::
 
     // src/Form/Type/ShippingType.php
     namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
-    use Symfony\Component\OptionsResolver\OptionsResolver;
     use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class ShippingType extends AbstractType
     {
@@ -45,238 +55,408 @@ for form fields, which is ``App\Form\Type``. Make sure the field extends
         }
     }
 
-.. tip::
+The ``configureOptions()`` method, which is explained later in this article,
+defines the options that can be configured for the form type and sets the
+default value of those options.
 
-    The location of this file is not important - the ``Form\Type`` directory
-    is just a convention.
+The ``getParent()`` method defines which is the form type used as the base of
+this type. In this case, the type extends from ``ChoiceType`` to reuse all of
+the logic and rendering of that field type.
 
-Here, the return value of the ``getParent()`` function indicates that you're
-extending the ``ChoiceType`` field. This means that, by default, you inherit
-all of the logic and rendering of that field type. To see some of the logic,
-check out the `ChoiceType`_ class. There are three methods that are particularly
-important:
+.. note::
 
-.. _form-type-methods-explanation:
+    The PHP class extension mechanism and the Symfony form field extension
+    mechanism are not the same. The parent type returned in ``getParent()`` is
+    what Symfony uses to build and manage the field type. Making the PHP class
+    extend from ``AbstractType`` is only a convenience way of implementing the
+    required ``FormTypeInterface``.
 
-``buildForm()``
-    Each field type has a ``buildForm()`` method, which is where
-    you configure and build any field(s). Notice that this is the same method
-    you use to setup *your* forms, and it works the same here.
+Now you can add this form type when :doc:`creating Symfony forms </forms>`::
 
-``buildView()``
-    This method is used to set any extra variables you'll
-    need when rendering your field in a template. For example, in `ChoiceType`_,
-    a ``multiple`` variable is set and used in the template to set (or not
-    set) the ``multiple`` attribute on the ``select`` field. See
-    `Creating a Template for the Field`_ for more details.
+    // src/Form/Type/OrderType.php
+    namespace App\Form\Type;
 
-``configureOptions()``
-    This defines options for your form type that
-    can be used in ``buildForm()`` and ``buildView()``. There are a lot of
-    options common to all fields (see :doc:`/reference/forms/types/form`),
-    but you can create any others that you need here.
+    use App\Form\Type\ShippingType;
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
-.. tip::
+    class OrderType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            $builder
+                // ...
+                ->add('shipping', ShippingType::class)
+            ;
+        }
 
-    If you're creating a field that consists of many fields, then be sure
-    to set your "parent" type as ``form`` or something that extends ``form``.
-    Also, if you need to modify the "view" of any of your child types from
-    your parent type, use the ``finishView()`` method.
+        // ...
+    }
 
-The goal of this field was to extend the choice type to enable selection of the
-shipping type. This is achieved by fixing the ``choices`` to a list of available
-shipping options.
+That's all. The ``shipping`` form field will be rendered correctly in any
+template because it reuses the templating logic defined by its parent type
+``ChoiceType``. If you prefer, you can also define a template for your custom
+types, as explained later in this article.
 
-Creating a Template for the Field
----------------------------------
+Creating Form Types Created From Scratch
+----------------------------------------
 
-Each field type is rendered by a template fragment whose name is determined in
-part by the class name of your type. Read the :ref:`from fragment naming <form-fragment-naming>`
-rules for more details.
+Some form types are so specific to your projects that they cannot be based on
+any :doc:`existing form types </reference/forms/types>` because they are too
+different. Consider an application that wants to reuse in different forms the
+following set of fields as the "postal address":
 
-.. note::
+.. raw:: html
 
-    The first part of the prefix (e.g. ``shipping``) comes from the class name
-    (``ShippingType`` -> ``shipping``). This can be controlled by overriding ``getBlockPrefix()``
-    in ``ShippingType``.
+    <object data="../_images/form/form-custom-type-postal-address.svg" type="image/svg+xml"></object>
 
-.. caution::
+As explained above, form types are PHP classes that implement
+:class:`Symfony\\Component\\Form\\FormTypeInterface`, although it's more
+convenient to extend instead from :class:`Symfony\\Component\\Form\\AbstractType`::
 
-    When the name of your form class matches any of the built-in field types,
-    your form might not be rendered correctly. A form type named
-    ``App\Form\PasswordType`` will have the same block name as the
-    built-in ``PasswordType`` and won't be rendered correctly. Override the
-    ``getBlockPrefix()`` method to return a unique block prefix (e.g.
-    ``app_password``) to avoid collisions.
+    // src/Form/Type/PostalAddressType.php
+    namespace App\Form\Type;
 
-In this case, since the parent field is ``ChoiceType``, you don't *need* to do
-any work as the custom field type will automatically be rendered like a ``ChoiceType``.
-But for the sake of this example, suppose that when your field is "expanded"
-(i.e. radio buttons or checkboxes, instead of a select field), you want to
-always render it in a ``ul`` element. In your form theme template (see above
-link for details), create a ``shipping_widget`` block to handle this:
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\FormType;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
-.. code-block:: html+twig
+    class PostalAddressType extends AbstractType
+    {
+        // ...
+    }
 
-    {# templates/form/fields.html.twig #}
-    {% block shipping_widget %}
-        {% spaceless %}
-            {% if expanded %}
-                <ul {{ block('widget_container_attributes') }}>
-                {% for child in form %}
-                    <li>
-                        {{ form_widget(child) }}
-                        {{ form_label(child) }}
-                    </li>
-                {% endfor %}
-                </ul>
-            {% else %}
-                {# let the choice widget render the select tag #}
-                {{ block('choice_widget') }}
-            {% endif %}
-        {% endspaceless %}
-    {% endblock %}
+When a form type doesn't extend from another specific type, there's no need to
+implement the ``getParent()`` method (Symfony will make the type extend from the
+generic :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType`,
+which is the parent of all the other types).
 
-.. tip::
+These are the most important methods that a form type class can define:
 
-    You can further customize the template used to render each children of the
-    choice type. The block to override in that case is named "block name" +
-    ``_entry`` + "element name" (``label``, ``errors`` or ``widget``) (e.g. to
-    customize the labels of the children of the Shipping widget you'd need to
-    define ``{% block shipping_entry_label %} ... {% endblock %}``).
+.. _form-type-methods-explanation:
 
-.. note::
+``buildForm()``
+    It adds and configures other types into this type. It's the same method used
+    when :ref:`creating Symfony form classes <creating-forms-in-classes>`.
 
-    Make sure the correct widget prefix is used. In this example the name should
-    be ``shipping_widget`` (see :ref:`form fragment naming <form-fragment-naming>`
-    rules). Further, the main config file should point to the custom form template
-    so that it's used when rendering all forms.
+``buildView()``
+    It sets any extra variables you'll need when rendering the field in a template.
 
-    When using Twig this is:
+``configureOptions()``
+    It defines the options configurable when using the form type, which are also
+    the options that can be used in ``buildForm()`` and ``buildView()`` methods.
 
-    .. configuration-block::
+``finishView()``
+    When creating a form type that consists of many fields, this method allows
+    to modify the "view" of any of those fields. For any other use case, it's
+    recommended to use instead the ``buildView()`` method.
 
-        .. code-block:: yaml
+Defining the Form Type
+~~~~~~~~~~~~~~~~~~~~~~
 
-            # config/packages/twig.yaml
-            twig:
-                form_themes:
-                    - 'form/fields.html.twig'
+Start by adding the ``buildForm()`` method to configure all the types included
+in the postal address. For the moment, all fields are of type ``TextType``::
 
-        .. code-block:: xml
+    // src/Form/Type/PostalAddressType.php
+    namespace App\Form\Type;
 
-            <!-- config/packages/twig.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:twig="http://symfony.com/schema/dic/twig"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/twig
-                    http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
+
+    class PostalAddressType extends AbstractType
+    {
+        // ...
 
-                <twig:config>
-                    <twig:form-theme>form/fields.html.twig</twig:form-theme>
-                </twig:config>
-            </container>
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            $builder
+                ->add('addressLine1', TextType::class, [
+                    'help' => 'Street address, P.O. box, company name',
+                ])
+                ->add('addressLine2', TextType::class, [
+                    'help' => 'Apartment, suite, unit, building, floor',
+                ])
+                ->add('city', TextType::class)
+                ->add('state', TextType::class, [
+                    'label' => 'State',
+                ])
+                ->add('zipCode', TextType::class, [
+                    'label' => 'ZIP Code',
+                ])
+            ;
+        }
+    }
 
-        .. code-block:: php
+.. tip::
 
-            // config/packages/twig.php
-            $container->loadFromExtension('twig', [
-                'form_themes' => [
-                    'form/fields.html.twig',
-                ],
-            ]);
+    Run the following command to verify that the form type was successfully
+    registered in the application:
 
-    For the PHP templating engine, your configuration should look like this:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/framework.yaml
-            framework:
-                templating:
-                    form:
-                        resources:
-                            - ':form:fields.html.php'
-
-        .. code-block:: xml
-
-            <!-- config/packages/framework.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xmlns:framework="http://symfony.com/schema/dic/symfony"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-                <framework:config>
-                    <framework:templating>
-                        <framework:form>
-                            <framework:resource>:form:fields.html.php</twig:resource>
-                        </framework:form>
-                    </framework:templating>
-                </framework:config>
-            </container>
-
-        .. code-block:: php
-
-            // config/packages/framework.php
-            $container->loadFromExtension('framework', [
-                'templating' => [
-                    'form' => [
-                        'resources' => [
-                            ':form:fields.html.php',
-                        ],
-                    ],
-                ],
-            ]);
+    .. code-block:: terminal
 
-Using the Field Type
---------------------
+        $ php bin/console debug:form
 
-You can now use your custom field type immediately, by creating a
-new instance of the type in one of your forms::
+This form type is ready to use it inside other forms and all its fields will be
+correctly rendered in any template::
 
     // src/Form/Type/OrderType.php
     namespace App\Form\Type;
 
+    use App\Form\Type\PostalAddressType;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
-    use App\Form\Type\ShippingType;
 
     class OrderType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
-            $builder->add('shipping_code', ShippingType::class, [
-                'placeholder' => 'Choose a delivery option',
-            ]);
+            $builder
+                // ...
+                ->add('address', PostalAddressType::class)
+            ;
         }
+
+        // ...
     }
 
-But this only works because the ``ShippingType()`` is very simple. What if
-the shipping codes were stored in configuration or in a database? The next
-section explains how more complex field types solve this problem.
+However, the real power of custom form types is achieved with custom form
+options (to make them flexible) and with custom templates (to make them look
+better).
 
-.. _form-field-service:
-.. _creating-your-field-type-as-a-service:
+.. _form-type-config-options:
 
-Accessing Services and Config
------------------------------
+Adding Configuration Options for the Form Type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you need to access :doc:`services </service_container>` from your form class,
-add a ``__construct()`` method like normal::
+Imagine that your project requires to make the ``PostalAddressType``
+configurable in two ways:
 
-    // src/Form/Type/ShippingType.php
+* In addition to "address line 1" and "address line 2", some addresses should be
+  allowed to display an "address line 3" to store extended address information;
+* Instead of displaying a free text input, some addresses should be able to
+  restrict the possible states to a given list.
+
+This is solved with "form type options", which allow to configure the behavior
+of the form types. The options are defined in the ``configureOptions()`` method
+and you can use all the :doc:`OptionsResolver component features </components/options_resolver>`
+to define, validate and process their values::
+
+    // src/Form/Type/PostalAddressType.php
     namespace App\Form\Type;
 
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\OptionsResolver\Options;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    class PostalAddressType extends AbstractType
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            // this defines the available options and their default values when
+            // they are not configured explicitly when using the form type
+            $resolver->setDefaults([
+                'allowed_states' => null,
+                'is_extended_address' => false,
+            ]);
+
+            // optionally you can also restrict the options type or types (to get
+            // automatic type validation and useful error messages for end users)
+            $resolver->setAllowedTypes('allowed_states', ['null', 'string', 'array']);
+            $resolver->setAllowedTypes('is_extended_address', 'bool');
+
+            // optionally you can transform the given values for the options to
+            // simplify the further processing of those options
+            $resolver->setNormalizer('allowed_states', static function (Options $options, $states) {
+                if (null === $states) {
+                    return $states;
+                }
+
+                if (is_string($states)) {
+                    $states = (array) $states;
+                }
+
+                return array_combine(array_values($states), array_values($states));
+            });
+        }
+    }
+
+Now you can configure these options when using the form type::
+
+    // src/Form/Type/OrderType.php
+    // ...
+
+    class OrderType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            $builder
+                // ...
+                ->add('address', PostalAddressType::class, [
+                    'is_extended_address' => true,
+                    'allowed_states' => ['CA', 'FL', 'TX'],
+                    // in this example, this config would also be valid:
+                    // 'allowed_states' => 'CA',
+                ])
+            ;
+        }
+
+        // ...
+    }
+
+The last step is to use these options when building the form::
+
+    // src/Form/Type/PostalAddressType.php
     // ...
+
+    class PostalAddressType extends AbstractType
+    {
+        // ...
+
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            // ...
+
+            if (true === $options['is_extended_address']) {
+                $builder->add('addressLine3', TextType::class, [
+                    'help' => 'Extended address info',
+                ]);
+            }
+
+            if (null !== $options['allowed_states']) {
+                $builder->add('state', ChoiceType::class, [
+                    'choices' => $options['allowed_states'],
+                ]);
+            } else {
+                $builder->add('state', TextType::class, [
+                    'label' => 'State/Province/Region',
+                ]);
+            }
+        }
+    }
+
+Creating the Form Type Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, custom form types will be rendered using the
+:doc:`form themes </form/form_themes>` configured in the application. However,
+for some types you may prefer to create a custom template in order to customize
+how they look or their HTML structure.
+
+First, create a new Twig template anywhere in the application to store the
+fragments used to render the types:
+
+.. code-block:: twig
+
+    {# templates/form/custom_types.html.twig #}
+
+    {# ... here you will add the Twig code ... #}
+
+Then, update the :ref:`form_themes option <reference-twig-tag-form-theme>` to
+add this new template at the beginning of the list (the first one overrides the
+rest of files):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/twig.yaml
+        twig:
+            form_themes:
+                - 'form/custom_types.html.twig'
+                - '...'
+
+    .. code-block:: xml
+
+        <!-- config/packages/twig.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <twig:config>
+                <twig:form-theme>form/custom_types.html.twig</twig:form-theme>
+                <twig:form-theme>...</twig:form-theme>
+            </twig:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/twig.php
+        $container->loadFromExtension('twig', [
+            'form_themes' => [
+                'form/custom_types.html.twig',
+                '...',
+            ],
+        ]);
+
+The last step is to create the actual Twig template that will render the type.
+The template contents depend on which HTML, CSS and JavaScript frameworks and
+libraries are used in your application:
+
+.. code-block:: html+twig
+
+    {# templates/form/custom_types.html.twig #}
+    {% block postal_address_row %}
+        {% for child in form.children if not child.rendered %}
+            <div class="form-group">
+                {{ form_label(child) }}
+                {{ form_widget(child) }}
+                {{ form_help(child) }}
+                {{ form_errors(child) }}
+            </div>
+        {% endfor %}
+    {% endblock %}
+
+.. note::
+
+    Symfony 4.2 deprecated calling ``FormRenderer::searchAndRenderBlock`` for
+    fields that have already been rendered. That's why the previous example
+    includes the ``... if not child.rendered`` statement.
+
+The first part of the Twig block name (e.g. ``postal_address``) comes from the
+class name (``PostalAddressType`` -> ``postal_address``). This can be controlled
+by overriding the ``getBlockPrefix()`` method in ``PostalAddressType``. The
+second part of the Twig block name (e.g. ``_row``) defines which form type part
+is being rendered (row, widget, help, errors, etc.)
+
+The article about form themes explains the
+:ref:`form fragment naming rules <form-fragment-naming>` in detail. The
+following diagram shows some of the Twig block names defined in this example:
+
+.. raw:: html
+
+    <object data="../_images/form/form-custom-type-postal-address-fragment-names.svg" type="image/svg+xml"></object>
+
+.. caution::
+
+    When the name of your form class matches any of the built-in field types,
+    your form might not be rendered correctly. A form type named
+    ``App\Form\PasswordType`` will have the same block name as the built-in
+    ``PasswordType`` and won't be rendered correctly. Override the
+    ``getBlockPrefix()`` method to return a unique block prefix (e.g.
+    ``app_password``) to avoid collisions.
+
+Passing Variables to the Form Type Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony passes a series of variables to the template used to render the form
+type. You can also pass your own variables, which can be based on the options
+defined by the form or be completely independent::
+
+
+    // src/Form/Type/PostalAddressType.php
     use Doctrine\ORM\EntityManagerInterface;
+    // ...
 
-    class ShippingType extends AbstractType
+    class PostalAddressType extends AbstractType
     {
         private $entityManager;
 
@@ -285,19 +465,39 @@ add a ``__construct()`` method like normal::
             $this->entityManager = $entityManager;
         }
 
-        // use $this->entityManager down anywhere you want ...
+        // ...
+
+        public function buildView(FormView $view, FormInterface $form, array $options)
+        {
+            // pass the form type option directly to the template
+            $view->vars['isExtendedAddress'] = $options['is_extended_address'];
+
+            // make a database query to find possible notifications related to postal addresses (e.g. to
+            // display dynamic messages such as 'Delivery to XX and YY states will be added next week!')
+            $view->vars['notification'] = $this->entityManager->find('...');
+        }
     }
 
-If you're using the default ``services.yaml`` configuration (i.e. services from the
-``Form/`` are loaded and ``autoconfigure`` is enabled), this will already work!
-See :ref:`service-container-creating-service` for more details.
+If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
+this example will already work! Otherwise, :ref:`create a service <service-container-creating-service>`
+for this form class and :doc:`tag it </service_container/tags>` with ``form.type``.
 
-.. tip::
+The variables added in ``buildView()`` are available in the form type template
+as any other regular Twig variable:
+
+.. code-block:: html+twig
 
-    If you're not using :ref:`autoconfigure <services-autoconfigure>`, make sure
-    to :doc:`tag </service_container/tags>` your service with ``form.type``.
+    {# templates/form/custom_types.html.twig #}
+    {% block postal_address_row %}
+        {# ... #}
 
-Have fun!
+        {% if isExtendedAddress %}
+            {# ... #}
+        {% endif %}
 
-.. _`ChoiceType`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php
-.. _`FieldType`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/FieldType.php
+        {% if notification is not empty %}
+            <div class="alert alert-primary" role="alert">
+                {{ notification }}
+            </div>
+        {% endif %}
+    {% endblock %}
diff --git a/form/create_form_type_extension.rst b/form/create_form_type_extension.rst
index 2bd6bd86980..fb1cd2e02b2 100644
--- a/form/create_form_type_extension.rst
+++ b/form/create_form_type_extension.rst
@@ -22,7 +22,9 @@ input.
 Defining the Form Type Extension
 --------------------------------
 
-First, create the form type extension class::
+First, create the form type extension class extending from
+:class:`Symfony\\Component\\Form\\AbstractTypeExtension` (you can implement
+:class:`Symfony\\Component\\Form\\FormTypeExtensionInterface` instead if you prefer)::
 
     // src/Form/Extension/ImageTypeExtension.php
     namespace App\Form\Extension;
@@ -33,29 +35,23 @@ First, create the form type extension class::
     class ImageTypeExtension extends AbstractTypeExtension
     {
         /**
-         * Returns the name of the type being extended.
-         *
-         * @return string The name of the type being extended
+         * Return the class of the type being extended.
          */
-        public function getExtendedType()
+        public static function getExtendedTypes(): iterable
         {
-            // use FormType::class to modify (nearly) every field in the system
-            return FileType::class;
+            // return FormType::class to modify (nearly) every field in the system
+            return [FileType::class];
         }
     }
 
-The only method you **must** implement is the ``getExtendedType()`` function.
-This is used to configure *which* field or field types you want to modify.
+The only method you **must** implement is ``getExtendedTypes()``, which is used
+to configure *which* field types you want to modify.
 
-In addition to the ``getExtendedType()`` function, you will probably want
-to override one of the following methods:
+Depending on your use case, you may need to override some of the following methods:
 
 * ``buildForm()``
-
 * ``buildView()``
-
 * ``configureOptions()``
-
 * ``finishView()``
 
 For more information on what those methods do, see the
@@ -64,61 +60,33 @@ For more information on what those methods do, see the
 Registering your Form Type Extension as a Service
 -------------------------------------------------
 
-The next step is to make Symfony aware of your extension. Do this by registering
-your class as a service and using the  ``form.type_extension`` tag:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        services:
-            # ...
-
-            App\Form\Extension\ImageTypeExtension:
-                tags:
-                    - { name: form.type_extension, extended_type: Symfony\Component\Form\Extension\Core\Type\FileType }
-
-    .. code-block:: xml
+Form type extensions must be :ref:`registered as services <service-container-creating-service>`
+and :doc:`tagged </service_container/tags>` with the ``form.type_extension`` tag.
+If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
 
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <service id="App\Form\Extension\ImageTypeExtension">
-                    <tag name="form.type_extension" extended-type="Symfony\Component\Form\Extension\Core\Type\FileType" />
-                </service>
-            </services>
-        </container>
+.. tip::
 
-    .. code-block:: php
+    There is an optional tag attribute called ``priority``, which defaults to
+    ``0`` and controls the order in which the form type extensions are loaded
+    (the higher the priority, the earlier an extension is loaded). This is
+    useful when you need to guarantee that one extension is loaded before or
+    after another extension. Using this attribute requires you to add the
+    service configuration explicitly.
 
-        // config/services.php
-        use App\Form\Extension\ImageTypeExtension;
-        use Symfony\Component\Form\Extension\Core\Type\FileType;
+Once the extension is registered, any method that you've overridden (e.g.
+``buildForm()``) will be called whenever *any* field of the given type
+(``FileType``) is built.
 
-        $container->autowire(ImageTypeExtension::class)
-            ->addTag('form.type_extension', [
-                'extended_type' => FileType::class
-            ])
-        ;
+.. tip::
 
-The ``extended_type`` key of the tag must match the class you're returning from
-the ``getExtendedType()`` method. As *soon* as you do this, any method that you've
-overridden (e.g. ``buildForm()``) will be called whenever *any* field of the given
-type (``FileType``) is built. Let's see an example next.
+    Run the following command to verify that the form type extension was
+    successfully registered in the application:
 
-.. tip::
+    .. code-block:: terminal
 
-    There is an optional tag attribute called ``priority``, which
-    defaults to ``0`` and controls the order in which the form
-    type extensions are loaded (the higher the priority, the earlier
-    an extension is loaded). This is useful when you need to guarantee
-    that one extension is loaded before or after another extension.
+        $ php bin/console debug:form
 
 Adding the extension Business Logic
 -----------------------------------
@@ -167,17 +135,18 @@ For example::
     namespace App\Form\Extension;
 
     use Symfony\Component\Form\AbstractTypeExtension;
-    use Symfony\Component\Form\FormView;
+    use Symfony\Component\Form\Extension\Core\Type\FileType;
     use Symfony\Component\Form\FormInterface;
-    use Symfony\Component\PropertyAccess\PropertyAccess;
+    use Symfony\Component\Form\FormView;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\FileType;
+    use Symfony\Component\PropertyAccess\PropertyAccess;
 
     class ImageTypeExtension extends AbstractTypeExtension
     {
-        public function getExtendedType()
+        public static function getExtendedTypes(): iterable
         {
-            return FileType::class;
+            // return FormType::class to modify (nearly) every field in the system
+            return [FileType::class];
         }
 
         public function configureOptions(OptionsResolver $resolver)
@@ -246,9 +215,9 @@ next to the file field. For example::
     namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
-    use Symfony\Component\Form\FormBuilderInterface;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\FileType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
     class MediaType extends AbstractType
     {
@@ -278,3 +247,21 @@ would apply to all of these (notable exceptions are the ``ButtonType`` form
 types). Also keep in mind that if you created (or are using) a *custom* form type,
 it's possible that it does *not* extend ``FormType``, and so your form type extension
 may not be applied to it.
+
+Another option is to return multiple form types in the ``getExtendedTypes()``
+method to extend all of them::
+
+    // ...
+    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
+    use Symfony\Component\Form\Extension\Core\Type\TimeType;
+
+    class DateTimeExtension extends AbstractTypeExtension
+    {
+        // ...
+
+        public static function getExtendedTypes(): iterable
+        {
+            return [DateTimeType::class, DateType::class, TimeType::class];
+        }
+    }
diff --git a/form/data_mappers.rst b/form/data_mappers.rst
index 23bb8939fa8..f25f1648a0b 100644
--- a/form/data_mappers.rst
+++ b/form/data_mappers.rst
@@ -33,7 +33,7 @@ Creating a Data Mapper
 Suppose that you want to save a set of colors to the database. For this, you're
 using an immutable color object::
 
-    // src/App/Painting/Color.php
+    // src/Painting/Color.php
     namespace App\Painting;
 
     final class Color
@@ -78,45 +78,48 @@ one of the values is changed.
 
 The red, green and blue form fields have to be mapped to the constructor
 arguments and the ``Color`` instance has to be mapped to red, green and blue
-form fields. Recognize a familiar pattern? It's time for a data mapper!
+form fields. Recognize a familiar pattern? It's time for a data mapper. The
+easiest way to create one is by implementing :class:`Symfony\\Component\\Form\\DataMapperInterface`
+in your form type::
 
-.. code-block:: php
-
-    // src/App/Form/DataMapper/ColorMapper.php
-    namespace App\Form\DataMapper;
+    // src/Form/ColorType.php
+    namespace App\Form;
 
     use App\Painting\Color;
+    use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\DataMapperInterface;
     use Symfony\Component\Form\Exception\UnexpectedTypeException;
     use Symfony\Component\Form\FormInterface;
 
-    final class ColorMapper implements DataMapperInterface
+    final class ColorType extends AbstractType implements DataMapperInterface
     {
+        // ...
+
         /**
-         * @param Color|null $data
+         * @param Color|null $viewData
          */
-        public function mapDataToForms($data, $forms)
+        public function mapDataToForms($viewData, $forms)
         {
             // there is no data yet, so nothing to prepopulate
-            if (null === $data) {
+            if (null === $viewData) {
                 return;
             }
 
             // invalid data type
-            if (!$data instanceof Color) {
-                throw new UnexpectedTypeException($data, Color::class);
+            if (!$viewData instanceof Color) {
+                throw new UnexpectedTypeException($viewData, Color::class);
             }
 
             /** @var FormInterface[] $forms */
             $forms = iterator_to_array($forms);
 
             // initialize form field values
-            $forms['red']->setData($data->getRed());
-            $forms['green']->setData($data->getGreen());
-            $forms['blue']->setData($data->getBlue());
+            $forms['red']->setData($viewData->getRed());
+            $forms['green']->setData($viewData->getGreen());
+            $forms['blue']->setData($viewData->getBlue());
         }
 
-        public function mapFormsToData($forms, &$data)
+        public function mapFormsToData($forms, &$viewData)
         {
             /** @var FormInterface[] $forms */
             $forms = iterator_to_array($forms);
@@ -124,7 +127,7 @@ form fields. Recognize a familiar pattern? It's time for a data mapper!
             // as data is passed by reference, overriding it will change it in
             // the form object as well
             // beware of type inconsistency, see caution below
-            $data = new Color(
+            $viewData = new Color(
                 $forms['red']->getData(),
                 $forms['green']->getData(),
                 $forms['blue']->getData()
@@ -141,20 +144,19 @@ form fields. Recognize a familiar pattern? It's time for a data mapper!
 Using the Mapper
 ----------------
 
-You're ready to use the data mapper for the ``ColorType`` form. Use the
-:method:`Symfony\\Component\\Form\\FormConfigBuilderInterface::setDataMapper`
-method to configure the data mapper::
+After creating the data mapper, you need to configure the form to use it. This is
+achieved using the :method:`Symfony\\Component\\Form\\FormConfigBuilderInterface::setDataMapper`
+method::
 
-    // src/App/Form/Type/ColorType.php
+    // src/Form/Type/ColorType.php
     namespace App\Form\Type;
 
-    use App\Form\DataMapper\ColorMapper;
-    use Symfony\Component\Form\AbstractType;
+    // ...
     use Symfony\Component\Form\Extension\Core\Type\IntegerType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
 
-    final class ColorType extends AbstractType
+    final class ColorType extends AbstractType implements DataMapperInterface
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
@@ -170,7 +172,8 @@ method to configure the data mapper::
                 ->add('blue', IntegerType::class, [
                     'empty_data' => '0',
                 ])
-                ->setDataMapper(new ColorMapper())
+                // configure the data mapper for this FormType
+                ->setDataMapper($this)
             ;
         }
 
@@ -179,19 +182,41 @@ method to configure the data mapper::
             // when creating a new color, the initial data should be null
             $resolver->setDefault('empty_data', null);
         }
+
+        // ...
     }
 
-Cool! When using the ``ColorType`` form, the custom ``ColorMapper`` will create
-a new ``Color`` object now.
+Cool! When using the ``ColorType`` form, the custom data mapper methods will
+create a new ``Color`` object now.
 
 .. caution::
 
     When a form has the ``inherit_data`` option set to ``true``, it does not use the data mapper and
     lets its parent map inner values.
 
-.. tip::
+.. sidebar:: Stateful Data Mappers
+
+    Sometimes, data mappers need to access services or need to maintain their
+    state. In this case, you cannot implement the methods in the form type
+    itself. Create a separate class implementing ``DataMapperInterface`` and
+    initialize it in your form type::
 
-    You can also implement the ``DataMapperInterface`` in the ``ColorType`` and add
-    the ``mapDataToForms()`` and ``mapFormsToData()`` in the form type directly
-    to avoid creating a new class. You'll then have to call
-    ``$builder->setDataMapper($this)``.
+        // src/Form/Type/ColorType.php
+
+        // ...
+        use App\Form\DataMapper\ColorMapper;
+
+        final class ColorType extends AbstractType
+        {
+            public function buildForm(FormBuilderInterface $builder, array $options)
+            {
+                $builder
+                    // ...
+
+                    // Initialize the data mapper class and e.g. pass some state
+                    ->setDataMapper(new ColorMapper($options['opacity']))
+                ;
+            }
+
+            // ...
+        }
diff --git a/form/data_transformers.rst b/form/data_transformers.rst
index b19f7238ed2..589fedc053d 100644
--- a/form/data_transformers.rst
+++ b/form/data_transformers.rst
@@ -33,9 +33,9 @@ Suppose you have a Task form with a tags ``text`` type::
     namespace App\Form\Type;
 
     use App\Entity\Task;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
 
     // ...
     class TaskType extends AbstractType
@@ -66,8 +66,8 @@ class::
     namespace App\Form\Type;
 
     use Symfony\Component\Form\CallbackTransformer;
-    use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
     // ...
 
     class TaskType extends AbstractType
@@ -252,7 +252,7 @@ that message with the ``invalid_message`` option (see below).
 Using the Transformer
 ~~~~~~~~~~~~~~~~~~~~~
 
-Next, you need to use the ``IssueToNumberTransformer`` object inside if ``TaskType``
+Next, you need to use the ``IssueToNumberTransformer`` object inside of ``TaskType``
 and add it to the ``issue`` field. No problem! Add a ``__construct()`` method
 and type-hint the new class::
 
@@ -291,24 +291,62 @@ and type-hint the new class::
         // ...
     }
 
-That's it! As long as you're using :ref:`autowire <services-autowire>` and
-:ref:`autoconfigure <services-autoconfigure>`, Symfony will automatically
-know to pass your ``TaskType`` an instance of the ``IssueToNumberTransformer``.
+Whenever the transformer throws an exception, the ``invalid_message`` is shown
+to the user. Instead of showing the same message every time, you can set the
+end-user error message in the data transformer using the
+``setInvalidMessage()`` method. It also allows you to include user values::
 
-.. tip::
+    // src/Form/DataTransformer/IssueToNumberTransformer.php
+    namespace App\Form\DataTransformer;
+
+    use Symfony\Component\Form\DataTransformerInterface;
+    use Symfony\Component\Form\Exception\TransformationFailedException;
+
+    class IssueToNumberTransformer implements DataTransformerInterface
+    {
+        // ...
+
+        public function reverseTransform($issueNumber)
+        {
+            // ...
+
+            if (null === $issue) {
+                $privateErrorMessage = sprintf('An issue with number "%s" does not exist!', $issueNumber);
+                $publicErrorMessage = 'The given "{{ value }}" value is not a valid issue number.';
+
+                $failure = new TransformationFailedException($privateErrorMessage);
+                $failure->setInvalidMessage($publicErrorMessage, [
+                    '{{ value }}' => $issueNumber,
+                ]);
+
+                throw $failure;
+            }
+
+            return $issue;
+        }
+    }
+
+.. versionadded:: 4.3
+
+    The ``setInvalidMessage()`` method was introduced in Symfony 4.3.
 
-    For more information about defining form types as services, read
-    :doc:`register your form type as a service </form/form_dependencies>`.
+That's it! If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+Symfony will automatically know to pass your ``TaskType`` an instance of the
+``IssueToNumberTransformer`` thanks to :ref:`autowire <services-autowire>` and
+:ref:`autoconfigure <services-autoconfigure>`.
+Otherwise, :ref:`register the form class as a service <service-container-creating-service>`
+and :doc:`tag it </service_container/tags>` with the ``form.type`` tag.
 
 Now, you can use your ``TaskType``::
 
-    // e.g. in a controller somewhere
+    // e.g. somewhere in a controller
     $form = $this->createForm(TaskType::class, $task);
 
     // ...
 
 Cool, you're done! Your user will be able to enter an issue number into the
-text field and it will be transformed back into an Issue object. This means
+text field, which will be transformed back into an Issue object. This means
 that, after a successful submission, the Form component will pass a real
 ``Issue`` object to ``Task::setIssue()`` instead of the issue number.
 
diff --git a/form/direct_submit.rst b/form/direct_submit.rst
index 6edd70dc740..48388b100e5 100644
--- a/form/direct_submit.rst
+++ b/form/direct_submit.rst
@@ -4,54 +4,18 @@
 How to Use the submit() Function to Handle Form Submissions
 ===========================================================
 
-With the ``handleRequest()`` method, you can handle form
-submissions::
+The recommended way of :ref:`processing Symfony forms <processing-forms>` is to
+use the :method:`Symfony\\Component\\Form\\FormInterface::handleRequest` method
+to detect when the form has been submitted. However, you can also use the
+:method:`Symfony\\Component\\Form\\FormInterface::submit` method to have better
+control over when exactly your form is submitted and what data is passed to it::
 
     use Symfony\Component\HttpFoundation\Request;
     // ...
 
     public function new(Request $request)
     {
-        $form = $this->createFormBuilder()
-            // ...
-            ->getForm();
-
-        $form->handleRequest($request);
-
-        if ($form->isSubmitted() && $form->isValid()) {
-            // perform some action...
-
-            return $this->redirectToRoute('task_success');
-        }
-
-        return $this->render('product/new.html.twig', [
-            'form' => $form->createView(),
-        ]);
-    }
-
-.. tip::
-
-    To see more about this method, read :ref:`form-handling-form-submissions`.
-
-.. _form-call-submit-directly:
-
-Calling Form::submit() manually
--------------------------------
-
-In some cases, you want better control over when exactly your form is submitted
-and what data is passed to it. Instead of using the
-:method:`Symfony\\Component\\Form\\FormInterface::handleRequest`
-method, pass the submitted data directly to
-:method:`Symfony\\Component\\Form\\FormInterface::submit`::
-
-    use Symfony\Component\HttpFoundation\Request;
-    // ...
-
-    public function new(Request $request)
-    {
-        $form = $this->createFormBuilder()
-            // ...
-            ->getForm();
+        $form = $this->createForm(TaskType::class, $task);
 
         if ($request->isMethod('POST')) {
             $form->submit($request->request->get($form->getName()));
@@ -63,7 +27,7 @@ method, pass the submitted data directly to
             }
         }
 
-        return $this->render('product/new.html.twig', [
+        return $this->render('task/new.html.twig', [
             'form' => $form->createView(),
         ]);
     }
diff --git a/form/dynamic_form_modification.rst b/form/dynamic_form_modification.rst
index 36619125cae..f2b37cb07c5 100644
--- a/form/dynamic_form_modification.rst
+++ b/form/dynamic_form_modification.rst
@@ -10,7 +10,7 @@ how to customize your form based on three common use-cases:
 1) :ref:`form-events-underlying-data`
 
    Example: you have a "Product" form and need to modify/add/remove a field
-    based on the data on the underlying Product being edited.
+   based on the data on the underlying Product being edited.
 
 2) :ref:`form-events-user-data`
 
@@ -144,10 +144,10 @@ you can also move the logic for creating the ``name`` field to an
     // src/Form/EventListener/AddNameFieldSubscriber.php
     namespace App\Form\EventListener;
 
-    use Symfony\Component\Form\FormEvent;
-    use Symfony\Component\Form\FormEvents;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormEvent;
+    use Symfony\Component\Form\FormEvents;
 
     class AddNameFieldSubscriber implements EventSubscriberInterface
     {
@@ -209,11 +209,11 @@ Using an event listener, your form might look like this::
     namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\FormBuilderInterface;
-    use Symfony\Component\Form\FormEvents;
     use Symfony\Component\Form\FormEvent;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+    use Symfony\Component\Form\FormEvents;
 
     class FriendMessageFormType extends AbstractType
     {
@@ -236,11 +236,16 @@ service into the form type so you can get the current user object::
     use Symfony\Component\Security\Core\Security;
     // ...
 
-    private $security;
-
-    public function __construct(Security $security)
+    class FriendMessageFormType extends AbstractType
     {
-        $this->security = $security;
+        private $security;
+
+        public function __construct(Security $security)
+        {
+            $this->security = $security;
+        }
+
+        // ....
     }
 
 Customizing the Form Type
@@ -250,12 +255,11 @@ Now that you have all the basics in place you can use the features of the
 security helper to fill in the listener logic::
 
     // src/Form/Type/FriendMessageFormType.php
-
     use App\Entity\User;
     use Doctrine\ORM\EntityRepository;
     use Symfony\Bridge\Doctrine\Form\Type\EntityType;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Security\Core\Security;
     // ...
 
@@ -322,10 +326,11 @@ security helper to fill in the listener logic::
 Using the Form
 ~~~~~~~~~~~~~~
 
-If you're using :ref:`autowire <services-autowire>` and
-:ref:`autoconfigure <services-autoconfigure>`, your form is ready to be used!
-Otherwise, see :doc:`/form/form_dependencies` to learn how to register your form
-type as a service.
+If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
+your form is ready to be used thanks to :ref:`autowire <services-autowire>` and
+:ref:`autoconfigure <services-autoconfigure>`.
+Otherwise, :ref:`register the form class as a service <service-container-creating-service>`
+and :doc:`tag it </service_container/tags>` with the ``form.type`` tag.
 
 In a controller, create the form like normal::
 
@@ -357,7 +362,7 @@ Dynamic Generation for Submitted Forms
 Another case that can appear is that you want to customize the form specific to
 the data that was submitted by the user. For example, imagine you have a registration
 form for sports gatherings. Some events will allow you to specify your preferred
-position on the field. This would be a ``choice`` field for example. However the
+position on the field. This would be a ``choice`` field for example. However, the
 possible choices will depend on each sport. Football will have attack, defense,
 goalkeeper etc... Baseball will have a pitcher but will not have a goalkeeper. You
 will need the correct options in order for validation to pass.
@@ -368,11 +373,11 @@ sport like this::
     // src/Form/Type/SportMeetupType.php
     namespace App\Form\Type;
 
+    use Symfony\Bridge\Doctrine\Form\Type\EntityType;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\FormEvent;
     use Symfony\Component\Form\FormEvents;
-    use Symfony\Bridge\Doctrine\Form\Type\EntityType;
     // ...
 
     class SportMeetupType extends AbstractType
@@ -435,8 +440,8 @@ The type would now look like::
     namespace App\Form\Type;
 
     use App\Entity\Sport;
-    use Symfony\Component\Form\FormInterface;
     use Symfony\Bridge\Doctrine\Form\Type\EntityType;
+    use Symfony\Component\Form\FormInterface;
     // ...
 
     class SportMeetupType extends AbstractType
@@ -447,7 +452,7 @@ The type would now look like::
                 ->add('sport', EntityType::class, [
                     'class'       => 'App\Entity\Sport',
                     'placeholder' => '',
-                ]);
+                ])
             ;
 
             $formModifier = function (FormInterface $form, Sport $sport = null) {
@@ -504,10 +509,10 @@ your application. Assume that you have a sport meetup creation controller::
     // src/Controller/MeetupController.php
     namespace App\Controller;
 
-    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-    use Symfony\Component\HttpFoundation\Request;
     use App\Entity\SportMeetup;
     use App\Form\Type\SportMeetupType;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Request;
     // ...
 
     class MeetupController extends AbstractController
diff --git a/form/embedded.rst b/form/embedded.rst
index fc43ef5336e..6568b09611f 100644
--- a/form/embedded.rst
+++ b/form/embedded.rst
@@ -6,8 +6,8 @@ How to Embed Forms
 
 Often, you'll want to build a form that will include fields from many different
 objects. For example, a registration form may contain data belonging to
-a ``User`` object as well as many ``Address`` objects. Fortunately, this
-is easy and natural with the Form component.
+a ``User`` object as well as many ``Address`` objects. Fortunately this can
+be achieved by the Form component.
 
 .. _forms-embedding-single-object:
 
@@ -60,7 +60,7 @@ Next, add a new ``category`` property to the ``Task`` class::
 .. tip::
 
     The ``Valid`` Constraint has been added to the property ``category``. This
-    cascades the validation to the corresponding entity. If you omit this constraint
+    cascades the validation to the corresponding entity. If you omit this constraint,
     the child entity would not be validated.
 
 Now that your application has been updated to reflect the new requirements,
@@ -94,8 +94,8 @@ inside the task form itself. To accomplish this, add a ``category`` field
 to the ``TaskType`` object whose type is an instance of the new ``CategoryType``
 class::
 
-    use Symfony\Component\Form\FormBuilderInterface;
     use App\Form\CategoryType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
diff --git a/form/events.rst b/form/events.rst
index 76c37d125d5..5620ec96f46 100644
--- a/form/events.rst
+++ b/form/events.rst
@@ -263,15 +263,15 @@ method of the ``FormFactory``::
 
     // ...
 
-    use Symfony\Component\Form\FormEvent;
-    use Symfony\Component\Form\FormEvents;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
     use Symfony\Component\Form\Extension\Core\Type\EmailType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormEvent;
+    use Symfony\Component\Form\FormEvents;
 
     $form = $formFactory->createBuilder()
         ->add('username', TextType::class)
-        ->add('show_email', CheckboxType::class)
+        ->add('showEmail', CheckboxType::class)
         ->addEventListener(FormEvents::PRE_SUBMIT, function (FormEvent $event) {
             $user = $event->getData();
             $form = $event->getForm();
@@ -283,7 +283,7 @@ method of the ``FormFactory``::
             // checks whether the user has chosen to display their email or not.
             // If the data was submitted previously, the additional value that is
             // included in the request variables needs to be removed.
-            if (true === $user['show_email']) {
+            if (isset($user['showEmail']) && $user['showEmail']) {
                 $form->add('email', EmailType::class);
             } else {
                 unset($user['email']);
@@ -300,8 +300,8 @@ callback for better readability::
     // src/Form/SubscriptionType.php
     namespace App\Form;
 
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\FormEvent;
     use Symfony\Component\Form\FormEvents;
 
@@ -312,7 +312,7 @@ callback for better readability::
         {
             $builder
                 ->add('username', TextType::class)
-                ->add('show_email', CheckboxType::class)
+                ->add('showEmail', CheckboxType::class)
                 ->addEventListener(
                     FormEvents::PRE_SET_DATA,
                     [$this, 'onPreSetData']
@@ -335,15 +335,15 @@ Event subscribers have different uses:
 * Listening to multiple events;
 * Regrouping multiple listeners inside a single class.
 
-.. code-block:: php
+Consider the following example of a form event subscriber::
 
     // src/Form/EventListener/AddEmailFieldListener.php
     namespace App\Form\EventListener;
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\Form\Extension\Core\Type\EmailType;
     use Symfony\Component\Form\FormEvent;
     use Symfony\Component\Form\FormEvents;
-    use Symfony\Component\Form\Extension\Core\Type\EmailType;
 
     class AddEmailFieldListener implements EventSubscriberInterface
     {
@@ -379,7 +379,7 @@ Event subscribers have different uses:
             // checks whether the user has chosen to display their email or not.
             // If the data was submitted previously, the additional value that
             // is included in the request variables needs to be removed.
-            if (true === $user['show_email']) {
+            if (isset($user['showEmail']) && $user['showEmail']) {
                 $form->add('email', EmailType::class);
             } else {
                 unset($user['email']);
@@ -391,14 +391,14 @@ Event subscribers have different uses:
 To register the event subscriber, use the ``addEventSubscriber()`` method::
 
     use App\Form\EventListener\AddEmailFieldListener;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
 
     // ...
 
     $form = $formFactory->createBuilder()
         ->add('username', TextType::class)
-        ->add('show_email', CheckboxType::class)
+        ->add('showEmail', CheckboxType::class)
         ->addEventSubscriber(new AddEmailFieldListener())
         ->getForm();
 
diff --git a/form/form_collections.rst b/form/form_collections.rst
index 243b0f28334..28b6283a271 100644
--- a/form/form_collections.rst
+++ b/form/form_collections.rst
@@ -84,8 +84,8 @@ objects::
 
 Then, create a form class so that a ``Tag`` object can be modified by the user::
 
-    // src/Form/Type/TagType.php
-    namespace App\Form\Type;
+    // src/Form/TagType.php
+    namespace App\Form;
 
     use App\Entity\Tag;
     use Symfony\Component\Form\AbstractType;
@@ -114,14 +114,14 @@ form itself, create a form for the ``Task`` class.
 Notice that you embed a collection of ``TagType`` forms using the
 :doc:`CollectionType </reference/forms/types/collection>` field::
 
-    // src/Form/Type/TaskType.php
-    namespace App\Form\Type;
+    // src/Form/TaskType.php
+    namespace App\Form;
 
     use App\Entity\Task;
     use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\CollectionType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\CollectionType;
 
     class TaskType extends AbstractType
     {
@@ -148,11 +148,11 @@ In your controller, you'll create a new form from the ``TaskType``::
     // src/Controller/TaskController.php
     namespace App\Controller;
 
-    use App\Entity\Task;
     use App\Entity\Tag;
-    use App\Form\Type\TaskType;
-    use Symfony\Component\HttpFoundation\Request;
+    use App\Entity\Task;
+    use App\Form\TaskType;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Request;
 
     class TaskController extends AbstractController
     {
@@ -254,7 +254,7 @@ type expects to receive exactly two, otherwise an error will be thrown:
 ``This form should not contain extra fields``. To make this flexible,
 add the ``allow_add`` option to your collection field::
 
-    // src/Form/Type/TaskType.php
+    // src/Form/TaskType.php
 
     // ...
     use Symfony\Component\Form\FormBuilderInterface;
@@ -295,7 +295,7 @@ new "tag" forms. To render it, make the following change to your template:
     on it. You could even choose to render only one of its fields (e.g. the
     ``name`` field):
 
-    .. code-block:: html+twig
+    .. code-block:: twig
 
         {{ form_widget(form.tags.vars.prototype.name)|e }}
 
@@ -418,7 +418,7 @@ for the tags in the ``Task`` class::
 
 Next, add a ``by_reference`` option to the ``tags`` field and set it to ``false``::
 
-    // src/Form/Type/TaskType.php
+    // src/Form/TaskType.php
 
     // ...
     public function buildForm(FormBuilderInterface $builder, array $options)
@@ -444,6 +444,12 @@ you will learn about next!).
     otherwise the form will still use ``setTag()`` even if ``by_reference`` is ``false``.
     You'll learn more about the ``removeTag()`` method later in this article.
 
+.. caution::
+
+    Symfony can only make the plural-to-singular conversion (e.g. from the
+    ``tags`` property to the ``addTag()`` method) for English words. Code
+    written in any other language won't work as expected.
+
 .. sidebar:: Doctrine: Cascading Relations and saving the "Inverse" side
 
     To save the new tags with Doctrine, you need to consider a couple more
@@ -490,13 +496,13 @@ you will learn about next!).
             <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                                https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
                 <entity name="App\Entity\Task">
                     <!-- ... -->
                     <one-to-many field="tags" target-entity="Tag">
                         <cascade>
-                            <cascade-persist />
+                            <cascade-persist/>
                         </cascade>
                     </one-to-many>
                 </entity>
@@ -510,12 +516,12 @@ you will learn about next!).
     of the relationship is modified.
 
     The trick is to make sure that the single "Task" is set on each "Tag".
-    One way to do this is to add some extra logic to ``addTag()``,
-    which is called by the form type since ``by_reference`` is set to
-    ``false``::
+    One way to do this is to add some extra logic to ``addTag()``, which
+    is called by the form type since ``by_reference`` is set to ``false``::
 
         // src/Entity/Task.php
 
+        // ...
         public function addTag(Tag $tag)
         {
             // for a many-to-many association:
@@ -550,7 +556,7 @@ The solution is similar to allowing tags to be added.
 
 Start by adding the ``allow_delete`` option in the form Type::
 
-    // src/Form/Type/TaskType.php
+    // src/Form/TaskType.php
 
     // ...
     public function buildForm(FormBuilderInterface $builder, array $options)
@@ -636,7 +642,7 @@ the relationship between the removed ``Tag`` and ``Task`` object.
     ``Tag`` is properly removed.
 
     In Doctrine, you have two sides of the relationship: the owning side and the
-    inverse side. Normally in this case you'll have a many-to-many relationship
+    inverse side. Normally in this case you'll have a many-to-one relationship
     and the deleted tags will disappear and persist correctly (adding new
     tags also works effortlessly).
 
@@ -649,7 +655,6 @@ the relationship between the removed ``Tag`` and ``Task`` object.
     is handling the "update" of your Task::
 
         // src/Controller/TaskController.php
-
         use App\Entity\Task;
         use Doctrine\Common\Collections\ArrayCollection;
 
@@ -711,6 +716,6 @@ the relationship between the removed ``Tag`` and ``Task`` object.
     elements of the collection. More advanced functionality like moving or duplicating
     an element in the collection and customizing the buttons is also possible.
 
-.. _`Owning Side and Inverse Side`: http://docs.doctrine-project.org/en/latest/reference/unitofwork-associations.html
+.. _`Owning Side and Inverse Side`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/unitofwork-associations.html
 .. _`JSFiddle`: http://jsfiddle.net/847Kf/4/
 .. _`symfony-collection`: https://github.com/ninsuo/symfony-collection
diff --git a/form/form_customization.rst b/form/form_customization.rst
index 0aaa095ae6c..3094eb08f40 100644
--- a/form/form_customization.rst
+++ b/form/form_customization.rst
@@ -86,7 +86,7 @@ Some of the Twig functions mentioned in the previous section allow to pass
 variables to configure their behavior. For example, the ``form_label()``
 function lets you define a custom label to override the one defined in the form:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ form_label(form.task, 'My Custom Task Label') }}
 
@@ -96,7 +96,7 @@ type, but one common option is ``attr``, which allows you to modify HTML
 attributes on the form element. The following would add the ``task_field`` CSS
 class to the rendered input text field:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ form_widget(form.task, {'attr': {'class': 'task_field'}}) }}
 
@@ -116,7 +116,7 @@ If you need to render form fields "by hand" then you can access individual
 values for fields (such as the ``id``, ``name`` and ``label``) using its
 ``vars``  property. For example to get the ``id``:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ form.task.vars.id }}
 
@@ -305,13 +305,25 @@ form_rest(form_view, variables)
 
 This renders all fields that have not yet been rendered for the given form.
 It's a good idea to always have this somewhere inside your form as it'll
-render hidden fields for you and make any fields you forgot to render more
-obvious (since it'll render the field for you).
+render hidden fields for you and make any fields you forgot to render easier to
+spot (since it'll render the field for you).
 
 .. code-block:: twig
 
     {{ form_rest(form) }}
 
+form_parent(form_view)
+......................
+
+.. versionadded:: 4.3
+
+    The ``form_parent()`` function was introduced in Symfony 4.3.
+
+Returns the parent form view or ``null`` if the form view already is the
+root form. Using this function should be preferred over accessing the parent
+form using ``form.parent``. The latter way will produce different results
+when a child form is named ``parent``.
+
 Tests
 ~~~~~
 
@@ -327,7 +339,7 @@ This test will check if the current choice is equal to the ``selected_value``
 or if the current choice is in the array (when ``selected_value`` is an
 array).
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <option {% if choice is selectedchoice(value) %}selected="selected"{% endif %} ...>
 
@@ -384,7 +396,7 @@ Variable                Usage
 ``block_prefixes``      An array of all the names of the parent types.
 ``cache_key``           A unique key which is used for caching.
 ``compound``            Whether or not a field is actually a holder for a group of children fields
-                        (for example, a ``choice`` field, which is actually a group of checkboxes.
+                        (for example, a ``choice`` field, which is actually a group of checkboxes).
 ``data``                The normalized data of the type.
 ``disabled``            If ``true``, ``disabled="disabled"`` is added to the field.
 ``errors``              An array of any errors attached to *this* specific field (e.g. ``form.title.errors``).
diff --git a/form/form_dependencies.rst b/form/form_dependencies.rst
index da91286be5a..96b067362ff 100644
--- a/form/form_dependencies.rst
+++ b/form/form_dependencies.rst
@@ -1,145 +1,12 @@
 How to Access Services or Config from Inside a Form
 ===================================================
 
-Sometimes, you may need to access a :doc:`service </service_container>` or other
-configuration from inside of your form class. To do this, you have 2 options:
-
-1) Pass Options to your Form
-----------------------------
-
-The simplest way to pass services or configuration to your form is via form *options*.
-Suppose you need to access the Doctrine entity manager so that you can make a
-query. First, allow (in fact, require) a new ``entity_manager`` option to be
-passed to your form::
-
-    // src/Form/TaskType.php
-    // ...
-
-    class TaskType extends AbstractType
-    {
-        // ...
-
-        public function configureOptions(OptionsResolver $resolver)
-        {
-            // ...
-
-            $resolver->setRequired('entity_manager');
-        }
-    }
-
-Now that you've done this, you *must* pass an ``entity_manager`` option when you
-create your form::
-
-    // src/Controller/DefaultController.php
-    use App\Form\TaskType;
-
-    // ...
-    public function new()
-    {
-        $entityManager = $this->getDoctrine()->getManager();
-
-        $task = ...;
-        $form = $this->createForm(TaskType::class, $task, [
-            'entity_manager' => $entityManager,
-        ]);
-
-        // ...
-    }
-
-Finally, the ``entity_manager`` option is accessible in the ``$options`` argument
-of your ``buildForm()`` method::
-
-    // src/Form/TaskType.php
-    // ...
-
-    class TaskType extends AbstractType
-    {
-        public function buildForm(FormBuilderInterface $builder, array $options)
-        {
-            /** @var \Doctrine\ORM\EntityManager $entityManager */
-            $entityManager = $options['entity_manager'];
-            // ...
-        }
-
-        // ...
-    }
-
-Use this method to pass *anything* to your form.
-
-2) Define your Form as a Service
---------------------------------
-
-Alternatively, you can define your form class as a service. This is a good idea if
-you want to re-use the form in several places - registering it as a service makes
-this easier.
-
-Suppose you need to access the :ref:`EntityManager <doctrine-entity-manager>` object
-so that you can make a query. First, add this as an argument to your form class::
-
-    // src/Form/TaskType.php
-
-    use Doctrine\ORM\EntityManagerInterface;
-    // ...
-
-    class TaskType extends AbstractType
-    {
-        private $entityManager;
-
-        public function __construct(EntityManagerInterface $entityManager)
-        {
-            $this->entityManager = $entityManager;
-        }
-
-        // ...
-    }
-
-If you're using :ref:`autowire <services-autowire>` and
-:ref:`autoconfigure <services-autoconfigure>`, then you don't need to do *anything*
-else: Symfony will automatically know how to pass the correct ``EntityManager`` object
-to your ``__construct()`` method.
-
-If you are **not using autowire and autoconfigure**, register your form as a service
-manually and tag it with ``form.type``:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        services:
-            App\Form\TaskType:
-                arguments: ['@doctrine.orm.entity_manager']
-                tags: [form.type]
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <service id="App\Form\TaskType">
-                    <argument type="service" id="doctrine.orm.entity_manager"/>
-                    <tag name="form.type" />
-                </service>
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        use App\Form\TaskType;
-        use Symfony\Component\DependencyInjection\Reference;
-
-        $container->register(TaskType::class)
-            ->addArgument(new Reference('doctrine.orm.entity_manager'))
-            ->addTag('form.type')
-        ;
-
-That's it! Your controller - where you create the form - doesn't need to change
-at all: Symfony is smart enough to load the ``TaskType`` from the container.
-
-Read :ref:`form-field-service` for more information.
+The content of this article is no longer relevant because in current Symfony
+versions, form classes are services by default and you can inject services in
+them using the :doc:`service autowiring </service_container/autowiring>` feature.
+
+Read the article about :doc:`creating custom form types </form/create_custom_field_type>`
+to see an example of how to inject the database service into a form type. In the
+same article you can also read about
+:ref:`configuration options for form types <form-type-config-options>`, which is
+another way of passing services to forms.
diff --git a/form/form_themes.rst b/form/form_themes.rst
index ea34a773d22..10241797e66 100644
--- a/form/form_themes.rst
+++ b/form/form_themes.rst
@@ -15,11 +15,12 @@ Symfony Built-In Form Themes
 
 Symfony comes with several **built-in form themes** that make your forms look
 great when using some of the most popular CSS frameworks. Each theme is defined
-in a single Twig template:
+in a single Twig template and they are enabled in the
+:ref:`twig.form_themes <config-twig-form-themes>` option:
 
 * `form_div_layout.html.twig`_, wraps each form field inside a ``<div>`` element
-  and it's the theme used by default in Symfony apps unless you configure it as
-  explained later in this article.
+  and it's the theme used by default in Symfony applications unless you configure
+  it as explained later in this article.
 * `form_table_layout.html.twig`_, wraps the entire form inside a ``<table>``
   element and each form field inside a ``<tr>`` element.
 * `bootstrap_3_layout.html.twig`_, wraps each form field inside a ``<div>``
@@ -68,8 +69,8 @@ want to use another theme for all the forms of your app, configure it in the
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <twig:form-theme>bootstrap_4_horizontal_layout.html.twig</twig:form-theme>
@@ -102,7 +103,7 @@ Although most of the times you'll apply form themes globally, you may need to
 apply a theme only to some specific form. You can do that with the
 :ref:`form_theme Twig tag <reference-twig-tag-form-theme>`:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {# this form theme will be applied only to the form of this template #}
     {% form_theme form 'foundation_5_layout.html.twig' %}
@@ -122,7 +123,7 @@ A form can also be customized by applying several themes. To do this, pass the
 path of all the Twig templates as an array using the ``with`` keyword (their
 order is important, because each theme overrides all the previous ones):
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {# apply multiple form themes but only to the form of this template #}
     {% form_theme form with [
@@ -137,14 +138,14 @@ Applying Different Themes to Child Forms
 
 You can also apply a form theme to a specific child of your form:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {% form_theme form.a_child_form 'form/my_custom_theme.html.twig' %}
 
 This is useful when you want to have a custom theme for a nested form that's
 different than the one of your main form. Specify both your themes:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {% form_theme form 'form/my_custom_theme.html.twig' %}
     {% form_theme form.a_child_form 'form/my_other_theme.html.twig' %}
@@ -157,11 +158,11 @@ Disabling Global Themes for Single Forms
 Global form themes defined in the app are always applied to all forms, even
 those which use the ``form_theme`` tag to apply their own themes. You may want
 to disable this for example when creating an admin interface for a bundle which
-can be installed on different Symfony apps (and so you can't control what themes
-are enabled globally). To do that, add the ``only`` keyword after the list of
-form themes:
+can be installed on different Symfony applications (and so you can't control what
+themes are enabled globally). To do that, add the ``only`` keyword after the list
+of form themes:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {% form_theme form with ['foundation_5_layout.html.twig'] only %}
 
@@ -175,13 +176,15 @@ form themes:
     yourself, or extend one of the built-in form themes with Twig's ``use``
     keyword instead of ``extends`` to re-use the original theme contents.
 
-    .. code-block:: html+twig
+    .. code-block:: twig
 
         {# templates/form/common.html.twig #}
         {% use "form_div_layout.html.twig" %}
 
         {# ... #}
 
+.. _create-your-own-form-theme:
+
 Creating your Own Form Theme
 ----------------------------
 
@@ -192,7 +195,7 @@ with one or more of those blocks that you want to use when rendering a form.
 Consider for example a form field that represents an integer property called
 ``age``. If you add this to the template:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ form_widget(form.age) }}
 
@@ -201,7 +204,7 @@ upon the form themes enabled in your app):
 
 .. code-block:: html
 
-    <input type="number" id="form_age" name="form[age]" required="required" value="33" />
+    <input type="number" id="form_age" name="form[age]" required="required" value="33"/>
 
 Symfony uses a Twig block called ``integer_widget`` to render that field. This
 is because the field type is ``integer`` and you're rendering its ``widget`` (as
@@ -260,8 +263,8 @@ based on your form type name (e.g. ``ProductType`` equates to ``product``). If
 you're not sure what your form name is, look at the HTML code rendered for your
 form. You can also define this value explicitly with the ``block_name`` option::
 
-    use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
@@ -275,15 +278,98 @@ form. You can also define this value explicitly with the ``block_name`` option::
 In this example, the fragment name will be ``_product_custom_name_widget``
 instead of the default ``_product_name_widget``.
 
+.. _form-fragment-custom-naming:
+
+Custom Fragment Naming for Individual Fields
+............................................
+
+The ``block_prefix`` option allows form fields to define their own custom
+fragment name. This is mostly useful to customize some instances of the same
+field without having to :doc:`create a custom form type </form/create_custom_field_type>`::
+
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
+
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder->add('name', TextType::class, [
+            'block_prefix' => 'wrapped_text',
+        ]);
+    }
+
+.. versionadded:: 4.3
+
+    The ``block_prefix`` option was introduced in Symfony 4.3.
+
+Now you can use ``wrapped_text_row``, ``wrapped_text_widget``, etc. as the block
+names.
+
 .. _form-custom-prototype:
 
 Fragment Naming for Collections
 ...............................
 
 When using a :doc:`collection of forms </form/form_collections>`, the fragment
-of each collection item follows the pattern ``_field-name_entry_part``. For
-example, if your form field is named ``tasks``, the fragment for each task will
-be named ``_tasks_entry`` (``_tasks_entry_label``, ``_tasks_entry_label``, etc.)
+of each collection item follows a predefined pattern. For example, consider the
+following complex example where a ``TaskManagerType`` has a collection of
+``TaskListType`` which in turn has a collection of ``TaskType``::
+
+    class TaskManagerType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options = [])
+        {
+            // ...
+            $builder->add('taskLists', CollectionType::class, [
+                'entry_type' => TaskListType::class,
+                'block_name' => 'task_lists',
+            ]);
+        }
+    }
+
+    class TaskListType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options = [])
+        {
+            // ...
+            $builder->add('tasks', CollectionType::class, [
+                'entry_type' => TaskType::class,
+            ]);
+        }
+    }
+
+    class TaskType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options = [])
+        {
+            $builder->add('name');
+            // ...
+        }
+    }
+
+Then you get all the following customizable blocks (where ``*`` can be replaced
+by ``row``, ``widget``, ``label``, or ``help``):
+
+.. code-block:: twig
+
+    {% block _task_manager_task_lists_* %}
+        {# the collection field of TaskManager #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_* %}
+        {# the inner TaskListType #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_tasks_* %}
+        {# the collection field of TaskListType #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_tasks_entry_* %}
+        {# the inner TaskType #}
+    {% endblock %}
+
+    {% block _task_manager_task_lists_entry_tasks_entry_name_* %}
+        {# the field of TaskType #}
+    {% endblock %}
 
 Template Fragment Inheritance
 .............................
@@ -314,6 +400,8 @@ for any overridden form blocks:
 
 .. code-block:: html+twig
 
+    {% extends 'base.html.twig' %}
+
     {% form_theme form _self %}
 
     {# this overrides the widget of any field of type integer, but only in the
@@ -332,25 +420,29 @@ for any overridden form blocks:
         </div>
     {% endblock %}
 
-
     {# ... render the form ... #}
 
-The disadvantage of this method is that the customized form blocks can't be
-reused when rendering other forms in other templates. If that's what you need,
-create a form theme in a separate template as explained in the next section.
+The main disadvantage of this method is that it only works if your template
+extends another (``'base.html.twig'`` in the previous example). If your template
+does not, you must point ``form_theme`` to a separate template, as explained in
+the next section.
+
+Another disadvantage is that the customized form blocks can't be reused when
+rendering other forms in other templates. If that's what you need, create a form
+theme in a separate template as explained in the next section.
 
 Creating a Form Theme in a Separate Template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is recommended when creating form themes that are used in your entire app
-or even reused in different Symfony apps. You only need to create a Twig
+or even reused in different Symfony applications. You only need to create a Twig
 template somewhere and follow the :ref:`form fragment naming <form-fragment-naming>`
 rules to know which Twig blocks to define.
 
 For example, if your form theme is simple and you only want to override the
 ``<input type="integer">`` elements, create this template:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {# templates/form/my_theme.html.twig #}
     {% block integer_widget %}
@@ -381,8 +473,8 @@ you want to apply the theme globally to all forms, define the
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <twig:form-theme>form/my_theme.html.twig</twig:form-theme>
@@ -402,7 +494,7 @@ you want to apply the theme globally to all forms, define the
 
 If you only want to apply it to some specific forms, use the ``form_theme`` tag:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {% form_theme form 'form/my_theme.html.twig' %}
 
@@ -426,7 +518,7 @@ built-in themes using the `Twig "use" tag`_ instead of the ``extends`` tag so
 you can inherit all its blocks (if you are unsure, extend from the default
 ``form_div_layout.html.twig`` theme):
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {# templates/form/my_theme.html.twig #}
     {% use 'form_div_layout.html.twig' %}
@@ -466,7 +558,6 @@ bit more complicated:
         </div>
     {% endblock %}
 
-
     {# ... render the form ... #}
 
 Customizing the Form Validation Errors
@@ -503,9 +594,6 @@ is a collection of fields (e.g. a whole form), and not just an individual field:
         {% endif %}
     {% endblock form_errors %}
 
-.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
-.. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig
-.. _`view on GitHub`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form
 .. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
 .. _`form_table_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig
 .. _`bootstrap_3_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig
diff --git a/form/inherit_data_option.rst b/form/inherit_data_option.rst
index 28dfce214ab..113e66d6381 100644
--- a/form/inherit_data_option.rst
+++ b/form/inherit_data_option.rst
@@ -47,8 +47,8 @@ Start with building two forms for these entities, ``CompanyType`` and ``Customer
     namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
-    use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
     class CompanyType extends AbstractType
     {
@@ -65,9 +65,9 @@ Start with building two forms for these entities, ``CompanyType`` and ``Customer
     // src/Form/Type/CustomerType.php
     namespace App\Form\Type;
 
-    use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
     class CustomerType extends AbstractType
     {
@@ -87,10 +87,10 @@ for that::
     namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
-    use Symfony\Component\Form\FormBuilderInterface;
-    use Symfony\Component\OptionsResolver\OptionsResolver;
     use Symfony\Component\Form\Extension\Core\Type\TextareaType;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class LocationType extends AbstractType
     {
diff --git a/form/type_guesser.rst b/form/type_guesser.rst
index 5c88e75bf45..dc7e059b6a0 100644
--- a/form/type_guesser.rst
+++ b/form/type_guesser.rst
@@ -86,12 +86,12 @@ With this knowledge, you can implement the ``guessType()`` method of the
 
     namespace App\Form\TypeGuesser;
 
-    use Symfony\Component\Form\Guess\Guess;
-    use Symfony\Component\Form\Guess\TypeGuess;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
     use Symfony\Component\Form\Extension\Core\Type\IntegerType;
     use Symfony\Component\Form\Extension\Core\Type\NumberType;
-    use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\Guess\Guess;
+    use Symfony\Component\Form\Guess\TypeGuess;
 
     class PHPDocTypeGuesser implements FormTypeGuesserInterface
     {
@@ -198,7 +198,7 @@ and tag it with ``form.type_guesser``:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Form\TypeGuesser\PHPDocTypeGuesser">
@@ -223,8 +223,8 @@ and tag it with ``form.type_guesser``:
     :method:`Symfony\\Component\\Form\\FormFactoryBuilder::addTypeGuessers` of
     the ``FormFactoryBuilder`` to register new type guessers::
 
-        use Symfony\Component\Form\Forms;
         use Acme\Form\PHPDocTypeGuesser;
+        use Symfony\Component\Form\Forms;
 
         $formFactory = Forms::createFormFactoryBuilder()
             // ...
@@ -232,3 +232,12 @@ and tag it with ``form.type_guesser``:
             ->getFormFactory();
 
         // ...
+
+.. tip::
+
+    Run the following command to verify that the form type guesser was
+    successfully registered in the application:
+
+    .. code-block:: terminal
+
+        $ php bin/console debug:form
diff --git a/form/unit_testing.rst b/form/unit_testing.rst
index 2256d114fe9..5a94152892b 100644
--- a/form/unit_testing.rst
+++ b/form/unit_testing.rst
@@ -182,31 +182,22 @@ allows you to return a list of extensions to register::
     namespace App\Tests\Form\Type;
 
     // ...
-    use App\Form\Type\TestedType;
     use Symfony\Component\Form\Extension\Validator\ValidatorExtension;
-    use Symfony\Component\Form\Form;
-    use Symfony\Component\Validator\ConstraintViolationList;
-    use Symfony\Component\Validator\Mapping\ClassMetadata;
-    use Symfony\Component\Validator\Validator\ValidatorInterface;
+    use Symfony\Component\Validator\Validation;
 
     class TestedTypeTest extends TypeTestCase
     {
-        private $validator;
-
         protected function getExtensions()
         {
-            $this->validator = $this->createMock(ValidatorInterface::class);
-            // use getMock() on PHPUnit 5.3 or below
-            // $this->validator = $this->getMock(ValidatorInterface::class);
-            $this->validator
-                ->method('validate')
-                ->will($this->returnValue(new ConstraintViolationList()));
-            $this->validator
-                ->method('getMetadataFor')
-                ->will($this->returnValue(new ClassMetadata(Form::class)));
+            $validator = Validation::createValidator();
+
+            // or if you also need to read constraints from annotations
+            $validator = Validation::createValidatorBuilder()
+                ->enableAnnotationMapping()
+                ->getValidator();
 
             return [
-                new ValidatorExtension($this->validator),
+                new ValidatorExtension($validator),
             ];
         }
 
diff --git a/form/use_empty_data.rst b/form/use_empty_data.rst
index 5e2b8c2b16a..c186396f8e4 100644
--- a/form/use_empty_data.rst
+++ b/form/use_empty_data.rst
@@ -46,8 +46,8 @@ that constructor with no arguments::
     // src/Form/Type/BlogType.php
 
     // ...
-    use Symfony\Component\Form\AbstractType;
     use App\Entity\Blog;
+    use Symfony\Component\Form\AbstractType;
     use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class BlogType extends AbstractType
@@ -75,7 +75,11 @@ The point is, you can set ``empty_data`` to the exact "new" object that you want
 .. tip::
 
     In order to pass arguments to the ``BlogType`` constructor, you'll need to
-    :doc:`register it as a service and tag with form.type </form/form_dependencies>`.
+    :ref:`register the form as a service <service-container-creating-service>`
+    and :doc:`tag it </service_container/tags>` with ``form.type``.
+    If you're using the
+    :ref:`default services.yaml configuration <service-container-services-load-example>`,
+    this is already done for you.
 
 .. _forms-empty-data-closure:
 
@@ -87,8 +91,8 @@ if it is needed.
 
 The closure must accept a ``FormInterface`` instance as the first argument::
 
-    use Symfony\Component\OptionsResolver\OptionsResolver;
     use Symfony\Component\Form\FormInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
     // ...
 
     public function configureOptions(OptionsResolver $resolver)
diff --git a/form/validation_groups.rst b/form/validation_groups.rst
index 2b8d87e43e5..09b420bceaf 100644
--- a/form/validation_groups.rst
+++ b/form/validation_groups.rst
@@ -8,21 +8,22 @@ Validation Groups
 -----------------
 
 If your object takes advantage of :doc:`validation groups </validation/groups>`,
-you'll need to specify which validation group(s) your form should use::
+you'll need to specify which validation group(s) your form should use. Pass
+this as an option when :ref:`creating forms in controllers <creating-forms-in-controllers>`::
 
     $form = $this->createFormBuilder($user, [
         'validation_groups' => ['registration'],
     ])->add(...);
 
-If you're creating :ref:`form classes <form-creating-form-classes>` (a good
-practice), then you'll need to add the following to the ``configureOptions()``
-method::
+When :ref:`creating forms in classes <creating-forms-in-classes>`, add the
+following to the ``configureOptions()`` method::
 
     use Symfony\Component\OptionsResolver\OptionsResolver;
 
     public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults([
+            // ...
             'validation_groups' => ['registration'],
         ]);
     }
diff --git a/form/without_class.rst b/form/without_class.rst
index 59330706696..440df791b2a 100644
--- a/form/without_class.rst
+++ b/form/without_class.rst
@@ -79,23 +79,23 @@ The answer is to setup the constraints yourself, and attach them to the individu
 fields. The overall approach is covered a bit more in :doc:`this validation article </validation/raw_values>`,
 but here's a short example::
 
-    use Symfony\Component\Validator\Constraints\Length;
-    use Symfony\Component\Validator\Constraints\NotBlank;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\FormBuilderInterface;
+    use Symfony\Component\Validator\Constraints\Length;
+    use Symfony\Component\Validator\Constraints\NotBlank;
 
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
         $builder
-           ->add('firstName', TextType::class, [
-               'constraints' => new Length(['min' => 3]),
-           ])
-           ->add('lastName', TextType::class, [
-               'constraints' => [
-                   new NotBlank(),
-                   new Length(['min' => 3]),
-               ],
-           ])
+            ->add('firstName', TextType::class, [
+                'constraints' => new Length(['min' => 3]),
+            ])
+            ->add('lastName', TextType::class, [
+                'constraints' => [
+                    new NotBlank(),
+                    new Length(['min' => 3]),
+                ],
+            ])
         ;
     }
 
@@ -103,9 +103,7 @@ but here's a short example::
 
     If you are using validation groups, you need to either reference the
     ``Default`` group when creating the form, or set the correct group on
-    the constraint you are adding.
-
-    .. code-block:: php
+    the constraint you are adding::
 
         new NotBlank(['groups' => ['create', 'update']]);
 
diff --git a/forms.rst b/forms.rst
index 1c99b1cb23c..93eb622f8a0 100644
--- a/forms.rst
+++ b/forms.rst
@@ -9,37 +9,37 @@ Forms
 
     Do you prefer video tutorials? Check out the `Symfony Forms screencast series`_.
 
-Dealing with HTML forms is one of the most common - and challenging - tasks for
-a web developer. Symfony integrates a Form component that makes dealing with
-forms easy. In this article, you'll build a complex form from the ground up,
-learning the most important features of the form library along the way.
+Creating and processing HTML forms is hard and repetitive. You need to deal with
+rendering HTML form fields, validating submitted data, mapping the form data
+into objects and a lot more. Symfony includes a powerful form feature that
+provides all these features and many more for truly complex scenarios.
 
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the form feature before using it:
 
 .. code-block:: terminal
 
     $ composer require symfony/form
 
-.. note::
+Usage
+-----
 
-    The Symfony Form component is a standalone library that can be used outside
-    of Symfony projects. For more information, see the
-    :doc:`Form component documentation </components/form>` on GitHub.
+The recommended workflow when working with Symfony forms is the following:
 
-.. index::
-   single: Forms; Create a simple form
+#. **Build the form** in a Symfony controller or using a dedicated form class;
+#. **Render the form** in a template so the user can edit and submit it;
+#. **Process the form** to validate the submitted data, transform it into PHP
+   data and do something with it (e.g. persist it in a database).
 
-Creating a Simple Form
-----------------------
+Each of these steps is explained in detail in the next sections. To make
+examples easier to follow, all of them assume that you're building a simple Todo
+list application that displays "tasks".
 
-Suppose you're building a simple todo list application that will need to
-display "tasks". Because your users will need to edit and create tasks, you're
-going to need to build a form. But before you begin, first focus on the generic
-``Task`` class that represents and stores the data for a single task::
+Users create and edit tasks using Symfony forms. Each task is an instance of the
+following ``Task`` class::
 
     // src/Entity/Task.php
     namespace App\Entity;
@@ -70,39 +70,64 @@ going to need to build a form. But before you begin, first focus on the generic
         }
     }
 
-This class is a "plain-old-PHP-object" because, so far, it has nothing
-to do with Symfony or any other library. It's a normal PHP object
-that directly solves a problem inside *your* application (i.e. the need to
-represent a task in your application). By the end of this article,
-you'll be able to submit data to a ``Task`` instance (via an HTML form), validate
-its data and persist it to the database.
+This class is a "plain-old-PHP-object" because, so far, it has nothing to do
+with Symfony or any other library. It's a normal PHP object that directly solves
+a problem inside *your* application (i.e. the need to represent a task in your
+application). But you can also edit :doc:`Doctrine entities </doctrine>` in the
+same way.
 
-.. index::
-   single: Forms; Create a form in a controller
+.. _form-types:
 
-Building the Form
-~~~~~~~~~~~~~~~~~
+Form Types
+~~~~~~~~~~
+
+Before creating your first Symfony form, it's important to understand the
+concept of "form type". In other projects, it's common to differentiate between
+"forms" and "form fields". In Symfony, all of them are "form types":
+
+* a single ``<input type="text">`` form field is a "form type" (e.g. ``TextType``);
+* a group of several HTML fields used to input a postal address is a "form type"
+  (e.g. ``PostalAddressType``);
+* an entire ``<form>`` with multiple fields to edit a user profile is a
+  "form type" (e.g. ``UserProfileType``).
+
+This may be confusing at first, but it will feel natural to you soon enough.
+Besides, it simplifies code and makes "composing" and "embedding" form fields
+much easier to implement.
+
+There are tens of :doc:`form types provided by Symfony </reference/forms/types>`
+and you can also :doc:`create your own form types </form/create_custom_field_type>`.
+
+Building Forms
+--------------
+
+Symfony provides a "form builder" object which allows you to describe the form
+fields using a fluent interface. Later, this builder creates the actual form
+object used to render and process contents.
+
+.. _creating-forms-in-controllers:
 
-Now that you've created a ``Task`` class, the next step is to create and
-render the actual HTML form. In Symfony, this is done by building a form
-object and then rendering it in a template. For now, this can all be done
-from inside a controller::
+Creating Forms in Controllers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your controller extends from the :ref:`AbstractController <the-base-controller-class-services>`,
+use the ``createFormBuilder()`` helper::
 
     // src/Controller/TaskController.php
     namespace App\Controller;
 
     use App\Entity\Task;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-    use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\DateType;
     use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\HttpFoundation\Request;
 
     class TaskController extends AbstractController
     {
         public function new(Request $request)
         {
-            // creates a task and gives it some dummy data for this example
+            // creates a task object and initializes some data for this example
             $task = new Task();
             $task->setTask('Write a blog post');
             $task->setDueDate(new \DateTime('tomorrow'));
@@ -113,119 +138,244 @@ from inside a controller::
                 ->add('save', SubmitType::class, ['label' => 'Create Task'])
                 ->getForm();
 
-            return $this->render('task/new.html.twig', [
-                'form' => $form->createView(),
-            ]);
+            // ...
         }
     }
 
-.. tip::
+If your controller does not extend from ``AbstractController``, you'll need to
+:ref:`fetch services in your controller <controller-accessing-services>` and
+use the ``createBuilder()`` method of the ``form.factory`` service.
 
-    This example shows you how to build your form directly in the controller.
-    Later, in the ":ref:`form-creating-form-classes`" section, you'll learn
-    how to build your form in a standalone class, which is recommended as
-    your form becomes reusable.
+In this example, you've added two fields to your form - ``task`` and ``dueDate``
+- corresponding to the ``task`` and ``dueDate`` properties of the ``Task``
+class. You've also assigned each a :ref:`form type <form-types>` (e.g. ``TextType``
+and ``DateType``), represented by its fully qualified class name. Finally, you
+added a submit button with a custom label for submitting the form to the server.
 
-Creating a form requires relatively little code because Symfony form objects
-are built with a "form builder". The form builder's purpose is to allow you
-to write simple form "recipes" and have it do all the heavy-lifting of actually
-building the form.
+.. _creating-forms-in-classes:
 
-In this example, you've added two fields to your form - ``task`` and ``dueDate`` -
-corresponding to the ``task`` and ``dueDate`` properties of the ``Task`` class.
-You've also assigned each a "type" (e.g. ``TextType`` and ``DateType``),
-represented by its fully qualified class name. Among other things, it determines
-which HTML form tag(s) is rendered for that field.
+Creating Form Classes
+~~~~~~~~~~~~~~~~~~~~~
 
-Finally, you added a submit button with a custom label for submitting the form to
-the server.
+Symfony recommends to :doc:`create thin controllers </best_practices/controllers>`.
+That's why it's better to move complex forms to dedicated classes instead of
+defining them in controller actions. Besides, forms defined in classes can be
+reused in multiple actions and services.
 
-Symfony comes with many built-in types that will be discussed shortly
-(see :ref:`forms-type-reference`).
+Form classes are :ref:`form types <form-types>` that implement
+:class:`Symfony\\Component\\Form\\FormTypeInterface`. However, it's better to
+extend from :class:`Symfony\\Component\\Form\\AbstractType`, which already
+implements the interface and provides some utilities::
 
-.. index::
-  single: Forms; Basic template rendering
+    // src/Form/Type/TaskType.php
+    namespace App\Form\Type;
 
-Rendering the Form
-~~~~~~~~~~~~~~~~~~
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
+    use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
+
+    class TaskType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            $builder
+                ->add('task', TextType::class)
+                ->add('dueDate', DateType::class)
+                ->add('save', SubmitType::class)
+            ;
+        }
+    }
+
+The form class contains all the directions needed to create the task form. In
+controllers extending from the :ref:`AbstractController <the-base-controller-class-services>`,
+use the ``createForm()`` helper (otherwise, use the ``create()`` method of the
+``form.factory`` service)::
+
+    // src/Controller/TaskController.php
+    use App\Form\Type\TaskType;
+    // ...
+
+    class TaskController extends AbstractController
+    {
+        public function new()
+        {
+            // creates a task object and initializes some data for this example
+            $task = new Task();
+            $task->setTask('Write a blog post');
+            $task->setDueDate(new \DateTime('tomorrow'));
+
+            $form = $this->createForm(TaskType::class, $task);
+
+            // ...
+        }
+    }
+
+.. _form-data-class:
+
+Every form needs to know the name of the class that holds the underlying data
+(e.g. ``App\Entity\Task``). Usually, this is just guessed based off of the
+object passed to the second argument to ``createForm()`` (i.e. ``$task``).
+Later, when you begin :doc:`embedding forms </form/embedded>`, this will no
+longer be sufficient.
+
+So, while not always necessary, it's generally a good idea to explicitly specify
+the ``data_class`` option by adding the following to your form type class::
+
+    // src/Form/Type/TaskType.php
+    use App\Entity\Task;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+    // ...
+
+    class TaskType extends AbstractType
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefaults([
+                'data_class' => Task::class,
+            ]);
+        }
+    }
+
+Rendering Forms
+---------------
+
+Now that the form has been created, the next step is to render it. Instead of
+passing the entire form object to the template, use the ``createView()`` method
+to build another object with the visual representation of the form::
+
+    // src/Controller/TaskController.php
+    namespace App\Controller;
+
+    use App\Entity\Task;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
+    use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\HttpFoundation\Request;
 
-Now that the form has been created, the next step is to render it. This is
-done by passing a special form "view" object to your template (notice the
-``$form->createView()`` in the controller above) and using a set of
-:ref:`form helper functions <reference-form-twig-functions>`:
+    class TaskController extends AbstractController
+    {
+        public function new(Request $request)
+        {
+            $task = new Task();
+            // ...
+
+            $form = $this->createForm(TaskType::class, $task);
+
+            return $this->render('task/new.html.twig', [
+                'form' => $form->createView(),
+            ]);
+        }
+    }
+
+Then, use some :ref:`form helper functions <reference-form-twig-functions>` to
+render the form contents:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {# templates/task/new.html.twig #}
     {{ form(form) }}
 
-.. image:: /_images/form/simple-form.png
-    :align: center
-
 That's it! The :ref:`form() function <reference-forms-twig-form>` renders all
 fields *and* the ``<form>`` start and end tags. By default, the form method is
-``POST`` and the target URL is the same that displayed the form.
-
-As easy as this is, it's not very flexible. Usually, you'll need more control
-about how the entire form or some of its fields look. Symfony provides several
-ways of doing that:
-
-* If your app uses a CSS framework such as Bootstrap or Foundation, use any of
-  the :ref:`built-in form themes <symfony-builtin-forms>` to make all your forms
-  match the style of the rest of your app;
-* If you want to customize only a few fields or a few forms of your app, read
-  the :doc:`How to Customize Form Rendering </form/form_customization>` article;
-* If you want to customize all your forms in the same way, create a
-  :doc:`Symfony form theme </form/form_themes>` (based on any of the built-in
-  themes or from scratch).
-
-Before moving on, notice how the rendered ``task`` input field has the value
-of the ``task`` property from the ``$task`` object (i.e. "Write a blog post").
-This is the first job of a form: to take data from an object and translate
-it into a format that's suitable for being rendered in an HTML form.
+``POST`` and the target URL is the same that displayed the form, but
+:ref:`you can change both <forms-change-action-method>`.
+
+Notice how the rendered ``task`` input field has the value of the ``task``
+property from the ``$task`` object (i.e. "Write a blog post"). This is the first
+job of a form: to take data from an object and translate it into a format that's
+suitable for being rendered in an HTML form.
 
 .. tip::
 
     The form system is smart enough to access the value of the protected
     ``task`` property via the ``getTask()`` and ``setTask()`` methods on the
     ``Task`` class. Unless a property is public, it *must* have a "getter" and
-    "setter" method so that the Form component can get and put data onto the
-    property. For a boolean property, you can use an "isser" or "hasser" method
-    (e.g. ``isPublished()`` or ``hasReminder()``) instead of a getter (e.g.
+    "setter" method so that Symfony can get and put data onto the property. For
+    a boolean property, you can use an "isser" or "hasser" method (e.g.
+    ``isPublished()`` or ``hasReminder()``) instead of a getter (e.g.
     ``getPublished()`` or ``getReminder()``).
 
-.. index::
-  single: Forms; Handling form submissions
+As short as this rendering is, it's not very flexible. Usually, you'll need more
+control about how the entire form or some of its fields look. For example, thanks
+to the :doc:`Bootstrap 4 integration with Symfony forms </form/bootstrap4>` you
+can set this option to generate forms compatible with the Bootstrap 4 CSS framework:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/twig.yaml
+        twig:
+            form_themes: ['bootstrap_4_layout.html.twig']
+
+    .. code-block:: xml
+
+        <!-- config/packages/twig.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <twig:config>
+                <twig:form-theme>bootstrap_4_layout.html.twig</twig:form-theme>
+                <!-- ... -->
+            </twig:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/twig.php
+        $container->loadFromExtension('twig', [
+            'form_themes' => [
+                'bootstrap_4_layout.html.twig',
+            ],
+
+            // ...
+        ]);
 
-.. _form-handling-form-submissions:
+The :ref:`built-in Symfony form themes <symfony-builtin-forms>` include
+Bootstrap 3 and 4 and Foundation 5. You can also
+:ref:`create your own Symfony form theme <create-your-own-form-theme>`.
 
-Handling Form Submissions
-~~~~~~~~~~~~~~~~~~~~~~~~~
+In addition to form themes, Symfony allows you to
+:doc:`customize the way fields are rendered </form/form_customization>` with
+multiple functions to render each field part separately (widgets, labels,
+errors, help messages, etc.)
 
-By default, the form will submit a POST request back to the same controller that
-renders it.
+.. _processing-forms:
 
-Here, the second job of a form is to translate user-submitted data back to the
-properties of an object. To make this happen, the submitted data from the
-user must be written into the Form object. Add the following functionality to
-your controller::
+Processing Forms
+----------------
+
+The :ref:`recommended way of processing forms <best-practice-handle-form>` is to
+use a single action for both rendering the form and handling the form submit.
+You can use separate actions, but using one action simplifies everything while
+keeping the code concise and maintainable.
+
+Processing a form means to translate user-submitted data back to the properties
+of an object. To make this happen, the submitted data from the user must be
+written into the form object::
 
     // ...
     use Symfony\Component\HttpFoundation\Request;
 
     public function new(Request $request)
     {
-        // just setup a fresh $task object (remove the dummy data)
+        // just setup a fresh $task object (remove the example data)
         $task = new Task();
 
-        $form = $this->createFormBuilder($task)
-            ->add('task', TextType::class)
-            ->add('dueDate', DateType::class)
-            ->add('save', SubmitType::class, ['label' => 'Create Task'])
-            ->getForm();
+        $form = $this->createForm(TaskType::class, $task);
 
         $form->handleRequest($request);
-
         if ($form->isSubmitted() && $form->isValid()) {
             // $form->getData() holds the submitted values
             // but, the original `$task` variable has also been updated
@@ -245,25 +395,17 @@ your controller::
         ]);
     }
 
-.. caution::
-
-    Be aware that the ``createView()`` method should be called *after* ``handleRequest()``
-    is called. Otherwise, changes done in the ``*_SUBMIT`` events aren't applied to the
-    view (like validation errors).
-
 This controller follows a common pattern for handling forms and has three
 possible paths:
 
-#. When initially loading the page in a browser, the form is created and
-   rendered. :method:`Symfony\\Component\\Form\\FormInterface::handleRequest`
-   recognizes that the form was not submitted and does nothing.
-   :method:`Symfony\\Component\\Form\\FormInterface::isSubmitted` returns ``false``
-   if the form was not submitted.
+#. When initially loading the page in a browser, the form hasn't been submitted
+   yet and ``$form->isSubmitted()`` returns ``false``. So, the form is created
+   and rendered;
 
 #. When the user submits the form, :method:`Symfony\\Component\\Form\\FormInterface::handleRequest`
    recognizes this and immediately writes the submitted data back into the
    ``task`` and ``dueDate`` properties of the ``$task`` object. Then this object
-   is validated. If it is invalid (validation is covered in the next section),
+   is validated (validation is explained in the next section). If it is invalid,
    :method:`Symfony\\Component\\Form\\FormInterface::isValid` returns
    ``false`` and the form is rendered again, but now with validation errors;
 
@@ -271,34 +413,36 @@ possible paths:
    written into the form, but this time :method:`Symfony\\Component\\Form\\FormInterface::isValid`
    returns ``true``. Now you have the opportunity to perform some actions using
    the ``$task`` object (e.g. persisting it to the database) before redirecting
-   the user to some other page (e.g. a "thank you" or "success" page).
+   the user to some other page (e.g. a "thank you" or "success" page);
 
-   .. note::
+.. note::
 
-      Redirecting a user after a successful form submission prevents the user
-      from being able to hit the "Refresh" button of their browser and re-post
-      the data.
+    Redirecting a user after a successful form submission is a best practice
+    that prevents the user from being able to hit the "Refresh" button of
+    their browser and re-post the data.
+
+.. caution::
+
+    The ``createView()`` method should be called *after* ``handleRequest()`` is
+    called. Otherwise, when using :doc:`form events </form/events>`, changes done
+    in the ``*_SUBMIT`` events won't be applied to the view (like validation errors).
 
 .. seealso::
 
     If you need more control over exactly when your form is submitted or which
-    data is passed to it, you can use the :method:`Symfony\\Component\\Form\\FormInterface::submit`
-    method. Read more about it :ref:`form-call-submit-directly`.
-
-.. index::
-   single: Forms; Validation
+    data is passed to it, you can
+    :doc:`use the submit() method to handle form submissions </form/direct_submit>`.
 
-.. _forms-form-validation:
+.. _validating-forms:
 
-Form Validation
----------------
+Validating Forms
+----------------
 
 In the previous section, you learned how a form can be submitted with valid
-or invalid data. In Symfony, validation is applied to the underlying object
-(e.g. ``Task``). In other words, the question isn't whether the "form" is
-valid, but whether or not the ``$task`` object is valid after the form has
-applied the submitted data to it. Calling ``$form->isValid()`` is a shortcut
-that asks the ``$task`` object whether or not it has valid data.
+or invalid data. In Symfony, the question isn't whether the "form" is valid, but
+whether or not the underlying object (``$task`` in this example) is valid after
+the form has applied the submitted data to it. Calling ``$form->isValid()`` is a
+shortcut that asks the ``$task`` object whether or not it has valid data.
 
 Before using validation, add support for it in your application:
 
@@ -336,7 +480,7 @@ object.
 
     .. code-block:: yaml
 
-        # config/validation.yaml
+        # config/validator/validation.yaml
         App\Entity\Task:
             properties:
                 task:
@@ -347,19 +491,19 @@ object.
 
     .. code-block:: xml
 
-        <!-- config/validation.xml -->
+        <!-- config/validator/validation.xml -->
         <?xml version="1.0" encoding="UTF-8"?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Task">
                 <property name="task">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
                 <property name="dueDate">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                     <constraint name="Type">\DateTime</constraint>
                 </property>
             </class>
@@ -368,9 +512,9 @@ object.
     .. code-block:: php
 
         // src/Entity/Task.php
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints\NotBlank;
         use Symfony\Component\Validator\Constraints\Type;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Task
         {
@@ -389,332 +533,362 @@ object.
         }
 
 That's it! If you re-submit the form with invalid data, you'll see the
-corresponding errors printed out with the form.
+corresponding errors printed out with the form. Read the
+:doc:`Symfony validation documentation </validation>` to learn more about this
+powerful feature.
 
-Validation is a very powerful feature of Symfony and has its own
-:doc:`dedicated article </validation>`.
+Other Common Form Features
+--------------------------
 
-.. _forms-html5-validation-disable:
+Form Type Options
+~~~~~~~~~~~~~~~~~
 
-.. sidebar:: HTML5 Validation
+Each :ref:`form type <form-types>` has a number of options to configure it, as
+explained in the :doc:`Symfony form types reference </reference/forms/types>`.
+Two commonly used options are ``required`` and ``label``.
 
-    Thanks to HTML5, many browsers can natively enforce certain validation constraints
-    on the client side. The most common validation is activated by rendering
-    a ``required`` attribute on fields that are required. For browsers that
-    support HTML5, this will result in a native browser message being displayed
-    if the user tries to submit the form with that field blank.
+The ``required`` Option
+.......................
 
-    Generated forms take full advantage of this new feature by adding sensible
-    HTML attributes that trigger the validation. The client-side validation,
-    however, can be disabled by adding the ``novalidate`` attribute to the
-    ``form`` tag or ``formnovalidate`` to the submit tag. This is especially
-    useful when you want to test your server-side validation constraints,
-    but are being prevented by your browser from, for example, submitting
-    blank fields.
+The most common option is the ``required`` option, which can be applied to any
+field. By default, this option is set to ``true``, meaning that HTML5-ready
+browsers will require to fill in all fields before submitting the form.
 
-    .. code-block:: html+twig
+If you don't want this behavior, either
+:ref:`disable client-side validation <forms-html5-validation-disable>` for the
+entire form or set the ``required`` option to ``false`` on one or more fields::
 
-        {# templates/task/new.html.twig #}
-        {{ form_start(form, {'attr': {'novalidate': 'novalidate'}}) }}
-        {{ form_widget(form) }}
-        {{ form_end(form) }}
+    ->add('dueDate', DateType::class, [
+        'required' => false,
+    ])
 
-.. index::
-   single: Forms; Built-in field types
+The ``required`` option does not perform any server-side validation. If a user
+submits a blank value for the field (either with an old browser or a web
+service, for example), it will be accepted as a valid value unless you also use
+Symfony's ``NotBlank`` or ``NotNull`` validation constraints.
 
-.. _forms-type-reference:
+The ``label`` Option
+....................
 
-Built-in Field Types
---------------------
+By default, the label of form fields are the *humanized* version of the
+property name (``user`` -> ``User``; ``postalAddress`` -> ``Postal Address``).
+Set the ``label`` option on fields to define their labels explicitly::
 
-Symfony comes standard with a large group of field types that cover all of
-the common form fields and data types you'll encounter:
+    ->add('dueDate', DateType::class, [
+        // set it to FALSE to not display the label for this field
+        'label'  => 'To Be Completed Before',
+    ])
 
-.. include:: /reference/forms/types/map.rst.inc
+.. tip::
 
-You can also create your own custom field types. See
-:doc:`/form/create_custom_field_type` for info.
+    By default, ``<label>`` tags of required fields are rendered with a
+    ``required`` CSS class, so you can display an asterisk for required
+    fields applying these CSS styles:
 
-.. index::
-   single: Forms; Field type options
+    .. code-block:: css
 
-Field Type Options
-~~~~~~~~~~~~~~~~~~
+        label.required:before {
+            content: "*";
+        }
 
-Each field type has a number of options that can be used to configure it.
-For example, the ``dueDate`` field is currently being rendered as 3 select
-boxes. However, the :doc:`DateType </reference/forms/types/date>` can be
-configured to be rendered as a single text box (where the user would enter
-the date as a string in the box)::
+.. _forms-change-action-method:
 
-    ->add('dueDate', DateType::class, ['widget' => 'single_text'])
+Changing the Action and HTTP Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. image:: /_images/form/simple-form-2.png
-    :align: center
+By default, a form will be submitted via an HTTP POST request to the same
+URL under which the form was rendered. When building the form in the controller,
+use the ``setAction()`` and ``setMethod()`` methods to change this::
 
-Each field type has a number of different options that can be passed to it.
-Many of these are specific to the field type and details can be found in
-the documentation for each type.
+    // src/Controller/TaskController.php
+    namespace App\Controller;
 
-.. sidebar:: The ``required`` Option
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
+    use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
 
-    The most common option is the ``required`` option, which can be applied to
-    any field. By default, the ``required`` option is set to ``true``, meaning
-    that HTML5-ready browsers will apply client-side validation if the field
-    is left blank. If you don't want this behavior, either
-    :ref:`disable HTML5 validation <forms-html5-validation-disable>`
-    or set the ``required`` option on your field to ``false``::
+    class TaskController extends AbstractController
+    {
+        public function new()
+        {
+            // ...
 
-        ->add('dueDate', DateType::class, [
-            'widget' => 'single_text',
-            'required' => false
-        ])
+            $form = $this->createFormBuilder($task)
+                ->setAction($this->generateUrl('target_route'))
+                ->setMethod('GET')
+                // ...
+                ->getForm();
 
-    Also note that setting the ``required`` option to ``true`` will **not**
-    result in server-side validation to be applied. In other words, if a
-    user submits a blank value for the field (either with an old browser
-    or web service, for example), it will be accepted as a valid value unless
-    you use Symfony's ``NotBlank`` or ``NotNull`` validation constraint.
+            // ...
+        }
+    }
 
-    In other words, the ``required`` option is "nice", but true server-side
-    validation should *always* be used.
+When building the form in a class, pass the action and method as form options::
 
-.. sidebar:: The ``label`` Option
+    // src/Controller/TaskController.php
+    namespace App\Controller;
 
-    The label for the form field can be set using the ``label`` option,
-    which can be applied to any field::
+    use App\Form\TaskType;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
-        ->add('dueDate', DateType::class, [
-            'widget' => 'single_text',
-            'label'  => 'Due Date',
-        ])
+    class TaskController extends AbstractController
+    {
+        public function new()
+        {
+            // ...
 
-    The label for a field can also be set in the template rendering the
-    form, see below. If you don't need a label associated to your input,
-    you can disable it by setting its value to ``false``.
+            $form = $this->createForm(TaskType::class, $task, [
+                'action' => $this->generateUrl('target_route'),
+                'method' => 'GET',
+            ]);
 
-    .. tip::
+            // ...
+        }
+    }
 
-        By default, ``<label>`` tags of required fields are rendered with a
-        ``required`` CSS class, so you can display an asterisk for required
-        fields applying these CSS styles:
+Finally, you can override the action and method in the template by passing them
+to the ``form()`` or the ``form_start()`` helper functions:
 
-        .. code-block:: css
+.. code-block:: twig
 
-            label.required:before {
-                content: "*";
-            }
+    {# templates/task/new.html.twig #}
+    {{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}
 
-.. index::
-   single: Forms; Field type guessing
+.. note::
 
-.. _forms-field-guessing:
+    If the form's method is not ``GET`` or ``POST``, but ``PUT``, ``PATCH`` or
+    ``DELETE``, Symfony will insert a hidden field with the name ``_method``
+    that stores this method. The form will be submitted in a normal ``POST``
+    request, but :doc:`Symfony's routing </routing>` is capable of detecting the
+    ``_method`` parameter and will interpret it as a ``PUT``, ``PATCH`` or
+    ``DELETE`` request. See the :ref:`configuration-framework-http_method_override` option.
 
-Field Type Guessing
--------------------
+Changing the Form Name
+~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you've added validation metadata to the ``Task`` class, Symfony
-already knows a bit about your fields. If you allow it, Symfony can "guess"
-the type of your field and set it up for you. In this example, Symfony can
-guess from the validation rules that both the ``task`` field is a normal
-``TextType`` field and the ``dueDate`` field is a ``DateType`` field::
+If you inspect the HTML contents of the rendered form, you'll see that the
+``<form>`` name and the field names are generated from the type class name
+(e.g. ``<form name="task" ...>`` and ``<select name="task[dueDate][date][month]" ...>``).
 
-    public function new()
-    {
-        $task = new Task();
+If you want to modify this, use the :method:`Symfony\\Component\\Form\\FormFactoryInterface::createNamed`
+method::
 
-        $form = $this->createFormBuilder($task)
-            ->add('task')
-            ->add('dueDate', null, ['widget' => 'single_text'])
-            ->add('save', SubmitType::class)
-            ->getForm();
-    }
+    // src/Controller/TaskController.php
+    use App\Form\TaskType;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
-The "guessing" is activated when you omit the second argument to the ``add()``
-method (or if you pass ``null`` to it). If you pass an options array as the
-third argument (done for ``dueDate`` above), these options are applied to
-the guessed field.
+    class TaskController extends AbstractController
+    {
+        public function newAction()
+        {
+            $task = ...;
+            $form = $this->get('form.factory')->createNamed('my_name', TaskType::class, $task);
 
-.. caution::
+            // ...
+        }
+    }
 
-    If your form uses a specific validation group, the field type guesser
-    will still consider *all* validation constraints when guessing your
-    field types (including constraints that are not part of the validation
-    group(s) being used).
+You can even suppress the name completely by setting it to an empty string.
 
-.. index::
-   single: Forms; Field type guessing
+.. _forms-html5-validation-disable:
 
-Field Type Options Guessing
+Client-Side HTML Validation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In addition to guessing the "type" for a field, Symfony can also try to guess
-the correct values of a number of field options.
-
-.. tip::
-
-    When these options are set, the field will be rendered with special HTML
-    attributes that provide for HTML5 client-side validation. However, it
-    doesn't generate the equivalent server-side constraints (e.g. ``Assert\Length``).
-    And though you'll need to manually add your server-side validation, these
-    field type options can then be guessed from that information.
-
-``required``
-    The ``required`` option can be guessed based on the validation rules (i.e. is
-    the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata (i.e. is the
-    field ``nullable``). This is very useful, as your client-side validation will
-    automatically match your validation rules.
-
-``maxlength``
-    If the field is some sort of text field, then the ``maxlength`` option attribute
-    can be guessed from the validation constraints (if ``Length`` or ``Range`` is used)
-    or from the Doctrine metadata (via the field's length).
+Thanks to HTML5, many browsers can natively enforce certain validation
+constraints on the client side. The most common validation is activated by
+adding a ``required`` attribute on fields that are required. For browsers
+that support HTML5, this will result in a native browser message being displayed
+if the user tries to submit the form with that field blank.
 
-.. caution::
+Generated forms take full advantage of this new feature by adding sensible HTML
+attributes that trigger the validation. The client-side validation, however, can
+be disabled by adding the ``novalidate`` attribute to the ``<form>`` tag or
+``formnovalidate`` to the submit tag. This is especially useful when you want to
+test your server-side validation constraints, but are being prevented by your
+browser from, for example, submitting blank fields.
 
-  These field options are *only* guessed if you're using Symfony to guess
-  the field type (i.e. omit or pass ``null`` as the second argument to ``add()``).
+.. code-block:: twig
 
-If you'd like to change one of the guessed values, you can override it by
-passing the option in the options field array::
+    {# templates/task/new.html.twig #}
+    {{ form_start(form, {'attr': {'novalidate': 'novalidate'}}) }}
+        {{ form_widget(form) }}
+    {{ form_end(form) }}
 
-    ->add('task', null, ['attr' => ['maxlength' => 4]])
+.. _form-type-guessing:
 
-.. index::
-   single: Forms; Creating form classes
-
-.. _form-creating-form-classes:
+Form Type Guessing
+~~~~~~~~~~~~~~~~~~
 
-Creating Form Classes
----------------------
+If the object handled by the form includes validation constraints, Symfony can
+introspect that metadata to guess the type of your field and set it up for you.
+In the above example, Symfony can guess from the validation rules that both the
+``task`` field is a normal ``TextType`` field and the ``dueDate`` field is a
+``DateType`` field.
 
-As you've seen, a form can be created and used directly in a controller.
-However, a better practice is to build the form in a separate, standalone PHP
-class, which can then be reused anywhere in your application. Create a new class
-that will house the logic for building the task form::
+When building the form, omit the second argument to the ``add()`` method, or
+pass ``null`` to it, to enable Symfony's "guessing mechanism"::
 
-    // src/Form/TaskType.php
-    namespace App\Form;
+    // src/Form/Type/TaskType.php
+    namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
-    use Symfony\Component\Form\FormBuilderInterface;
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
     use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
+    use Symfony\Component\Form\FormBuilderInterface;
 
     class TaskType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
+                // if you don't define field options, you can omit the second argument
                 ->add('task')
-                ->add('dueDate', null, ['widget' => 'single_text'])
+                // if you define field options, pass NULL as second argument
+                ->add('dueDate', null, ['required' => false])
                 ->add('save', SubmitType::class)
             ;
         }
     }
 
-This new class contains all the directions needed to create the task form. It can
-be used to build a form object in the controller::
-
-    // src/Controller/TaskController.php
-    use App\Form\TaskType;
+.. caution::
 
-    public function new()
-    {
-        $task = ...;
-        $form = $this->createForm(TaskType::class, $task);
+    When using a specific :doc:`form validation group </form/validation_groups>`,
+    the field type guesser will still consider *all* validation constraints when
+    guessing your field types (including constraints that are not part of the
+    validation group(s) being used).
 
-        // ...
-    }
+Form Type Options Guessing
+..........................
 
-Placing the form logic into its own class means that the form can be
-reused elsewhere in your project. This is the best way to create forms, but
-the choice is ultimately up to you.
+When the guessing mechanism is enabled for some field (i.e. you omit or pass
+``null`` as the second argument to ``add()``), in addition to its form type,
+the following options can be guessed too:
 
-.. _form-data-class:
+``required``
+    The ``required`` option can be guessed based on the validation rules (i.e. is
+    the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata (i.e. is the
+    field ``nullable``). This is very useful, as your client-side validation will
+    automatically match your validation rules.
 
-.. sidebar:: Setting the ``data_class``
+``maxlength``
+    If the field is some sort of text field, then the ``maxlength`` option attribute
+    can be guessed from the validation constraints (if ``Length`` or ``Range`` is used)
+    or from the :doc:`Doctrine </doctrine>` metadata (via the field's length).
 
-    Every form needs to know the name of the class that holds the underlying
-    data (e.g. ``App\Entity\Task``). Usually, this is just guessed
-    based off of the object passed to the second argument to ``createForm()``
-    (i.e. ``$task``). Later, when you begin embedding forms, this will no
-    longer be sufficient. So, while not always necessary, it's generally a
-    good idea to explicitly specify the ``data_class`` option by adding the
-    following to your form type class::
+If you'd like to change one of the guessed values, override it by passing the
+option in the options field array::
 
-        // src/Form/TaskType.php
-        use App\Entity\Task;
-        use Symfony\Component\OptionsResolver\OptionsResolver;
+    ->add('task', null, ['attr' => ['maxlength' => 4]])
 
-        // ...
-        public function configureOptions(OptionsResolver $resolver)
-        {
-            $resolver->setDefaults([
-                'data_class' => Task::class,
-            ]);
-        }
+.. versionadded:: 4.3
 
-.. tip::
+    Starting from Symfony 4.3, :doc:`Doctrine </doctrine>` metadata is introspected
+    to add :ref:`automatic validation constraints <automatic_object_validation>`.
 
-    When mapping forms to objects, all fields are mapped. Any fields on the
-    form that do not exist on the mapped object will cause an exception to
-    be thrown.
+Unmapped Fields
+~~~~~~~~~~~~~~~
 
-    In cases where you need extra fields in the form (for example: a "do you
-    agree with these terms" checkbox) that will not be mapped to the underlying
-    object, you need to set the ``mapped`` option to ``false``::
+When editing an object via a form, all form fields are considered properties of
+the object. Any fields on the form that do not exist on the object will cause an
+exception to be thrown.
 
-        use Symfony\Component\Form\FormBuilderInterface;
+If you need extra fields in the form that won't be stored in the object (for
+example to add an *"I agree with these terms"* checkbox), set the ``mapped``
+option to ``false`` in those fields::
 
-        public function buildForm(FormBuilderInterface $builder, array $options)
-        {
-            $builder
-                ->add('task')
-                ->add('dueDate')
-                ->add('agreeTerms', CheckboxType::class, ['mapped' => false])
-                ->add('save', SubmitType::class)
-            ;
-        }
+    use Symfony\Component\Form\FormBuilderInterface;
 
-    Additionally, if there are any fields on the form that aren't included in
-    the submitted data, those fields will be explicitly set to ``null``.
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder
+            ->add('task')
+            ->add('dueDate')
+            ->add('agreeTerms', CheckboxType::class, ['mapped' => false])
+            ->add('save', SubmitType::class)
+        ;
+    }
 
-    The field data can be accessed in a controller with::
+These "unmapped fields" can be set and accessed in a controller with::
 
-        $form->get('agreeTerms')->getData();
+    $form->get('agreeTerms')->getData();
+    $form->get('agreeTerms')->setData(true);
 
-    In addition, the data of an unmapped field can also be modified directly::
+Additionally, if there are any fields on the form that aren't included in
+the submitted data, those fields will be explicitly set to ``null``.
 
-        $form->get('agreeTerms')->setData(true);
+Learn more
+----------
 
+When building forms, keep in mind that the first goal of a form is to translate
+data from an object (``Task``) to an HTML form so that the user can modify that
+data. The second goal of a form is to take the data submitted by the user and to
+re-apply it to the object.
 
-.. note::
+There's a lot more to learn and a lot of *powerful* tricks in the Symfony forms:
 
-    The form name is automatically generated from the type class name. If you want
-    to modify it, use the :method:`Symfony\\Component\\Form\\FormFactoryInterface::createNamed` method.
-    You can even suppress the name completely by setting it to an empty string.
+Reference:
 
-Final Thoughts
---------------
+.. toctree::
+    :maxdepth: 1
 
-When building forms, keep in mind that the first goal of a form is to translate data
-from an object (``Task``) to an HTML form so that the user can modify that data.
-The second goal of a form is to take the data submitted by the user and to re-apply
-it to the object.
+    /reference/forms/types
 
-There's a lot more to learn and a lot of *powerful* tricks in the form system.
+Advanced Features:
 
-Learn more
-----------
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    /form/*
     /controller/upload_file
-    /reference/forms/types
     /security/csrf
+    /form/form_dependencies
+    /form/create_custom_field_type
+    /form/data_transformers
+    /form/data_mappers
+    /form/create_form_type_extension
+    /form/type_guesser
+
+Form Themes and Customization:
+
+.. toctree::
+    :maxdepth: 1
+
+    /form/bootstrap4
+    /form/form_customization
+    /form/form_themes
+
+Events:
+
+.. toctree::
+    :maxdepth: 1
+
+    /form/events
+    /form/dynamic_form_modification
+
+Validation:
+
+.. toctree::
+    :maxdepth: 1
+
+    /form/validation_groups
+    /form/validation_group_service_resolver
+    /form/button_based_validation
+    /form/disabling_validation
+
+Misc.:
+
+.. toctree::
+    :maxdepth: 1
+
+    /form/direct_submit
+    /form/embedded
+    /form/form_collections
+    /form/inherit_data_option
+    /form/multiple_buttons
+    /form/unit_testing
+    /form/use_empty_data
+    /form/without_class
 
-.. _`Symfony Form component`: https://github.com/symfony/form
-.. _`DateTime`: https://php.net/manual/en/class.datetime.php
 .. _`Symfony Forms screencast series`: https://symfonycasts.com/screencast/symfony-forms
diff --git a/frontend.rst b/frontend.rst
index b5094326146..1545c8acaaf 100644
--- a/frontend.rst
+++ b/frontend.rst
@@ -28,7 +28,8 @@ to solve the most common Webpack use cases.
 .. tip::
 
     Encore is made by `Symfony`_ and works *beautifully* in Symfony applications.
-    But it can easily be used in any application... in any language!
+    But it can be used in any PHP application and even with other server side
+    programming languages!
 
 .. _encore-toc:
 
@@ -68,11 +69,12 @@ Guides
 
 * :doc:`Using Bootstrap CSS & JS </frontend/encore/bootstrap>`
 * :doc:`Creating Page-Specific CSS/JS </frontend/encore/page-specific-assets>`
-* :doc:`jQuery and Legacy Applications </frontend/encore/legacy-apps>`
+* :doc:`jQuery and Legacy Applications </frontend/encore/legacy-applications>`
 * :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
 * :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`
 * :doc:`Adding custom loaders & plugins </frontend/encore/custom-loaders-plugins>`
 * :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
+* :doc:`Using Encore in a Virtual Machine </frontend/encore/virtual-machine>`
 
 Issues & Questions
 ..................
@@ -107,6 +109,6 @@ Other Front-End Articles
 .. _`Webpack`: https://webpack.js.org/
 .. _`Webpacker`: https://github.com/rails/webpacker
 .. _`Mix`: https://laravel.com/docs/mix
-.. _`Symfony`: http://symfony.com/
+.. _`Symfony`: https://symfony.com/
 .. _`Full API`: https://github.com/symfony/webpack-encore/blob/master/index.js
 .. _`Webpack Encore screencast series`: https://symfonycasts.com/screencast/webpack-encore
diff --git a/frontend/assetic/index.rst b/frontend/assetic/index.rst
index 76434529920..63955c9f8dd 100644
--- a/frontend/assetic/index.rst
+++ b/frontend/assetic/index.rst
@@ -5,4 +5,4 @@ Assetic
 
     Using Assetic to manage web assets in Symfony applications is no longer
     recommended. Instead, use :doc:`Webpack Encore </frontend>`, which bridges
-    Symfony apps with modern JavaScript-based tools to manage web assets.
+    Symfony applications with modern JavaScript-based tools to manage web assets.
diff --git a/frontend/custom_version_strategy.rst b/frontend/custom_version_strategy.rst
index 0e61e613c3e..390ef51e4da 100644
--- a/frontend/custom_version_strategy.rst
+++ b/frontend/custom_version_strategy.rst
@@ -133,7 +133,7 @@ After creating the strategy PHP class, register it as a Symfony service.
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd"
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
         >
             <services>
                 <service id="App\Asset\VersionStrategy\GulpBusterVersionStrategy" public="false">
@@ -146,8 +146,8 @@ After creating the strategy PHP class, register it as a Symfony service.
     .. code-block:: php
 
         // config/services.php
-        use Symfony\Component\DependencyInjection\Definition;
         use App\Asset\VersionStrategy\GulpBusterVersionStrategy;
+        use Symfony\Component\DependencyInjection\Definition;
 
         $container->autowire(GulpBusterVersionStrategy::class)
             ->setArguments(
@@ -178,11 +178,11 @@ the :ref:`version_strategy <reference-assets-version-strategy>` option:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:assets version-strategy="App\Asset\VersionStrategy\GulpBusterVersionStrategy" />
+                <framework:assets version-strategy="App\Asset\VersionStrategy\GulpBusterVersionStrategy"/>
             </framework:config>
         </container>
 
diff --git a/frontend/encore/advanced-config.rst b/frontend/encore/advanced-config.rst
index c21e03bedeb..f67ab192b50 100644
--- a/frontend/encore/advanced-config.rst
+++ b/frontend/encore/advanced-config.rst
@@ -1,14 +1,12 @@
 Advanced Webpack Config
 =======================
 
-Encore generates the Webpack configuration that's used in your
+Summarized, Encore generates the Webpack configuration that's used in your
 ``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
-`configuration options`_, because many can be easily added on your own.
+`configuration options`_, because many can be added on your own.
 
-For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
-modify the config after fetching it from Encore:
-
-.. TODO update the following config example when https://github.com/symfony/webpack-encore/pull/486 is merged and configureWatchOptions() is introduced
+For example, suppose you need to resolve automatically a new extension.
+To do that, modify the config after fetching it from Encore:
 
 .. code-block:: javascript
 
@@ -20,14 +18,9 @@ modify the config after fetching it from Encore:
 
     // fetch the config, then modify it!
     var config = Encore.getWebpackConfig();
-    // if you run 'encore dev --watch'
-    config.watchOptions = { poll: true, ignored: /node_modules/ };
-    // if you run 'encore dev-server'
-    config.devServer.watchOptions = { poll: true, ignored: /node_modules/ };
 
-    // other examples: add an alias or extension
-    // config.resolve.alias.local = path.resolve(__dirname, './resources/src');
-    // config.resolve.extensions.push('json');
+    // add an extension
+    config.resolve.extensions.push('json');
 
     // export the final config
     module.exports = config;
@@ -45,6 +38,20 @@ But be careful not to accidentally override any config from Encore:
     // BAD - this replaces any extensions added by Encore
     // config.resolve.extensions = ['json'];
 
+Configuring Watching Options and Polling
+----------------------------------------
+
+Encore provides the method ``configureWatchOptions()`` to configure
+`Watching Options`_ when running ``encore dev --watch`` or ``encore dev-server``:
+
+.. code-block:: javascript
+
+    Encore.configureWatchOptions(function(watchOptions) {
+        // enable polling and check for changes every 250ms
+        // polling is useful when running Encore inside a Virtual Machine
+        watchOptions.poll = 250;
+    });
+
 Defining Multiple Webpack Configurations
 ----------------------------------------
 
@@ -56,8 +63,8 @@ state of the current configuration to build a new one:
 
     // define the first configuration
     Encore
-        .setOutputPath('public/build/')
-        .setPublicPath('/build')
+        .setOutputPath('public/build/first_build/')
+        .setPublicPath('/build/first_build')
         .addEntry('app', './assets/js/app.js')
         .addStyleEntry('global', './assets/css/global.scss')
         .enableSassLoader()
@@ -76,8 +83,8 @@ state of the current configuration to build a new one:
 
     // define the second configuration
     Encore
-        .setOutputPath('public/build/')
-        .setPublicPath('/build')
+        .setOutputPath('public/build/second_build/')
+        .setPublicPath('/build/second_build')
         .addEntry('mobile', './assets/js/mobile.js')
         .addStyleEntry('mobile', './assets/css/mobile.less')
         .enableLessLoader()
@@ -100,6 +107,30 @@ prefer to build configs separately, pass the ``--config-name`` option:
 
     $ yarn encore dev --config-name firstConfig
 
+Next, define the output directories of each build:
+
+.. code-block:: yaml
+
+    # config/packages/webpack_encore.yaml
+    webpack_encore:
+        output_path: '%kernel.project_dir%/public/default_build'
+        builds:
+            firstConfig: '%kernel.project_dir%/public/first_build'
+            secondConfig: '%kernel.project_dir%/public/second_build'
+
+Finally, use the third optional parameter of the ``encore_entry_*_tags()``
+functions to specify which build to use:
+
+.. code-block:: twig
+
+    {# Using the entrypoints.json file located in ./public/first_build #}
+    {{ encore_entry_script_tags('app', null, 'firstConfig') }}
+    {{ encore_entry_link_tags('global', null, 'firstConfig') }}
+
+    {# Using the entrypoints.json file located in ./public/second_build #}
+    {{ encore_entry_script_tags('mobile', null, 'secondConfig') }}
+    {{ encore_entry_link_tags('mobile', null, 'secondConfig') }}
+
 Generating a Webpack Configuration Object without using the Command-Line Interface
 ----------------------------------------------------------------------------------
 
@@ -146,7 +177,48 @@ normally use from the command-line interface:
         keepPublicPath: true,
     });
 
+Having the full control on Loaders Rules
+----------------------------------------
+
+The method ``configureLoaderRule()`` provides a clean way to configure Webpack loaders rules (``module.rules``, see `Configuration <https://webpack.js.org/concepts/loaders/#configuration>`_).
+
+This is a low-level method. All your modifications will be applied just before pushing the loaders rules to Webpack.
+It means that you can override the default configuration provided by Encore, which may break things. Be careful when using it.
+
+One use might be to configure the ``eslint-loader`` to lint Vue files too.
+The following code is equivalent:
+
+.. code-block:: javascript
+
+    // Manually
+    const webpackConfig = Encore.getWebpackConfig();
+
+    const eslintLoader = webpackConfig.module.rules.find(rule => rule.loader === 'eslint-loader');
+    eslintLoader.test = /\.(jsx?|vue)$/;
+
+    return webpackConfig;
+
+    // Using Encore.configureLoaderRule()
+    Encore.configureLoaderRule('eslint', loaderRule => {
+        loaderRule.test = /\.(jsx?|vue)$/
+    });
+
+    return Encore.getWebpackConfig();
+
+The following loaders are configurable with ``configureLoaderRule()``:
+  - ``javascript`` (alias ``js``)
+  - ``css``
+  - ``images``
+  - ``fonts``
+  - ``sass`` (alias ``scss``)
+  - ``less``
+  - ``stylus``
+  - ``vue``
+  - ``eslint``
+  - ``typescript`` (alias ``ts``)
+  - ``handlebars``
+
 .. _`configuration options`: https://webpack.js.org/configuration/
-.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions
 .. _`array of configurations`: https://github.com/webpack/docs/wiki/configuration#multiple-configurations
 .. _`Karma`: https://karma-runner.github.io
+.. _`Watching Options`: https://webpack.js.org/configuration/watch/#watchoptions
diff --git a/frontend/encore/babel.rst b/frontend/encore/babel.rst
index 2affea43c5f..f7cba9a4892 100644
--- a/frontend/encore/babel.rst
+++ b/frontend/encore/babel.rst
@@ -18,17 +18,19 @@ Need to extend the Babel configuration further? The easiest way is via
 
         .configureBabel(function(babelConfig) {
             // add additional presets
-            // babelConfig.presets.push('@babel/preset-flow');
+            babelConfig.presets.push('@babel/preset-flow');
 
             // no plugins are added by default, but you can add some
-            // babelConfig.plugins.push('styled-jsx/babel');
+            babelConfig.plugins.push('styled-jsx/babel');
         }, {
             // node_modules is not processed through Babel by default
             // but you can whitelist specific modules to process
-            // include_node_modules: ['foundation-sites']
+            include_node_modules: ['foundation-sites'],
 
-            // or completely control the exclude
-            // exclude: /bower_components/
+            // or completely control the exclude rule (note that you
+            // can't use both "include_node_modules" and "exclude" at
+            // the same time)
+            exclude: /bower_components/
         })
     ;
 
@@ -39,12 +41,12 @@ The ``@babel/preset-env`` preset rewrites your JavaScript so that the final synt
 will work in whatever browsers you want. To configure the browsers that you need
 to support, see :ref:`browserslist_package_config`.
 
-After change our "browerslist" config, you will need to manually remove the babel
+After changing your "browserslist" config, you will need to manually remove the babel
 cache directory:
 
 .. code-block:: terminal
 
-    $ On Unix run this command. On Windows, clear this directory manually
+    # On Unix run this command. On Windows, clear this directory manually
     $ rm -rf node_modules/.cache/babel-loader/
 
 Creating a .babelrc File
diff --git a/frontend/encore/cdn.rst b/frontend/encore/cdn.rst
index ab4a5881c34..a7a2884c13a 100644
--- a/frontend/encore/cdn.rst
+++ b/frontend/encore/cdn.rst
@@ -1,9 +1,8 @@
 Using a CDN
 ===========
 
-Are you deploying to a CDN? That's awesome :) - and configuring Encore for that is
-easy. Once you've made sure that your built files are uploaded to the CDN, configure
-it in Encore:
+Are you deploying to a CDN? That's awesome :) Once you've made sure that your
+built files are uploaded to the CDN, configure it in Encore:
 
 .. code-block:: diff
 
@@ -39,3 +38,10 @@ You *do* need to make sure that the ``script`` and ``link`` tags you include on
 pages also use the CDN. Fortunately, the
 :ref:`entrypoints.json <encore-entrypointsjson-simple-description>` paths are updated
 to include the full URL to the CDN.
+
+If you are using ``Encore.enableIntegrityHashes()`` and your CDN and your domain
+are not the `same-origin`_, you may need to set the ``crossorigin`` option in
+your webpack_encore.yaml configuration to ``anonymous`` or ``use-credentials``
+to overcome CORS errors.
+
+.. _`same-origin`: https://en.wikipedia.org/wiki/Same-origin_policy
diff --git a/frontend/encore/dev-server.rst b/frontend/encore/dev-server.rst
index 6fce0012d8f..a29e6f5e903 100644
--- a/frontend/encore/dev-server.rst
+++ b/frontend/encore/dev-server.rst
@@ -26,25 +26,6 @@ by the normal `webpack-dev-server`_. For example:
 
 This will start a server at ``https://localhost:9000``.
 
-.. note::
-
-    This Webpack server is independent from
-    :doc:`Symfony's development web server </setup/built_in_web_server>` and
-    you need to run both separately.
-
-Using dev-server inside a VM
-----------------------------
-
-If you're using ``dev-server`` from inside a virtual machine, then you'll need
-to bind to all IP addresses and allow any host to access the server:
-
-.. code-block:: terminal
-
-    $ ./node_modules/.bin/encore dev-server --host 0.0.0.0 --disable-host-check
-
-You can now access the dev-server using the IP address to your virtual machine on
-port 8080 - e.g. http://192.168.1.1:8080.
-
 Hot Module Replacement HMR
 --------------------------
 
diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst
index 6cfffc8b34a..37f76d09f3b 100644
--- a/frontend/encore/faq.rst
+++ b/frontend/encore/faq.rst
@@ -92,7 +92,7 @@ or ``jQuery`` to be a global variable. But, when you use Webpack and ``require('
 no global variables are set.
 
 The fix depends on if the error is happening in your code or inside some third-party
-code that you're using. See :doc:`/frontend/encore/legacy-apps` for the fix.
+code that you're using. See :doc:`/frontend/encore/legacy-applications` for the fix.
 
 Uncaught ReferenceError: webpackJsonp is not defined
 ----------------------------------------------------
@@ -137,3 +137,34 @@ Babel. But, you can change that via the ``configureBabel()`` method. See
 :doc:`/frontend/encore/babel` for details.
 
 .. _`rsync`: https://rsync.samba.org/
+
+How Do I Integrate my Encore Configuration with my IDE?
+-------------------------------------------------------
+
+`Webpack integration in PhpStorm`_ and other IDEs makes your development more
+productive (for example by resolving aliases). However, you may face this error:
+
+.. code-block:: text
+
+    Encore.setOutputPath() cannot be called yet because the runtime environment
+    doesn't appear to be configured. Make sure you're using the encore executable
+    or call Encore.configureRuntimeEnvironment() first if you're purposely not
+    calling Encore directly.
+
+It fails because the Encore Runtime Environment is only configured when you are
+running it (e.g. when executing ``yarn encore dev``). Fix this issue calling to
+``Encore.isRuntimeEnvironmentConfigured()`` and
+``Encore.configureRuntimeEnvironment()`` methods:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    const Encore = require('@symfony/webpack-encore')
+
+    if (!Encore.isRuntimeEnvironmentConfigured()) {
+        Encore.configureRuntimeEnvironment(process.env.NODE_ENV || 'dev');
+    }
+
+    // ... the rest of the Encore configuration
+
+.. _`Webpack integration in PhpStorm`: https://www.jetbrains.com/help/phpstorm/using-webpack.html
diff --git a/frontend/encore/installation.rst b/frontend/encore/installation.rst
index 3d5d3f0ee3f..0518bf6d853 100644
--- a/frontend/encore/installation.rst
+++ b/frontend/encore/installation.rst
@@ -8,21 +8,22 @@ Symfony application or not.
 Installing Encore in Symfony Applications
 -----------------------------------------
 
-If your application is using :doc:`Symfony Flex </setup/flex>`, run the
-following commands:
+Run these commands to install both the PHP and JavaScript dependencies in your
+project:
 
 .. code-block:: terminal
 
-    $ composer require encore
+    $ composer require symfony/webpack-encore-bundle
     $ yarn install
 
-This will install and enable the `WebpackEncoreBundle`_, add the ``assets/``
-directory, create a ``webpack.config.js`` file, and add ``node_modules/`` to
-``.gitignore``. If you are not using Symfony Flex, you'll need to create all
-this by yourself following the instructions shown in the next section.
+If you are using :ref:`Symfony Flex <symfony-flex>`, this will install and enable
+the `WebpackEncoreBundle`_, create the ``assets/`` directory, add a
+``webpack.config.js`` file, and add ``node_modules/`` to ``.gitignore``. You can
+skip the rest of this article and go write your first JavaScript and CSS by
+reading :doc:`/frontend/encore/simple-example`!
 
-Nice work! You can skip the rest of this article and go write your first
-JavaScript and CSS by reading :doc:`/frontend/encore/simple-example`!
+If you are not using Symfony Flex, you'll need to create all these directories
+and files by yourself following the instructions shown in the next section.
 
 Installing Encore in non Symfony Applications
 ---------------------------------------------
@@ -51,7 +52,7 @@ Creating the webpack.config.js File
 Next, create a new ``webpack.config.js`` file at the root of your project. This
 is the main config file for both Webpack and Webpack Encore:
 
-.. code-block:: js
+.. code-block:: javascript
 
     var Encore = require('@symfony/webpack-encore');
 
@@ -70,7 +71,7 @@ is the main config file for both Webpack and Webpack Encore:
          * (including one that's included on every page - e.g. "app")
          *
          * Each entry will result in one JavaScript file (e.g. app.js)
-         * and one CSS file (e.g. app.css) if you JavaScript imports CSS.
+         * and one CSS file (e.g. app.css) if your JavaScript imports CSS.
          */
         .addEntry('app', './assets/js/app.js')
         //.addEntry('page1', './assets/js/page1.js')
@@ -129,5 +130,4 @@ You'll customize and learn more about these file in :doc:`/frontend/encore/simpl
 
 .. _`install Node.js`: https://nodejs.org/en/download/
 .. _`Yarn package manager`: https://yarnpkg.com/lang/en/docs/install/
-.. _`npm`: https://www.npmjs.com/
 .. _`WebpackEncoreBundle`: https://github.com/symfony/webpack-encore-bundle
diff --git a/frontend/encore/legacy-apps.rst b/frontend/encore/legacy-applications.rst
similarity index 100%
rename from frontend/encore/legacy-apps.rst
rename to frontend/encore/legacy-applications.rst
diff --git a/frontend/encore/postcss.rst b/frontend/encore/postcss.rst
index 16d3ede5b17..e9671e2a6a8 100644
--- a/frontend/encore/postcss.rst
+++ b/frontend/encore/postcss.rst
@@ -48,7 +48,8 @@ You can also pass options to the `postcss-loader`_ by passing a callback:
         // ...
     +     .enablePostCssLoader((options) => {
     +         options.config = {
-    +             path: 'config/postcss.config.js'
+    +             // the directory where the postcss.config.js file is stored
+    +             path: 'path/to/config'
     +         };
     +     })
     ;
@@ -79,5 +80,4 @@ See `browserslist`_ for more details on the syntax.
 .. _`autoprefixing`: https://github.com/postcss/autoprefixer
 .. _`linting`: https://stylelint.io/
 .. _`browserslist`: https://github.com/browserslist/browserslist
-.. _`babel-preset-env`: https://github.com/babel/babel/tree/master/packages/babel-preset-env
 .. _`postcss-loader`: https://github.com/postcss/postcss-loader
diff --git a/frontend/encore/reactjs.rst b/frontend/encore/reactjs.rst
index f2a27d6f8a2..7cc808a9e55 100644
--- a/frontend/encore/reactjs.rst
+++ b/frontend/encore/reactjs.rst
@@ -5,7 +5,7 @@ Using React? First enable support for it in ``webpack.config.js``:
 
 .. code-block:: terminal
 
-    $ yarn add --dev @babel/preset-react
+    $ yarn add @babel/preset-react --dev
     $ yarn add react react-dom prop-types
 
 Enable react in your ``webpack.config.js``:
@@ -26,5 +26,3 @@ install any missing dependencies. After running that command and restarting
 Encore, you're done!
 
 Your ``.js`` and ``.jsx`` files will now be transformed through ``babel-preset-react``.
-
-.. _`babel-preset-react`: https://babeljs.io/docs/plugins/preset-react/
diff --git a/frontend/encore/server-data.rst b/frontend/encore/server-data.rst
index ae19c262e86..ebb1f3cb8a5 100644
--- a/frontend/encore/server-data.rst
+++ b/frontend/encore/server-data.rst
@@ -6,7 +6,7 @@ In Symfony applications, you may find that you need to pass some dynamic data
 dynamic configuration is by storing information in ``data`` attributes and reading
 them later in JavaScript. For example:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <div class="js-user-rating" data-is-authenticated="{{ app.user ? 'true' : 'false' }}">
         <!-- ... -->
@@ -36,7 +36,7 @@ store any content. In Twig, use the ``html_attr`` escaping strategy to avoid mes
 with HTML attributes. For example, if your ``User`` object has some ``getProfileData()``
 method that returns an array, you could do the following:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <div data-user-profile="{{ app.user ? app.user.profileData|json_encode|e('html_attr') }}">
         <!-- ... -->
diff --git a/frontend/encore/shared-entry.rst b/frontend/encore/shared-entry.rst
index 303b3ee5d06..6693b649d8d 100644
--- a/frontend/encore/shared-entry.rst
+++ b/frontend/encore/shared-entry.rst
@@ -30,7 +30,7 @@ then ``jquery`` would be packaged into *both* files, which is wasteful. By makin
 *no longer* be packaged into any other files. The same is true for any CSS.
 
 Because ``app.js`` contains all the common code that other entry files depend on,
-it's obvious that its script (and link) tag must be on every page.
+its script (and link) tag must be on every page.
 
 .. tip::
 
diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst
index 7bc0ee3eda0..3571287f425 100644
--- a/frontend/encore/simple-example.rst
+++ b/frontend/encore/simple-example.rst
@@ -23,7 +23,7 @@ application: it will *require* all of the dependencies it needs (e.g. jQuery or
 
 Encore's job (via Webpack) is simple: to read and follow *all* of the ``require``
 statements and create one final ``app.js`` (and ``app.css``) that contains *everything*
-your app needs. Of course, Encore can do a lot more: minify files, pre-process Sass/LESS,
+your app needs. Encore can do a lot more: minify files, pre-process Sass/LESS,
 support React, Vue.js, etc.
 
 Configuring Encore/Webpack
@@ -83,7 +83,7 @@ Congrats! You now have three new files:
 Next, include these in your base layout file. Two Twig helpers from WebpackEncoreBundle
 can do most of the work for you:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {# templates/base.html.twig #}
     <!DOCTYPE html>
@@ -212,8 +212,8 @@ To import values, use ``import``:
 Page-Specific JavaScript or CSS (Multiple Entries)
 --------------------------------------------------
 
-So far, you only have one final JavaScript file: ``app.js``. For simple apps or
-SPA's (Single Page Applications), that might be fine! However, as your app grows,
+So far, you only have one final JavaScript file: ``app.js``. For small applications
+or SPA's (Single Page Applications), that might be fine! However, as your app grows,
 you may want to have page-specific JavaScript or CSS (e.g. checkout, account,
 etc.). To handle this, create a new "entry" JavaScript file for each page:
 
@@ -302,8 +302,10 @@ Then, tell Encore to enable the Sass pre-processor:
 Because you just changed your ``webpack.config.js`` file, you'll need to restart
 Encore. When you do, you'll see an error!
 
->   Error: Install sass-loader & node-sass to use enableSassLoader()
->     yarn add sass-loader@^7.0.1 node-sass --dev
+.. code-block:: terminal
+
+    >   Error: Install sass-loader & node-sass to use enableSassLoader()
+    >     yarn add sass-loader@^7.0.1 node-sass --dev
 
 Encore supports many features. But, instead of forcing all of them on you, when
 you need a feature, Encore will tell you what you need to install. Run:
@@ -322,7 +324,7 @@ Compiling Only a CSS File
 .. caution::
 
     Using ``addStyleEntry()`` is supported, but not recommended. A better option
-    is to use follow the pattern above: use ``addEntry()`` to point to a JavaScript
+    is to follow the pattern above: use ``addEntry()`` to point to a JavaScript
     file, then require the CSS needed from inside of that.
 
 If you want to only compile a CSS file, that's possible via ``addStyleEntry()``:
diff --git a/frontend/encore/split-chunks.rst b/frontend/encore/split-chunks.rst
index e619256c125..a86686b6b14 100644
--- a/frontend/encore/split-chunks.rst
+++ b/frontend/encore/split-chunks.rst
@@ -33,7 +33,7 @@ Twig functions from WebpackEncoreBundle, you don't need to do anything else! The
 functions automatically read this file and render as many ``script`` or ``link``
 tags as needed:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {#
         May now render multiple script tags:
diff --git a/frontend/encore/typescript.rst b/frontend/encore/typescript.rst
index 03cf18eac8d..686d5ea0974 100644
--- a/frontend/encore/typescript.rst
+++ b/frontend/encore/typescript.rst
@@ -33,5 +33,4 @@ processed by ``ts-loader``.
 
 .. _`TypeScript`: https://www.typescriptlang.org/
 .. _`ts-loader options`: https://github.com/TypeStrong/ts-loader#options
-.. _`fork-ts-checker-webpack-plugin`: https://www.npmjs.com/package/fork-ts-checker-webpack-plugin
 .. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js
diff --git a/frontend/encore/url-loader.rst b/frontend/encore/url-loader.rst
index 166f59481bb..976cd6974d8 100644
--- a/frontend/encore/url-loader.rst
+++ b/frontend/encore/url-loader.rst
@@ -48,4 +48,4 @@ key from the object that is passed to the ``configureUrlLoader()`` method:
         })
     ;
 
-.. _`URL loader`: https://github.com/webpack-contrib/url-loader
+.. _`URL Loader`: https://github.com/webpack-contrib/url-loader
diff --git a/frontend/encore/versioning.rst b/frontend/encore/versioning.rst
index 2f3a114c857..c9c2bed17c3 100644
--- a/frontend/encore/versioning.rst
+++ b/frontend/encore/versioning.rst
@@ -64,10 +64,27 @@ an ``img`` tag) to certain assets. If you're using Symfony, just activate the
 That's it! Be sure to wrap each path in the Twig ``asset()`` function
 like normal:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <img src="{{ asset('build/images/logo.png') }}">
 
+Troubleshooting
+---------------
+
+Asset Versioning and Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When deploying a new version of your application, versioned assets will include
+a new hash, making the previous assets no longer available. This is usually not
+a problem when deploying applications using a rolling update, blue/green or
+symlink strategies.
+
+However, even when applying those techniques, there could be a lapse of time
+when some publicly/privately cached response requests the previous version of
+the assets. If your application can't afford to serve any broken asset, the best
+solution is to use a CDN (or custom made service) that keeps all the old assets
+cached for some time.
+
 Learn more
 ----------
 
diff --git a/frontend/encore/virtual-machine.rst b/frontend/encore/virtual-machine.rst
new file mode 100644
index 00000000000..068d5c8451f
--- /dev/null
+++ b/frontend/encore/virtual-machine.rst
@@ -0,0 +1,121 @@
+Using Encore in a Virtual Machine
+=================================
+
+Encore is compatible with virtual machines such as `VirtualBox`_ and `VMWare`_
+but you may need to make some changes to your configuration to make it work.
+
+File Watching Issues
+--------------------
+
+When using a virtual machine, your project root directory is shared with the
+virtual machine using `NFS`_. This introduces issues with files watching, so
+you must enable the `polling`_ option to make it work:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+
+    // ...
+
+    // will be applied for `encore dev --watch` and `encore dev-server` commands
+    Encore.configureWatchOptions(watchOptions => {
+        watchOptions.poll = 250; // check for changes every 250 milliseconds
+    });
+
+Development Server Issues
+-------------------------
+
+Configure the Public Path
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    You can skip this section if your application is running on
+    ``http://localhost`` instead a custom local domain-name like
+    ``http://app.vm``.
+
+When running the development server, you will probably see the following errors
+in the web console:
+
+.. code-block:: text
+
+    GET http://localhost:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED
+    GET http://localhost:8080/build/runtime.js net::ERR_CONNECTION_REFUSED
+    ...
+
+If your Symfony application is running on a custom domain (e.g.
+``http://app.vm``), you must configure the public path explicitly in your
+``package.json``:
+
+.. code-block:: diff
+
+    {
+        ...
+        "scripts": {
+    -        "dev-server": "encore dev-server",
+    +        "dev-server": "encore dev-server --public http://app.vm:8080",
+            ...
+        }
+    }
+
+After restarting Encore and reloading your web page, you will probably see
+different issues in the web console:
+
+.. code-block:: text
+
+    GET http://app.vm:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED
+    GET http://app.vm:8080/build/runtime.js net::ERR_CONNECTION_REFUSED
+
+You still need to make other configuration changes, as explained in the
+following sections.
+
+Allow External Access
+~~~~~~~~~~~~~~~~~~~~~
+
+Add the ``--host 0.0.0.0`` argument to the ``dev-server`` configuration in your
+``package.json`` file to make the development server accept all incoming
+connections:
+
+.. code-block:: diff
+
+    {
+        ...
+        "scripts": {
+    -        "dev-server": "encore dev-server --public http://app.vm:8080",
+    +        "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0",
+            ...
+        }
+    }
+
+.. caution::
+
+    Make sure to run the development server inside your virtual machine only;
+    otherwise other computers can have access to it.
+
+Fix "Invalid Host header" Issue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Webpack will respond ``Invalid Host header`` when trying to access files from
+the dev-server. To fix this, add the argument ``--disable-host-check``:
+
+.. code-block:: diff
+
+    {
+        ...
+        "scripts": {
+    -        "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0",
+    +        "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0 --disable-host-check",
+            ...
+        }
+    }
+
+.. caution::
+
+    Beware that `it's not recommended to disable host checking`_ in general, but
+    here it's required to solve the issue when using Encore in a virtual machine.
+
+.. _`VirtualBox`: https://www.virtualbox.org/
+.. _`VMWare`: https://www.vmware.com
+.. _`NFS`: https://en.wikipedia.org/wiki/Network_File_System
+.. _`polling`: https://webpack.js.org/configuration/watch/#watchoptionspoll
+.. _`it's not recommended to disable host checking`: https://webpack.js.org/configuration/dev-server/#devserverdisablehostcheck
diff --git a/frontend/encore/vuejs.rst b/frontend/encore/vuejs.rst
index b73bc406a30..9f0881b0bc9 100644
--- a/frontend/encore/vuejs.rst
+++ b/frontend/encore/vuejs.rst
@@ -40,7 +40,119 @@ updated styles still requires a page refresh.
 
 See :doc:`/frontend/encore/dev-server` for more details.
 
-.. _`babel-preset-react`: https://babeljs.io/docs/plugins/preset-react/
+JSX Support
+-----------
+
+You can enable `JSX with Vue.js`_ by configuring the second parameter of the
+``.enableVueLoader()`` method:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
+        .addEntry('main', './assets/main.js')
+
+    -     .enableVueLoader()
+    +     .enableVueLoader(() => {}, {
+    +         useJsx: true
+    +     })
+    ;
+
+Next, run or restart Encore. When you do, you will see an error message helping
+you install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Your ``.jsx`` files will now be transformed through ``@vue/babel-preset-jsx``.
+
+Using styles
+~~~~~~~~~~~~
+
+You can't use ``<style>`` in ``.jsx`` files. As a workaround, you can import
+``.css``, ``.scss``, etc. files manually:
+
+.. code-block:: javascript
+
+    // App.jsx
+
+    import './App.css'
+
+    export default {
+        name: 'App',
+        render() {
+            return (
+                <div>
+                    ...
+                </div>
+            )
+        }
+    }
+
+.. note::
+
+    Importing styles this way makes them global. See the next section for
+    scoping them to your component.
+
+Using Scoped Styles
+~~~~~~~~~~~~~~~~~~~
+
+You can't use `Scoped Styles`_ (``<style scoped>``) either in ``.jsx`` files. As
+a workaround, you can use `CSS Modules`_ by suffixing import paths with
+``?module``:
+
+.. code-block:: javascript
+
+    // Component.jsx
+
+    import styles from './Component.css?module' // suffix with "?module"
+
+    export default {
+        name: 'Component',
+        render() {
+            return (
+                <div>
+                    <h1 class={styles.title}>
+                        Hello World
+                    </h1>
+                </div>
+            )
+        }
+    }
+
+.. code-block:: css
+
+    /* Component.css */
+
+    .title {
+        color: red
+    }
+
+The output will be something like ``<h1 class="title_a3dKp">Hello World</h1>``.
+
+Using images
+~~~~~~~~~~~~
+
+You can't use ``<img src="./image.png">`` in ``.jsx`` files. As a workaround,
+you can import them with ``require()`` function:
+
+.. code-block:: javascript
+
+    export default {
+        name: 'Component',
+        render() {
+            return (
+                <div>
+                    <img src={require("./image.png")}/>
+                </div>
+            )
+        }
+    }
+
 .. _`Vue.js`: https://vuejs.org/
 .. _`vue-loader options`: https://vue-loader.vuejs.org/options.html
 .. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js
+.. _`JSX with Vue.js`: https://github.com/vuejs/jsx
+.. _`Scoped Styles`: https://vue-loader.vuejs.org/guide/scoped-css.html
+.. _`CSS Modules`: https://github.com/css-modules/css-modules
diff --git a/getting_started/index.rst b/getting_started/index.rst
index 129263b3a36..acd7ddc5dcd 100644
--- a/getting_started/index.rst
+++ b/getting_started/index.rst
@@ -4,9 +4,9 @@ Getting Started
 .. toctree::
     :maxdepth: 1
 
-    ../setup
-    ../page_creation
-    ../routing
-    ../controller
-    ../templating
-    ../configuration
+    /setup
+    /page_creation
+    /routing
+    /controller
+    /templating
+    /configuration
diff --git a/http_cache.rst b/http_cache.rst
index 267a8b327c6..18f4462e539 100644
--- a/http_cache.rst
+++ b/http_cache.rst
@@ -13,7 +13,7 @@ Caching on the Shoulders of Giants
 ----------------------------------
 
 With HTTP Caching, you cache the full output of a page (i.e. the response) and bypass
-your application *entirely* on subsequent requests. Of course, caching entire responses
+your application *entirely* on subsequent requests. Caching entire responses
 isn't always possible for highly dynamic sites, or is it? With
 :doc:`Edge Side Includes (ESI) </http_cache/esi>`, you can use the power of HTTP caching
 on only *fragments* of your site.
@@ -99,13 +99,9 @@ caching kernel:
     use App\Kernel;
 
     // ...
-    $env = $_SERVER['APP_ENV'] ?? 'dev';
-    $debug = (bool) ($_SERVER['APP_DEBUG'] ?? ('prod' !== $env));
-    // ...
-    $kernel = new Kernel($env, $debug);
-
+    $kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
     + // Wrap the default Kernel with the CacheKernel one in 'prod' environment
-    + if ('prod' === $env) {
+    + if ('prod' === $kernel->getEnvironment()) {
     +     $kernel = new CacheKernel($kernel);
     + }
 
@@ -155,7 +151,26 @@ For a full list of the options and their meaning, see the
 
 When you're in debug mode (the second argument of ``Kernel`` constructor in the
 front controller is ``true``), Symfony automatically adds an ``X-Symfony-Cache``
-header to the response. Use this to get information about cache hits and misses.
+header to the response. You can also use the ``trace_level`` config
+option and set it to either ``none``, ``short`` or ``full`` to
+add this information.
+
+``short`` will add the information for the master request only.
+It's written in a concise way that makes it easy to record the
+information in your server log files. For example, in Apache you can
+use ``%{X-Symfony-Cache}o`` in ``LogFormat`` format statements.
+This information can be used to extract general information about
+cache efficiency of your routes.
+
+.. tip::
+
+    You can change the name of the header used for the trace
+    information using the ``trace_header`` config option.
+
+.. versionadded:: 4.3
+
+    The ``trace_level`` and ``trace_header`` configuration options
+    were introduced in Symfony 4.3.
 
 .. _http-cache-symfony-versus-varnish:
 
@@ -282,7 +297,7 @@ Validation Caching
    single: Cache; Cache-Control header
    single: HTTP headers; Cache-Control
 
-With expiration caching, you simply say "cache for 3600 seconds!". But, when someone
+With expiration caching, you say "cache for 3600 seconds!". But, when someone
 updates cached content, you won't see that content on your site until the cache
 expires.
 
@@ -307,7 +322,7 @@ two things:
   and mutating your application.
 
 * POST requests are generally considered uncacheable, but `they can be cached`_
-  when they include explicit freshness information. However POST caching is not
+  when they include explicit freshness information. However, POST caching is not
   widely implemented, so you should avoid it if possible.
 
 * You should *never* change the state of your application (e.g. update a blog post)
@@ -380,9 +395,6 @@ Symfony won't modify it::
 
     $response->headers->set(AbstractSessionListener::NO_AUTO_CACHE_CONTROL_HEADER, 'true');
 
-.. versionadded:: 4.1
-    The ``NO_AUTO_CACHE_CONTROL_HEADER`` header was introduced in Symfony 4.1.
-
 Summary
 -------
 
@@ -406,7 +418,6 @@ Learn more
 .. _`Cache Tutorial`: http://www.mnot.net/cache_docs/
 .. _`Varnish`: https://www.varnish-cache.org/
 .. _`Squid in reverse proxy mode`: http://wiki.squid-cache.org/SquidFaq/ReverseProxy
-.. _`HTTP Bis`: http://tools.ietf.org/wg/httpbis/
 .. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234
 .. _`RFC 7232 - Conditional Requests`: https://tools.ietf.org/html/rfc7232
 .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
diff --git a/http_cache/_expiration-and-validation.rst.inc b/http_cache/_expiration-and-validation.rst.inc
new file mode 100644
index 00000000000..3ae2113e242
--- /dev/null
+++ b/http_cache/_expiration-and-validation.rst.inc
@@ -0,0 +1,14 @@
+.. sidebar:: Expiration and Validation
+
+    You can use both validation and expiration within the same ``Response``.
+    As expiration wins over validation, you can benefit from the best of
+    both worlds. In other words, by using both expiration and validation, you
+    can instruct the cache to serve the cached content, while checking back
+    at some interval (the expiration) to verify that the content is still valid.
+
+    .. tip::
+
+        You can also define HTTP caching headers for expiration and validation by using
+        annotations. See the `FrameworkExtraBundle documentation`_.
+
+.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html
diff --git a/http_cache/esi.rst b/http_cache/esi.rst
index 8f4a31f770f..295a84b2816 100644
--- a/http_cache/esi.rst
+++ b/http_cache/esi.rst
@@ -27,7 +27,7 @@ as this is the only useful one outside of Akamai context:
             <!-- ... some content -->
 
             <!-- Embed the content of another page here -->
-            <esi:include src="http://..." />
+            <esi:include src="http://..."/>
 
             <!-- ... more content -->
         </body>
@@ -75,13 +75,13 @@ First, to use ESI, be sure to enable it in your application configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <!-- ... -->
-                <framework:esi enabled="true" />
+                <framework:esi enabled="true"/>
             </framework:config>
         </container>
 
@@ -205,13 +205,13 @@ that must be enabled in your configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <!-- ... -->
             <framework:config>
-                <framework:fragment path="/_fragment" />
+                <framework:fragment path="/_fragment"/>
             </framework:config>
         </container>
 
@@ -250,6 +250,6 @@ The ``render_esi`` helper supports two other useful options:
 ``ignore_errors``
     If set to true, an ``onerror`` attribute will be added to the ESI with a value
     of ``continue`` indicating that, in the event of a failure, the gateway cache
-    will simply remove the ESI tag silently.
+    will remove the ESI tag silently.
 
 .. _`ESI`: http://www.w3.org/TR/esi-lang
diff --git a/http_cache/expiration.rst b/http_cache/expiration.rst
index d9d7eed8117..ee2aedf0b19 100644
--- a/http_cache/expiration.rst
+++ b/http_cache/expiration.rst
@@ -12,18 +12,7 @@ until the cached response expires.
 The expiration model can be accomplished using one of two, nearly identical,
 HTTP headers: ``Expires`` or ``Cache-Control``.
 
-.. sidebar:: Expiration and Validation
-
-    You can use both validation and expiration within the same ``Response``.
-    As expiration wins over validation, you can benefit from the best of
-    both worlds. In other words, by using both expiration and validation, you
-    can instruct the cache to serve the cached content, while checking back
-    at some interval (the expiration) to verify that the content is still valid.
-
-    .. tip::
-
-        You can also define HTTP caching headers for expiration and validation by using
-        annotations. See the `FrameworkExtraBundle documentation`_.
+.. include:: /http_cache/_expiration-and-validation.rst.inc
 
 .. index::
     single: Cache; Cache-Control header
@@ -92,5 +81,4 @@ servers should not send ``Expires`` dates more than one year in the future."
     header is defined.
 
 .. _`expiration model`: http://tools.ietf.org/html/rfc2616#section-13.2
-.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html
 .. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234#section-4.2.1
diff --git a/http_cache/ssi.rst b/http_cache/ssi.rst
new file mode 100644
index 00000000000..44ebda2990c
--- /dev/null
+++ b/http_cache/ssi.rst
@@ -0,0 +1,141 @@
+.. index::
+    single: Cache; SSI
+    single: SSI
+
+.. _server-side-includes:
+
+Working with Server Side Includes
+=================================
+
+In a similar way as :doc:`ESI (Edge Side Includes) </http_cache/esi>`,
+SSI can be used to control HTTP caching on fragments of a response.
+The most important difference that is SSI is known directly by most
+web servers like `Apache`_, `Nginx`_ etc.
+
+The SSI instructions are done via HTML comments:
+
+.. code-block:: html
+
+    <!DOCTYPE html>
+    <html>
+        <body>
+            <!-- ... some content -->
+
+            <!-- Embed the content of another page here -->
+            <!--#include virtual="http://..." -->
+
+            <!-- ... more content -->
+        </body>
+    </html>
+
+There are some other `available directives`_ but
+Symfony manages only the ``#include virtual`` one.
+
+.. caution::
+
+    Be careful with SSI, your website may be victim of injections.
+    Please read this `OWASP article`_ first!
+
+When the web server reads an SSI directive, it requests the given URI or gives
+directly from its cache. It repeats this process until there is no more
+SSI directives to handle. Then, it merges all responses into one and sends
+it to the client.
+
+.. _using-ssi-in-symfony:
+
+Using SSI in Symfony
+~~~~~~~~~~~~~~~~~~~~
+
+First, to use SSI, be sure to enable it in your application configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            ssi: { enabled: true }
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/symfony"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:ssi enabled="true"/>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        $container->loadFromExtension('framework', [
+            'ssi' => ['enabled' => true],
+        ]);
+
+Suppose you have a page with private content like a Profile page and you want
+to cache a static GDPR content block. With SSI, you can add some expiration
+on this block and keep the page private::
+
+    // src/Controller/ProfileController.php
+
+    // ...
+    class ProfileController extends AbstractController
+    {
+        public function index(): Response
+        {
+            // by default, responses are private
+            return $this->render('profile/index.html.twig');
+        }
+
+        public function gdpr(): Response
+        {
+            $response = $this->render('profile/gdpr.html.twig');
+
+            // sets to public and adds some expiration
+            $response->setSharedMaxAge(600);
+
+            return $response;
+        }
+    }
+
+The profile index page has not public caching, but the GDPR block has
+10 minutes of expiration. Let's include this block into the main one:
+
+.. code-block:: twig
+
+    {# templates/profile/index.html.twig #}
+
+    {# you can use a controller reference #}
+    {{ render_ssi(controller('App\Controller\ProfileController::gdpr')) }}
+
+    {# ... or a URL #}
+    {{ render_ssi(url('profile_gdpr')) }}
+
+The ``render_ssi`` twig helper will generate something like:
+
+.. code-block:: html
+
+    <!--#include virtual="/_fragment?_hash=abcdef1234&_path=_controller=App\Controller\ProfileController::gdpr" -->
+
+``render_ssi`` ensures that SSI directive are generated only if the request
+has the header requirement like ``Surrogate-Capability: device="SSI/1.0"``
+(normally given by the web server).
+Otherwise it will embed directly the sub-response.
+
+.. note::
+
+    For more information about Symfony cache fragments, take a tour on
+    the :ref:`ESI documentation <http_cache-fragments>`.
+
+.. _`Apache`: https://httpd.apache.org/docs/current/en/howto/ssi.html
+.. _`Nginx`: https://nginx.org/en/docs/http/ngx_http_ssi_module.html
+.. _`available directives`: https://en.wikipedia.org/wiki/Server_Side_Includes#Directives
+.. _`OWASP article`: https://www.owasp.org/index.php/Server-Side_Includes_(SSI)_Injection
diff --git a/http_cache/validation.rst b/http_cache/validation.rst
index f2882d70b13..e45ad19885a 100644
--- a/http_cache/validation.rst
+++ b/http_cache/validation.rst
@@ -29,18 +29,7 @@ page again (see below for an implementation example).
 Like with expiration, there are two different HTTP headers that can be used
 to implement the validation model: ``ETag`` and ``Last-Modified``.
 
-.. sidebar:: Expiration and Validation
-
-    You can use both validation and expiration within the same ``Response``.
-    As expiration wins over validation, you can benefit from the best of
-    both worlds. In other words, by using both expiration and validation, you
-    can instruct the cache to serve the cached content, while checking back
-    at some interval (the expiration) to verify that the content is still valid.
-
-    .. tip::
-
-        You can also define HTTP caching headers for expiration and validation by using
-        annotations. See the `FrameworkExtraBundle documentation`_.
+.. include:: /http_cache/_expiration-and-validation.rst.inc
 
 .. index::
     single: Cache; Etag header
@@ -62,7 +51,7 @@ To see a simple implementation, generate the ETag as the md5 of the content::
     // src/Controller/DefaultController.php
     namespace App\Controller;
 
-    use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpFoundation\Request;
 
     class DefaultController extends AbstractController
@@ -126,9 +115,9 @@ header value::
     namespace App\Controller;
 
     // ...
-    use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\HttpFoundation\Request;
     use App\Entity\Article;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
 
     class ArticleController extends AbstractController
     {
@@ -186,8 +175,8 @@ exposing a simple and efficient pattern::
     namespace App\Controller;
 
     // ...
-    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
 
     class ArticleController extends AbstractController
     {
@@ -230,5 +219,3 @@ headers that must not be present for ``304`` responses (see
 :method:`Symfony\\Component\\HttpFoundation\\Response::setNotModified`).
 
 .. _`expiration model`: https://tools.ietf.org/html/rfc2616#section-13.2
-.. _`validation model`: http://tools.ietf.org/html/rfc2616#section-13.3
-.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html
diff --git a/http_cache/varnish.rst b/http_cache/varnish.rst
index ae7a6395b70..776097339f9 100644
--- a/http_cache/varnish.rst
+++ b/http_cache/varnish.rst
@@ -63,7 +63,7 @@ authentication, have Varnish remove the corresponding header from requests to
 prevent clients from bypassing the cache. In practice, you will need sessions
 at least for some parts of the site, e.g. when using forms with
 :doc:`CSRF Protection </security/csrf>`. In this situation, make sure to
-:doc:`only start a session when actually needed </session/avoid_session_start>`
+:ref:`only start a session when actually needed <session-avoid-start>`
 and clear the session when it is no longer needed. Alternatively, you can look
 into :ref:`caching pages that contain CSRF protected forms <caching-pages-that-contain-csrf-protected-forms>`.
 
@@ -134,9 +134,8 @@ using Varnish 3:
     .. code-block:: varnish3
 
         sub vcl_fetch {
-            /* By default, Varnish3 ignores Cache-Control: no-cache and private
-               https://www.varnish-cache.org/docs/3.0/tutorial/increasing_your_hitrate.html#cache-control
-             */
+            // By default, Varnish3 ignores Cache-Control: no-cache and private
+            // https://www.varnish-cache.org/docs/3.0/tutorial/increasing_your_hitrate.html#cache-control
             if (beresp.http.Cache-Control ~ "private" ||
                 beresp.http.Cache-Control ~ "no-cache" ||
                 beresp.http.Cache-Control ~ "no-store"
@@ -236,11 +235,10 @@ proxy before it has expired, it adds complexity to your caching setup.
 
 .. _`Varnish`: https://www.varnish-cache.org
 .. _`Edge Architecture`: http://www.w3.org/TR/edge-arch
-.. _`GZIP and Varnish`: https://www.varnish-cache.org/docs/3.0/phk/gzip.html
-.. _`Clean the cookies header`: https://www.varnish-cache.org/trac/wiki/VCLExampleRemovingSomeCookies
+.. _`clean the cookies header`: https://www.varnish-cache.org/trac/wiki/VCLExampleRemovingSomeCookies
 .. _`Surrogate-Capability Header`: http://www.w3.org/TR/edge-arch
 .. _`cache invalidation`: http://tools.ietf.org/html/rfc2616#section-13.10
 .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
-.. _`default.vcl`: https://github.com/varnish/Varnish-Cache/blob/3.0/bin/varnishd/default.vcl
-.. _`builtin.vcl`: https://github.com/varnish/Varnish-Cache/blob/4.1/bin/varnishd/builtin.vcl
+.. _`default.vcl`: https://github.com/varnishcache/varnish-cache/blob/3.0/bin/varnishd/default.vcl
+.. _`builtin.vcl`: https://github.com/varnishcache/varnish-cache/blob/4.1/bin/varnishd/builtin.vcl
 .. _`User Context`: http://foshttpcachebundle.readthedocs.org/en/latest/features/user-context.html
diff --git a/index.rst b/index.rst
index 4c23c8cbb01..7fc90780628 100644
--- a/index.rst
+++ b/index.rst
@@ -32,6 +32,7 @@ Topics
     :maxdepth: 1
 
     bundles
+    cache
     console
     doctrine
     deployment
@@ -41,7 +42,10 @@ Topics
     frontend
     http_cache
     logging
+    mailer
+    mercure
     messenger
+    migration
     performance
     profiler
     routing
diff --git a/introduction/from_flat_php_to_symfony2.rst b/introduction/from_flat_php_to_symfony.rst
similarity index 98%
rename from introduction/from_flat_php_to_symfony2.rst
rename to introduction/from_flat_php_to_symfony.rst
index 3af19f3fce1..63b32c5ed8d 100644
--- a/introduction/from_flat_php_to_symfony2.rst
+++ b/introduction/from_flat_php_to_symfony.rst
@@ -133,7 +133,7 @@ of *your* code that processes user input and prepares the response.
 
 In this case, the controller prepares data from the database and then includes
 a template to present that data. With the controller isolated, you could
-easily change *just* the template file if you needed to render the blog
+change *just* the template file if you needed to render the blog
 entries in some other format (e.g. ``list.json.php`` for JSON format).
 
 Isolating the Application (Domain) Logic
@@ -243,9 +243,8 @@ the ``templates/layout.php``:
 You now have a setup that will allow you to reuse the layout.
 Unfortunately, to accomplish this, you're forced to use a few ugly
 PHP functions (``ob_start()``, ``ob_get_clean()``) in the template. Symfony
-uses a :doc:`Templating </components/templating>` component
-that allows this to be accomplished cleanly and easily. You'll see it in
-action shortly.
+solves this using a :doc:`Templating </components/templating>` component.
+You'll see it in action shortly.
 
 Adding a Blog "show" Page
 -------------------------
@@ -307,7 +306,7 @@ Creating the second page now requires very little work and no code is duplicated
 this page introduces even more lingering problems that a framework can solve
 for you. For example, a missing or invalid ``id`` query parameter will cause
 the page to crash. It would be better if this caused a 404 page to be rendered,
-but this can't really be done easily yet.
+but this can't really be done yet.
 
 Another major problem is that each individual controller file must include
 the ``model.php`` file. What if each controller file suddenly needed to include
@@ -704,10 +703,8 @@ A good selection of `Symfony community tools`_ can be found on GitHub.
 
 .. _`Model-View-Controller`: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
 .. _`Doctrine`: http://www.doctrine-project.org
-.. _`SQL injection attack`: https://en.wikipedia.org/wiki/SQL_injection
 .. _`Composer`: https://getcomposer.org
 .. _`download Composer`: https://getcomposer.org/download/
 .. _`Validator`: https://github.com/symfony/validator
 .. _`Varnish`: https://www.varnish-cache.org/
-.. _`Twig`: https://twig.symfony.com
 .. _`Symfony community tools`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories
diff --git a/introduction/http_fundamentals.rst b/introduction/http_fundamentals.rst
index 82c08057116..11fc83efadf 100644
--- a/introduction/http_fundamentals.rst
+++ b/introduction/http_fundamentals.rst
@@ -23,7 +23,6 @@ to communicate with each other. For example, when checking for the latest
 .. image:: /_images/http/xkcd-full.png
    :align: center
 
-And while the actual language used is a bit more formal, it's still dead-simple.
 HTTP is the term used to describe this text-based language. The goal of
 your server is *always* to understand text requests and return text responses.
 
@@ -121,7 +120,7 @@ like this:
     Content-Type: text/html
 
     <html>
-      <!-- ... HTML for the xkcd comic -->
+        <!-- ... HTML for the xkcd comic -->
     </html>
 
 The HTTP response contains the requested resource (the HTML content in this
@@ -147,8 +146,7 @@ Requests, Responses and Web Development
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This request-response conversation is the fundamental process that drives all
-communication on the web. And as important and powerful as this process is,
-it's inescapably simple.
+communication on the web.
 
 The most important fact is this: regardless of the language you use, the
 type of application you build (web, mobile, JSON API) or the development
@@ -275,11 +273,11 @@ and more.
     that you can use in *any* PHP project. This also contains classes for handling
     sessions, file uploads and more.
 
-If Symfony offered nothing else, you would already have a toolkit for conveniently
-accessing request information and an object-oriented interface for creating
-the response. Even as you learn the many powerful features in Symfony, keep
-in mind that the goal of your application is always *to interpret a request
-and create the appropriate response based on your application logic*.
+If Symfony offered nothing else, you would already have a toolkit for accessing
+request information and an object-oriented interface for creating the response.
+Even as you learn the many powerful features in Symfony, keep in mind that the
+goal of your application is always *to interpret a request and create the
+appropriate response based on your application logic*.
 
 The Journey from the Request to the Response
 --------------------------------------------
@@ -328,7 +326,7 @@ executing different PHP files, the front controller is *always* executed,
 and the routing of different URLs to different parts of your application
 is done internally.
 
-A very simple front controller might look like this::
+A small front controller might look like this::
 
     // index.php
     use Symfony\Component\HttpFoundation\Request;
@@ -391,9 +389,6 @@ Here's what we've learned so far:
 .. _`XMLHttpRequest`: https://en.wikipedia.org/wiki/XMLHttpRequest
 .. _`HTTP 1.1 RFC`: http://www.w3.org/Protocols/rfc2616/rfc2616.html
 .. _`HTTP Bis`: http://datatracker.ietf.org/wg/httpbis/
-.. _`Live HTTP Headers`: https://addons.mozilla.org/en-US/firefox/addon/live-http-headers/
 .. _`List of HTTP header fields`: https://en.wikipedia.org/wiki/List_of_HTTP_header_fields
 .. _`list of HTTP status codes`: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 .. _`List of common media types`: https://www.iana.org/assignments/media-types/media-types.xhtml
-.. _`Validator`: https://github.com/symfony/validator
-.. _`Swift Mailer`: http://swiftmailer.org/
diff --git a/logging.rst b/logging.rst
index 80f0a3a6140..c54b30f7c0d 100644
--- a/logging.rst
+++ b/logging.rst
@@ -41,7 +41,7 @@ To log a message, inject the default logger in your controller::
     }
 
 The ``logger`` service has different methods for different logging levels/priorities.
-See LoggerInterface_ for a list of all of the methods on the logger.
+See `LoggerInterface`_ for a list of all of the methods on the logger.
 
 Monolog
 -------
@@ -118,9 +118,9 @@ to write logs using the :phpfunction:`syslog` function:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler
@@ -197,9 +197,9 @@ one of the messages reaches an ``action_level``. Take this example:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler
@@ -241,7 +241,7 @@ one of the messages reaches an ``action_level``. Take this example:
                     'type'  => 'syslog',
                     'level' => 'error',
                 ],
-            ),
+            ],
         ]);
 
 Now, if even one log entry has an ``error`` level or higher, then *all* log entries
@@ -303,9 +303,9 @@ option of your handler to ``rotating_file``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <!-- "max_files": max number of log files to keep
@@ -338,6 +338,16 @@ option of your handler to ``rotating_file``:
 Using a Logger inside a Service
 -------------------------------
 
+If your application uses :ref:`service autoconfiguration <services-autoconfigure>`,
+any service whose class implements ``Psr\Log\LoggerAwareInterface`` will
+receive a call to its method ``setLogger()`` with the default logger service
+passed as a service.
+
+.. versionadded:: 4.2
+
+    The automatic call to ``setLogger()`` when implementing ``LoggerAwareInterface``
+    was introduced in Symfony 4.2.
+
 If you want to use in your own services a pre-configured logger which uses a
 specific channel (``app`` by default), use the ``monolog.logger`` tag  with the
 ``channel`` property as explained in the
diff --git a/logging/channels_handlers.rst b/logging/channels_handlers.rst
index c0789c647e1..200f9504ea0 100644
--- a/logging/channels_handlers.rst
+++ b/logging/channels_handlers.rst
@@ -15,8 +15,8 @@ the channel).
 .. note::
 
     Each channel corresponds to a logger service (``monolog.logger.XXX``)
-    in the container (use the ``debug:container`` command to see a full list)
-    and those are injected into different services.
+    in the container (use the ``php bin/console debug:container monolog`` command
+    to see a full list) and those are injected into different services.
 
 .. _logging-channel-handler:
 
@@ -53,9 +53,9 @@ from the ``security`` channel:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler name="security" type="stream" path="%kernel.logs_dir%/security.log">
@@ -96,7 +96,7 @@ from the ``security`` channel:
 
 .. caution::
 
-    The ``channels`` configuration only works for top level handlers. Handlers
+    The ``channels`` configuration only works for top-level handlers. Handlers
     that are nested inside a group, buffer, filter, fingers crossed or other
     such handler will ignore this configuration and will process every message
     passed to them.
@@ -148,9 +148,9 @@ You can also configure additional channels without the need to tag your services
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:channel>foo</monolog:channel>
diff --git a/logging/formatter.rst b/logging/formatter.rst
index 14d4f3dfe4d..b41cd7ad06e 100644
--- a/logging/formatter.rst
+++ b/logging/formatter.rst
@@ -3,9 +3,8 @@ How to Define a Custom Logging Formatter
 
 Each logging handler uses a ``Formatter`` to format the record before logging
 it. All Monolog handlers use an instance of
-``Monolog\Formatter\LineFormatter`` by default but you can configure a
-different one. Your formatter must implement
-``Monolog\Formatter\FormatterInterface``.
+``Monolog\Formatter\LineFormatter`` by default but you can replace it.
+Your formatter must implement ``Monolog\Formatter\FormatterInterface``.
 
 For example, to use the built-in ``JsonFormatter``, register it as a service then
 configure your handler to use it:
@@ -14,19 +13,13 @@ configure your handler to use it:
 
     .. code-block:: yaml
 
-        # config/services.yaml
-        services:
-            # ...
-
-            Monolog\Formatter\JsonFormatter: ~
-
         # config/packages/prod/monolog.yaml (and/or config/packages/dev/monolog.yaml)
         monolog:
             handlers:
                 file:
                     type: stream
                     level: debug
-                    formatter: Monolog\Formatter\JsonFormatter
+                    formatter: 'monolog.formatter.json'
 
     .. code-block:: xml
 
@@ -36,13 +29,9 @@ configure your handler to use it:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
-
-            <services>
-                <service id="Monolog\Formatter\JsonFormatter" />
-            </services>
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <!-- config/packages/prod/monolog.xml (and/or config/packages/dev/monolog.xml) -->
             <monolog:config>
@@ -50,7 +39,7 @@ configure your handler to use it:
                     name="file"
                     type="stream"
                     level="debug"
-                    formatter="Monolog\Formatter\JsonFormatter"
+                    formatter="monolog.formatter.json"
                 />
             </monolog:config>
         </container>
@@ -60,15 +49,13 @@ configure your handler to use it:
         // config/services.php
         use Monolog\Formatter\JsonFormatter;
 
-        $container->register(JsonFormatter::class);
-
         // config/packages/prod/monolog.php (and/or config/packages/dev/monolog.php)
         $container->loadFromExtension('monolog', [
             'handlers' => [
                 'file' => [
                     'type'      => 'stream',
                     'level'     => 'debug',
-                    'formatter' => JsonFormatter::class,
+                    'formatter' => 'monolog.formatter.json',
                 ],
             ],
         ]);
diff --git a/logging/monolog_console.rst b/logging/monolog_console.rst
index 8d3622de9d3..0713fa6e8bd 100644
--- a/logging/monolog_console.rst
+++ b/logging/monolog_console.rst
@@ -90,7 +90,7 @@ The Monolog console handler is enabled by default:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <monolog:config>
                 <!-- ... -->
diff --git a/logging/monolog_email.rst b/logging/monolog_email.rst
index afbbe0654f4..14d4fe092c2 100644
--- a/logging/monolog_email.rst
+++ b/logging/monolog_email.rst
@@ -4,7 +4,7 @@
 How to Configure Monolog to Email Errors
 ========================================
 
-Monolog_ can be configured to send an email when an error occurs with an
+`Monolog`_ can be configured to send an email when an error occurs with an
 application. The configuration for this requires a few nested handlers
 in order to avoid receiving too many emails. This configuration looks
 complicated at first but each handler is fairly straightforward when
@@ -48,8 +48,8 @@ it is broken down.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/monolog http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/monolog https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <!--
@@ -138,8 +138,8 @@ is then passed onto the ``deduplicated`` handler.
     set the ``action_level`` to ``error`` instead of ``critical``. See the
     code above for an example.
 
-The ``deduplicated`` handler keeps all the messages for a request and
-then passes them onto the nested handler in one go, but only if the records are
+The ``deduplicated`` handler keeps all the messages for a request and then
+passes them onto the nested handler in one go, but only if the records are
 unique over a given period of time (60 seconds by default). If the records are
 duplicates they are discarded. Adding this handler reduces the amount of
 notifications to a manageable level, specially in critical failure scenarios.
@@ -167,7 +167,7 @@ You can adjust the time period using the ``time`` option:
         <monolog:handler name="deduplicated"
             type="deduplication"
             time="10"
-            handler="swift" />
+            handler="swift"/>
 
     .. code-block:: php
 
@@ -180,7 +180,9 @@ You can adjust the time period using the ``time`` option:
                     // the time in seconds during which duplicate entries are discarded (default: 60)
                     'time' => 10,
                     'handler' => 'swift',
-                ]
+                ],
+            ],
+        ]);
 
 The messages are then passed to the ``swift`` handler. This is the handler that
 actually deals with emailing you the error. The settings for this are
@@ -212,12 +214,12 @@ get logged on the server as well as the emails being sent:
                     type:    deduplication
                     handler: swift
                 swift:
-                    type:       swift_mailer
-                    from_email: 'error@example.com'
-                    to_email:   'error@example.com'
-                    subject:    'An Error Occurred! %%message%%'
-                    level:      debug
-                    formatter:  monolog.formatter.html
+                    type:         swift_mailer
+                    from_email:   'error@example.com'
+                    to_email:     'error@example.com'
+                    subject:      'An Error Occurred! %%message%%'
+                    level:        debug
+                    formatter:    monolog.formatter.html
                     content_type: text/html
 
     .. code-block:: xml
@@ -227,8 +229,8 @@ get logged on the server as well as the emails being sent:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/monolog http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/monolog https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler
diff --git a/logging/monolog_exclude_http_codes.rst b/logging/monolog_exclude_http_codes.rst
index d1e3a4b2f8d..9c1bd81bdcc 100644
--- a/logging/monolog_exclude_http_codes.rst
+++ b/logging/monolog_exclude_http_codes.rst
@@ -6,10 +6,6 @@
 How to Configure Monolog to Exclude Specific HTTP Codes from the Log
 ====================================================================
 
-.. versionadded:: 4.1
-    The ability to exclude log messages based on their status codes was
-    introduced in Symfony 4.1 and MonologBundle 3.3.
-
 Sometimes your logs become flooded with unwanted HTTP errors, for example,
 403s and 404s. When using a ``fingers_crossed`` handler, you can exclude
 logging these HTTP codes based on the MonologBundle configuration:
@@ -34,9 +30,9 @@ logging these HTTP codes based on the MonologBundle configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler type="fingers_crossed" name="main" handler="...">
@@ -45,7 +41,7 @@ logging these HTTP codes based on the MonologBundle configuration:
                         <monolog:url>^/foo</monolog:url>
                         <monolog:url>^/bar</monolog:url>
                     </monolog:excluded-http-code>
-                    <monolog:excluded-http-code code="404" />
+                    <monolog:excluded-http-code code="404"/>
                 </monolog:handler>
             </monolog:config>
         </container>
@@ -63,3 +59,11 @@ logging these HTTP codes based on the MonologBundle configuration:
                 ],
             ],
         ]);
+
+.. caution::
+
+    Combining ``excluded_http_codes`` with a ``passthru_level`` lower than
+    ``error`` (i.e. ``debug``, ``info``, ``notice`` or ``warning``) will not
+    actually exclude log messages for those HTTP codes because they are logged
+    with level of ``error`` or higher and ``passthru_level`` takes precedence
+    over the HTTP codes being listed in ``excluded_http_codes``.
diff --git a/logging/monolog_regex_based_excludes.rst b/logging/monolog_regex_based_excludes.rst
index 91d259a6508..be4a6ee8b7e 100644
--- a/logging/monolog_regex_based_excludes.rst
+++ b/logging/monolog_regex_based_excludes.rst
@@ -39,9 +39,9 @@ configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler type="fingers_crossed" name="main" handler="...">
@@ -66,3 +66,13 @@ configuration:
                 ],
             ],
         ]);
+
+
+.. caution::
+
+    Combining ``excluded_404s`` with a ``passthru_level`` lower than
+    ``error`` (i.e. ``debug``, ``info``, ``notice`` or ``warning``) will not
+    actually exclude log messages for the URL(s) listed in ``excluded_404s``
+    because they are logged with level of ``error`` or higher and
+    ``passthru_level`` takes precedence over the URLs being listed in
+    ``excluded_404s``.
diff --git a/logging/processors.rst b/logging/processors.rst
index f4ad8c29da1..64ac4893ff4 100644
--- a/logging/processors.rst
+++ b/logging/processors.rst
@@ -72,9 +72,9 @@ information:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <services>
                 <service id="monolog.formatter.session_request"
@@ -84,7 +84,7 @@ information:
                 </service>
 
                 <service id="App\Logger\SessionRequestProcessor">
-                    <tag name="monolog.processor" />
+                    <tag name="monolog.processor"/>
                 </service>
             </services>
         </container>
@@ -126,9 +126,9 @@ Finally, set the formatter to be used on whatever handler you want:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
                 <monolog:handler
@@ -159,6 +159,31 @@ If you use several handlers, you can also register a processor at the
 handler level or at the channel level instead of registering it globally
 (see the following sections).
 
+Symfony's MonologBridge provides processors that can be registered inside your application.
+
+:class:`Symfony\\Bridge\\Monolog\\Processor\\DebugProcessor`
+    Adds additional information useful for debugging like a timestamp or an
+    error message to the record.
+
+:class:`Symfony\\Bridge\\Monolog\\Processor\\TokenProcessor`
+    Adds information from the current user's token to the record namely
+    username, roles and whether the user is authenticated.
+
+:class:`Symfony\\Bridge\\Monolog\\Processor\\WebProcessor`
+    Overrides data from the request using the data inside Symfony's request
+    object.
+
+:class:`Symfony\\Bridge\\Monolog\\Processor\\RouteProcessor`
+    Adds information about current route (controller, action, route parameters).
+
+:class:`Symfony\\Bridge\\Monolog\\Processor\\ConsoleCommandProcessor`
+    Adds information about current console command.
+
+.. versionadded:: 4.3
+
+    The ``RouteProcessor`` and the ``ConsoleCommandProcessor`` were introduced
+    in Symfony 4.3.
+
 Registering Processors per Handler
 ----------------------------------
 
@@ -183,13 +208,13 @@ the ``monolog.processor`` tag:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <services>
                 <service id="App\Logger\SessionRequestProcessor">
-                    <tag name="monolog.processor" handler="main" />
+                    <tag name="monolog.processor" handler="main"/>
                 </service>
             </services>
         </container>
@@ -227,13 +252,13 @@ the ``monolog.processor`` tag:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:monolog="http://symfony.com/schema/dic/monolog"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/monolog
-                http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <services>
                 <service id="App\Logger\SessionRequestProcessor">
-                    <tag name="monolog.processor" channel="main" />
+                    <tag name="monolog.processor" channel="main"/>
                 </service>
             </services>
         </container>
diff --git a/mailer.rst b/mailer.rst
new file mode 100644
index 00000000000..a4922c877d2
--- /dev/null
+++ b/mailer.rst
@@ -0,0 +1,661 @@
+Sending Emails with Mailer
+==========================
+
+.. versionadded:: 4.3
+
+    The Mailer component was added in Symfony 4.3 and is currently experimental.
+    The previous solution - Swift Mailer - is still valid: :doc:`Swift Mailer</email>`.
+
+Installation
+------------
+
+.. caution::
+
+    The Mailer component is experimental in Symfony 4.3: some backwards compatibility
+    breaks could occur before 4.4.
+
+Symfony's Mailer & :doc:`Mime </components/mime>` components form a *powerful* system
+for creating and sending emails - complete with support for multipart messages, Twig
+integration, CSS inlining, file attachments and a lot more. Get them installed with:
+
+.. code-block:: terminal
+
+    $ composer require symfony/mailer
+
+Transport Setup
+---------------
+
+Emails are delivered via a "transport". And without installing anything else, you
+can deliver emails over ``smtp`` by configuring your ``.env`` file:
+
+.. code-block:: bash
+
+    # .env
+    MAILER_DSN=smtp://user:pass@smtp.example.com
+
+.. warning::
+
+    If you are migrating from Swiftmailer (and the Swiftmailer bundle), be
+    warned that the DSN format is different.
+
+Using a 3rd Party Transport
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+But an easier option is to send emails via a 3rd party provider. Mailer supports
+several - install whichever you want:
+
+==================  =============================================
+Service             Install with
+==================  =============================================
+Amazon SES          ``composer require symfony/amazon-mailer``
+Gmail               ``composer require symfony/google-mailer``
+MailChimp           ``composer require symfony/mailchimp-mailer``
+Mailgun             ``composer require symfony/mailgun-mailer``
+Postmark            ``composer require symfony/postmark-mailer``
+SendGrid            ``composer require symfony/sendgrid-mailer``
+==================  =============================================
+
+Each library includes a :ref:`Symfony Flex recipe <symfony-flex>` that will add
+example configuration to your ``.env`` file. For example, suppose you want to
+use SendGrid. First, install it:
+
+.. code-block:: terminal
+
+    $ composer require symfony/sendgrid-mailer
+
+You'll now have a new line in your ``.env`` file that you can uncomment:
+
+.. code-block:: bash
+
+    # .env
+    SENDGRID_KEY=
+    MAILER_DSN=smtp://$SENDGRID_KEY@sendgrid
+
+The ``MAILER_DSN`` isn't a *real* SMTP address: it's a simple format that offloads
+most of the configuration work to mailer. The ``@sendgrid`` part of the address
+activates the SendGrid mailer library that you just installed, which knows all
+about how to deliver messages to SendGrid.
+
+The *only* part you need to change is to set ``SENDGRID_KEY`` to your key (in
+``.env`` or ``.env.local``).
+
+Each transport will have different environment variables that the library will use
+to configure the *actual* address and authentication for delivery. Some also have
+options that can be configured with query parameters on end of the ``MAILER_DSN`` -
+like ``?region=`` for Amazon SES. Some transports support sending via ``http``
+or ``smtp`` - both work the same, but ``http`` is recommended when available.
+
+.. tip::
+
+    Check the :ref:`DSN formats <mailer_dsn>` for all supported providers.
+
+Creating & Sending Messages
+---------------------------
+
+To send an email, autowire the mailer using
+:class:`Symfony\\Component\\Mailer\\MailerInterface` (service id ``mailer``)
+and create an :class:`Symfony\\Component\\Mime\\Email` object::
+
+    // src/Controller/MailerController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Mailer\MailerInterface;
+    use Symfony\Component\Mime\Email;
+
+    class MailerController extends AbstractController
+    {
+        /**
+         * @Route("/email")
+         */
+        public function sendEmail(MailerInterface $mailer)
+        {
+            $email = (new Email())
+                ->from('hello@example.com')
+                ->to('you@example.com')
+                //->cc('cc@example.com')
+                //->bcc('bcc@example.com')
+                //->replyTo('fabien@example.com')
+                //->priority(Email::PRIORITY_HIGH)
+                ->subject('Time for Symfony Mailer!')
+                ->text('Sending emails is fun again!')
+                ->html('<p>See Twig integration for better HTML integration!</p>');
+
+            $mailer->send($email);
+
+            // ...
+        }
+    }
+
+That's it! The message will be sent via whatever transport you configured.
+
+Email Addresses
+~~~~~~~~~~~~~~~
+
+All the methods that require email addresses (``from()``, ``to()``, etc.) accept
+both strings or address objects::
+
+    // ...
+    use Symfony\Component\Mime\Address;
+    use Symfony\Component\Mime\NamedAddress;
+
+    $email = (new Email())
+        // email address as a simple string
+        ->from('fabien@example.com')
+
+        // email address as an object
+        ->from(new Address('fabien@example.com'))
+
+        // email address as an object (email clients will display the name
+        // instead of the email address)
+        ->from(new NamedAddress('fabien@example.com', 'Fabien'))
+
+        // ...
+    ;
+
+Multiple addresses are defined with the ``addXXX()`` methods::
+
+    $email = (new Email())
+        ->to('foo@example.com')
+        ->addTo('bar@example.com')
+        ->addTo('baz@example.com')
+
+        // ...
+    ;
+
+Alternatively, you can pass multiple addresses to each method::
+
+    $toAddresses = ['foo@example.com', new Address('bar@example.com')];
+
+    $email = (new Email())
+        ->to(...$toAddresses)
+        ->cc('cc1@example.com', 'cc2@example.com')
+
+        // ...
+    ;
+
+Message Contents
+~~~~~~~~~~~~~~~~
+
+The text and HTML contents of the email messages can be strings (usually the
+result of rendering some template) or PHP resources::
+
+    $email = (new Email())
+        // ...
+        // simple contents defined as a string
+        ->text('Lorem ipsum...')
+        ->html('<p>Lorem ipsum...</p>')
+
+        // attach a file stream
+        ->text(fopen('/path/to/emails/user_signup.txt', 'r'))
+        ->html(fopen('/path/to/emails/user_signup.html', 'r'))
+    ;
+
+.. tip::
+
+    You can also use Twig templates to render the HTML and text contents. Read
+    the `Twig: HTML & CSS`_ section later in this article to
+    learn more.
+
+File Attachments
+~~~~~~~~~~~~~~~~
+
+Use the ``attachFromPath()`` method to attach files that exist on your file system::
+
+    $email = (new Email())
+        // ...
+        ->attachFromPath('/path/to/documents/terms-of-use.pdf')
+        // optionally you can tell email clients to display a custom name for the file
+        ->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy')
+        // optionally you can provide an explicit MIME type (otherwise it's guessed)
+        ->attachFromPath('/path/to/documents/contract.doc', 'Contract', 'application/msword')
+        // you can also use an absolute URL if your PHP config allows getting URLs using fopen()
+        // (this is not recommended because your application may or may not work depending on PHP config)
+        ->attachFromPath('http://example.com/path/to/documents/contract.doc', 'Contract', 'application/msword')
+    ;
+
+Alternatively you can use the ``attach()`` method to attach contents from a stream::
+
+    $email = (new Email())
+        // ...
+        ->attach(fopen('/path/to/documents/contract.doc', 'r'))
+    ;
+
+Embedding Images
+~~~~~~~~~~~~~~~~
+
+If you want to display images inside your email, you must embed them
+instead of adding them as attachments. When using Twig to render the email
+contents, as explained `later in this article <Embedding Images>`_,
+the images are embedded automatically. Otherwise, you need to embed them manually.
+
+First, use the ``embed()`` or ``embedFromPath()`` method to add an image from a
+file or stream::
+
+    $email = (new Email())
+        // ...
+        // get the image contents from a PHP resource
+        ->embed(fopen('/path/to/images/logo.png', 'r'), 'logo')
+        // get the image contents from an existing file
+        ->embedFromPath('/path/to/images/signature.gif', 'footer-signature')
+    ;
+
+The second optional argument of both methods is the image name ("Content-ID" in
+the MIME standard). Its value is an arbitrary string used later to reference the
+images inside the HTML contents::
+
+    $email = (new Email())
+        // ...
+        ->embed(fopen('/path/to/images/logo.png', 'r'), 'logo')
+        ->embedFromPath('/path/to/images/signature.gif', 'footer-signature')
+        // reference images using the syntax 'cid:' + "image embed name"
+        ->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...')
+    ;
+
+Global from Address
+-------------------
+
+Instead of calling ``->from()`` *every* time you create a new email, you can
+create an event subscriber to set it automatically::
+
+    // src/EventListener/MailerFromListener.php
+    namespace App\EventListener;
+
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\Mailer\Event\MessageEvent;
+    use Symfony\Component\Mime\Email;
+
+    class MailerFromListener implements EventSubscriberInterface
+    {
+        public function onMessageSend(MessageEvent $event)
+        {
+            $message = $event->getMessage();
+
+            // make sure it's an Email object
+            if (!$message instanceof Email) {
+                return;
+            }
+
+            // always set the from address
+            $message->from('fabien@example.com');
+        }
+
+        public static function getSubscribedEvents()
+        {
+            return [MessageEvent::class => 'onMessageSend'];
+        }
+    }
+
+.. _mailer-twig:
+
+Twig: HTML & CSS
+----------------
+
+The Mime component integrates with the :doc:`Twig template engine </templating>`
+to provide advanced features such as CSS style inlining and support for HTML/CSS
+frameworks to create complex HTML email messages. First, make sure Twig is installed:
+
+.. code-block:: terminal
+
+    $ composer require symfony/twig-bundle
+
+HTML Content
+~~~~~~~~~~~~
+
+To define the contents of your email with Twig, use the
+:class:`Symfony\\Bridge\\Twig\\Mime\\TemplatedEmail` class. This class extends
+the normal :class:`Symfony\\Component\\Mime\\Email` class but adds some new methods
+for Twig templates::
+
+    use Symfony\Bridge\Twig\Mime\TemplatedEmail;
+
+    $email = (new TemplatedEmail())
+        ->from('fabien@example.com')
+        ->to(new NamedAddress('ryan@example.com', 'Ryan'))
+        ->subject('Thanks for signing up!')
+
+        // path of the Twig template to render
+        ->htmlTemplate('emails/signup.html.twig')
+
+        // pass variables (name => value) to the template
+        ->context([
+            'expiration_date' => new \DateTime('+7 days'),
+            'username' => 'foo',
+        ])
+    ;
+
+Then, create the template:
+
+.. code-block:: html+twig
+
+    {# templates/emails/signup.html.twig #}
+    <h1>Welcome {{ email.toName }}!</h1>
+
+    <p>
+        You signed up as {{ username }} the following email:
+    </p>
+    <p><code>{{ email.to[0].address }}</code></p>
+
+    <p>
+        <a href="#">Click here to activate your account</a>
+        (this link is valid until {{ expiration_date|date('F jS') }})
+    </p>
+
+The Twig template has access to any of the parameters passed in the ``context()``
+method of the ``TemplatedEmail`` class and also to a special variable called
+``email``, which is an instance of
+:class:`Symfony\\Bridge\\Twig\\Mime\\WrappedTemplatedEmail`.
+
+Text Content
+~~~~~~~~~~~~
+
+When the text content of a ``TemplatedEmail`` is not explicitly defined, mailer
+will generate it automatically by converting the HTML contents into text. If you
+have `league/html-to-markdown`_ installed in your application,
+it uses that to turn HTML into Markdown (so the text email has some visual appeal).
+Otherwise, it applies the :phpfunction:`strip_tags` PHP function to the original
+HTML contents.
+
+If you want to define the text content yourself, use the ``text()`` method
+explained in the previous sections or the ``textTemplate()`` method provided by
+the ``TemplatedEmail`` class:
+
+.. code-block:: diff
+
+    + use Symfony\Bridge\Twig\Mime\TemplatedEmail;
+
+    $email = (new TemplatedEmail())
+        // ...
+
+        ->htmlTemplate('emails/signup.html.twig')
+    +     ->textTemplate('emails/signup.txt.twig')
+        // ...
+    ;
+
+Embedding Images
+~~~~~~~~~~~~~~~~
+
+Instead of dealing with the ``<img src="cid: ...">`` syntax explained in the
+previous sections, when using Twig to render email contents you can refer to
+image files as usual. First, to simplify things, define a Twig namespace called
+``images`` that points to whatever directory your images are stored in:
+
+.. code-block:: yaml
+
+    # config/packages/twig.yaml
+    twig:
+        # ...
+
+        paths:
+            # point this wherever your images live
+            '%kernel.project_dir%/assets/images': images
+
+Now, use the special ``email.image()`` Twig helper to embed the images inside
+the email contents:
+
+.. code-block:: html+twig
+
+    {# '@images/' refers to the Twig namespace defined earlier #}
+    <img src="{{ email.image('@images/logo.png') }}" alt="Logo">
+
+    <h1>Welcome {{ email.toName }}!</h1>
+    {# ... #}
+
+.. _mailer-inline-css:
+
+Inlining CSS Styles
+~~~~~~~~~~~~~~~~~~~
+
+Designing the HTML contents of an email is very different from designing a
+normal HTML page. For starters, most email clients only support a subset of all
+CSS features. In addition, popular email clients like Gmail don't support
+defining styles inside ``<style> ... </style>`` sections and you must **inline
+all the CSS styles**.
+
+CSS inlining means that every HTML tag must define a ``style`` attribute with
+all its CSS styles. This can make organizing your CSS a mess. That's why Twig
+provides a ``CssInlinerExtension`` that automates everything for you. Install
+it with:
+
+.. code-block:: terminal
+
+    $ composer require twig/cssinliner-extension
+
+The extension is enabled automatically. To use this, wrap the entire template
+with the ``inline_css`` filter:
+
+.. code-block:: html+twig
+
+    {% apply inline_css %}
+        <style>
+            {# here, define your CSS styles as usual #}
+            h1 {
+                color: #333;
+            }
+        </style>
+
+        <h1>Welcome {{ email.toName }}!</h1>
+        {# ... #}
+    {% endapply %}
+
+Using External CSS Files
+........................
+
+You can also define CSS styles in external files and pass them as
+arguments to the filter:
+
+.. code-block:: html+twig
+
+    {% apply inline_css(source('@css/email.css')) %}
+        <h1>Welcome {{ username }}!</h1>
+        {# ... #}
+    {% endapply %}
+
+You can pass unlimited number of arguments to ``inline_css()`` to load multiple
+CSS files. For this example to work, you also need to define a new Twig namespace
+called ``css`` that points to the directory where ``email.css`` lives:
+
+.. _mailer-css-namespace:
+
+.. code-block:: yaml
+
+    # config/packages/twig.yaml
+    twig:
+        # ...
+
+        paths:
+            # point this wherever your css files live
+            '%kernel.project_dir%/assets/css': css
+
+.. _mailer-markdown:
+
+Rendering Markdown Content
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Twig provides another extension called ``MarkdownExtension`` that lets you
+define the email contents using `Markdown syntax`_. To use this, install the
+extension and a Markdown conversion library (the extension is compatible with
+several popular libraries):
+
+.. code-block:: terminal
+
+    # instead of league/commonmark, you can also use erusev/parsedown or michelf/php-markdown
+    $ composer require twig/markdown-extension league/commonmark
+
+The extension adds a ``markdown`` filter, which you can use to convert parts or
+the entire email contents from Markdown to HTML:
+
+.. code-block:: twig
+
+    {% apply markdown %}
+        Welcome {{ email.toName }}!
+        ===========================
+
+        You signed up to our site using the following email:
+        `{{ email.to[0].address }}`
+
+        [Click here to activate your account]({{ url('...') }})
+    {% endapply %}
+
+.. _mailer-inky:
+
+Inky Email Templating Language
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating beautifully designed emails that work on every email client is so
+complex that there are HTML/CSS frameworks dedicated to that. One of the most
+popular frameworks is called `Inky`_. It defines a syntax based on some simple
+tags which are later transformed into the real HTML code sent to users:
+
+.. code-block:: html
+
+    <!-- a simplified example of the Inky syntax -->
+    <container>
+        <row>
+            <columns>This is a column.</columns>
+        </row>
+    </container>
+
+Twig provides integration with Inky via the ``InkyExtension``. First, install
+the extension in your application:
+
+.. code-block:: terminal
+
+    $ composer require twig/inky-extension
+
+The extension adds an ``inky`` filter, which can be used to convert parts or the
+entire email contents from Inky to HTML:
+
+.. code-block:: html+twig
+
+    {% apply inky %}
+        <container>
+            <row class="header">
+                <columns>
+                    <spacer size="16"></spacer>
+                    <h1 class="text-center">Welcome {{ email.toName }}!</h1>
+                </columns>
+
+                {# ... #}
+            </row>
+        </container>
+    {% endapply %}
+
+You can combine all filters to create complex email messages:
+
+.. code-block:: twig
+
+    {% apply inky|inline_css(source('@css/foundation-emails.css')) %}
+        {# ... #}
+    {% endapply %}
+
+This makes use of the :ref:`css Twig namespace <mailer-css-namespace>` we created
+earlier. You could, for example, `download the foundation-emails.css file`_
+directly from GitHub and save it in ``assets/css``.
+
+Sending Messages Async
+----------------------
+
+When you call ``$mailer->send($email)``, the email is sent to the transport immediately.
+To improve performance, you can leverage :doc:`Messenger </messenger>` to send
+the messages later via a Messenger transport.
+
+Start by following the :doc:`Messenger </messenger>` documentation and configuring
+a transport. Once everything is set up, when you call ``$mailer->send()``, a
+:class:`Symfony\\Component\\Mailer\\Messenger\\SendEmailMessage` message will
+be dispatched through the default message bus (``messenger.default_bus``). Assuming
+you have a transport called ``async``, you can route the message there:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                transports:
+                    async: "%env(MESSENGER_TRANSPORT_DSN)%"
+
+                routing:
+                    'Symfony\Component\Mailer\Messenger\SendEmailMessage':  async
+
+    .. code-block:: xml
+
+        <!-- config/packages/messenger.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:messenger>
+                    <framework:routing message-class="Symfony\Component\Mailer\Messenger\SendEmailMessage">
+                        <framework:sender service="async"/>
+                    </framework:routing>
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', [
+            'messenger' => [
+                'routing' => [
+                    'Symfony\Component\Mailer\Messenger\SendEmailMessage' => 'async',
+                ],
+            ],
+        ]);
+
+Thanks to this, instead of being delivered immediately, messages will be sent to
+the transport to be handled later (see :ref:`messenger-worker`).
+
+Development & Debugging
+-----------------------
+
+Disabling Delivery
+~~~~~~~~~~~~~~~~~~
+
+While developing (or testing), you may want to disable delivery of messages entirely.
+You can do this by forcing Mailer to use the ``NullTransport`` in only the ``dev``
+environment:
+
+.. code-block:: yaml
+
+    # config/packages/dev/mailer.yaml
+    framework:
+        mailer:
+            dsn: 'smtp://null'
+
+.. note::
+
+    If you're using Messenger and routing to a transport, the message will *still*
+    be sent to that transport.
+
+Always Send to the Same Address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of disabling delivery entirely, you might want to *always* send emails to
+a specific address, instead of the *real* address. To do that, you can take
+advantage of the ``EnvelopeListener`` and register it *only* for the ``dev``
+environment:
+
+.. code-block:: yaml
+
+    # config/services_dev.yaml
+    services:
+        mailer.dev.set_recipients:
+            class: Symfony\Component\Mailer\EventListener\EnvelopeListener
+            tags: ['kernel.event_subscriber']
+            arguments:
+                $sender: null
+                $recipients: ['youremail@example.com']
+
+.. _`download the foundation-emails.css file`: https://github.com/zurb/foundation-emails/blob/develop/dist/foundation-emails.css
+.. _`league/html-to-markdown`: https://github.com/thephpleague/html-to-markdown
+.. _`Markdown syntax`: https://commonmark.org/
+.. _`Inky`: https://foundation.zurb.com/emails.html
diff --git a/mercure.rst b/mercure.rst
new file mode 100644
index 00000000000..76511afd2e5
--- /dev/null
+++ b/mercure.rst
@@ -0,0 +1,544 @@
+.. index::
+   single: Mercure
+
+Pushing Data to Clients Using the Mercure Protocol
+==================================================
+
+Being able to broadcast data in real-time from servers to clients is a
+requirement for many modern web and mobile applications.
+
+Creating an UI reacting in live to changes made by other users
+(e.g. a user changes the data currently browsed by several other users,
+all UIs are instantly updated),
+notifying the user when :doc:`an asynchronous job </messenger>` has been
+completed or creating chat applications are among the typical use cases
+requiring "push" capabilities.
+
+Symfony provides a straightforward component, built on top of
+`the Mercure protocol`_, specifically designed for this class of use cases.
+
+Mercure is an open protocol designed from the ground to publish updates from
+server to clients. It is a modern and efficient alternative to timer-based
+polling and to WebSocket.
+
+Because it is built on top `Server-Sent Events (SSE)`_, Mercure is supported
+out of the box in most modern browsers (Edge and IE require `a polyfill`_) and
+has `high-level implementations`_ in many programming languages.
+
+Mercure comes with an authorization mechanism,
+automatic re-connection in case of network issues
+with retrieving of lost updates, "connection-less" push for smartphones and
+auto-discoverability (a supported client can automatically discover and
+subscribe to updates of a given resource thanks to a specific HTTP header).
+
+All these features are supported in the Symfony integration.
+
+Unlike WebSocket, which is only compatible with HTTP 1.x,
+Mercure leverages the multiplexing capabilities provided by HTTP/2
+and HTTP/3 (but also supports older versions of HTTP).
+
+`In this recording`_ you can see how a Symfony web API leverages Mercure
+and API Platform to update in live a React app and a mobile app (React Native)
+generated using the API Platform client generator.
+
+Installation
+------------
+
+Installing the Symfony Component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
+install the Mercure support before using it:
+
+.. code-block:: terminal
+
+    $ composer require mercure
+
+Running a Mercure Hub
+~~~~~~~~~~~~~~~~~~~~~
+
+To manage persistent connections, Mercure relies on a Hub: a dedicated server
+that handles persistent SSE connections with the clients.
+The Symfony app publishes the updates to the hub, that will broadcast them to
+clients.
+
+.. image:: /_images/mercure/schema.png
+
+An official and open source (AGPL) implementation of a Hub can be downloaded
+as a static binary from `Mercure.rocks`_.
+
+Run the following command to start it:
+
+.. code-block:: terminal
+
+    $ JWT_KEY='aVerySecretKey' ADDR='localhost:3000' ALLOW_ANONYMOUS=1 CORS_ALLOWED_ORIGINS=* ./mercure
+
+.. note::
+
+    Alternatively to the binary, a Docker image, a Helm chart for Kubernetes
+    and a managed, High Availability Hub are also provided by Mercure.rocks.
+
+.. tip::
+
+    The `API Platform distribution`_ comes with a Docker Compose configuration
+    as well as a Helm chart for Kubernetes that are 100% compatible with Symfony,
+    and contain a Mercure hub.
+    You can copy them in your project, even if you don't use API Platform.
+
+Configuration
+-------------
+
+The preferred way to configure the MercureBundle is using
+:doc:`environment variables </configuration>`.
+
+Set the URL of your hub as the value of the ``MERCURE_PUBLISH_URL`` env var.
+The ``.env`` file of your project has been updated by the Flex recipe to
+provide example values.
+Set it to the URL of the Mercure Hub (``http://localhost:3000/hub`` by default).
+
+In addition, the Symfony application must bear a `JSON Web Token`_ (JWT)
+to the Mercure Hub to be authorized to publish updates.
+
+This JWT should be stored in the ``MERCURE_JWT_SECRET`` environment variable.
+
+The JWT must be signed with the same secret key as the one used by
+the Hub to verify the JWT (``aVerySecretKey`` in our example).
+Its payload must contain at least the following structure to be allowed to
+publish:
+
+.. code-block:: json
+
+    {
+        "mercure": {
+            "publish": []
+        }
+    }
+
+Because the array is empty, the Symfony app will only be authorized to publish
+public updates (see the authorization_ section for further information).
+
+.. tip::
+
+    The jwt.io website is a convenient way to create and sign JWTs.
+    Checkout this `example JWT`_, that grants publishing rights for all *targets*
+    (notice the star in the array).
+    Don't forget to set your secret key properly in the bottom of the right panel of the form!
+
+.. caution::
+
+    Don't put the secret key in ``MERCURE_JWT_SECRET``, it will not work!
+    This environment variable must contain a JWT, signed with the secret key.
+
+    Also, be sure to keep both the secret key and the JWTs... secrets!
+
+Basic Usage
+-----------
+
+Publishing
+~~~~~~~~~~
+
+The Mercure Component provides an ``Update`` value object representing
+the update to publish. It also provides a ``Publisher`` service to dispatch
+updates to the Hub.
+
+The ``Publisher`` service can be injected using the
+:doc:`autowiring </service_container/autowiring>` in any other
+service, including controllers::
+
+    // src/Controller/PublishController.php
+    namespace App\Controller;
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Mercure\Publisher;
+    use Symfony\Component\Mercure\Update;
+
+    class PublishController
+    {
+        public function __invoke(Publisher $publisher): Response
+        {
+            $update = new Update(
+                'http://example.com/books/1',
+                json_encode(['status' => 'OutOfStock'])
+            );
+
+            // The Publisher service is an invokable object
+            $publisher($update);
+
+            return new Response('published!');
+        }
+    }
+
+The first parameter to pass to the ``Update`` constructor is
+the **topic** being updated. This topic should be an `IRI`_
+(Internationalized Resource Identifier, RFC 3987): a unique identifier
+of the resource being dispatched.
+
+Usually, this parameter contains the original URL of the resource
+transmitted to the client, but it can be any valid `IRI`_, it doesn't
+have to be an URL that exists (similarly to XML namespaces).
+
+The second parameter of the constructor is the content of the update.
+It can be anything, stored in any format.
+However, serializing the resource in a hypermedia format such as JSON-LD,
+Atom, HTML or XML is recommended.
+
+Subscribing
+~~~~~~~~~~~
+
+Subscribing to updates in JavaScript is straightforward:
+
+.. code-block:: javascript
+
+    const eventSource = new EventSource('http://localhost:3000/hub?topic=' + encodeURIComponent('http://example.com/books/1'));
+    eventSource.onmessage = event => {
+        // Will be called every time an update is published by the server
+        console.log(JSON.parse(event.data));
+    }
+
+Mercure also allows to subscribe to several topics,
+and to use URI Templates as patterns:
+
+.. code-block:: javascript
+
+    // URL is a built-in JavaScript class to manipulate URLs
+    const url = new URL('http://localhost:3000/hub');
+    url.searchParams.append('topic', 'http://example.com/books/1');
+    // Subscribe to updates of several Book resources
+    url.searchParams.append('topic', 'http://example.com/books/2');
+    // All Review resources will match this pattern
+    url.searchParams.append('topic', 'http://example.com/reviews/{id}');
+
+    const eventSource = new EventSource(url);
+    eventSource.onmessage = event => {
+        console.log(JSON.parse(event.data));
+    }
+
+.. tip::
+
+    Google Chrome DevTools natively integrate a `practical UI`_ displaying in live
+    the received events:
+
+    .. image:: /_images/mercure/chrome.png
+
+    To use it:
+
+    * open the DevTools
+    * select the "Network" tab
+    * click on the request to the Mercure hub
+    * click on the "EventStream" sub-tab.
+
+.. tip::
+
+    Test if a URI Template match an URL using `the online debugger`_
+
+Async dispatching
+-----------------
+
+Instead of calling the ``Publisher`` service directly, you can also let Symfony
+dispatching the updates asynchronously thanks to the provided integration with
+the Messenger component.
+
+First, be sure :doc:`to install the Messenger component </messenger>`
+and to configure properly a transport (if you don't, the handler will
+be called synchronously).
+
+Then, dispatch the Mercure ``Update`` to the Messenger's Message Bus,
+it will be handled automatically::
+
+    // src/Controller/PublishController.php
+    namespace App\Controller;
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Mercure\Update;
+    use Symfony\Component\Messenger\MessageBusInterface;
+
+    class PublishController
+    {
+        public function __invoke(MessageBusInterface $bus): Response
+        {
+            $update = new Update(
+                'http://example.com/books/1',
+                json_encode(['status' => 'OutOfStock'])
+            );
+
+            // Sync, or async (RabbitMQ, Kafka...)
+            $bus->dispatch($update);
+
+            return new Response('published!');
+        }
+    }
+
+Discovery
+---------
+
+The Mercure protocol comes with a discovery mechanism.
+To leverage it, the Symfony application must expose the URL of the Mercure Hub
+in a ``Link`` HTTP header.
+
+.. image:: /_images/mercure/discovery.png
+
+You can create ``Link`` headers with the :doc:`WebLink Component </web_link>`,
+by using the ``AbstractController::addLink`` helper method::
+
+    // src/Controller/DiscoverController.php
+    namespace App\Controller;
+
+    use Fig\Link\Link;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\JsonResponse;
+    use Symfony\Component\HttpFoundation\Request;
+
+    class DiscoverController extends AbstractController
+    {
+        public function __invoke(Request $request): JsonResponse
+        {
+            // This parameter is automatically created by the MercureBundle
+            $hubUrl = $this->getParameter('mercure.default_hub');
+
+            // Link: <http://localhost:3000/hub>; rel="mercure"
+            $this->addLink($request, new Link('mercure', $hubUrl));
+
+            return $this->json([
+                '@id' => '/books/1',
+                'availability' => 'https://schema.org/InStock',
+            ]);
+        }
+    }
+
+Then, this header can be parsed client-side to find the URL of the Hub,
+and to subscribe to it:
+
+.. code-block:: javascript
+
+    // Fetch the original resource served by the Symfony web API
+    fetch('/books/1') // Has Link: <http://localhost:3000/hub>; rel="mercure"
+        .then(response => {
+            // Extract the hub URL from the Link header
+            const hubUrl = response.headers.get('Link').match(/<([^>]+)>;\s+rel=(?:mercure|"[^"]*mercure[^"]*")/)[1];
+
+            // Append the topic(s) to subscribe as query parameter
+            const hub = new URL(hubUrl);
+            hub.searchParams.append('topic', 'http://example.com/books/{id}');
+
+            // Subscribe to updates
+            const eventSource = new EventSource(hub);
+            eventSource.onmessage = event => console.log(event.data);
+        });
+
+Authorization
+-------------
+
+Mercure also allows to dispatch updates only to authorized clients.
+To do so, set the list of **targets** allowed to receive the update
+as the third parameter of the ``Update`` constructor::
+
+    // src/Controller/Publish.php
+    namespace App\Controller;
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Mercure\Publisher;
+    use Symfony\Component\Mercure\Update;
+
+    class PublishController
+    {
+        public function __invoke(Publisher $publisher): Response
+        {
+            $update = new Update(
+                'http://example.com/books/1',
+                json_encode(['status' => 'OutOfStock']),
+                ['http://example.com/user/kevin', 'http://example.com/groups/admin'] // Here are the targets
+            );
+
+            // Publisher's JWT must contain all of these targets or * in mercure.publish or you'll get a 401
+            // Subscriber's JWT must contain at least one of these targets or * in mercure.subscribe to receive the update
+            $publisher($update);
+
+            return new Response('published to the selected targets!');
+        }
+    }
+
+To subscribe to private updates, subscribers must provide
+a JWT containing at least one target marking the update to the Hub.
+
+To provide this JWT, the subscriber can use a cookie,
+or a ``Authorization`` HTTP header.
+Cookies are automatically sent by the browsers when opening an ``EventSource`` connection.
+They are the most secure and preferred way when the client is a web browser.
+If the client is not a web browser, then using an authorization header is the way to go.
+
+In the following example controller,
+the generated cookie contains a JWT, itself containing the appropriate targets.
+This cookie will be automatically sent by the web browser when connecting to the Hub.
+Then, the Hub will verify the validity of the provided JWT, and extract the targets
+from it.
+
+To generate the JWT, we'll use the ``lcobucci/jwt`` library. Install it:
+
+.. code-block:: terminal
+
+    $ composer require lcobucci/jwt
+
+And here is the controller::
+
+    // src/Controller/DiscoverController.php
+    namespace App\Controller;
+
+    use Fig\Link\Link;
+    use Lcobucci\JWT\Builder;
+    use Lcobucci\JWT\Signer\Hmac\Sha256;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
+
+    class DiscoverController extends AbstractController
+    {
+        public function __invoke(Request $request): Response
+        {
+            $hubUrl = $this->getParameter('mercure.default_hub');
+            $this->addLink($request, new Link('mercure', $hubUrl));
+
+            $username = $this->getUser()->getUsername(); // Retrieve the username of the current user
+            $token = (new Builder())
+                // set other appropriate JWT claims, such as an expiration date
+                ->set('mercure', ['subscribe' => ["http://example.com/user/$username"]]) // could also include the security roles, or anything else
+                ->sign(new Sha256(), $this->getParameter('mercure_secret_key')) // don't forget to set this parameter! Test value: aVerySecretKey
+                ->getToken();
+
+            $response = $this->json(['@id' => '/demo/books/1', 'availability' => 'https://schema.org/InStock']);
+            $response->headers->set(
+                'set-cookie',
+                sprintf('mercureAuthorization=%s; path=/hub; secure; httponly; SameSite=strict', $token)
+            );
+
+            return $response;
+        }
+    }
+
+.. caution::
+
+    To use the cookie authentication method, the Symfony app and the Hub
+    must be served from the same domain (can be different sub-domains).
+
+Generating Programmatically The JWT Used to Publish
+---------------------------------------------------
+
+Instead of directly storing a JWT in the configuration,
+you can create a service that will return the token used by
+the ``Publisher`` object::
+
+    // src/Mercure/MyJwtProvider.php
+    namespace App\Mercure;
+
+    final class MyJwtProvider
+    {
+        public function __invoke(): string
+        {
+            return 'the-JWT';
+        }
+    }
+
+Then, reference this service in the bundle configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/mercure.yaml
+        mercure:
+            hubs:
+                default:
+                    url: https://mercure-hub.example.com/hub
+                    jwt_provider: App\Mercure\MyJwtProvider
+
+    .. code-block:: xml
+
+        <!-- config/packages/mercure.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <config>
+            <hub
+                name="default"
+                url="https://mercure-hub.example.com/hub"
+                jwt-provider="App\Mercure\MyJwtProvider"
+            />
+        </config>
+
+    .. code-block:: php
+
+        // config/packages/mercure.php
+        use App\Mercure\MyJwtProvider;
+
+        $container->loadFromExtension('mercure', [
+            'hubs' => [
+                'default' => [
+                    'url' => 'https://mercure-hub.example.com/hub',
+                    'jwt_provider' => MyJwtProvider::class,
+                ],
+            ],
+        ]);
+
+This method is especially convenient when using tokens having an expiration
+date, that can be refreshed programmatically.
+
+Web APIs
+--------
+
+When creating a web API, it's convenient to be able to instantly push
+new versions of the resources to all connected devices, and to update
+their views.
+
+API Platform can use the Mercure Component to dispatch updates automatically,
+every time an API resource is created, modified or deleted.
+
+Start by installing the library using its official recipe:
+
+.. code-block:: terminal
+
+    $ composer require api
+
+Then, creating the following entity is enough to get a fully-featured
+hypermedia API, and automatic update broadcasting through the Mercure hub::
+
+    // src/Entity/Book.php
+    namespace App\Entity;
+
+    use ApiPlatform\Core\Annotation\ApiResource;
+    use Doctrine\ORM\Mapping as ORM;
+
+    /**
+    * @ApiResource(mercure=true)
+    * @ORM\Entity
+    */
+    class Book
+    {
+        /**
+         * @ORM\Id
+         * @ORM\Column
+         */
+        public $name;
+
+        /**
+         * @ORM\Column
+         */
+        public $status;
+    }
+
+As showcased `in this recording`_, the API Platform Client Generator also
+allows to scaffold complete React and React Native applications from this API.
+These applications will render the content of Mercure updates in real-time.
+
+Checkout `the dedicated API Platform documentation`_ to learn more about
+its Mercure support.
+
+.. _`the Mercure protocol`: https://github.com/dunglas/mercure#protocol-specification
+.. _`Server-Sent Events (SSE)`: https://developer.mozilla.org/docs/Server-sent_events
+.. _`a polyfill`: https://github.com/Yaffle/EventSource
+.. _`high-level implementations`: https://github.com/dunglas/mercure#tools
+.. _`In this recording`: https://www.youtube.com/watch?v=UI1l0JOjLeI
+.. _`Mercure.rocks`: https://mercure.rocks
+.. _`API Platform distribution`: https://api-platform.com/docs/distribution/
+.. _`JSON Web Token`: https://tools.ietf.org/html/rfc7519
+.. _`example JWT`: https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.iHLdpAEjX4BqCsHJEegxRmO-Y6sMxXwNATrQyRNt3GY
+.. _`IRI`: https://tools.ietf.org/html/rfc3987
+.. _`practical UI`: https://twitter.com/chromedevtools/status/562324683194785792
+.. _`the dedicated API Platform documentation`: https://api-platform.com/docs/core/mercure/
+.. _`the online debugger`: https://uri-template-tester.mercure.rocks
diff --git a/messenger.rst b/messenger.rst
index 9ac8ffc3cd6..c7a55d3e2ba 100644
--- a/messenger.rst
+++ b/messenger.rst
@@ -1,30 +1,34 @@
 .. index::
    single: Messenger
 
-How to Use the Messenger
-========================
+Messenger: Sync & Queued Message Handling
+=========================================
 
-Symfony's Messenger provides a message bus and some routing capabilities to send
-messages within your application and through transports such as message queues.
-Before using it, read the :doc:`Messenger component docs </components/messenger>`
-to get familiar with its concepts.
+Messenger provides a message bus with the ability to send messages and then
+handle them immediately in your application or send them through transports
+(e.g. queues) to be handled later. To learn more deeply about it, read the
+:doc:`Messenger component docs </components/messenger>`.
 
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
-install messenger before using it:
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
+install messenger:
 
 .. code-block:: terminal
 
     $ composer require messenger
 
-Message
--------
+Creating a Message & Handler
+----------------------------
 
-Before you can send a message, you must create it first. There is no specific
-requirement for a message, except it should be serializable and unserializable
-by a Symfony Serializer instance::
+Messenger centers around two different classes that you'll create: (1) a message
+class that holds data and (2) a handler(s) class that will be called when that
+message is dispatched. The handler class will read the message class and perform
+some task.
+
+There are no specific requirements for a message class, except that it can be
+serialized::
 
     // src/Message/SmsNotification.php
     namespace App\Message;
@@ -38,35 +42,17 @@ by a Symfony Serializer instance::
             $this->content = $content;
         }
 
-        // ...getters
-    }
-
-Using the Messenger Service
----------------------------
-
-Once enabled, the ``message_bus`` service can be injected in any service where
-you need it, like in a controller::
-
-    // src/Controller/DefaultController.php
-    namespace App\Controller;
-
-    use App\Message\SmsNotification;
-    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-    use Symfony\Component\Messenger\MessageBusInterface;
-
-    class DefaultController extends AbstractController
-    {
-        public function index(MessageBusInterface $bus)
+        public function getContent(): string
         {
-            $bus->dispatch(new SmsNotification('A string to be sent...'));
+            return $this->content;
         }
     }
 
-Registering Handlers
---------------------
+.. _messenger-handler:
 
-In order to do something when your message is dispatched, you need to create a
-message handler. It's a class with an ``__invoke`` method::
+A message handler is a PHP callable, the easiest way to create it is to create a class that implements
+``MessageHandlerInterface`` and has an ``__invoke()`` method that's
+type-hinted with the message class (or a message interface)::
 
     // src/MessageHandler/SmsNotificationHandler.php
     namespace App\MessageHandler;
@@ -78,74 +64,76 @@ message handler. It's a class with an ``__invoke`` method::
     {
         public function __invoke(SmsNotification $message)
         {
-            // do something with it.
+            // ... do some work - like sending an SMS message!
         }
     }
 
-Message handlers must be registered as services and :doc:`tagged </service_container/tags>`
-with the ``messenger.message_handler`` tag. If you're using the
-:ref:`default services.yaml configuration <service-container-services-load-example>` and implement
-:class:`Symfony\\Component\\Messenger\\Handler\\MessageHandlerInterface`
-or :class:`Symfony\\Component\\Messenger\\Handler\\MessageSubscriberInterface`,
-this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
+Thanks to :ref:`autoconfiguration <services-autoconfigure>` and the ``SmsNotification``
+type-hint, Symfony knows that this handler should be called when an ``SmsNotification``
+message is dispatched. Most of the time, this is all you need to do. But you can
+also :ref:`manually configure message handlers <messenger-handler-config>`. To
+see all the configured handlers, run:
 
-If you're not using service autoconfiguration, then you need to add this config:
+.. code-block:: terminal
 
-.. configuration-block::
+    $ php bin/console debug:messenger
 
-    .. code-block:: yaml
+Dispatching the Message
+-----------------------
 
-        # config/services.yaml
-        services:
-            App\MessageHandler\SmsNotificationHandler:
-                tags: [messenger.message_handler]
+You're ready! To dispatch the message (and call the handler), inject the
+``message_bus`` service (via the ``MessageBusInterface``), like in a controller::
 
-    .. code-block:: xml
+    // src/Controller/DefaultController.php
+    namespace App\Controller;
 
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+    use App\Message\SmsNotification;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Messenger\MessageBusInterface;
 
-            <services>
-                <service id="App\MessageHandler\SmsNotificationHandler">
-                   <tag name="messenger.message_handler" />
-                </service>
-            </services>
-        </container>
+    class DefaultController extends AbstractController
+    {
+        public function index(MessageBusInterface $bus)
+        {
+            // will cause the SmsNotificationHandler to be called
+            $bus->dispatch(new SmsNotification('Look! I created a message!'));
 
-    .. code-block:: php
+            // or use the shortcut
+            $this->dispatchMessage(new SmsNotification('Look! I created a message!'));
 
-        // config/services.php
-        use App\MessageHandler\SmsNotificationHandler;
+            // ...
+        }
+    }
 
-        $container->register(SmsNotificationHandler::class)
-            ->addTag('messenger.message_handler');
+Transports: Async/Queued Messages
+---------------------------------
+
+By default, messages are handled as soon as they are dispatched. If you want
+to handle a message asynchronously, you can configure a transport. A transport
+is capable of sending messages (e.g. to a queueing system) and then
+:ref:`receiving them via a worker<messenger-worker>`. Messenger supports
+:ref:`multiple transports <messenger-transports-config>`.
 
 .. note::
 
-    If the message cannot be guessed from the handler's type-hint, use the
-    ``handles`` attribute on the tag.
+    If you want to use a transport that's not supported, check out the
+    `Enqueue's transport`_, which supports things like Kafka, Amazon SQS and
+    Google Pub/Sub.
 
-Transports
-----------
+A transport is registered using a "DSN". Thanks to Messenger's Flex recipe, your
+``.env`` file already has a few examples.
 
-By default, messages are processed as soon as they are dispatched. If you prefer
-to process messages asynchronously, you must configure a transport. These
-transports communicate with your application via queuing systems or third parties.
-The built-in AMQP transport allows you to communicate with most of the AMQP
-brokers such as RabbitMQ.
+.. code-block:: bash
 
-.. note::
+    # MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/messages
+    # MESSENGER_TRANSPORT_DSN=doctrine://default
+    # MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages
 
-    If you need more message brokers, you should have a look at `Enqueue's transport`_
-    which supports things like Kafka, Amazon SQS or Google Pub/Sub.
+Uncomment whichever transport you want (or set it in ``.env.local``). See
+:ref:`messenger-transports-config` for more details.
 
-A transport is registered using a "DSN", which is a string that represents the
-connection credentials and configuration. By default, when you've installed
-the messenger component, the following configuration should have been created:
+Next, in ``config/packages/messenger.yaml``, let's define a transport called ``async``
+that uses this configuration:
 
 .. configuration-block::
 
@@ -155,7 +143,12 @@ the messenger component, the following configuration should have been created:
         framework:
             messenger:
                 transports:
-                    amqp: "%env(MESSENGER_TRANSPORT_DSN)%"
+                    async: "%env(MESSENGER_TRANSPORT_DSN)%"
+
+                    # or expanded to configure more options
+                    #async:
+                    #    dsn: "%env(MESSENGER_TRANSPORT_DSN)%"
+                    #    options: []
 
     .. code-block:: xml
 
@@ -165,13 +158,20 @@ the messenger component, the following configuration should have been created:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:transport name="amqp" dsn="%env(MESSENGER_TRANSPORT_DSN)%" />
+                    <framework:transport name="async">%env(MESSENGER_TRANSPORT_DSN)%</framework:transport>
+
+                    <!-- or expanded to configure more options -->
+                    <framework:transport name="async"
+                        dsn="%env(MESSENGER_TRANSPORT_DSN)%"
+                    >
+                        <option key="...">...</option>
+                    </framework:transport>
                 </framework:messenger>
             </framework:config>
         </container>
@@ -182,40 +182,24 @@ the messenger component, the following configuration should have been created:
         $container->loadFromExtension('framework', [
             'messenger' => [
                 'transports' => [
-                    'amqp' => '%env(MESSENGER_TRANSPORT_DSN)%',
+                    'async' => '%env(MESSENGER_TRANSPORT_DSN)%',
+
+                    // or expanded to configure more options
+                    'async' => [
+                       'dsn' => '%env(MESSENGER_TRANSPORT_DSN)%',
+                       'options' => []
+                    ],
                 ],
             ],
         ]);
 
-.. code-block:: bash
-
-    # .env
-    ###> symfony/messenger ###
-    MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/messages
-    ###< symfony/messenger ###
-
-This is enough to allow you to route your message to the ``amqp`` transport.
-This will also configure the following services for you:
-
-#. A ``messenger.sender.amqp`` sender to be used when routing messages;
-#. A ``messenger.receiver.amqp`` receiver to be used when consuming messages.
-
-.. note::
-
-    In order to use Symfony's built-in AMQP transport, you will need the Serializer
-    Component. Ensure that it is installed with:
-
-    .. code-block:: terminal
-
-        $ composer require symfony/serializer-pack
+.. _messenger-routing:
 
-Routing
--------
+Routing Messages to a Transport
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Instead of calling a handler, you have the option to route your message(s) to a
-sender. Part of a transport, it is responsible for sending your message somewhere.
-You can configure which message is routed to which sender with the following
-configuration:
+Now that you have a transport configured, instead of handling a message immediately,
+you can configure them to be sent to a transport:
 
 .. configuration-block::
 
@@ -224,8 +208,12 @@ configuration:
         # config/packages/messenger.yaml
         framework:
             messenger:
+                transports:
+                    async: "%env(MESSENGER_TRANSPORT_DSN)%"
+
                 routing:
-                    'My\Message\Message':  amqp # The name of the defined transport
+                    # async is whatever name you gave your transport above
+                    'App\Message\SmsNotification':  async
 
     .. code-block:: xml
 
@@ -235,14 +223,15 @@ configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:routing message-class="My\Message\Message">
-                        <framework:sender service="amqp" />
+                    <framework:routing message-class="App\Message\SmsNotification">
+                        <!-- async is whatever name you gave your transport above -->
+                        <framework:sender service="async"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -254,16 +243,18 @@ configuration:
         $container->loadFromExtension('framework', [
             'messenger' => [
                 'routing' => [
-                    'My\Message\Message' => 'amqp',
+                    // async is whatever name you gave your transport above
+                    'App\Message\SmsNotification' => 'async',
                 ],
             ],
         ]);
 
-Such configuration would only route the ``My\Message\Message`` message to be
-asynchronous, the rest of the messages would still be directly handled.
+Thanks to this, the ``App\Message\SmsNotification`` will be sent to the ``async``
+transport and its handler(s) will *not* be called immediately. Any messages not
+matched under ``routing`` will still be handled immediately.
 
-You can route all classes of messages to the same sender using an asterisk
-instead of a class name:
+You can also route classes by their parent class or interface. Or send messages
+to multiple transport:
 
 .. configuration-block::
 
@@ -273,8 +264,11 @@ instead of a class name:
         framework:
             messenger:
                 routing:
-                    'My\Message\MessageAboutDoingOperationalWork': another_transport
-                    '*': amqp
+                    # route all messages that extend this example base class or interface
+                    'App\Message\AbstractAsyncMessage': async
+                    'App\Message\AsyncMessageInterface': async
+
+                    'My\Message\ToBeSentToTwoSenders': [async, audit]
 
     .. code-block:: xml
 
@@ -284,17 +278,22 @@ instead of a class name:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:routing message-class="My\Message\Message">
-                        <framework:sender service="another_transport" />
+                    <!-- route all messages that extend this example base class or interface -->
+                    <framework:routing message-class="App\Message\AbstractAsyncMessage">
+                        <framework:sender service="async"/>
+                    </framework:routing>
+                    <framework:routing message-class="App\Message\AsyncMessageInterface">
+                        <framework:sender service="async"/>
                     </framework:routing>
-                    <framework:routing message-class="*">
-                        <framework:sender service="amqp" />
+                    <framework:routing message-class="My\Message\ToBeSentToTwoSenders">
+                        <framework:sender service="async"/>
+                        <framework:sender service="audit"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -306,13 +305,72 @@ instead of a class name:
         $container->loadFromExtension('framework', [
             'messenger' => [
                 'routing' => [
-                    'My\Message\Message' => 'another_transport',
-                    '*' => 'amqp',
+                    // route all messages that extend this example base class or interface
+                    'App\Message\AbstractAsyncMessage' => 'async',
+                    'App\Message\AsyncMessageInterface' => 'async',
+                    'My\Message\ToBeSentToTwoSenders' => ['async', 'audit'],
                 ],
             ],
         ]);
 
-A class of messages can also be routed to multiple senders by specifying a list:
+Doctrine Entities in Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to pass a Doctrine entity in a message, it's better to pass the entity's
+primary key (or whatever relevant information the handler actually needs, like ``email``,
+etc) instead of the object::
+
+    class NewUserWelcomeEmail
+    {
+        private $userId;
+
+        public function __construct(int $userId)
+        {
+            $this->userId = $userId;
+        }
+
+        public function getUserId(): int
+        {
+            return $this->userId;
+        }
+    }
+
+Then, in your handler, you can query for a fresh object::
+
+    // src/MessageHandler/NewUserWelcomeEmailHandler.php
+    namespace App\MessageHandler;
+
+    use App\Message\NewUserWelcomeEmail;
+    use App\Repository\UserRepository;
+    use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
+
+    class NewUserWelcomeEmailHandler implements MessageHandlerInterface
+    {
+        private $userRepository;
+
+        public function __construct(UserRepository $userRepository)
+        {
+            $this->userRepository = $userRepository;
+        }
+
+        public function __invoke(NewUserWelcomeEmail $welcomeEmail)
+        {
+            $user = $this->userRepository->find($welcomeEmail->getUserId());
+
+            // ... send an email!
+        }
+    }
+
+This guarantees the entity contains fresh data.
+
+Handling Messages Synchronously
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a message doesn't :ref:`match any routing rules <messenger-routing>`, it won't
+be sent to any transport and will be handled immediately. In some cases (like
+when `binding handlers to different transports`_),
+it's easier or more flexible to handle this explicitly: by creating a ``sync``
+transport and "sending" messages there to be handled immediately:
 
 .. configuration-block::
 
@@ -321,8 +379,13 @@ A class of messages can also be routed to multiple senders by specifying a list:
         # config/packages/messenger.yaml
         framework:
             messenger:
+                transports:
+                    # ... other transports
+
+                    sync: 'sync://'
+
                 routing:
-                    'My\Message\ToBeSentToTwoSenders': [amqp, audit]
+                    App\Message\SmsNotification: sync
 
     .. code-block:: xml
 
@@ -332,15 +395,18 @@ A class of messages can also be routed to multiple senders by specifying a list:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:routing message-class="My\Message\ToBeSentToTwoSenders">
-                        <framework:sender service="amqp" />
-                        <framework:sender service="audit" />
+                    <!-- ... other transports -->
+
+                    <framework:transport name="sync" dsn="sync://"/>
+
+                    <framework:routing message-class="App\Message\SmsNotification">
+                        <framework:sender service="sync"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -351,14 +417,77 @@ A class of messages can also be routed to multiple senders by specifying a list:
         // config/packages/messenger.php
         $container->loadFromExtension('framework', [
             'messenger' => [
+                'transports' => [
+                    // ... other transports
+
+                    'sync' => 'sync://',
+                ],
                 'routing' => [
-                    'My\Message\ToBeSentToTwoSenders' => ['amqp', 'audit'],
+                    'App\Message\SmsNotification' => 'sync',
                 ],
             ],
         ]);
 
-By specifying the ``send_and_handle`` option, you can also route a class of messages to a sender
-while still having them passed to their respective handler:
+Creating your Own Transport
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also create your own transport if you need to send or receive messages
+from something that is not supported. See :doc:`/messenger/custom-transport`.
+
+.. _messenger-worker:
+
+Consuming Messages (Running the Worker)
+---------------------------------------
+
+Once your messages have been routed, in most cases, you'll need to "consume" them.
+You can do this with the ``messenger:consume`` command:
+
+.. code-block:: terminal
+
+    $ php bin/console messenger:consume async
+
+    # use -vv to see details about what's happening
+    $ php bin/console messenger:consume async -vv
+
+.. versionadded:: 4.3
+
+    The ``messenger:consume`` command was renamed in Symfony 4.3 (previously it
+    was called ``messenger:consume-messages``).
+
+The first argument is the receiver's name (or service id if you routed to a
+custom service). By default, the command will run forever: looking for new messages
+on your transport and handling them. This command is called your "worker".
+
+Deploying to Production
+~~~~~~~~~~~~~~~~~~~~~~~
+
+On production, there are a few important things to think about:
+
+**Use Supervisor to keep your worker(s) running**
+    You'll want one or more "workers" running at all times. To do that, use a
+    process control system like :ref:`Supervisor <messenger-supervisor>`.
+
+**Don't Let Workers Run Forever**
+    Some services (like Doctrine's EntityManager) will consume more memory
+    over time. So, instead of allowing your worker to run forever, use a flag
+    like ``messenger:consume --limit=10`` to tell your worker to only handle 10
+    messages before exiting (then Supervisor will create a new process). There
+    are also other options like ``--memory-limit=128M`` and ``--time-limit=3600``.
+
+**Restart Workers on Deploy**
+    Each time you deploy, you'll need to restart all your worker processes so
+    that they see the newly deployed code. To do this, run ``messenger:stop-workers``
+    on deploy. This will signal to each worker that it should finish the message
+    it's currently handling and shut down gracefully. Then, Supervisor will create
+    new worker processes. The command uses the :ref:`app <cache-configuration-with-frameworkbundle>`
+    cache internally - so make sure this is configured to use an adapter you like.
+
+Prioritized Transports
+~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes certain types of messages should have a higher priority and be handled
+before others. To make this possible, you can create multiple transports and route
+different messages to them. For example:
 
 .. configuration-block::
 
@@ -367,10 +496,21 @@ while still having them passed to their respective handler:
         # config/packages/messenger.yaml
         framework:
             messenger:
+                transports:
+                    async_priority_high:
+                        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+                        options:
+                            # queue_name is specific to the doctrine transport
+                            # try "exchange" for amqp or "group1" for redis
+                            queue_name: high
+                    async_priority_low:
+                        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+                        options:
+                            queue_name: low
+
                 routing:
-                    'My\Message\ThatIsGoingToBeSentAndHandledLocally':
-                         senders: [amqp]
-                         send_and_handle: true
+                    'App\Message\SmsNotification':  async_priority_low
+                    'App\Message\NewUserWelcomeEmail':  async_priority_high
 
     .. code-block:: xml
 
@@ -380,14 +520,24 @@ while still having them passed to their respective handler:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:routing message-class="My\Message\ThatIsGoingToBeSentAndHandledLocally" send-and-handle="true">
-                        <framework:sender service="amqp" />
+                    <framework:transport name="async_priority_high" dsn="%env(MESSENGER_TRANSPORT_DSN)%">
+                        <option key="queue_name">high</option>
+                    </framework:transport>
+                    <framework:transport name="async_priority_low" dsn="%env(MESSENGER_TRANSPORT_DSN)%">
+                        <option key="queue_name">low</option>
+                    </framework:transport>
+
+                    <framework:routing message-class="App\Message\SmsNotification">
+                        <framework:sender service="async_priority_low"/>
+                    </framework:routing>
+                    <framework:routing message-class="App\Message\NewUserWelcomeEmail">
+                        <framework:sender service="async_priority_high"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -398,57 +548,92 @@ while still having them passed to their respective handler:
         // config/packages/messenger.php
         $container->loadFromExtension('framework', [
             'messenger' => [
-                'routing' => [
-                    'My\Message\ThatIsGoingToBeSentAndHandledLocally' => [
-                        'senders' => ['amqp'],
-                        'send_and_handle' => true,
+                'transports' => [
+                    'async_priority_high' => [
+                        'dsn' => '%env(MESSENGER_TRANSPORT_DSN)%',
+                        'options' => [
+                            'queue_name' => 'high',
+                        ],
+                    ],
+                    'async_priority_low' => [
+                        'dsn' => '%env(MESSENGER_TRANSPORT_DSN)%',
+                        'options' => [
+                            'queue_name' => 'low',
+                        ],
                     ],
                 ],
+                'routing' => [
+                    'App\Message\SmsNotification' => 'async_priority_low',
+                    'App\Message\NewUserWelcomeEmail' => 'async_priority_high',
+                ],
             ],
         ]);
 
-Consuming Messages
-------------------
+You can then run individual workers for each transport or instruct one worker
+to handle messages in a priority order:
+
+.. code-block:: terminal
+
+    $ php bin/console messenger:consume async_priority_high async_priority_low
+
+The worker will always first look for messages waiting on ``async_priority_high``. If
+there are none, *then* it will consume messages from ``async_priority_low``.
+
+.. _messenger-supervisor:
 
-Once your messages have been routed, you will like to consume your messages in most
-of the cases. To do so, you can use the ``messenger:consume-messages`` command
-like this:
+Supervisor Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Supervisor is a great tool to guarantee that your worker process(es) is
+*always* running (even if it closes due to failure, hitting a message limit
+or thanks to ``messenger:stop-workers``). You can install it on Ubuntu, for
+example, via:
 
 .. code-block:: terminal
 
-    $ bin/console messenger:consume-messages amqp
+    $ sudo apt-get install supervisor
 
-The first argument is the receiver's service name. It might have been created by
-your ``transports`` configuration or it can be your own receiver.
+Supervisor configuration files typically live in a ``/etc/supervisor/conf.d``
+directory. For example, you can create a new ``messenger-worker.conf`` file
+there to make sure that 2 instances of ``messenger:consume`` are running at all
+times:
 
-Middleware
-----------
+.. code-block:: ini
 
-What happens when you dispatch a message to a message bus(es) depends on its
-collection of middleware (and their order). By default, the middleware configured
-for each bus looks like this:
+    ;/etc/supervisor/conf.d/messenger-worker.conf
+    [program:messenger-consume]
+    command=php /path/to/your/app/bin/console messenger:consume async --time-limit=3600
+    user=ubuntu
+    numprocs=2
+    autostart=true
+    autorestart=true
+    process_name=%(program_name)s_%(process_num)02d
 
-#. ``logging`` middleware. Responsible for logging the beginning and the end of the
-   message within the bus;
+Change the ``async`` argument to use the name of your transport (or transports)
+and ``user`` to the Unix user on your server. Next, tell Supervisor to read your
+config and start your workers:
 
-#. _Your own collection of middleware_;
+.. code-block:: terminal
 
-#. ``route_messages`` middleware. Will route the messages you configured to their
-   corresponding sender and stop the middleware chain;
+    $ sudo supervisorctl reread
 
-#. ``call_message_handler`` middleware. Will call the message handler(s) for the
-   given message.
+    $ sudo supervisorctl update
 
-.. note::
+    $ sudo supervisorctl start messenger-consume:*
 
-    These middleware names are actually shortcuts working by convention.
-    The real service ids are prefixed with the ``messenger.middleware.`` namespace.
+See the `Supervisor docs`_ for more details.
 
-Disabling default Middleware
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _messenger-retries-failures:
+
+Retries & Failures
+------------------
 
-If you don't want the default collection of middleware to be present on your bus,
-you can disable them like this:
+If an exception is thrown while consuming a message from a transport it will
+automatically be re-sent to the transport to be tried again. By default, a message
+will be retried 3 times before being discarded or
+:ref:`sent to the failure transport <messenger-failure-transport>`. Each retry
+will also be delayed, in case the failure was due to a temporary issue. All of
+this is configurable for each transport:
 
 .. configuration-block::
 
@@ -457,47 +642,167 @@ you can disable them like this:
         # config/packages/messenger.yaml
         framework:
             messenger:
-                buses:
-                    messenger.bus.default:
-                        default_middleware: false
+                transports:
+                    async_priority_high:
+                        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+
+                        # default configuration
+                        retry_strategy:
+                            max_retries: 3
+                            # milliseconds delay
+                            delay: 1000
+                            # causes the delay to be higher before each retry
+                            # e.g. 1 second delay, 2 seconds, 4 seconds
+                            multiplier: 2
+                            max_delay: 0
+                            # override all of this with a service that
+                            # implements Symfony\Component\Messenger\Retry\RetryStrategyInterface
+                            # service: null
+
+Avoiding Retrying
+~~~~~~~~~~~~~~~~~
+
+Sometimes handling a message might fail in a way that you *know* is permanent
+and should not be retried. If you throw
+:class:`Symfony\\Component\\Messenger\\Exception\\UnrecoverableMessageHandlingException`,
+the message will not be retried.
+
+.. _messenger-failure-transport:
+
+Saving & Retrying Failed Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a message fails it is retried multiple times (``max_retries``) and then will
+be discarded. To avoid this happening, you can instead configure a ``failure_transport``:
 
-    .. code-block:: xml
+.. configuration-block::
 
-        <!-- config/packages/messenger.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+    .. code-block:: yaml
 
-            <framework:config>
-                <framework:messenger>
-                    <framework:bus name="messenger.bus.default" default-middleware="false" />
-                </framework:messenger>
-            </framework:config>
-        </container>
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                # after retrying, messages will be sent to the "failed" transport
+                failure_transport: failed
 
-    .. code-block:: php
+                transports:
+                    # ... other transports
 
-        // config/packages/messenger.php
-        $container->loadFromExtension('framework', [
-            'messenger' => [
-                'buses' => [
-                    'messenger.bus.default' => [
-                        'default_middleware' => false,
-                    ],
-                ],
-            ],
-        ]);
+                    failed: 'doctrine://default?queue_name=failed'
+
+In this example, if handling a message fails 3 times (default ``max_retries``),
+it will then be sent to the ``failed`` transport. While you *can* use
+``messenger:consume failed`` to consume this like a normal transport, you'll
+usually want to manually view the messages in the failure transport and choose
+to retry them:
+
+.. code-block:: terminal
+
+    # see all messages in the failure transport
+    $ php bin/console messenger:failed:show
+
+    # see details about a specific failure
+    $ php bin/console messenger:failed:show 20 -vv
+
+    # view and retry messages one-by-one
+    $ php bin/console messenger:failed:retry -vv
+
+    # retry specific messages
+    $ php bin/console messenger:failed:retry 20 30 --force
+
+    # remove a message without retrying it
+    $ php bin/console messenger:failed:remove 20
+
+If the message fails again, it will be re-sent back to the failure transport
+due to the normal :ref:`retry rules <messenger-retries-failures>`. Once the max
+retry has been hit, the message will be discarded permanently.
+
+.. _messenger-transports-config:
+
+Transport Configuration
+-----------------------
+
+Messenger supports a number of different transport types, each with their own
+options.
+
+AMQP Transport
+~~~~~~~~~~~~~~
+
+The ``amqp`` transport configuration looks like this:
+
+.. code-block:: bash
+
+    # .env
+    MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/messages
+
+To use Symfony's built-in AMQP transport, you need the AMQP PHP extension.
+
+.. note::
+
+    By default, the transport will automatically create any exchanges, queues and
+    binding keys that are needed. That can be disabled, but some functionality
+    may not work correctly (like delayed queues).
+
+The transport has a number of other options, including ways to configure
+the exchange, queues binding keys and more. See the documentation on
+:class:`Symfony\\Component\\Messenger\\Transport\\AmqpExt\\Connection`.
+
+You can also configure AMQP-specific settings on your message by adding
+:class:`Symfony\\Component\\Messenger\\Transport\\AmqpExt\\AmqpStamp` to
+your Envelope::
 
-Adding your own Middleware
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+    use Symfony\Component\Messenger\Transport\AmqpExt\AmqpStamp;
+    // ...
 
-As described in the component documentation, you can add your own middleware
-within the buses to add some extra capabilities like this:
+    $attributes = [];
+    $bus->dispatch(new SmsNotification(), [
+        new AmqpStamp('custom-routing-key', AMQP_NOPARAM, $attributes)
+    ]);
+
+.. caution::
+
+    The consumers do not show up in an admin panel as this transport does not rely on
+    ``\AmqpQueue::consume()`` which is blocking. Having a blocking receiver makes
+    the ``--time-limit/--memory-limit`` options of the ``messenger:consume`` command as well as
+    the ``messenger:stop-workers`` command inefficient, as they all rely on the fact that
+    the receiver returns immediately no matter if it finds a message or not. The consume
+    worker is responsible for iterating until it receives a message to handle and/or until one
+    of the stop conditions is reached. Thus, the worker's stop logic cannot be reached if it
+    is stuck in a blocking call.
+
+Doctrine Transport
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The Doctrine transport was introduced in Symfony 4.3.
+
+The Doctrine transport can be used to store messages in a database table.
+
+.. code-block:: bash
+
+    # .env
+    MESSENGER_TRANSPORT_DSN=doctrine://default
+
+The format is ``doctrine://<connection_name>``, in case you have multiple connections
+and want to use one other than the "default". The transport will automatically create
+a table named ``messenger_messages`` (this is configurable) when the transport is
+first used. You can disable that with the ``auto_setup`` option and set the table
+up manually by calling the ``messenger:setup-transports`` command.
+
+.. tip::
+
+    To avoid tools like Doctrine Migrations from trying to remove this table because
+    it's not part of your normal schema, you can set the ``schema_filter`` option:
+
+    .. code-block:: yaml
+
+        # config/packages/doctrine.yaml
+        doctrine:
+            dbal:
+                schema_filter: '~^(?!messenger_messages)~'
+
+The transport has a number of options:
 
 .. configuration-block::
 
@@ -506,11 +811,12 @@ within the buses to add some extra capabilities like this:
         # config/packages/messenger.yaml
         framework:
             messenger:
-                buses:
-                    messenger.bus.default:
-                        middleware:
-                            - 'App\Middleware\MyMiddleware'
-                            - 'App\Middleware\AnotherMiddleware'
+                transports:
+                    async_priority_high: "%env(MESSENGER_TRANSPORT_DSN)%?queue_name=high_priority"
+                    async_normal:
+                        dsn: "%env(MESSENGER_TRANSPORT_DSN)%"
+                        options:
+                            queue_name: normal_priority
 
     .. code-block:: xml
 
@@ -520,16 +826,16 @@ within the buses to add some extra capabilities like this:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:bus name="messenger.bus.default">
-                        <framework:middleware id="App\Middleware\MyMiddleware" />
-                        <framework:middleware id="App\Middleware\AnotherMiddleware" />
-                    </framework:bus>
+                    <framework:transport name="async_priority_high" dsn="%env(MESSENGER_TRANSPORT_DSN)%?queue_name=high_priority"/>
+                    <framework:transport name="async_priority_low" dsn="%env(MESSENGER_TRANSPORT_DSN)%">
+                        <framework:option queue_name="normal_priority"/>
+                    </framework:transport>
                 </framework:messenger>
             </framework:config>
         </container>
@@ -539,26 +845,178 @@ within the buses to add some extra capabilities like this:
         // config/packages/messenger.php
         $container->loadFromExtension('framework', [
             'messenger' => [
-                'buses' => [
-                    'messenger.bus.default' => [
-                        'middleware' => [
-                            'App\Middleware\MyMiddleware',
-                            'App\Middleware\AnotherMiddleware',
-                        ],
+                'transports' => [
+                    'async_priority_high' => 'dsn' => '%env(MESSENGER_TRANSPORT_DSN)%?queue_name=high_priority',
+                    'async_priority_low' => [
+                        'dsn' => '%env(MESSENGER_TRANSPORT_DSN)%',
+                        'options' => [
+                            'queue_name' => 'normal_priority'
+                        ]
                     ],
                 ],
             ],
         ]);
 
-Note that if the service is abstract, a different instance of the service will
-be created per bus.
+Options defined under ``options`` take precedence over ones defined in the DSN.
+
+==================  ===================================  ======================
+     Option         Description                          Default
+==================  ===================================  ======================
+table_name          Name of the table                    messenger_messages
+queue_name          Name of the queue (a column in the   default
+                    table, to use one table for
+                    multiple transports)
+redeliver_timeout   Timeout before retrying a message    3600
+                    that's in the queue but in the
+                    "handling" state (if a worker died
+                    for some reason, this will occur,
+                    eventually you should retry the
+                    message) - in seconds.
+auto_setup          Whether the table should be created
+                    automatically during send / get.     true
+==================  ===================================  ======================
+
+Redis Transport
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The Redis transport was introduced in Symfony 4.3.
+
+The Redis transport uses `streams`_ to queue messages.
+
+.. code-block:: bash
+
+    # .env
+    MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages
+    # Full DSN Example
+    MESSENGER_TRANSPORT_DSN=redis://password@localhost:6379/messages/symfony/consumer?auto_setup=true&serializer=1
+
+To use the Redis transport, you will need the Redis PHP extension (^4.3) and
+a running Redis server (^5.0).
+
+.. caution::
+
+    The Redis transport does not support "delayed" messages.
+
+A number of options can be configured via the DSN or via the ``options`` key
+under the transport in ``messenger.yaml``:
 
-Using Middleware Factories
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==================  =====================================  =======
+     Option               Description                      Default
+==================  =====================================  =======
+stream              The Redis stream name                  messages
+group               The Redis consumer group name          symfony
+consumer            Consumer name used in Redis            consumer
+auto_setup          Create the Redis group automatically?  true
+auth                The Redis password
+serializer          How to serialize the final payload     ``Redis::SERIALIZER_PHP``
+                    in Redis (the
+                    ``Redis::OPT_SERIALIZER`` option)
+==================  =====================================  =======
 
-Some third-party bundles and libraries provide configurable middleware via
-factories. Defining such requires a two-step configuration based on Symfony's
-:doc:`dependency injection </service_container>` features:
+In Memory Transport
+~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The ``in-memory`` transport was introduced in Symfony 4.3.
+
+The ``in-memory`` transport does not actually delivery messages. Instead, it
+holds them in memory during the request, which can be useful for testing.
+For example, if you have an ``async_priority_normal`` transport, you could
+override it in the ``test`` environment to use this transport:
+
+.. code-block:: yaml
+
+    # config/packages/test/messenger.yaml
+    framework:
+        messenger:
+            transports:
+                async_priority_normal: 'in-memory:///'
+
+Then, while testing, messages will *not* be delivered to the real transport.
+Even better, in a test, you can check that exactly one message was sent
+during a request::
+
+    // tests/DefaultControllerTest.php
+    namespace App\Tests;
+
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+    use Symfony\Component\Messenger\Transport\InMemoryTransport;
+
+    class DefaultControllerTest extends WebTestCase
+    {
+        public function testSomething()
+        {
+            $client = static::createClient();
+            // ...
+
+            $this->assertSame(200, $client->getResponse()->getStatusCode());
+
+            /* @var InMemoryTransport $transport */
+            $transport = self::$container->get('messenger.transport.async_priority_normal');
+            $this->assertCount(1, $transport->get());
+        }
+    }
+
+.. note::
+
+        All ``in-memory`` transports will be reset automatically after each test **in**
+        test classes extending
+        :class:`Symfony\\Bundle\\FrameworkBundle\\Test\\KernelTestCase`
+        or :class:`Symfony\\Bundle\\FrameworkBundle\\Test\\WebTestCase`.
+
+Serializing Messages
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The default serializer changed in 4.3 from the Symfony serializer to the
+    native PHP serializer. Existing applications should configure their transports
+    to use the Symfony serializer to avoid losing already-queued messages after
+    upgrading.
+
+When messages are sent to (and received from) a transport, they're serialized
+using PHP's native ``serialize()`` & ``unserialize()`` functions. You can change
+this globally (or for each transport) to a service that implements
+:class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\SerializerInterface`:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                serializer:
+                    default_serializer: messenger.transport.symfony_serializer
+                    symfony_serializer:
+                        format: json
+                        context: { }
+
+                transports:
+                    async_priority_normal:
+                        dsn: # ...
+                        serializer: messenger.transport.symfony_serializer
+
+The ``messenger.transport.symfony_serializer`` is a built-in service that uses
+the :doc:`Serializer component </serializer>` and can be configured in a few ways.
+If you *do* choose to use the Symfony serializer, you can control the context
+on a case-by-case basis via the :class:`Symfony\\Component\\Messenger\\Stamp\\SerializerStamp`
+(see `Envelopes & Stamps`_).
+
+Customizing Handlers
+--------------------
+
+.. _messenger-handler-config:
+
+Manually Configuring Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony will normally :ref:`find and register your handler automatically <messenger-handler>`.
+But, you can also configure a handler manually - and pass it some extra config -
+by tagging the handler service with ``messenger.message_handler``
 
 .. configuration-block::
 
@@ -566,23 +1024,17 @@ factories. Defining such requires a two-step configuration based on Symfony's
 
         # config/services.yaml
         services:
+            App\MessageHandler\SmsNotificationHandler:
+                tags: [messenger.message_handler]
 
-            # Step 1: a factory class is registered as a service with the required
-            # dependencies to instantiate a middleware
-            doctrine.orm.messenger.middleware_factory.transaction:
-                class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory
-                arguments: ['@doctrine']
-
-            # Step 2: an abstract definition that will call the factory with default
-            # arguments or the ones provided in the middleware config
-            messenger.middleware.doctrine_transaction:
-                class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
-                factory: 'doctrine.orm.messenger.middleware_factory.transaction:createMiddleware'
-                abstract: true
-                # the default arguments to use when none provided from config. Example:
-                # middleware:
-                #     - doctrine_transaction: ~
-                arguments: ['default']
+                # or configure with options
+                tags:
+                    -
+                        name: messenger.message_handler
+                        # only needed if can't be guessed by type-hint
+                        handles: App\Message\SmsNotification
+
+                        # options returned by getHandledMessages() are supported here
 
     .. code-block:: xml
 
@@ -591,26 +1043,11 @@ factories. Defining such requires a two-step configuration based on Symfony's
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <!-- Step 1: a factory class is registered as a service with the required
-                     dependencies to instantiate a middleware -->
-                <service id="doctrine.orm.messenger.middleware_factory.transaction"
-                    class="Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory">
-
-                    <argument type="service" id="doctrine" />
-                </service>
-
-                <!-- Step 2: an abstract definition that will call the factory with default
-                     arguments or the ones provided in the middleware config -->
-                <service id="messenger.middleware.doctrine_transaction"
-                    class="Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware"
-                    abstract="true">
-
-                    <factory service="doctrine.orm.messenger.middleware_factory.transaction"
-                        method="createMiddleware" />
-                    <argument>default</argument>
+                <service id="App\MessageHandler\SmsNotificationHandler">
+                   <tag name="messenger.message_handler"/>
                 </service>
             </services>
         </container>
@@ -618,32 +1055,108 @@ factories. Defining such requires a two-step configuration based on Symfony's
     .. code-block:: php
 
         // config/services.php
-        use Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware;
-        use Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory;
-        use Symfony\Component\DependencyInjection\Reference;
-
-        // Step 1: a factory class is registered as a service with the required
-        // dependencies to instantiate a middleware
-        $container
-            ->register('doctrine.orm.messenger.middleware_factory.transaction', DoctrineTransactionMiddlewareFactory::class)
-            ->setArguments([new Reference('doctrine')]);
-
-        // Step 2: an abstract definition that will call the factory with default
-        // arguments or the ones provided in the middleware config
-        $container->register('messenger.middleware.doctrine_transaction', DoctrineTransactionMiddleware::class)
-            ->setFactory([
-                new Reference('doctrine.orm.messenger.middleware_factory.transaction'),
-                'createMiddleware'
-            ])
-            ->setAbstract(true)
-            ->setArguments(['default']);
-
-The "default" value in this example is the name of the entity manager to use,
-which is the argument expected by the
-``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method.
-
-Then you can reference and configure the
-``messenger.middleware.doctrine_transaction`` service as a middleware:
+        use App\MessageHandler\SmsNotificationHandler;
+
+        $container->register(SmsNotificationHandler::class)
+            ->addTag('messenger.message_handler');
+
+Handler Subscriber & Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A handler class can handle multiple messages or configure itself by implementing
+:class:`Symfony\\Component\\Messenger\\Handler\\MessageSubscriberInterface`::
+
+    // src/MessageHandler/SmsNotificationHandler.php
+    namespace App\MessageHandler;
+
+    use App\Message\OtherSmsNotification;
+    use App\Message\SmsNotification;
+    use Symfony\Component\Messenger\Handler\MessageSubscriberInterface;
+
+    class SmsNotificationHandler implements MessageSubscriberInterface
+    {
+        public function __invoke(SmsNotification $message)
+        {
+            // ...
+        }
+
+        public function handleOtherSmsNotification(OtherSmsNotification $message)
+        {
+            // ...
+        }
+
+        public static function getHandledMessages(): iterable
+        {
+            // handle this message on __invoke
+            yield SmsNotification::class;
+
+            // also handle this message on handleOtherSmsNotification
+            yield OtherSmsNotification::class => [
+                'method' => 'handleOtherSmsNotification',
+                //'priority' => 0,
+                //'bus' => 'messenger.bus.default',
+            ];
+        }
+    }
+
+Binding Handlers to Different Transports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each message can have multiple handlers, and when a message is consumed
+*all* of its handlers are called. But you can also configure a handler to only
+be called when it's received from a *specific* transport. This allows you to
+have a single message where each handler is called by a different "worker"
+that's consuming a different transport.
+
+Suppose you have an ``UploadedImage`` message with two handlers:
+
+* ``ThumbnailUploadedImageHandler``: you want this to be handled by
+  a transport called ``image_transport``
+
+* ``NotifyAboutNewUploadedImageHandler``: you want this to be handled
+  by a transport called ``async_priority_normal``
+
+To do this, add the ``from_transport`` option to each handler. For example::
+
+    // src/MessageHandler/ThumbnailUploadedImageHandler.php
+    namespace App\MessageHandler;
+
+    use App\Message\UploadedImage;
+    use Symfony\Component\Messenger\Handler\MessageSubscriberInterface;
+
+    class ThumbnailUploadedImageHandler implements MessageSubscriberInterface
+    {
+        public function __invoke(UploadedImage $uploadedImage)
+        {
+            // do some thumbnailing
+        }
+
+        public static function getHandledMessages(): iterable
+        {
+            yield UploadedImage::class => [
+                'from_transport' => 'image_transport',
+            ];
+        }
+    }
+
+And similarly::
+
+    // src/MessageHandler/NotifyAboutNewUploadedImageHandler.php
+    // ...
+
+    class NotifyAboutNewUploadedImageHandler implements MessageSubscriberInterface
+    {
+        // ...
+
+        public static function getHandledMessages(): iterable
+        {
+            yield UploadedImage::class => [
+                'from_transport' => 'async_priority_normal',
+            ];
+        }
+    }
+
+Then, make sure to "route" your message to *both* transports:
 
 .. configuration-block::
 
@@ -652,13 +1165,13 @@ Then you can reference and configure the
         # config/packages/messenger.yaml
         framework:
             messenger:
-                buses:
-                    command_bus:
-                        middleware:
-                            # Using defaults
-                            - doctrine_transaction
-                            # Using another entity manager
-                            - doctrine_transaction: ['custom']
+                transports:
+                    async_priority_normal: # ...
+                    image_transport: # ...
+
+                routing:
+                    # ...
+                    'App\Message\UploadedImage': [image_transport, async_priority_normal]
 
     .. code-block:: xml
 
@@ -668,20 +1181,19 @@ Then you can reference and configure the
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:bus name="command_bus">
-                        <!-- Using defaults -->
-                        <framework:middleware id="doctrine_transaction" />
-                        <!-- Using another entity manager -->
-                        <framework:middleware id="doctrine_transaction">
-                            <framework:argument>custom</framework:argument>
-                        </framework:middleware>
-                    </framework:bus>
+                    <framework:transport name="async_priority_normal" dsn="..."/>
+                    <framework:transport name="image_transport" dsn="..."/>
+
+                    <framework:routing message-class="App\Message\UploadedImage">
+                        <framework:sender service="image_transport"/>
+                        <framework:sender service="async_priority_normal"/>
+                    </framework:routing>
                 </framework:messenger>
             </framework:config>
         </container>
@@ -691,123 +1203,162 @@ Then you can reference and configure the
         // config/packages/messenger.php
         $container->loadFromExtension('framework', [
             'messenger' => [
-                'buses' => [
-                    'command_bus' => [
-                        'middleware' => [
-                            // Using defaults
-                            'doctrine_transaction',
-                            // Using another entity manager
-                            ['id' => 'doctrine_transaction', 'arguments' => ['custom']],
-                        ],
-                    ],
+                'transports' => [
+                    'async_priority_normal' => '...',
+                    'image_transport' => '...',
                 ],
+                'routing' => [
+                    'App\Message\UploadedImage' => ['image_transport', 'async_priority_normal']
+                ]
             ],
         ]);
 
-.. note::
+That's it! You can now consume each transport:
 
-    Middleware factories only allow scalar and array arguments in config (no
-    references to other services). For most advanced use-cases, register a
-    concrete definition of the middleware manually and use its id.
+.. code-block:: terminal
 
-.. tip::
+    # will only call ThumbnailUploadedImageHandler when handling the message
+    $ php bin/console messenger:consume image_transport -vv
 
-    The ``messenger.middleware.doctrine_transaction`` middleware is a built-in
-    middleware wired automatically when the DoctrineBundle and the Messenger
-    component are installed and enabled.
+    $ php bin/console messenger:consume async_priority_normal -vv
 
-Your own Transport
-------------------
+.. caution::
 
-Once you have written your transport's sender and receiver, you can register your
-transport factory to be able to use it via a DSN in the Symfony application.
+    If a handler does *not* have ``from_transport`` config, it will be executed
+    on *every* transport that the message is received from.
 
-Create your Transport Factory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Extending Messenger
+-------------------
 
-You need to give FrameworkBundle the opportunity to create your transport from a
-DSN. You will need a transport factory::
+Envelopes & Stamps
+~~~~~~~~~~~~~~~~~~
 
-    use Symfony\Component\Messenger\Transport\TransportFactoryInterface;
-    use Symfony\Component\Messenger\Transport\TransportInterface;
-    use Symfony\Component\Messenger\Transport\ReceiverInterface;
-    use Symfony\Component\Messenger\Transport\SenderInterface;
+A message can be any PHP object. Sometimes, you may need to configure something
+extra about the message - like the way it should be handled inside Amqp or adding
+a delay before the message should be handled. You can do that by adding a "stamp"
+to your message::
 
-    class YourTransportFactory implements TransportFactoryInterface
+    use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\MessageBusInterface;
+    use Symfony\Component\Messenger\Stamp\DelayStamp;
+
+    public function index(MessageBusInterface $bus)
     {
-        public function createTransport(string $dsn, array $options): TransportInterface
-        {
-            return new YourTransport(/* ... */);
-        }
+        $bus->dispatch(new SmsNotification('...'), [
+            // wait 5 seconds before processing
+            new DelayStamp(5000)
+        ]);
 
-        public function supports(string $dsn, array $options): bool
-        {
-            return 0 === strpos($dsn, 'my-transport://');
-        }
+        // or explicitly create an Envelope
+        $bus->dispatch(new Envelope(new SmsNotification('...'), [
+            new DelayStamp(5000)
+        ]));
+
+        // ...
     }
 
-The transport object needs to implement the ``TransportInterface`` (which simply combines
-the ``SenderInterface`` and ``ReceiverInterface``). It will look like this::
+Internally, each message is wrapped in an ``Envelope``, which holds the message
+and stamps. You can create this manually or allow the message bus to do it. There
+are a variety of different stamps for different purposes and they're used internally
+to track information about a message - like the message bus that's handling it
+or if it's being retried after failure.
 
-    class YourTransport implements TransportInterface
-    {
-        public function send($message): void
-        {
-            // ...
-        }
+Middleware
+~~~~~~~~~~
 
-        public function receive(callable $handler): void
-        {
-            // ...
-        }
+What happens when you dispatch a message to a message bus depends on its
+collection of middleware (and their order). By default, the middleware configured
+for each bus looks like this:
 
-        public function stop(): void
-        {
-            // ...
-        }
-    }
+#. ``add_bus_name_stamp_middleware`` - adds a stamp to record which bus this
+   message was dispatched into;
 
-Register your Factory
-~~~~~~~~~~~~~~~~~~~~~
+#. ``dispatch_after_current_bus``- see :doc:`/messenger/message-recorder`;
+
+#. ``failed_message_processing_middleware`` - processes messages that are being
+   retried via the :ref:`failure transport <messenger-failure-transport>` to make
+   them properly function as if they were being received from their original transport;
+
+#. Your own collection of middleware_;
+
+#. ``send_message`` - if routing is configured for the transport, this sends
+   messages to that transport and stops the middleware chain;
+
+#. ``handle_message`` - calls the message handler(s) for the given message.
+
+.. note::
+
+    These middleware names are actually shortcuts names. The real service ids
+    are prefixed with ``messenger.middleware.``.
+
+You can add your own middleware to this list, or completely disable the default
+middleware and *only* include your own:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # config/services.yaml
-        services:
-            Your\Transport\YourTransportFactory:
-                tags: [messenger.transport_factory]
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                buses:
+                    messenger.bus.default:
+                        middleware:
+                            # service ids that implement Symfony\Component\Messenger\Middleware
+                            - 'App\Middleware\MyMiddleware'
+                            - 'App\Middleware\AnotherMiddleware'
+
+                        #default_middleware: false
 
     .. code-block:: xml
 
-        <!-- config/services.xml -->
+        <!-- config/packages/messenger.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
-            <services>
-                <service id="Your\Transport\YourTransportFactory">
-                   <tag name="messenger.transport_factory" />
-                </service>
-            </services>
+            <framework:config>
+                <framework:messenger>
+                    <framework:middleware id="App\Middleware\MyMiddleware"/>
+                    <framework:middleware id="App\Middleware\AnotherMiddleware"/>
+                    <framework:bus name="messenger.bus.default" default-middleware="false"/>
+                </framework:messenger>
+            </framework:config>
         </container>
 
     .. code-block:: php
 
-        // config/services.php
-        use Your\Transport\YourTransportFactory;
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', [
+            'messenger' => [
+                'buses' => [
+                    'messenger.bus.default' => [
+                        'middleware' => [
+                            'App\Middleware\MyMiddleware',
+                            'App\Middleware\AnotherMiddleware',
+                        ],
+                        'default_middleware' => false,
+                    ],
+                ],
+            ],
+        ]);
 
-        $container->register(YourTransportFactory::class)
-            ->setTags(['messenger.transport_factory']);
 
-Use your Transport
-~~~~~~~~~~~~~~~~~~
+.. note::
+
+    If a middleware service is abstract, a different instance of the service will
+    be created per bus.
 
-Within the ``framework.messenger.transports.*`` configuration, create your
-named transport using your own DSN:
+Middleware for Doctrine
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use Doctrine in your app, a number of optional middleware exist that you
+may want to use:
 
 .. configuration-block::
 
@@ -816,8 +1367,27 @@ named transport using your own DSN:
         # config/packages/messenger.yaml
         framework:
             messenger:
-                transports:
-                    yours: 'my-transport://...'
+                buses:
+                    command_bus:
+                        middleware:
+                            # wraps all handlers in a single Doctrine transaction
+                            # handlers do not need to call flush() and an error
+                            # in any handler will cause a rollback
+                            - doctrine_transaction
+
+                            # each time a message is handled, the Doctrine connection
+                            # is "pinged" and reconnected if it's closed. Useful
+                            # if your workers run for a long time and the database
+                            # connection is sometimes lost
+                            - doctrine_ping_connection
+
+                            # After handling, the Doctrine connection is closed,
+                            # which can free up database connections in a worker,
+                            # instead of keeping them open forever
+                            - doctrine_close_connection
+
+                            # or pass a different entity manager to any
+                            #- doctrine_transaction: ['custom']
 
     .. code-block:: xml
 
@@ -827,13 +1397,24 @@ named transport using your own DSN:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:messenger>
-                    <framework:transport name="yours" dsn="my-transport://..." />
+                    <framework:bus name="command_bus">
+                        <framework:middleware id="doctrine_transaction"/>
+                        <framework:middleware id="doctrine_ping_connection"/>
+                        <framework:middleware id="doctrine_close_connection"/>
+
+                        <!-- or pass a different entity manager to any -->
+                        <!--
+                        <framework:middleware id="doctrine_transaction">
+                            <framework:argument>custom</framework:argument>
+                        </framework:middleware>
+                        -->
+                    </framework:bus>
                 </framework:messenger>
             </framework:config>
         </container>
@@ -843,24 +1424,49 @@ named transport using your own DSN:
         // config/packages/messenger.php
         $container->loadFromExtension('framework', [
             'messenger' => [
-                'transports' => [
-                    'yours' => 'my-transport://...',
+                'buses' => [
+                    'command_bus' => [
+                        'middleware' => [
+                            'doctrine_transaction',
+                            'doctrine_ping_connection',
+                            'doctrine_close_connection',
+                            // Using another entity manager
+                            ['id' => 'doctrine_transaction', 'arguments' => ['custom']],
+                        ],
+                    ],
                 ],
             ],
         ]);
 
-In addition of being able to route your messages to the ``yours`` sender, this
-will give you access to the following services:
+Messenger Events
+~~~~~~~~~~~~~~~~
+
+In addition to middleware, Messenger also dispatches several events. You can
+:doc:`create an event listener </event_dispatcher>` to hook into various parts
+of the process. For each, the event class is the event name:
 
-#. ``messenger.sender.yours``: the sender;
-#. ``messenger.receiver.yours``: the receiver.
+* :class:`Symfony\\Component\\Messenger\\Event\\SendMessageToTransportsEvent`
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageFailedEvent`
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageHandledEvent`
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageReceivedEvent`
+* :class:`Symfony\\Component\\Messenger\\Event\\WorkerStoppedEvent`
+
+Multiple Buses, Command & Event Buses
+-------------------------------------
+
+Messenger gives you a single message bus service by default. But, you can configure
+as many as you want, creating "command", "query" or "event" buses and controlling
+their middleware. See :doc:`/messenger/multiple_buses`.
 
 Learn more
 ----------
+
 .. toctree::
     :maxdepth: 1
     :glob:
 
     /messenger/*
 
-.. _`enqueue's transport`: https://github.com/php-enqueue/messenger-adapter
+.. _`Enqueue's transport`: https://github.com/php-enqueue/messenger-adapter
+.. _`streams`: https://redis.io/topics/streams-intro
+.. _`Supervisor docs`: http://supervisord.org/
diff --git a/messenger/custom-transport.rst b/messenger/custom-transport.rst
new file mode 100644
index 00000000000..020b92655ab
--- /dev/null
+++ b/messenger/custom-transport.rst
@@ -0,0 +1,147 @@
+How to Create Your own Messenger Transport
+==========================================
+
+Once you have written your transport's sender and receiver, you can register your
+transport factory to be able to use it via a DSN in the Symfony application.
+
+Create your Transport Factory
+-----------------------------
+
+You need to give FrameworkBundle the opportunity to create your transport from a
+DSN. You will need a transport factory::
+
+    use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface;
+    use Symfony\Component\Messenger\Transport\Sender\SenderInterface;
+    use Symfony\Component\Messenger\Transport\TransportFactoryInterface;
+    use Symfony\Component\Messenger\Transport\TransportInterface;
+
+    class YourTransportFactory implements TransportFactoryInterface
+    {
+        public function createTransport(string $dsn, array $options): TransportInterface
+        {
+            return new YourTransport(/* ... */);
+        }
+
+        public function supports(string $dsn, array $options): bool
+        {
+            return 0 === strpos($dsn, 'my-transport://');
+        }
+    }
+
+The transport object needs to implement the
+:class:`Symfony\\Component\\Messenger\\Transport\\TransportInterface`
+(which combines the :class:`Symfony\\Component\\Messenger\\Transport\\Sender\\SenderInterface`
+and :class:`Symfony\\Component\\Messenger\\Transport\\Receiver\\ReceiverInterface`)::
+
+    use Symfony\Component\Messenger\Envelope;
+
+    class YourTransport implements TransportInterface
+    {
+        public function get(): iterable
+        {
+            // ...
+        }
+
+        public function ack(Envelope $envelope): void
+        {
+            // ...
+        }
+
+        public function reject(Envelope $envelope): void
+        {
+            // ...
+        }
+
+        public function send(Envelope $envelope): Envelope
+        {
+            // ...
+        }
+    }
+
+Register your Factory
+---------------------
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            Your\Transport\YourTransportFactory:
+                tags: [messenger.transport_factory]
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="Your\Transport\YourTransportFactory">
+                   <tag name="messenger.transport_factory"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use Your\Transport\YourTransportFactory;
+
+        $container->register(YourTransportFactory::class)
+            ->setTags(['messenger.transport_factory']);
+
+Use your Transport
+------------------
+
+Within the ``framework.messenger.transports.*`` configuration, create your
+named transport using your own DSN:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                transports:
+                    yours: 'my-transport://...'
+
+    .. code-block:: xml
+
+        <!-- config/packages/messenger.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:messenger>
+                    <framework:transport name="yours" dsn="my-transport://..."/>
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', [
+            'messenger' => [
+                'transports' => [
+                    'yours' => 'my-transport://...',
+                ],
+            ],
+        ]);
+
+In addition of being able to route your messages to the ``yours`` sender, this
+will give you access to the following services:
+
+#. ``messenger.sender.yours``: the sender;
+#. ``messenger.receiver.yours``: the receiver.
diff --git a/messenger/handler_results.rst b/messenger/handler_results.rst
new file mode 100644
index 00000000000..08a244d5e32
--- /dev/null
+++ b/messenger/handler_results.rst
@@ -0,0 +1,105 @@
+.. index::
+    single: Messenger; Getting results / Working with command & query buses
+
+Getting Results from your Handler
+=================================
+
+When a message is handled, the :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware`
+adds a :class:`Symfony\\Component\\Messenger\\Stamp\\HandledStamp` for each object that handled the message.
+You can use this to get the value returned by the handler(s)::
+
+    use Symfony\Component\Messenger\MessageBusInterface;
+    use Symfony\Component\Messenger\Stamp\HandledStamp;
+
+    $envelope = $messageBus->dispatch(SomeMessage());
+
+    // get the value that was returned by the last message handler
+    $handledStamp = $envelope->last(HandledStamp::class);
+    $handledStamp->getResult();
+
+    // or get info about all of handlers
+    $handledStamps = $envelope->all(HandledStamp::class);
+
+A :class:`Symfony\\Component\\Messenger\\HandleTrait` also exists in order to ease
+leveraging a Messenger bus for synchronous needs.
+The :method:`Symfony\\Component\\Messenger\\HandleTrait::handle` method ensures
+there is exactly one handler registered and returns its result.
+
+Working with Command & Query Buses
+----------------------------------
+
+The Messenger component can be used in CQRS architectures where command & query
+buses are central pieces of the application. Read Martin Fowler's
+`article about CQRS`_ to learn more and
+:doc:`how to configure multiple buses </messenger/multiple_buses>`.
+
+As queries are usually synchronous and expected to be handled once,
+getting the result from the handler is a common need.
+
+To avoid boilerplate code, you can leverage the ``HandleTrait`` in any class
+that has a ``$messageBus`` property::
+
+    // src/Action/ListItems.php
+    namespace App\Action;
+
+    use App\Message\ListItemsQuery;
+    use App\MessageHandler\ListItemsQueryResult;
+    use Symfony\Component\Messenger\HandleTrait;
+    use Symfony\Component\Messenger\MessageBusInterface;
+
+    class ListItems
+    {
+        use HandleTrait;
+
+        public function __construct(MessageBusInterface $messageBus)
+        {
+            $this->messageBus = $messageBus;
+        }
+
+        public function __invoke()
+        {
+            $result = $this->query(new ListItemsQuery(/* ... */));
+
+            // Do something with the result
+            // ...
+        }
+
+        // Creating such a method is optional, but allows type-hinting the result
+        private function query(ListItemsQuery $query): ListItemsResult
+        {
+            return $this->handle($query);
+        }
+    }
+
+Hence, you can use the trait to create command & query bus classes.
+For example, you could create a special ``QueryBus`` class and inject it
+wherever you need a query bus behavior instead of the ``MessageBusInterface``::
+
+    // src/MessageBus/QueryBus.php
+    namespace App\MessageBus;
+
+    use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\HandleTrait;
+    use Symfony\Component\Messenger\MessageBusInterface;
+
+    class QueryBus
+    {
+        use HandleTrait;
+
+        public function __construct(MessageBusInterface $messageBus)
+        {
+            $this->messageBus = $messageBus;
+        }
+
+        /**
+         * @param object|Envelope $query
+         *
+         * @return mixed The handler returned value
+         */
+        public function query($query)
+        {
+            return $this->handle($query);
+        }
+    }
+
+.. _`article about CQRS`: https://martinfowler.com/bliki/CQRS.html
diff --git a/messenger/message-recorder.rst b/messenger/message-recorder.rst
new file mode 100644
index 00000000000..4402cd5799c
--- /dev/null
+++ b/messenger/message-recorder.rst
@@ -0,0 +1,135 @@
+.. index::
+    single: Messenger; Record messages; Transaction messages
+
+Transactional Messages: Handle New Messages After Handling is Done
+==================================================================
+
+A message handler can ``dispatch`` new messages during execution, to either the
+same or a different bus (if the application has
+`multiple buses </messenger/multiple_buses>`_). Any errors or exceptions that
+occur during this process can have unintended consequences, such as:
+
+- If using the ``DoctrineTransactionMiddleware`` and a dispatched message throws
+  an exception, then any database transactions in the original handler will be
+  rolled back.
+- If the message is dispatched to a different bus, then the dispatched message
+  will be handled even if some code later in the current handler throws an
+  exception.
+
+An Example ``RegisterUser`` Process
+-----------------------------------
+
+Let's take the example of an application with both a *command* and an *event*
+bus. The application dispatches a command named ``RegisterUser`` to the command
+bus. The command is handled by the ``RegisterUserHandler`` which creates a
+``User`` object, stores that object to a database and dispatches a
+``UserRegistered`` message to the event bus.
+
+There are many handlers to the ``UserRegistered`` message, one handler may send
+a welcome email to the new user. We are using the ``DoctrineTransactionMiddleware``
+to wrap all database queries in one database transaction.
+
+**Problem 1:** If an exception is thrown when sending the welcome email, then
+the user will not be created because the ``DoctrineTransactionMiddleware`` will
+rollback the Doctrine transaction, in which the user has been created.
+
+**Problem 2:** If an exception is thrown when saving the user to the database,
+the welcome email is still sent because it is handled asynchronously.
+
+DispatchAfterCurrentBusMiddleware Middleware
+--------------------------------------------
+
+For many applications, the desired behavior is to *only* handle messages that
+are dispatched by a handler once that handler has fully finished. This can be by
+using the ``DispatchAfterCurrentBusMiddleware`` and adding a
+``DispatchAfterCurrentBusStamp`` stamp to
+`the message Envelope </components/messenger#adding-metadata-to-messages-envelopes>`_::
+
+    namespace App\Messenger\CommandHandler;
+
+    use App\Entity\User;
+    use App\Messenger\Command\RegisterUser;
+    use App\Messenger\Event\UserRegistered;
+    use Doctrine\ORM\EntityManagerInterface;
+    use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\MessageBusInterface;
+    use Symfony\Component\Messenger\Stamp\DispatchAfterCurrentBusStamp;
+
+    class RegisterUserHandler
+    {
+        private $eventBus;
+        private $em;
+
+        public function __construct(MessageBusInterface $eventBus, EntityManagerInterface $em)
+        {
+            $this->eventBus = $eventBus;
+            $this->em = $em;
+        }
+
+        public function __invoke(RegisterUser $command)
+        {
+            $user = new User($command->getUuid(), $command->getName(), $command->getEmail());
+            $this->em->persist($user);
+
+            // The DispatchAfterCurrentBusStamp marks the event message to be handled
+            // only if this handler does not throw an exception.
+
+            $event = new UserRegistered($command->getUuid());
+            $this->eventBus->dispatch(
+                (new Envelope($event))
+                    ->with(new DispatchAfterCurrentBusStamp())
+            );
+
+            // ...
+        }
+    }
+
+.. code-block:: php
+
+    namespace App\Messenger\EventSubscriber;
+
+    use App\Entity\User;
+    use App\Messenger\Event\UserRegistered;
+    use Doctrine\ORM\EntityManagerInterface;
+    use Symfony\Component\Mailer\MailerInterface;
+    use Symfony\Component\Mime\RawMessage;
+
+    class WhenUserRegisteredThenSendWelcomeEmail
+    {
+        private $mailer;
+        private $em;
+
+        public function __construct(MailerInterface $mailer, EntityManagerInterface $em)
+        {
+            $this->mailer = $mailer;
+            $this->em = $em;
+        }
+
+        public function __invoke(UserRegistered $event)
+        {
+            $user = $this->em->getRepository(User::class)->find($event->getUuid());
+
+            $this->mailer->send(new RawMessage('Welcome '.$user->getFirstName()));
+        }
+    }
+
+This means that the ``UserRegistered`` message would not be handled until
+*after* the ``RegisterUserHandler`` had completed and the new ``User`` was
+persisted to the database. If the ``RegisterUserHandler`` encounters an
+exception, the ``UserRegistered`` event will never be handled. And if an
+exception is thrown while sending the welcome email, the Doctrine transaction
+will not be rolled back.
+
+.. note::
+
+    If ``WhenUserRegisteredThenSendWelcomeEmail`` throws an exception, that
+    exception will be wrapped into a ``DelayedMessageHandlingException``. Using
+    ``DelayedMessageHandlingException::getExceptions`` will give you all
+    exceptions that are thrown while handing a message with the
+    ``DispatchAfterCurrentBusStamp``.
+
+The ``dispatch_after_current_bus`` middleware is enabled by default. If you're
+configuring your middleware manually, be sure to register
+``dispatch_after_current_bus`` before ``doctrine_transaction`` in the middleware
+chain. Also, the ``dispatch_after_current_bus`` middleware must be loaded for
+*all* of the buses being used.
diff --git a/messenger/multiple_buses.rst b/messenger/multiple_buses.rst
index d56fd27468f..a60a3e3f60b 100644
--- a/messenger/multiple_buses.rst
+++ b/messenger/multiple_buses.rst
@@ -24,18 +24,18 @@ an **event bus**. The event bus could have zero or more subscribers.
         framework:
             messenger:
                 # The bus that is going to be injected when injecting MessageBusInterface
-                default_bus: messenger.bus.commands
+                default_bus: command.bus
                 buses:
-                    messenger.bus.commands:
+                    command.bus:
                         middleware:
                             - validation
                             - doctrine_transaction
-                    messenger.bus.queries:
+                    query.bus:
                         middleware:
                             - validation
-                    messenger.bus.events:
+                    event.bus:
+                        default_middleware: allow_no_handlers
                         middleware:
-                            - allow_no_handler
                             - validation
 
     .. code-block:: xml
@@ -46,23 +46,22 @@ an **event bus**. The event bus could have zero or more subscribers.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <!-- The bus that is going to be injected when injecting MessageBusInterface -->
-                <framework:messenger default-bus="messenger.bus.commands">
-                    <framework:bus name="messenger.bus.commands">
-                        <framework:middleware id="validation" />
-                        <framework:middleware id="doctrine_transaction" />
+                <framework:messenger default-bus="command.bus">
+                    <framework:bus name="command.bus">
+                        <framework:middleware id="validation"/>
+                        <framework:middleware id="doctrine_transaction"/>
                     <framework:bus>
-                    <framework:bus name="messenger.bus.queries">
-                        <framework:middleware id="validation" />
+                    <framework:bus name="query.bus">
+                        <framework:middleware id="validation"/>
                     <framework:bus>
-                    <framework:bus name="messenger.bus.events">
-                        <framework:middleware id="validation" />
-                        <framework:middleware id="allow_no_handler" />
+                    <framework:bus name="event.bus" default-middleware="allow_no_handlers">
+                        <framework:middleware id="validation"/>
                     <framework:bus>
                 </framework:messenger>
             </framework:config>
@@ -74,89 +73,44 @@ an **event bus**. The event bus could have zero or more subscribers.
         $container->loadFromExtension('framework', [
             'messenger' => [
                 // The bus that is going to be injected when injecting MessageBusInterface
-                'default_bus' => 'messenger.bus.commands',
+                'default_bus' => 'command.bus',
                 'buses' => [
-                    'messenger.bus.commands' => [
+                    'command.bus' => [
                         'middleware' => [
                             'validation',
                             'doctrine_transaction',
                         ],
                     ],
-                    'messenger.bus.queries' => [
+                    'query.bus' => [
                         'middleware' => [
                             'validation',
                         ],
                     ],
-                    'messenger.bus.events' => [
+                    'event.bus' => [
+                        'default_middleware' => 'allow_no_handlers',
                         'middleware' => [
                             'validation',
-                            'allow_no_handler',
                         ],
                     ],
                 ],
             ],
         ]);
 
-This will generate the ``messenger.bus.commands``, ``messenger.bus.queries``
-and ``messenger.bus.events`` services that you can inject in your services.
+This will create three new services:
 
-Type-hints and Auto-wiring
---------------------------
+* ``command.bus``: autowireable with the :class:`Symfony\\Component\\Messenger\\MessageBusInterface`
+  type-hint (because this is the ``default_bus``);
 
-Auto-wiring is a great feature that allows you to reduce the amount of configuration
-required for your service container to be created. By using ``MessageBusInterface``
-as argument typehint in your services, the default configured bus will be injected
-(i.e ``messenger.bus.commands`` in above examples).
+* ``query.bus``: autowireable with ``MessageBusInterface $queryBus``;
 
-When working with multiple buses, you can use the ``DependencyInjection`` component's
-binding capabilities to clarify which bus will be injected based on the argument's name:
+* ``event.bus``: autowireable with ``MessageBusInterface $eventBus``.
 
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        services:
-            _defaults:
-                # ...
-
-                bind:
-                    $commandBus: '@messenger.bus.commands'
-                    $queryBus: '@messenger.bus.queries'
-                    $eventBus: '@messenger.bus.events'
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <defaults>
-                   <bind key="$commandBus" type="service" id="messenger.bus.commands" />
-                   <bind key="$queryBus" type="service" id="messenger.bus.queries" />
-                   <bind key="$eventBus" type="service" id="messenger.bus.events" />
-                </defaults>
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-
-        $container->bind('$commandBus', 'messenger.bus.commands');
-        $container->bind('$queryBus', 'messenger.bus.queries');
-        $container->bind('$eventBus', 'messenger.bus.events');
-
-Restrict handlers per bus
+Restrict Handlers per Bus
 -------------------------
 
 By default, each handler will be available to handle messages on *all*
 of your buses. To prevent dispatching a message to the wrong bus without an error,
-you can restrict each handler to a specific bus using the `messenger.message_handler` tag:
+you can restrict each handler to a specific bus using the ``messenger.message_handler`` tag:
 
 .. configuration-block::
 
@@ -165,7 +119,10 @@ you can restrict each handler to a specific bus using the `messenger.message_han
         # config/services.yaml
         services:
             App\MessageHandler\SomeCommandHandler:
-                tags: [{ name: messenger.message_handler, bus: messenger.bus.commands }]
+                tags: [{ name: messenger.message_handler, bus: command.bus }]
+                # prevent handlers from being registered twice (or you can remove
+                # the MessageHandlerInterface that autoconfigure uses to find handlers)
+                autoconfigure: false
 
     .. code-block:: xml
 
@@ -174,11 +131,11 @@ you can restrict each handler to a specific bus using the `messenger.message_han
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\MessageHandler\SomeCommandHandler">
-                    <tag name="messenger.message_handler" bus="messenger.bus.commands" />
+                    <tag name="messenger.message_handler" bus="command.bus"/>
                 </service>
             </services>
         </container>
@@ -186,13 +143,12 @@ you can restrict each handler to a specific bus using the `messenger.message_han
     .. code-block:: php
 
         // config/services.php
-
         $container->services()
             ->set(App\MessageHandler\SomeCommandHandler::class)
-            ->tag('messenger.message_handler', ['bus' => 'messenger.bus.commands']);
+            ->tag('messenger.message_handler', ['bus' => 'command.bus']);
 
 This way, the ``App\MessageHandler\SomeCommandHandler`` handler will only be
-known by the ``messenger.bus.commands`` bus.
+known by the ``command.bus`` bus.
 
 You can also automatically add this tag to a number of classes by following
 a naming convention and registering all of the handler services by name with
@@ -204,18 +160,20 @@ the correct tag:
 
         # config/services.yaml
 
-        # put this after the `App\` line that registers all your services
+        # put this after the "App\" line that registers all your services
         command_handlers:
             namespace: App\MessageHandler\
             resource: '%kernel.project_dir%/src/MessageHandler/*CommandHandler.php'
+            autoconfigure: false
             tags:
-                - { name: messenger.message_handler, bus: messenger.bus.commands }
+                - { name: messenger.message_handler, bus: command.bus }
 
         query_handlers:
             namespace: App\MessageHandler\
             resource: '%kernel.project_dir%/src/MessageHandler/*QueryHandler.php'
+            autoconfigure: false
             tags:
-                - { name: messenger.message_handler, bus: messenger.bus.queries }
+                - { name: messenger.message_handler, bus: query.bus }
 
     .. code-block:: xml
 
@@ -224,16 +182,16 @@ the correct tag:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- command handlers -->
-                <prototype namespace="App\MessageHandler\" resource="%kernel.project_dir%/src/MessageHandler/*CommandHandler.php">
-                    <tag name="messenger.message_handler" bus="messenger.bus.commands" />
+                <prototype namespace="App\MessageHandler\" resource="%kernel.project_dir%/src/MessageHandler/*CommandHandler.php" autoconfigure="false">
+                    <tag name="messenger.message_handler" bus="command.bus"/>
                 </service>
                 <!-- query handlers -->
-                <prototype namespace="App\MessageHandler\" resource="%kernel.project_dir%/src/MessageHandler/*QueryHandler.php">
-                    <tag name="messenger.message_handler" bus="messenger.bus.queries" />
+                <prototype namespace="App\MessageHandler\" resource="%kernel.project_dir%/src/MessageHandler/*QueryHandler.php" autoconfigure="false">
+                    <tag name="messenger.message_handler" bus="query.bus"/>
                 </service>
             </services>
         </container>
@@ -245,14 +203,16 @@ the correct tag:
         // Command handlers
         $container->services()
             ->load('App\MessageHandler\\', '%kernel.project_dir%/src/MessageHandler/*CommandHandler.php')
-            ->tag('messenger.message_handler', ['bus' => 'messenger.bus.commands']);
+            ->autoconfigure(false)
+            ->tag('messenger.message_handler', ['bus' => 'command.bus']);
 
         // Query handlers
         $container->services()
             ->load('App\MessageHandler\\', '%kernel.project_dir%/src/MessageHandler/*QueryHandler.php')
-            ->tag('messenger.message_handler', ['bus' => 'messenger.bus.queries']);
+            ->autoconfigure(false)
+            ->tag('messenger.message_handler', ['bus' => 'query.bus']);
 
-Debugging the buses
+Debugging the Buses
 -------------------
 
 The ``debug:messenger`` command lists available messages & handlers per bus.
@@ -260,13 +220,13 @@ You can also restrict the list to a specific bus by providing its name as argume
 
 .. code-block:: terminal
 
-    $ bin/console debug:messenger
+    $ php bin/console debug:messenger
 
       Messenger
       =========
 
-      messenger.bus.commands
-      ----------------------
+      command.bus
+      -----------
 
        The following messages can be dispatched:
 
@@ -277,8 +237,8 @@ You can also restrict the list to a specific bus by providing its name as argume
             handled by App\MessageHandler\MultipleBusesMessageHandler
        ---------------------------------------------------------------------------------------
 
-      messenger.bus.queries
-      ---------------------
+      query.bus
+      ---------
 
        The following messages can be dispatched:
 
diff --git a/migration.rst b/migration.rst
new file mode 100644
index 00000000000..89bfd5c21c1
--- /dev/null
+++ b/migration.rst
@@ -0,0 +1,467 @@
+.. index::
+   single: Migration
+
+Migrating an Existing Application to Symfony
+============================================
+
+When you have an existing application that was not built with Symfony,
+you might want to move over parts of that application without rewriting
+the existing logic completely. For those cases there is a pattern called
+`Strangler Application`_. The basic idea of this pattern is to create a
+new application that gradually takes over functionality from an existing
+application. This migration approach can be implemented with Symfony in
+various ways and has some benefits over a rewrite such as being able
+to introduce new features in the existing application and reducing risk
+by avoiding a "big bang"-release for the new application.
+
+.. admonition:: Screencast
+    :class: screencast
+
+    The topic of migrating from an existing application towards Symfony is
+    sometimes discussed during conferences. For example the talk
+    `Modernizing with Symfony`_ reiterates some of the points from this page.
+
+Prerequisites
+-------------
+
+Before you start introducing Symfony to the existing application, you have to
+ensure certain requirements are met by your existing application and
+environment.  Making the decisions and preparing the environment before
+starting the migration process is crucial for its success.
+
+.. note::
+
+    The following steps do not require you to have the new Symfony
+    application in place and in fact it might be safer to introduce these
+    changes beforehand in your existing application.
+
+Choosing the Target Symfony Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most importantly, this means that you will have to decide which version you
+are aiming to migrate to, either a current stable release or the long
+term support version (LTS). The main difference is, how frequently you
+will need to upgrade in order to use a supported version. In the context
+of a migration, other factors, such as the supported PHP-version or
+support for libraries/bundles you use, may have a strong impact as well.
+Using the most recent, stable release will likely give you more features,
+but it will also require you to update more frequently to ensure you will
+get support for bug fixes and security patches and you will have to work
+faster on fixing deprecations to be able to upgrade.
+
+.. tip::
+
+    When upgrading to Symfony you might be tempted to also use
+    :ref:`Flex <symfony-flex>`. Please keep in mind that it primarily
+    focuses on bootstrapping a new Symfony application according to best
+    practices regarding the directory structure. When you work in the
+    constraints of an existing application you might not be able to
+    follow these constraints, making Flex less useful.
+
+First of all your environment needs to be able to support the minimum
+requirements for both applications. In other words, when the Symfony
+release you aim to use requires PHP 7.1 and your existing application
+does not yet support this PHP version, you will probably have to upgrade
+your legacy project. Use the ``check:requirements`` command to check if your
+server meets the :ref:`technical requirements for running Symfony applications <symfony-tech-requirements>`
+and compare them with your current application's environment to make sure you
+are able to run both applications on the same system. Having a test
+system, that is as close to the production environment as possible,
+where you can just install a new Symfony project next to the existing one
+and check if it is working will give you an even more reliable result.
+
+.. tip::
+
+    If your current project is running on an older PHP version such as
+    PHP 5.x upgrading to a recent version will give you a performance
+    boost without having to change your code.
+
+Setting up Composer
+~~~~~~~~~~~~~~~~~~~
+
+Another point you will have to look out for is conflicts between
+dependencies in both applications. This is especially important if your
+existing application already uses Symfony components or libraries commonly
+used in Symfony applications such as Doctrine ORM, Swiftmailer or Twig.
+A good way for ensuring compatibility is to use the same ``composer.json``
+for both project's dependencies.
+
+Once you have introduced composer for managing your project's dependencies
+you can use its autoloader to ensure you do not run into any conflicts due
+to custom autoloading from your existing framework. This usually entails
+adding an `autoload`_-section to your ``composer.json`` and configuring it
+based on your application and replacing your custom logic with something
+like this::
+
+    require __DIR__.'/vendor/autoload.php';
+
+Removing Global State from the Legacy Application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In older PHP applications it was quite common to rely on global state and
+even mutate it during runtime. This might have side effects on the newly
+introduced Symfony application. In other words code relying on globals
+in the existing application should be refactored to allow for both systems
+to work simultaneously. Since relying on global state is considered an
+anti-pattern nowadays you might want to start working on this even before
+doing any integration.
+
+Setting up the Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There might be additional steps you need to take depending on the libraries
+you use, the original framework your project is based on and most importantly
+the age of the project as PHP itself underwent many improvements throughout
+the years that your code might not have caught on to, yet. As long as both
+your existing code and a new Symfony project can run in parallel on the
+same system you are on a good way. All these steps do not require you to
+introduce Symfony just yet and will already open up some opportunities for
+modernizing your existing code.
+
+Establishing a Safety Net for Regressions
+-----------------------------------------
+
+Before you can safely make changes to the existing code, you must ensure that
+nothing will break. One reason for choosing to migrate is making sure that the
+application is in a state where it can run at all times. The best way for
+ensuring a working state is to establish automated tests.
+
+It is quite common for an existing application to either not have a test suite
+at all or have low code coverage. Introducing unit tests for this code is
+likely not cost effective as the old code might be replaced with functionality
+from Symfony components or might be adapted to the new application.
+Additionally legacy code tends to be hard to write tests for making the process
+slow and cumbersome.
+
+Instead of providing low level tests, that ensure each class works as expected, it
+might makes sense to write high level tests ensuring that at least anything user
+facing works on at least a superficial level. These kinds of tests are commonly
+called End-to-End tests, because they cover the whole application from what the
+user sees in the browser down to the very code that is being run and connected
+services like a database. To automate this you have to make sure that you can
+get a test instance of your system running as easily as possible and making
+sure that external systems do not change your production environment, e.g.
+provide a separate test database with (anonymized) data from a production
+system or being able to setup a new schema with a basic dataset for your test
+environment. Since these tests do not rely as much on isolating testable code
+and instead look at the interconnected system, writing them is usually easier
+and more productive when doing a migration. You can then limit your effort on
+writing lower level tests on parts of the code that you have to change or
+replace in the new application making sure it is testable right from the start.
+
+There are tools aimed at End-to-End testing you can use such as
+`Symfony Panther`_ or you can write :doc:`functional tests </testing>`
+in the new Symfony application as soon as the initial setup is completed.
+For example you can add so called Smoke Tests, which only ensure a certain
+path is accessible by checking the HTTP status code returned or looking for
+a text snippet from the page.
+
+Introducing Symfony to the Existing Application
+-----------------------------------------------
+
+The following instructions only provide an outline of common tasks for
+setting up a Symfony application that falls back to a legacy application
+whenever a route is not accessible. Your mileage may vary and likely you
+will need to adjust some of this or even provide additional configuration
+or retrofitting to make it work with your application. This guide is not
+supposed to be comprehensive and instead aims to be a starting point.
+
+.. tip::
+
+    If you get stuck or need additional help you can reach out to the
+    :doc:`Symfony community </contributing/community/index>` whenever you need
+    concrete feedback on an issue you are facing.
+
+Booting Symfony in a Front Controller
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When looking at how a typical PHP application is bootstrapped there are
+two major approaches. Nowadays most frameworks provide a so called
+front controller which acts as an entrypoint. No matter which URL-path
+in your application you are going to, every request is being sent to
+this front controller, which then determines which parts of your
+application to load, e.g. which controller and action to call. This is
+also the approach that Symfony takes with ``public/index.php`` being
+the front controller. Especially in older applications it was common
+that different paths were handled by different PHP files.
+
+In any case you have to create a ``public/index.php`` that will start
+your Symfony application by either copying the file from the
+``FrameworkBundle``-recipe or by using Flex and requiring the
+FrameworkBundle. You will also likely have to update you web server
+(e.g. Apache or nginx) to always use this front controller. You can
+look at :doc:`Web Server Configuration </setup/web_server_configuration>`
+for examples on how this might look. For example when using Apache you can
+use Rewrite Rules to ensure PHP files are ignored and instead only index.php
+is called:
+
+.. code-block:: apache
+
+    RewriteEngine On
+
+    RewriteCond %{REQUEST_URI}::$1 ^(/.+)/(.*)::\2$
+    RewriteRule ^(.*) - [E=BASE:%1]
+
+    RewriteCond %{ENV:REDIRECT_STATUS} ^$
+    RewriteRule ^index\.php(?:/(.*)|$) %{ENV:BASE}/$1 [R=301,L]
+
+    RewriteRule ^index\.php - [L]
+
+    RewriteCond %{REQUEST_FILENAME} -f
+    RewriteCond %{REQUEST_FILENAME} !^.+\.php$
+    RewriteRule ^ - [L]
+
+    RewriteRule ^ %{ENV:BASE}/index.php [L]
+
+This change will make sure that from now on your Symfony application is
+the first one handling all requests. The next step is to make sure that
+your existing application is started and taking over whenever Symfony
+can not yet handle a path previously managed by the existing application.
+
+From this point, many tactics are possible and every project requires its
+unique approach for migration. This guide shows two examples of commonly used
+approaches, which you can use as a base for your own approach:
+
+* `Front Controller with Legacy Bridge`_, which leaves the legacy application
+  untouched and allows to migrate it in phases to the Symfony application.
+* `Legacy Route Loader`_, where the legacy application is integrated in phases
+  into Symfony, with a fully integrated final result.
+
+Front Controller with Legacy Bridge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have a running Symfony application that takes over all requests,
+falling back to your legacy application is done by extending the original front
+controller script with some logic for going to your legacy system. The file
+could look something like this::
+
+    // public/index.php
+    use App\Kernel;
+    use App\LegacyBridge;
+    use Symfony\Component\Debug\Debug;
+    use Symfony\Component\HttpFoundation\Request;
+
+    require dirname(__DIR__).'/config/bootstrap.php';
+
+    /*
+     * The kernel will always be available globally, allowing you to
+     * access it from your existing application and through it the
+     * service container. This allows for introducing new features in
+     * the existing application.
+     */
+    global $kernel;
+
+    if ($_SERVER['APP_DEBUG']) {
+        umask(0000);
+
+        Debug::enable();
+    }
+
+    if ($trustedProxies = $_SERVER['TRUSTED_PROXIES'] ?? $_ENV['TRUSTED_PROXIES'] ?? false) {
+        Request::setTrustedProxies(
+          explode(',', $trustedProxies),
+          Request::HEADER_X_FORWARDED_ALL ^ Request::HEADER_X_FORWARDED_HOST
+        );
+    }
+
+    if ($trustedHosts = $_SERVER['TRUSTED_HOSTS'] ?? $_ENV['TRUSTED_HOSTS'] ?? false) {
+        Request::setTrustedHosts([$trustedHosts]);
+    }
+
+    $kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG'], dirname(__DIR__));
+    $request = Request::createFromGlobals();
+    $response = $kernel->handle($request);
+
+    /*
+     * LegacyBridge will take care of figuring out whether to boot up the
+     * existing application or to send the Symfony response back to the client.
+     */
+    $scriptFile = LegacyBridge::prepareLegacyScript($request, $response, __DIR__);
+    if ($scriptFile !== null) {
+        require $scriptFile;
+    } else {
+        $response->send();
+    }
+    $kernel->terminate($request, $response);
+
+There are 2 major deviations from the original file:
+
+Line 15
+  First of all, ``$kernel`` is made globally available. This allows you to use
+  Symfony features inside your existing application and gives access to
+  services configured in our Symfony application. This helps you prepare your
+  own code to work better within the Symfony application before you transition
+  it over. For instance, by replacing outdated or redundant libraries with
+  Symfony components.
+
+Line 38 - 47
+  Instead of sending the Symfony response directly, a ``LegacyBridge`` is
+  called to decide whether the legacy application should be booted and used to
+  create the response instead.
+
+This legacy bridge is responsible for figuring out which file should be loaded
+in order to process the old application logic. This can either be a front
+controller similar to Symfony's ``public/index.php`` or a specific script file
+based on the current route. The basic outline of this LegacyBridge could look
+somewhat like this::
+
+    // src/LegacyBridge.php
+    namespace App;
+
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
+
+    class LegacyBridge
+    {
+        public static function prepareLegacyScript(Request $request, Response $response, string $publicDirectory): string
+        {
+            // If Symfony successfully handled the route, you do not have to do anything.
+            if (false === $response->isNotFound()) {
+                return;
+            }
+
+            // Figure out how to map to the needed script file
+            // from the existing application and possibly (re-)set
+            // some env vars.
+            $legacyScriptFilename = ...;
+
+            return $legacyScriptFilename;
+        }
+    }
+
+This is the most generic approach you can take, that is likely to work
+no matter what your previous system was. You might have to account for
+certain "quirks", but since your original application is only started
+after Symfony finished handling the request you reduced the chances
+for side effects and any interference.
+
+Since the old script is called in the global variable scope it will reduce side
+effects on the old code which can sometimes require variables from the global
+scope. At the same time, because your Symfony application will always be
+booted first, you can access the container via the ``$kernel`` variable and
+then fetch any service (using :method:`Symfony\\Component\\HttpKernel\\KernelInterface::getContainer`).
+This can be helpful if you want to introduce new features to your legacy
+application, without switching over the whole action to the new application.
+For example, you could now use the Symfony Translator in your old application
+or instead of using your old database logic, you could use Doctrine to refactor
+old queries. This will also allow you to incrementally improve the legacy code
+making it easier to transition it over to the new Symfony application.
+
+The major downside is, that both systems are not well integrated
+into each other leading to some redundancies and possibly duplicated code.
+For example, since the Symfony application is already done handling the
+request you can not take advantage of kernel events or utilize Symfony's
+routing for determining which legacy script to call.
+
+Legacy Route Loader
+~~~~~~~~~~~~~~~~~~~
+
+The major difference to the LegacyBridge-approach from before is, that the
+logic is moved inside the Symfony application. It removes some of the
+redundancies and allows us to also interact with parts of the legacy
+application from inside Symfony, instead of just the other way around.
+
+.. tip::
+
+    The following route loader is just a generic example that you might
+    have to tweak for your legacy application. You can familiarize
+    yourself with the concepts by reading up on it in :doc:`Routing </routing>`.
+
+The legacy route loader is :doc:`a custom route loader </routing/custom_route_loader>`.
+The legacy route loader has a similar functionality as the previous
+LegacyBridge, but it is a service that is registered inside Symfony's Routing
+component::
+
+    // src/Legacy/LegacyRouteLoader.php
+    namespace App\Legacy;
+
+    use Symfony\Component\Config\Loader\Loader;
+    use Symfony\Component\Routing\Route;
+    use Symfony\Component\Routing\RouteCollection;
+
+    class LegacyRouteLoader extends Loader
+    {
+        // ...
+
+        public function load($resource, $type = null)
+        {
+            $collection = new RouteCollection();
+            $finder = new Finder();
+            $finder->files()->name('*.php');
+
+            /** @var SplFileInfo $legacyScriptFile */
+            foreach ($finder->in($this->webDir) as $legacyScriptFile) {
+                // This assumes all legacy files use ".php" as extension
+                $filename = basename($legacyScriptFile->getRelativePathname(), '.php');
+                $routeName = sprintf('app.legacy.%s', str_replace('/', '__', $filename));
+
+                $collection->add($routeName, new Route($legacyScriptFile->getRelativePathname(), [
+                    '_controller' => 'App\Controller\LegacyController::loadLegacyScript',
+                    'requestPath' => '/' . $legacyScriptFile->getRelativePathname(),
+                    'legacyScript' => $legacyScriptFile->getPathname(),
+                ]));
+            }
+
+            return $collection;
+        }
+    }
+
+You will also have to register the loader in your application's
+``routing.yaml`` as described in the documentation for
+:doc:`Custom Route Loaders </routing/custom_route_loader>`.
+Depending on your configuration, you might also have to tag the service with
+``routing.loader``. Afterwards you should be able to see all the legacy routes
+in your route configuration, e.g. when you call the ``debug:router``-command:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:router
+
+In order to use these routes you will need to create a controller that handles
+these routes. You might have noticed the ``_controller`` attribute in the
+previous code example, which tells Symfony which Controller to call whenever it
+tries to access one of our legacy routes. The controller itself can then use the
+other route attributes (i.e. ``requestPath`` and ``legacyScript``) to determine
+which script to call and wrap the output in a response class::
+
+    // src/Controller/LegacyController.php
+    namespace App\Controller;
+
+    use Symfony\Component\HttpFoundation\StreamedResponse;
+
+    class LegacyController
+    {
+        public function loadLegacyScript(string $requestPath, string $legacyScript)
+        {
+            return StreamedResponse::create(
+                function () use ($requestPath, $legacyScript) {
+                    $_SERVER['PHP_SELF'] = $requestPath;
+                    $_SERVER['SCRIPT_NAME'] = $requestPath;
+                    $_SERVER['SCRIPT_FILENAME'] = $legacyScript;
+
+                    chdir(dirname($legacyScript));
+
+                    require $legacyScript;
+                }
+            );
+        }
+    }
+
+This controller will set some server variables that might be needed by
+the legacy application. This will simulate the legacy script being called
+directly, in case it relies on these variables (e.g. when determining
+relative paths or file names). Finally the action requires the old script,
+which essentially calls the original script as before, but it runs inside
+our current application scope, instead of the global scope.
+
+There are some risks to this approach, as it is no longer run in the global
+scope. However, since the legacy code now runs inside a controller action, you gain
+access to many functionalities from the new Symfony application, including the
+chance to use Symfony's event lifecycle. For instance, this allows you to
+transition the authentication and authorization of the legacy application over
+to the Symfony application using the Security component and its firewalls.
+
+.. _`Strangler Application`: https://www.martinfowler.com/bliki/StranglerApplication.html
+.. _`autoload`: https://getcomposer.org/doc/04-schema.md#autoload
+.. _`Modernizing with Symfony`: https://youtu.be/YzyiZNY9htQ
+.. _`Symfony Panther`: https://github.com/symfony/panther
diff --git a/page_creation.rst b/page_creation.rst
index bf97528d061..4dd1d0eb335 100644
--- a/page_creation.rst
+++ b/page_creation.rst
@@ -41,7 +41,7 @@ Creating a Page: Route and Controller
     article and can access your new Symfony app in the browser.
 
 Suppose you want to create a page - ``/lucky/number`` - that generates a lucky (well,
-random) number and prints it. To do that, create a "Controller class" and a
+random) number and prints it. To do that, create a "Controller" class and a
 "controller" method inside of it::
 
     <?php
@@ -133,7 +133,7 @@ Auto-Installing Recipes with Symfony Flex
 
 You may not have noticed, but when you ran ``composer require annotations``, two
 special things happened, both thanks to a powerful Composer plugin called
-:doc:`Flex </setup/flex>`.
+:ref:`Flex <symfony-flex>`.
 
 First, ``annotations`` isn't a real package name: it's an *alias* (i.e. shortcut)
 that Flex resolves to ``sensio/framework-extra-bundle``.
@@ -145,9 +145,6 @@ to do a lot, like adding configuration files, creating directories, updating ``.
 and adding new config to your ``.env`` file. Flex *automates* the installation of
 packages so you can get back to coding.
 
-You can learn more about Flex by reading ":doc:`/setup/flex`". But that's not necessary:
-Flex works automatically in the background when you add packages.
-
 The bin/console Command
 -----------------------
 
@@ -240,10 +237,9 @@ Template files live in the ``templates/`` directory, which was created for you a
 when you installed Twig. Create a new ``templates/lucky`` directory with a new
 ``number.html.twig`` file inside:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {# templates/lucky/number.html.twig #}
-
     <h1>Your lucky number is {{ number }}</h1>
 
 The ``{{ number }}`` syntax is used to *print* variables in Twig. Refresh your browser
@@ -265,8 +261,8 @@ Great news! You've already worked inside the most important directories in your
 project:
 
 ``config/``
-    Contains... configuration of course!. You will configure routes, :doc:`services </service_container>`
-    and packages.
+    Contains... configuration!. You will configure routes,
+    :doc:`services </service_container>` and packages.
 
 ``src/``
     All your PHP code lives here.
@@ -302,7 +298,7 @@ What's Next?
 ------------
 
 Congrats! You're already starting to master Symfony and learn a whole new
-way of building beautiful, functional, fast and maintainable apps.
+way of building beautiful, functional, fast and maintainable applications.
 
 Ok, time to finish mastering the fundamentals by reading these articles:
 
diff --git a/performance.rst b/performance.rst
index 25491cd6199..fdf181839c9 100644
--- a/performance.rst
+++ b/performance.rst
@@ -75,7 +75,7 @@ overhead that can be avoided as follows:
     opcache.validate_timestamps=0
 
 After each deploy, you must empty and regenerate the cache of OPcache. Otherwise
-you won't see the updates made in the application. Given than in PHP, the CLI
+you won't see the updates made in the application. Given that in PHP, the CLI
 and the web processes don't share the same OPcache, you cannot clear the web
 server OPcache by executing some command in your terminal. These are some of the
 possible solutions:
@@ -123,16 +123,15 @@ in ``vendor/composer/autoload_classmap.php``.
 Execute this command to generate the class map (and make it part of your
 deployment process too):
 
-.. code-block:: bash
+.. code-block:: terminal
 
-    $ composer dump-autoload --optimize --no-dev --classmap-authoritative
+    $ composer dump-autoload --no-dev --classmap-authoritative
 
-* ``--optimize`` dumps every PSR-0 and PSR-4 compatible class used in your
-  application;
 * ``--no-dev`` excludes the classes that are only needed in the development
-  environment (e.g. tests);
-* ``--classmap-authoritative`` prevents Composer from scanning the file
-  system for classes that are not found in the class map.
+  environment (i.e. ``require-dev`` dependencies and ``autoload-dev`` rules);
+* ``--classmap-authoritative`` creates a class map for PSR-0 and PSR-4 compatible classes
+  used in your application and prevents Composer from scanning the file system for
+  classes that are not found in the class map. (see: `Composer's autoloader optimization`_).
 
 Learn more
 ----------
@@ -141,7 +140,6 @@ Learn more
 
 .. _`byte code caches`: https://en.wikipedia.org/wiki/List_of_PHP_accelerators
 .. _`OPcache`: https://php.net/manual/en/book.opcache.php
-.. _`bootstrap file`: https://github.com/sensiolabs/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php
 .. _`Composer's autoloader optimization`: https://getcomposer.org/doc/articles/autoloader-optimization.md
 .. _`APC`: https://php.net/manual/en/book.apc.php
 .. _`APCu Polyfill component`: https://github.com/symfony/polyfill-apcu
diff --git a/profiler.rst b/profiler.rst
index 6deabbe4703..e37bdd8ba7d 100644
--- a/profiler.rst
+++ b/profiler.rst
@@ -2,25 +2,220 @@ Profiler
 ========
 
 The profiler is a powerful **development tool** that gives detailed information
-about the execution of any request.
-
-**Never** enable the profiler in production environments as it will lead to
-major security vulnerabilities in your project.
+about the execution of any request. **Never** enable the profiler in production
+environments as it will lead to major security vulnerabilities in your project.
 
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the profiler before using it:
 
 .. code-block:: terminal
 
     $ composer require --dev symfony/profiler-pack
 
+Now browse any page of your application in the development environment to let
+the profiler collect information. Then, click on any element of the debug
+toolbar injected at the bottom of your pages to open the web interface of the
+Symfony Profiler, which will look like this:
+
+.. image:: /_images/profiler/web-interface.png
+   :align: center
+   :class: with-browser
+
+Accessing Profiling Data Programmatically
+-----------------------------------------
+
+Most of the times, the profiler information is accessed and analyzed using its
+web-based interface. However, you can also retrieve profiling information
+programmatically thanks to the methods provided by the ``profiler`` service.
+
+When the response object is available, use the
+:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfileFromResponse`
+method to access to its associated profile::
+
+    // ... $profiler is the 'profiler' service
+    $profile = $profiler->loadProfileFromResponse($response);
+
+When the profiler stores data about a request, it also associates a token with it;
+this token is available in the ``X-Debug-Token`` HTTP header of the response.
+Using this token, you can access the profile of any past response thanks to the
+:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfile` method::
+
+    $token = $response->headers->get('X-Debug-Token');
+    $profile = $profiler->loadProfile($token);
+
+.. tip::
+
+    When the profiler is enabled but not the web debug toolbar, inspect the page
+    with your browser's developer tools to get the value of the ``X-Debug-Token``
+    HTTP header.
+
+The ``profiler`` service also provides the
+:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::find` method to
+look for tokens based on some criteria::
+
+    // gets the latest 10 tokens
+    $tokens = $profiler->find('', '', 10, '', '', '');
+
+    // gets the latest 10 tokens for all URL containing /admin/
+    $tokens = $profiler->find('', '/admin/', 10, '', '', '');
+
+    // gets the latest 10 tokens for local POST requests
+    $tokens = $profiler->find('127.0.0.1', '', 10, 'POST', '', '');
+
+    // gets the latest 10 tokens for requests that happened between 2 and 4 days ago
+    $tokens = $profiler->find('', '', 10, '', '4 days ago', '2 days ago');
+
+Data Collectors
+---------------
+
+The profiler gets its information using some services called "data collectors".
+Symfony comes with several collectors that get information about the request,
+the logger, the routing, the cache, etc.
+
+Run this command to get the list of collectors actually enabled in your app:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:container --tag=data_collector
+
+You can also :doc:`create your own data collector </profiler/data_collector>` to
+store any data generated by your app and display it in the debug toolbar and the
+profiler web interface.
+
+.. _profiler-timing-execution:
+
+Timing the Execution of the Application
+---------------------------------------
+
+If you want to measure the time some tasks take in your application, there's no
+need to create a custom data collector. Instead, use the `Stopwatch component`_
+which provides utilities to profile code and displays the results on the
+"Performance" panel of the Profiler web interface.
+
+When using :ref:`autowiring <services-autowire>`, type-hint any argument with
+the :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class and Symfony will
+inject the Stopwatch service. Then, use the ``start()``, ``lap()`` and
+``stop()`` methods to measure time::
+
+    // a user signs up and the timer starts...
+    $stopwatch->start('user-sign-up');
+
+    // ...do things to sign up the user...
+    $stopwatch->lap('user-sign-up');
+
+    // ...the sign up process is finished
+    $stopwatch->stop('user-sign-up');
+
+.. tip::
+
+    Consider using a professional profiler such as `Blackfire`_ to measure and
+    analyze the execution of your application in detail.
+
+Enabling the Profiler Conditionally
+-----------------------------------
+
+.. caution::
+
+    The possibility to use a matcher to enable the profiler conditionally was
+    removed in Symfony 4.0.
+
+Symfony Profiler cannot be enabled/disabled conditionally using matchers, because
+that feature was removed in Symfony 4.0. However, you can use the ``enable()``
+and ``disable()`` methods of the :class:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler`
+class in your controllers to manage the profiler programmatically::
+
+    use Symfony\Component\HttpKernel\Profiler\Profiler;
+    // ...
+
+    class DefaultController
+    {
+        // ...
+
+        public function someMethod(?Profiler $profiler)
+        {
+            // $profiler won't be set if your environment doesn't have the profiler (like prod, by default)
+            if (null !== $profiler) {
+                // if it exists, disable the profiler for this particular controller action
+                $profiler->disable();
+            }
+
+            // ...
+        }
+    }
+
+In order for the profiler to be injected into your controller you need to
+create an alias pointing to the existing ``profiler`` service:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services_dev.yaml
+        services:
+            Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler'
+
+    .. code-block:: xml
+
+        <!-- config/services_dev.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="Symfony\Component\HttpKernel\Profiler\Profiler" alias="profiler"/>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services_dev.php
+        use Symfony\Component\HttpKernel\Profiler\Profiler;
+
+        $container->setAlias(Profiler::class, 'profiler');
+
+Updating the Web Debug Toolbar After AJAX Requests
+--------------------------------------------------
+
+`Single-page applications`_ (SPA) are web applications that interact with the
+user by dynamically rewriting the current page rather than loading entire new
+pages from a server.
+
+By default, the debug toolbar displays the information of the initial page load
+and doesn't refresh after each AJAX request. However, you can set the
+``Symfony-Debug-Toolbar-Replace`` header to a value of ``1`` in the response to
+the AJAX request to force the refresh of the toolbar::
+
+    $response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
+
+Ideally this header should only be set during development and not for
+production. To do that, create an :doc:`event subscriber </event_dispatcher>`
+and listen to the :ref:`kernel.response<component-http-kernel-kernel-response>`
+event::
+
+    use Symfony\Component\HttpKernel\Event\ResponseEvent;
+
+    // ...
+
+    public function onKernelResponse(ResponseEvent $event)
+    {
+        if (!$this->getKernel()->isDebug()) {
+            return;
+        }
+
+        $response = $event->getResponse();
+        $response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
+    }
+
 .. toctree::
-    :maxdepth: 1
+    :hidden:
 
     profiler/data_collector
-    profiler/profiling_data
-    profiler/matchers
-    profiler/wdt_follow_ajax
+
+.. _`Single-page applications`: https://en.wikipedia.org/wiki/Single-page_application
+.. _`Stopwatch component`: https://symfony.com/components/Stopwatch
+.. _`Blackfire`: https://blackfire.io/docs/introduction?utm_source=symfony&utm_medium=symfonycom_docs&utm_campaign=profiler
diff --git a/profiler/data_collector.rst b/profiler/data_collector.rst
index e90d8ebed7b..38419cb3edf 100644
--- a/profiler/data_collector.rst
+++ b/profiler/data_collector.rst
@@ -24,9 +24,9 @@ request::
     // src/DataCollector/RequestCollector.php
     namespace App\DataCollector;
 
-    use Symfony\Component\HttpKernel\DataCollector\DataCollector;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\DataCollector\DataCollector;
 
     class RequestCollector extends DataCollector
     {
@@ -248,7 +248,7 @@ to specify a tag that contains the template:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\DataCollector\RequestCollector" public="false">
diff --git a/profiler/matchers.rst b/profiler/matchers.rst
deleted file mode 100644
index ed6ae8afdfd..00000000000
--- a/profiler/matchers.rst
+++ /dev/null
@@ -1,66 +0,0 @@
-.. index::
-    single: Profiling; Matchers
-
-How to Use Matchers to Enable the Profiler Conditionally
-========================================================
-
-.. caution::
-
-    The possibility to use a matcher to enable the profiler conditionally was
-    removed in Symfony 4.0.
-
-Symfony Profiler cannot be enabled/disabled conditionally using matchers, because
-that feature was removed in Symfony 4.0. However, you can use the ``enable()``
-and ``disable()`` methods of the :class:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler`
-class in your controllers to manage the profiler programmatically::
-
-    use Symfony\Component\HttpKernel\Profiler\Profiler;
-    // ...
-
-    class DefaultController
-    {
-        // ...
-
-        public function someMethod(?Profiler $profiler)
-        {
-            // $profiler won't be set if your environment doesn't have the profiler (like prod, by default)
-            if (null !== $profiler) {
-                // if it exists, disable the profiler for this particular controller action
-                $profiler->disable();
-            }
-
-            // ...
-        }
-    }
-
-In order for the profiler to be injected into your controller you need to
-create an alias pointing to the existing ``profiler`` service:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services_dev.yaml
-        services:
-            Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler'
-
-    .. code-block:: xml
-
-        <!-- config/services_dev.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <service id="Symfony\Component\HttpKernel\Profiler\Profiler" alias="profiler" />
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        // config/services_dev.php
-        use Symfony\Component\HttpKernel\Profiler\Profiler;
-
-        $container->setAlias(Profiler::class, 'profiler');
diff --git a/profiler/profiling_data.rst b/profiler/profiling_data.rst
deleted file mode 100644
index 9eab1d91e97..00000000000
--- a/profiler/profiling_data.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-.. index::
-   single: Profiling; Profiling data
-
-How to Access Profiling Data Programmatically
-=============================================
-
-Most of the times, the profiler information is accessed and analyzed using its
-web-based visualizer. However, you can also retrieve profiling information
-programmatically thanks to the methods provided by the ``profiler`` service.
-
-When the response object is available, use the
-:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfileFromResponse`
-method to access to its associated profile::
-
-    // ... $profiler is the 'profiler' service
-    $profile = $profiler->loadProfileFromResponse($response);
-
-When the profiler stores data about a request, it also associates a token with it;
-this token is available in the ``X-Debug-Token`` HTTP header of the response.
-Using this token, you can access the profile of any past response thanks to the
-:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfile` method::
-
-    $token = $response->headers->get('X-Debug-Token');
-    $profile = $profiler->loadProfile($token);
-
-.. tip::
-
-    When the profiler is enabled but not the web debug toolbar, inspect the page
-    with your browser's developer tools to get the value of the ``X-Debug-Token``
-    HTTP header.
-
-The ``profiler`` service also provides the
-:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::find` method to
-look for tokens based on some criteria::
-
-    // gets the latest 10 tokens
-    $tokens = $profiler->find('', '', 10, '', '', '');
-
-    // gets the latest 10 tokens for all URL containing /admin/
-    $tokens = $profiler->find('', '/admin/', 10, '', '', '');
-
-    // gets the latest 10 tokens for local POST requests
-    $tokens = $profiler->find('127.0.0.1', '', 10, 'POST', '', '');
-
-    // gets the latest 10 tokens for requests that happened between 2 and 4 days ago
-    $tokens = $profiler->find('', '', 10, '', '4 days ago', '2 days ago');
diff --git a/profiler/wdt_follow_ajax.rst b/profiler/wdt_follow_ajax.rst
deleted file mode 100644
index 7918d281e54..00000000000
--- a/profiler/wdt_follow_ajax.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-.. index::
-    single: Profiling: WDT Auto-update after AJAX Request
-
-How to Make the Web Debug Toolbar Auto-update After AJAX Requests
-=================================================================
-
-For single page applications it would be more convenient if the toolbar
-showed the information for the most recent AJAX request instead of the
-initial page load.
-
-By setting the ``Symfony-Debug-Toolbar-Replace`` header to a value of ``1`` in the
-AJAX request, the toolbar will be automatically reloaded for the request. The
-header can be set on the response object::
-
-    $response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
-
-Only Setting the Header During Development
--------------------------------------------
-
-Ideally this header should only be set during development and not for
-production. This can be accomplished by setting the header in a
-:ref:`kernel.response <component-http-kernel-kernel-response>` event listener::
-
-    use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
-
-    // ...
-
-    public function onKernelResponse(FilterResponseEvent $event)
-    {
-        $response = $event->getResponse();
-
-        $response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
-    }
-
-.. seealso::
-
-    Read more about :doc:`Symfony events </reference/events>`.
-
-If you are using Symfony Flex, you should define your event listener service in the
-``config/services_dev.yml`` file so that it only exists in the ``dev`` environment.
-
-.. seealso::
-
-    Read more on
-    :doc:`creating dev only services </configuration/configuration_organization>`.
diff --git a/quick_tour/flex_recipes.rst b/quick_tour/flex_recipes.rst
index 1e6bc32ca3c..2fbe73d5d6a 100644
--- a/quick_tour/flex_recipes.rst
+++ b/quick_tour/flex_recipes.rst
@@ -95,11 +95,12 @@ Thanks to Flex, after one command, you can start using Twig immediately:
     +            'name' => $name,
     +        ]);
          }
+    }
 
 By extending ``AbstractController``, you now have access to a number of shortcut
 methods and tools, like ``render()``. Create the new template:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {# templates/default/index.html.twig #}
     <h1>Hello {{ name }}</h1>
@@ -111,7 +112,7 @@ its syntax and power later.
 But, right now, the page *only* contains the ``h1`` tag. To give it an HTML layout,
 extend ``base.html.twig``:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {# templates/default/index.html.twig #}
     {% extends 'base.html.twig' %}
@@ -144,19 +145,19 @@ and performance data!
 Oh, and as you install more libraries, you'll get more tools (like a web debug toolbar
 icon that shows database queries).
 
-You can now directly use the profiler because it configured *itself* thanks to the recipe.
-What else can we install this easily?
+You can now directly use the profiler because it configured *itself* thanks to
+the recipe. What else can we install?
 
 Rich API Support
 ----------------
 
-Are you building an API? You can already return JSON easily from any controller::
+Are you building an API? You can already return JSON from any controller::
 
     // src/Controller/DefaultController.php
     namespace App\Controller;
 
-    use Symfony\Component\Routing\Annotation\Route;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Routing\Annotation\Route;
 
     class DefaultController extends AbstractController
     {
@@ -174,7 +175,7 @@ Are you building an API? You can already return JSON easily from any controller:
         }
     }
 
-But for a *truly* rich API, try installing `Api Platform`_:
+But for a *truly* rich API, try installing `API Platform`_:
 
 .. code-block:: terminal
 
@@ -238,8 +239,10 @@ me? List your routes by running:
      ...
     ------------------------------ -------- -------------------------------------
 
-Easily Remove Recipes
----------------------
+.. _ easily-remove-recipes:
+
+Removing Recipes
+----------------
 
 Not convinced yet? No problem: remove the library:
 
@@ -259,5 +262,5 @@ build features *without* sacrificing code quality or performance. It's all about
 the service container, and it's Symfony's super power. Read on: about :doc:`/quick_tour/the_architecture`.
 
 .. _`https://flex.symfony.com`: https://flex.symfony.com
-.. _`Api Platform`: https://api-platform.com/
+.. _`API Platform`: https://api-platform.com/
 .. _`Twig`: https://twig.symfony.com/
diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst
index ae4487ca97c..19d77648f7d 100644
--- a/quick_tour/the_architecture.rst
+++ b/quick_tour/the_architecture.rst
@@ -25,8 +25,8 @@ use the logger in a controller, add a new argument type-hinted with ``LoggerInte
     namespace App\Controller;
 
     use Psr\Log\LoggerInterface;
-    use Symfony\Component\Routing\Annotation\Route;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Routing\Annotation\Route;
 
     class DefaultController extends AbstractController
     {
@@ -63,16 +63,21 @@ What other possible classes or interfaces could you use? Find out by running:
 
     $ php bin/console debug:autowiring
 
-=============================================================== =====================================
-Class/Interface Type                                            Alias Service ID
-=============================================================== =====================================
-``Psr\Cache\CacheItemPoolInterface``                            alias for "cache.app.recorder"
-``Psr\Log\LoggerInterface``                                     alias for "monolog.logger"
-``Symfony\Component\EventDispatcher\EventDispatcherInterface``  alias for "debug.event_dispatcher"
-``Symfony\Component\HttpFoundation\RequestStack``               alias for "request_stack"
-``Symfony\Component\HttpFoundation\Session\SessionInterface``   alias for "session"
-``Symfony\Component\Routing\RouterInterface``                   alias for "router.default"
-=============================================================== =====================================
+      # this is just a *small* sample of the output...
+
+      Describes a logger instance.
+      Psr\Log\LoggerInterface (monolog.logger)
+
+      Request stack that controls the lifecycle of requests.
+      Symfony\Component\HttpFoundation\RequestStack (request_stack)
+
+      Interface for the session.
+      Symfony\Component\HttpFoundation\Session\SessionInterface (session)
+
+      RouterInterface is the interface that all Router classes must implement.
+      Symfony\Component\Routing\RouterInterface (router.default)
+
+      [...]
 
 This is just a short summary of the full list! And as you add more packages, this
 list of tools will grow!
@@ -105,8 +110,8 @@ Great! You can use this immediately in your controller::
 
     use App\GreetingGenerator;
     use Psr\Log\LoggerInterface;
-    use Symfony\Component\Routing\Annotation\Route;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Routing\Annotation\Route;
 
     class DefaultController extends AbstractController
     {
@@ -195,7 +200,7 @@ that extends ``AbstractExtension``::
 
 After creating just *one* file, you can use this immediately:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {# templates/default/index.html.twig #}
     {# Will print something like "Hey Symfony!" #}
diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
index 9f6c3ae8f38..7ec7f08ac51 100644
--- a/quick_tour/the_big_picture.rst
+++ b/quick_tour/the_big_picture.rst
@@ -39,15 +39,15 @@ Symfony application:
     ├─ var/
     └─ vendor/
 
-Can we already load the project in a browser? Of course! You can setup
-:doc:`Nginx or Apache </setup/web_server_configuration>` and configure their document
-root to be the ``public/`` directory. But, for development, Symfony has its own server.
-Install and run it with:
+Can we already load the project in a browser? Yes! You can setup
+:doc:`Nginx or Apache </setup/web_server_configuration>` and configure their
+document root to be the ``public/`` directory. But, for development, it's better
+to :doc:`install the Symfony local web server </setup/symfony_server>` and run
+it as follows:
 
 .. code-block:: terminal
 
-    $ composer require server --dev
-    $ php bin/console server:start
+    $ symfony server:start
 
 Try your new app by going to ``http://localhost:8000`` in a browser!
 
diff --git a/reference/configuration/debug.rst b/reference/configuration/debug.rst
index d7eb5a4a199..6732459f3c3 100644
--- a/reference/configuration/debug.rst
+++ b/reference/configuration/debug.rst
@@ -20,7 +20,7 @@ key in your application configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/debug``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/debug/debug-1.0.xsd``
+    ``https://symfony.com/schema/dic/debug/debug-1.0.xsd``
 
 Configuration
 -------------
@@ -77,7 +77,7 @@ destination for dumps. Typically, you would set this to ``php://stderr``:
 
         # config/packages/debug.yaml
         debug:
-           dump_destination: php://stderr
+            dump_destination: php://stderr
 
     .. code-block:: xml
 
@@ -87,17 +87,17 @@ destination for dumps. Typically, you would set this to ``php://stderr``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:debug="http://symfony.com/schema/dic/debug"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/debug http://symfony.com/schema/dic/debug/debug-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/debug https://symfony.com/schema/dic/debug/debug-1.0.xsd">
 
-            <debug:config dump-destination="php://stderr" />
+            <debug:config dump-destination="php://stderr"/>
         </container>
 
     .. code-block:: php
 
         // config/packages/debug.php
         $container->loadFromExtension('debug', [
-           'dump_destination' => 'php://stderr',
+            'dump_destination' => 'php://stderr',
         ]);
 
 Configure it to ``"tcp://%env(VAR_DUMPER_SERVER)%"`` in order to use the :ref:`ServerDumper feature <var-dumper-dump-server>`.
diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst
index cbbfff5fb8c..7600f1f07a7 100644
--- a/reference/configuration/doctrine.rst
+++ b/reference/configuration/doctrine.rst
@@ -22,7 +22,7 @@ configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/doctrine``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd``
+    ``https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd``
 
 .. index::
     single: Configuration; Doctrine DBAL
@@ -78,9 +78,9 @@ The following block shows all possible configuration keys:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/doctrine
-                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:dbal
@@ -116,10 +116,10 @@ The following block shows all possible configuration keys:
     to find your PostgreSQL version and ``mysql -V`` to get your MySQL
     version).
 
-    If you are running a MariaDB database, you must prefix the ``server_version``
+    If you are running a MariaDB database, you must prefix the ``server_version``
     value with ``mariadb-`` (e.g. ``server_version: mariadb-10.2.12``).
 
-    Always wrap the server version number with quotes to parse it as a string
+    Always wrap the server version number with quotes to parse it as a string
     instead of a float number. Otherwise, the floating-point representation
     issues can make your version be considered a different number (e.g. ``5.6``
     will be rounded as ``5.5999999999999996447286321199499070644378662109375``).
@@ -157,8 +157,6 @@ which is the first one defined or the one configured via the
 Each connection is also accessible via the ``doctrine.dbal.[name]_connection``
 service where ``[name]`` is the name of the connection.
 
-.. _DBAL documentation: http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html
-
 Doctrine ORM Configuration
 --------------------------
 
@@ -194,7 +192,7 @@ can be placed directly under ``doctrine.orm`` config level.
         orm:
             # ...
             query_cache_driver:
-               # ...
+                # ...
             metadata_cache_driver:
                 # ...
             result_cache_driver:
@@ -321,11 +319,11 @@ directory instead:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:orm auto-mapping="true">
-                    <mapping name="AppBundle" dir="SomeResources/config/doctrine" type="xml" />
+                    <mapping name="AppBundle" dir="SomeResources/config/doctrine" type="xml"/>
                 </doctrine:orm>
             </doctrine:config>
         </container>
@@ -372,7 +370,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:orm>
@@ -436,4 +434,4 @@ If the ``dir`` configuration is set and the ``is_bundle`` configuration
 is ``true``, the DoctrineBundle will prefix the ``dir`` configuration with
 the path of the bundle.
 
-.. _`DQL User Defined Functions`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/dql-user-defined-functions.html
+.. _DBAL documentation: https://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
index be438427e1a..69962b39488 100644
--- a/reference/configuration/framework.rst
+++ b/reference/configuration/framework.rst
@@ -22,7 +22,7 @@ configured under the ``framework`` key in your application configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/symfony``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/symfony/symfony-1.0.xsd``
+    ``https://symfony.com/schema/dic/symfony/symfony-1.0.xsd``
 
 Configuration
 -------------
@@ -50,6 +50,7 @@ Configuration
   * :ref:`app <reference-cache-app>`
   * `default_doctrine_provider`_
   * `default_memcached_provider`_
+  * `default_pdo_provider`_
   * `default_psr6_provider`_
   * `default_redis_provider`_
   * `directory`_
@@ -72,6 +73,7 @@ Configuration
   * :ref:`enabled <reference-csrf_protection-enabled>`
 
 * `default_locale`_
+* `disallow_search_engine_index`_
 * `esi`_
 
   * :ref:`enabled <reference-esi-enabled>`
@@ -83,8 +85,57 @@ Configuration
 * `fragments`_
 
   * :ref:`enabled <reference-fragments-enabled>`
+  * `hinclude_default_template`_
   * :ref:`path <reference-fragments-path>`
 
+* `http_client`_
+
+  * :ref:`default_options <reference-http-client-default-options>`
+
+    * `bindto`_
+    * `cafile`_
+    * `capath`_
+    * `ciphers`_
+    * `headers`_
+    * `http_version`_
+    * `local_cert`_
+    * `local_pk`_
+    * `max_redirects`_
+    * `no_proxy`_
+    * `passphrase`_
+    * `peer_fingerprint`_
+    * `proxy`_
+    * `resolve`_
+    * `timeout`_
+    * `verify_host`_
+    * `verify_peer`_
+
+  * `max_host_connections`_
+  * :ref:`scoped_clients <reference-http-client-scoped-clients>`
+
+    * `scope`_
+    * `auth_basic`_
+    * `auth_bearer`_
+    * `base_uri`_
+    * `bindto`_
+    * `cafile`_
+    * `capath`_
+    * `ciphers`_
+    * `headers`_
+    * `http_version`_
+    * `local_cert`_
+    * `local_pk`_
+    * `max_redirects`_
+    * `no_proxy`_
+    * `passphrase`_
+    * `peer_fingerprint`_
+    * `proxy`_
+    * `query`_
+    * `resolve`_
+    * `timeout`_
+    * `verify_host`_
+    * `verify_peer`_
+
 * `http_method_override`_
 * `ide`_
 * :ref:`lock <reference-lock>`
@@ -105,6 +156,7 @@ Configuration
 
   * `magic_call`_
   * `throw_exception_on_invalid_index`_
+  * `throw_exception_on_invalid_property_path`_
 
 * `property_info`_
 
@@ -120,7 +172,8 @@ Configuration
   * `https_port`_
   * `resource`_
   * `strict_requirements`_
-  * `type`_
+  * :ref:`type <reference-router-type>`
+  * `utf8`_
 
 * `secret`_
 * `serializer`_
@@ -136,10 +189,12 @@ Configuration
 
 * `session`_
 
+  * `cache_limiter`_
   * `cookie_domain`_
   * `cookie_httponly`_
   * `cookie_lifetime`_
   * `cookie_path`_
+  * `cookie_samesite`_
   * `cookie_secure`_
   * :ref:`enabled <reference-session-enabled>`
   * `gc_divisor`_
@@ -149,7 +204,10 @@ Configuration
   * `metadata_update_threshold`_
   * `name`_
   * `save_path`_
+  * `sid_length`_
+  * `sid_bits_per_character`_
   * `storage_id`_
+  * `use_cookies`_
 
 * `templating`_
 
@@ -159,7 +217,6 @@ Configuration
 
     * `resources`_
 
-  * `hinclude_default_template`_
   * `loaders`_
 
 * `test`_
@@ -183,9 +240,30 @@ Configuration
 
     * :ref:`paths <reference-validation-mapping-paths>`
 
+  * :ref:`not_compromised_password <reference-validation-not-compromised-password>`
+
+    * :ref:`enabled <reference-validation-not-compromised-password-enabled>`
+    * `endpoint`_
+
+  * `static_method`_
   * `strict_email`_
   * `translation_domain`_
 
+* `workflows`_
+
+  * :ref:`enabled <reference-workflows-enabled>`
+  * :ref:`name <reference-workflows-name>`
+
+    * `audit_trail`_
+    * `initial_marking`_
+    * `marking_store`_
+    * `metadata`_
+    * `places`_
+    * `supports`_
+    * `support_strategy`_
+    * `transitions`_
+    * :ref:`type <reference-workflows-type>`
+
 secret
 ~~~~~~
 
@@ -225,7 +303,8 @@ named ``kernel.http_method_override``.
 
 .. seealso::
 
-    For more information, see :doc:`/form/action_method`.
+    :ref:`Changing the Action and HTTP Method <forms-change-action-method>` of
+    Symfony forms.
 
 .. caution::
 
@@ -260,8 +339,8 @@ ide
 Symfony turns file paths seen in variable dumps and exception messages into
 links that open those files right inside your browser. If you prefer to open
 those files in your favorite IDE or text editor, set this option to any of the
-following values: ``phpstorm``, ``sublime``, ``textmate``, ``macvim``, ``emacs``
-and ``atom``.
+following values: ``phpstorm``, ``sublime``, ``textmate``, ``macvim``, ``emacs``,
+``atom`` and ``vscode``.
 
 .. note::
 
@@ -289,10 +368,10 @@ doubling them to prevent Symfony from interpreting them as container parameters)
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
-            <framework:config ide="myide://open?url=file://%%f&line=%%l" />
+            <framework:config ide="myide://open?url=file://%%f&line=%%l"/>
         </container>
 
     .. code-block:: php
@@ -327,8 +406,11 @@ need to escape the percent signs (``%``) by doubling them.
 
         // /path/to/guest/.../file will be opened
         // as /path/to/host/.../file on the host
-        // and /foo/.../file as /bar/.../file also
-        'myide://%f:%l&/path/to/guest/>/path/to/host/&/foo/>/bar/&...'
+        // and /var/www/app/ as /projects/my_project/ also
+        'myide://%%f:%%l&/path/to/guest/>/path/to/host/&/var/www/app/>/projects/my_project/&...'
+
+        // example for PhpStorm
+        'phpstorm://open?file=%%f&line=%%l&/var/www/app/>/projects/my_project/'
 
 .. _reference-framework-test:
 
@@ -363,6 +445,21 @@ method.
     You can read more information about the default locale in
     :ref:`translation-default-locale`.
 
+disallow_search_engine_index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true`` when the debug mode is enabled, ``false`` otherwise.
+
+.. versionadded:: 4.3
+
+    The ``disallow_search_engine_index`` option was introduced in Symfony 4.3.
+
+If ``true``, Symfony adds a ``X-Robots-Tag: noindex`` HTTP tag to all responses
+(unless your own app adds that header, in which case it's not modified). This
+`X-Robots-Tag HTTP header`_ tells search engines to not index your web site.
+This option is a protection measure in case you accidentally publish your site
+in debug mode.
+
 trusted_hosts
 ~~~~~~~~~~~~~
 
@@ -403,8 +500,8 @@ the application won't respond and the user will receive a 400 response.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:trusted-host>^example\.com$</framework:trusted-host>
@@ -520,11 +617,11 @@ You can also set ``esi`` to ``true`` to enable it:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:esi />
+                <framework:esi/>
             </framework:config>
         </container>
 
@@ -556,6 +653,24 @@ used to render ESI fragments independently of the rest of the page.
 This setting is automatically set to ``true`` when one of the child settings
 is configured.
 
+hinclude_default_template
+.........................
+
+**type**: ``string`` **default**: ``null``
+
+.. versionadded:: 4.3
+
+    The ``framework.fragments.hinclude_default_template`` option was introduced
+    in Symfony 4.3. In previous Symfony versions it was defined under
+    ``framework.templating.hinclude_default_template``.
+
+Sets the content shown during the loading of the fragment or when JavaScript
+is disabled. This can be either a template name or the content itself.
+
+.. seealso::
+
+    See :doc:`/templating/hinclude` for more information about hinclude.
+
 .. _reference-fragments-path:
 
 path
@@ -566,6 +681,277 @@ path
 The path prefix for fragments. The fragment listener will only be executed
 when the request starts with this path.
 
+.. _reference-http-client:
+
+http_client
+~~~~~~~~~~~
+
+When the HttpClient component is installed, an HTTP client is available
+as a service named ``http_client`` or using the autowiring alias
+:class:`Symfony\\Contracts\\HttpClient\\HttpClientInterface`.
+
+.. _reference-http-client-default-options:
+
+This service can be configured using ``framework.http_client.default_options``:
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        # ...
+        http_client:
+            max_host_connections: 10
+            default_options:
+                headers: { 'X-Powered-By': 'ACME App' }
+                max_redirects: 7
+
+.. _reference-http-client-scoped-clients:
+
+Multiple pre-configured HTTP client services can be defined, each with its
+service name defined as a key under ``scoped_clients``. Scoped clients inherit
+the default options defined for the ``http_client`` service. You can override
+these options and can define a few others:
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        # ...
+        http_client:
+            scoped_clients:
+                my_api.client:
+                    auth_bearer: secret_bearer_token
+                    # ...
+
+Options defined for scoped clients apply only to URLs that match either their
+`base_uri`_ or the `scope`_ option when it is defined. Non-matching URLs always
+use default options.
+
+Each scoped client also defines a corresponding named autowiring alias.
+If you use for example
+``Symfony\Contracts\HttpClient\HttpClientInterface $myApiClient``
+as the type and name of an argument, autowiring will inject the ``my_api.client``
+service into your autowired classes.
+
+auth_basic
+..........
+
+**type**: ``string``
+
+The username and password used to create the ``Authorization`` HTTP header
+used in HTTP Basic authentication. The value of this option must follow the
+format ``username:password``.
+
+auth_bearer
+...........
+
+**type**: ``string``
+
+The token used to create the ``Authorization`` HTTP header used in HTTP Bearer
+authentication (also called token authentication).
+
+base_uri
+........
+
+**type**: ``string``
+
+URI that is merged into relative URIs, following the rules explained in the
+`RFC 3986`_ standard. This is useful when all the requests you make share a
+common prefix (e.g. ``https://api.github.com/``) so you can avoid adding it to
+every request.
+
+Here are some common examples of how ``base_uri`` merging works in practice:
+
+===================  ==============  ======================
+``base_uri``         Relative URI    Actual Requested URI
+===================  ==============  ======================
+http://foo.com       /bar            http://foo.com/bar
+http://foo.com/foo   /bar            http://foo.com/bar
+http://foo.com/foo   bar             http://foo.com/bar
+http://foo.com/foo/  bar             http://foo.com/foo/bar
+http://foo.com       http://baz.com  http://baz.com
+http://foo.com/?bar  bar             http://foo.com/bar
+===================  ==============  ======================
+
+bindto
+......
+
+**type**: ``string``
+
+A network interface name, IP address, a host name or a UNIX socket to use as the
+outgoing network interface.
+
+cafile
+......
+
+**type**: ``string``
+
+The path of the certificate authority file that contains one or more
+certificates used to verify the other servers' certificates.
+
+capath
+......
+
+**type**: ``string``
+
+The path to a directory that contains one or more certificate authority files.
+
+ciphers
+.......
+
+**type**: ``string``
+
+A list of the names of the ciphers allowed for the SSL/TLS connections. They
+can be separated by colons, commas or spaces (e.g. ``'RC4-SHA:TLS13-AES-128-GCM-SHA256'``).
+
+headers
+.......
+
+**type**: ``array``
+
+An associative array of the HTTP headers added before making the request. This
+value must use the format ``['header-name' => header-value, ...]``.
+
+http_version
+............
+
+**type**: ``string`` | ``null`` **default**: ``null``
+
+The HTTP version to use, typically ``'1.1'``  or ``'2.0'``. Leave it to ``null``
+to let Symfony select the best version automatically.
+
+local_cert
+..........
+
+**type**: ``string``
+
+The path to a file that contains the `PEM formatted`_ certificate used by the
+HTTP client. This is often combined with the ``local_pk`` and ``passphrase``
+options.
+
+local_pk
+........
+
+**type**: ``string``
+
+The path of a file that contains the `PEM formatted`_ private key of the
+certificate defined in the ``local_cert`` option.
+
+max_host_connections
+....................
+
+**type**: ``integer`` **default**: ``6``
+
+Defines the maximum amount of simultaneously open connections to a single host
+(considering a "host" the same as a "host name + port number" pair). This limit
+also applies for proxy connections, where the proxy is considered to be the host
+for which this limit is applied.
+
+max_redirects
+.............
+
+**type**: ``integer`` **default**: ``20``
+
+The maximum number of redirects to follow. Use ``0`` to not follow any
+redirection.
+
+no_proxy
+........
+
+**type**: ``string`` | ``null`` **default**: ``null``
+
+A comma separated list of hosts that do not require a proxy to be reached, even
+if one is configured. Use the ``'*'`` wildcard to match all hosts and an empty
+string to match none (disables the proxy).
+
+passphrase
+..........
+
+**type**: ``string``
+
+The passphrase used to encrypt the certificate stored in the file defined in the
+``local_cert`` option.
+
+peer_fingerprint
+................
+
+**type**: ``array``
+
+When negotiating a TLS or SSL connection, the server sends a certificate
+indicating its identity. A public key is extracted from this certificate and if
+it does not exactly match any of the public keys provided in this option, the
+connection is aborted before sending or receiving any data.
+
+The value of this option is an associative array of ``algorithm => hash``
+(e.g ``['pin-sha256' => '...']``).
+
+proxy
+.....
+
+**type**: ``string`` | ``null``
+
+The HTTP proxy to use to make the requests. Leave it to ``null`` to detect the
+proxy automatically based on your system configuration.
+
+query
+.....
+
+**type**: ``array``
+
+An associative array of the query string values added to the URL before making
+the request. This value must use the format ``['parameter-name' => parameter-value, ...]``.
+
+resolve
+.......
+
+**type**: ``array``
+
+A list of hostnames and their IP addresses to pre-populate the DNS cache used by
+the HTTP client in order to avoid a DNS lookup for those hosts. This option is
+useful to improve security when IPs are checked before the URL is passed to the
+client and to make your tests easier.
+
+The value of this option is an associative array of ``domain => IP address``
+(e.g ``['symfony.com' => '46.137.106.254', ...]``).
+
+scope
+.....
+
+**type**: ``string``
+
+For scoped clients only: the regular expression that the URL must match before
+applying all other non-default options. By default, the scope is derived from
+`base_uri`_.
+
+timeout
+.......
+
+**type**: ``float`` **default**: depends on your PHP config
+
+Time, in seconds, to wait for a response. If the response stales for longer, a
+:class:`Symfony\\Component\\HttpClient\\Exception\\TransportException` is thrown.
+Its default value is the same as the value of PHP's `default_socket_timeout`_
+config option.
+
+verify_host
+...........
+
+**type**: ``boolean``
+
+If ``true``, the certificate sent by other servers is verified to ensure that
+their common name matches the host included in the URL. This is usually
+combined with ``verify_peer`` to also verify the certificate authenticity.
+
+verify_peer
+...........
+
+**type**: ``boolean``
+
+If ``true``, the certificate sent by other servers when negotiating a TLS or SSL
+connection is verified for authenticity. Authenticating the certificate is not
+enough to be sure about the server, so you should combine this with the
+``verify_host`` option.
+
 profiler
 ~~~~~~~~
 
@@ -660,9 +1046,9 @@ To configure a ``jsonp`` format:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:request>
@@ -695,6 +1081,8 @@ resource
 The path the main routing resource (e.g. a YAML file) that contains the
 routes and imports the router should load.
 
+.. _reference-router-type:
+
 type
 ....
 
@@ -702,7 +1090,7 @@ type
 
 The type of the resource to hint the loaders about the format. This isn't
 needed when you use the default routers with the expected file extensions
-(``.xml``, ``.yml`` or ``.yaml``, ``.php``).
+(``.xml``, ``.yaml``, ``.php``).
 
 http_port
 .........
@@ -723,8 +1111,8 @@ strict_requirements
 
 **type**: ``mixed`` **default**: ``true``
 
-Determines the routing generator behaviour. When generating a route that
-has specific :doc:`requirements </routing/requirements>`, the generator
+Determines the routing generator behavior. When generating a route that
+has specific :ref:`parameter requirements <routing-requirements>`, the generator
 can behave differently in case the used parameters do not meet these requirements.
 
 The value can be one of:
@@ -741,6 +1129,17 @@ The value can be one of:
 ``true`` is recommended in the development environment, while ``false``
 or ``null`` might be preferred in production.
 
+utf8
+....
+
+**type**: ``boolean`` **default**: ``false``
+
+When this option is set to ``true``, route patterns can include UTF-8 characters.
+If the charset of your application is UTF-8 (as defined in the
+:ref:`getCharset() method <configuration-kernel-charset>` of your kernel) it's
+recommended to set it to ``true``. This will make non-UTF8 URLs to generate 404
+errors.
+
 .. _config-framework-session:
 
 session
@@ -758,18 +1157,15 @@ alias will be set to this service id. This class has to implement
 handler_id
 ..........
 
-**type**: ``string`` **default**: ``'session.handler.native_file'``
-
-The service id used for session storage. The ``session.handler`` service
-alias will be set to this service id.
-
-You can also set it to ``null``, to default to the handler of your PHP
-installation.
+**type**: ``string`` **default**: ``null``
 
-.. seealso::
+The service id used for session storage. The default ``null`` value means to use
+the native PHP session mechanism. Set it to ``'session.handler.native_file'`` to
+let Symfony manage the sessions itself using files to store the session
+metadata.
 
-    You can see an example of the usage of this in
-    :doc:`/doctrine/pdo_session_storage`.
+If you prefer to make Symfony store sessions in a database read
+:doc:`/doctrine/pdo_session_storage`.
 
 .. _name:
 
@@ -778,7 +1174,7 @@ name
 
 **type**: ``string`` **default**: ``null``
 
-This specifies the name of the session cookie. By default it will use the
+This specifies the name of the session cookie. By default, it will use the
 cookie name which is defined in the ``php.ini`` with the ``session.name``
 directive.
 
@@ -797,24 +1193,101 @@ cookie_path
 
 **type**: ``string`` **default**: ``/``
 
-This determines the path to set in the session cookie. By default it will
+This determines the path to set in the session cookie. By default, it will
 use ``/``.
 
+cache_limiter
+.............
+
+**type**: ``string`` or ``int`` **default**: ``''``
+
+If set to ``0``, Symfony won't set any particular header related to the cache
+and it will rely on the cache control method configured in the
+`session.cache-limiter`_ PHP.ini option.
+
+Unlike the other session options, ``cache_limiter`` is set as a regular
+:ref:`container parameter <configuration-parameters>`:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        parameters:
+            session.storage.options:
+                cache_limiter: 0
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <parameters>
+                <parameter key="session.storage.options" type="collection">
+                    <parameter key="cache_limiter">0</parameter>
+                </parameter>
+            </parameters>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        $container->setParameter('session.storage.options', [
+            'cache_limiter' => 0,
+        ]);
+
 cookie_domain
 .............
 
 **type**: ``string`` **default**: ``''``
 
-This determines the domain to set in the session cookie. By default it's
+This determines the domain to set in the session cookie. By default, it's
 blank, meaning the host name of the server which generated the cookie according
 to the cookie specification.
 
+cookie_samesite
+...............
+
+**type**: ``string`` or ``null`` **default**: ``null``
+
+It controls the way cookies are sent when the HTTP request was not originated
+from the same domain the cookies are associated to. Setting this option is
+recommended to mitigate `CSRF security attacks`_.
+
+By default, browsers send all cookies related to the domain of the HTTP request.
+This may be a problem for example when you visit a forum and some malicious
+comment includes a link like ``https://some-bank.com/?send_money_to=attacker&amount=1000``.
+If you were previously logged into your bank website, the browser will send all
+those cookies when making that HTTP request.
+
+The possible values for this option are:
+
+* ``null``, use it to disable this protection. Same behavior as in older Symfony
+  versions.
+* ``'strict'`` (or the ``Cookie::SAMESITE_STRICT`` constant), use it to never
+  send any cookie when the HTTP request is not originated from the same domain.
+* ``'lax'`` (or the ``Cookie::SAMESITE_LAX`` constant), use it to allow sending
+  cookies when the request originated from a different domain, but only when the
+  user consciously made the request (by clicking a link or submitting a form
+  with the ``GET`` method).
+
+.. note::
+
+    This option is available starting from PHP 7.3, but Symfony has a polyfill
+    so you can use it with any older PHP version as well.
+
 cookie_secure
 .............
 
-**type**: ``boolean`` **default**: ``false``
+**type**: ``boolean`` or ``string`` **default**: ``false``
 
-This determines whether cookies should only be sent over secure connections.
+This determines whether cookies should only be sent over secure connections. In
+addition to ``true`` and ``false``, there's a special ``'auto'`` value that
+means ``true`` for HTTPS requests and ``false`` for HTTP requests.
 
 cookie_httponly
 ...............
@@ -852,6 +1325,29 @@ This determines the number of seconds after which data will be seen as "garbage"
 and potentially cleaned up. Garbage collection may occur during session
 start and depends on `gc_divisor`_ and `gc_probability`_.
 
+sid_length
+..........
+
+**type**: ``integer`` **default**: ``32``
+
+This determines the length of session ID string, which can be an integer between
+``22`` and ``256`` (both inclusive), being ``32`` the recommended value. Longer
+session IDs are harder to guess.
+
+This option is related to the `session.sid_length PHP option`_.
+
+sid_bits_per_character
+......................
+
+**type**: ``integer`` **default**: ``4``
+
+This determines the number of bits in encoded session ID character. The possible
+values are ``4`` (0-9, a-f), ``5`` (0-9, a-v), and ``6`` (0-9, a-z, A-Z, "-", ",").
+The more bits results in stronger session ID. ``5`` is recommended value for
+most environments.
+
+This option is related to the `session.sid_bits_per_character PHP option`_.
+
 save_path
 .........
 
@@ -859,7 +1355,6 @@ save_path
 
 This determines the argument to be passed to the save handler. If you choose
 the default file handler, this is the path where the session files are created.
-For more information, see :doc:`/session/sessions_directory`.
 
 You can also set this value to the ``save_path`` of your ``php.ini`` by
 setting the value to ``null``:
@@ -881,11 +1376,11 @@ setting the value to ``null``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:session save-path="null" />
+                <framework:session save-path="null"/>
             </framework:config>
         </container>
 
@@ -938,11 +1433,11 @@ Whether to enable the session support in the framework.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:session enabled="true" />
+                <framework:session enabled="true"/>
             </framework:config>
         </container>
 
@@ -955,6 +1450,15 @@ Whether to enable the session support in the framework.
             ],
         ]);
 
+use_cookies
+...........
+
+**type**: ``boolean`` **default**: ``null``
+
+This specifies if the session ID is stored on the client side using cookies or
+not. By default, it will use the value defined in the ``php.ini`` with the
+``session.use_cookies`` directive.
+
 assets
 ~~~~~~
 
@@ -985,11 +1489,11 @@ This option allows you to define a base path to be used for assets:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:assets base-path="/images" />
+                <framework:assets base-path="/images"/>
             </framework:config>
         </container>
 
@@ -1034,11 +1538,11 @@ collection each time it generates an asset's path:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:assets base-url="http://cdn.example.com/" />
+                <framework:assets base-url="http://cdn.example.com/"/>
             </framework:config>
         </container>
 
@@ -1079,14 +1583,14 @@ You can group assets into packages, to specify different base URLs for them:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:assets>
                     <framework:package
                         name="avatars"
-                        base-url="http://static_cdn.example.com/avatars" />
+                        base-url="http://static_cdn.example.com/avatars"/>
                 </framework:assets>
             </framework:config>
         </container>
@@ -1137,7 +1641,7 @@ For example, suppose you have the following:
 
 .. code-block:: html+twig
 
-    <img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
+    <img src="{{ asset('images/logo.png') }}" alt="Symfony!"/>
 
 By default, this will render a path to your image such as ``/images/logo.png``.
 Now, activate the ``version`` option:
@@ -1160,11 +1664,11 @@ Now, activate the ``version`` option:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:assets version="v2" />
+                <framework:assets version="v2"/>
             </framework:config>
         </container>
 
@@ -1252,7 +1756,7 @@ individually for each asset package:
     .. code-block:: yaml
 
         # config/packages/framework.yaml
-       framework:
+        framework:
             assets:
                 # this strategy is applied to every asset (including packages)
                 version_strategy: 'app.asset.my_versioning_strategy'
@@ -1274,23 +1778,23 @@ individually for each asset package:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:assets version-strategy="app.asset.my_versioning_strategy">
                     <!-- this package removes any versioning (its assets won't be versioned) -->
                     <framework:package
                         name="foo_package"
-                        version="null" />
+                        version="null"/>
                     <!-- this package uses its own strategy (the default strategy is ignored) -->
                     <framework:package
                         name="bar_package"
-                        version-strategy="app.asset.another_version_strategy" />
+                        version-strategy="app.asset.another_version_strategy"/>
                     <!-- this package inherits the default strategy -->
                     <framework:package
                         name="baz_package"
-                        base_path="/images" />
+                        base_path="/images"/>
                 </framework:assets>
             </framework:config>
         </container>
@@ -1350,7 +1854,7 @@ package:
     .. code-block:: yaml
 
         # config/packages/framework.yaml
-       framework:
+        framework:
             assets:
                 # this manifest is applied to every asset (including packages)
                 json_manifest_path: "%kernel.project_dir%/public/build/manifest.json"
@@ -1369,8 +1873,8 @@ package:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <!-- this manifest is applied to every asset (including packages) -->
@@ -1378,11 +1882,11 @@ package:
                     <!-- this package uses its own manifest (the default file is ignored) -->
                     <framework:package
                         name="foo_package"
-                        json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json" />
+                        json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json"/>
                     <!-- this package uses the global manifest (the default file is used) -->
                     <framework:package
                         name="bar_package"
-                        base-path="/images" />
+                        base-path="/images"/>
                 </framework:assets>
             </framework:config>
         </container>
@@ -1421,17 +1925,11 @@ package:
 templating
 ~~~~~~~~~~
 
-hinclude_default_template
-.........................
-
-**type**: ``string`` **default**: ``null``
-
-Sets the content shown during the loading of the fragment or when JavaScript
-is disabled. This can be either a template name or the content itself.
-
-.. seealso::
+.. deprecated:: 4.3
 
-    See :doc:`/templating/hinclude` for more information about hinclude.
+    The integration of the Templating component in FrameworkBundle has been
+    deprecated since version 4.3 and will be removed in 5.0. That's why all the
+    configuration options defined under ``framework.templating`` are deprecated too.
 
 .. _reference-templating-form:
 
@@ -1443,6 +1941,12 @@ resources
 
 **type**: ``string[]`` **default**: ``['FrameworkBundle:Form']``
 
+.. deprecated:: 4.3
+
+    The integration of the Templating component in FrameworkBundle has been
+    deprecated since version 4.3 and will be removed in 5.0. Form theming with
+    PHP templates will no longer be supported and you'll need to use Twig instead.
+
 A list of all resources for form theming in PHP. This setting is not required
 if you're :ref:`using the Twig format for your themes <forms-theming-twig>`.
 
@@ -1468,8 +1972,8 @@ configure this like:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:templating>
@@ -1615,6 +2119,18 @@ throw_exception_on_invalid_index
 When enabled, the ``property_accessor`` service throws an exception when you
 try to access an invalid index of an array.
 
+throw_exception_on_invalid_property_path
+........................................
+
+**type**: ``boolean`` **default**: ``true``
+
+.. versionadded:: 4.3
+
+    The ``throw_exception_on_invalid_property_path`` option was introduced in Symfony 4.3.
+
+When enabled, the ``property_accessor`` service throws an exception when you
+try to access an invalid property path of an object.
+
 property_info
 ~~~~~~~~~~~~~
 
@@ -1670,12 +2186,63 @@ translation_domain
 The translation domain that is used when translating validation constraint
 error messages.
 
+.. _reference-validation-not-compromised-password:
+
+not_compromised_password
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`
+constraint makes HTTP requests to a public API to check if the given password
+has been compromised in a data breach.
+
+.. _reference-validation-not-compromised-password-enabled:
+
+enabled
+.......
+
+**type**: ``boolean`` **default**: ``true``
+
+.. versionadded:: 4.3
+
+    The ``enabled`` option was introduced in Symfony 4.3.
+
+If you set this option to ``false``, no HTTP requests will be made and the given
+password will be considered valid. This is useful when you don't want or can't
+make HTTP requests, such as in ``dev`` and ``test`` environments or in
+continuous integration servers.
+
+endpoint
+........
+
+**type**: ``string`` **default**: ``null``
+
+.. versionadded:: 4.3
+
+    The ``endpoint`` option was introduced in Symfony 4.3.
+
+By default, the :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`
+constraint uses the public API provided by `haveibeenpwned.com`_. This option
+allows to define a different, but compatible, API endpoint to make the password
+checks. It's useful for example when the Symfony application is run in an
+intranet without public access to Internet.
+
+static_method
+.............
+
+**type**: ``string | array`` **default**: ``['loadValidatorMetadata']``
+
+Defines the name of the static method which is called to load the validation
+metadata of the class. You can define an array of strings with the names of
+several methods. In that case, all of them will be called in that order to load
+the metadata.
+
 strict_email
 ............
 
 **type**: ``Boolean`` **default**: ``false``
 
-.. versionadded:: 4.1
+.. deprecated:: 4.1
+
     The ``strict_email`` option was deprecated in Symfony 4.1. Use the new
     ``email_validation_mode`` option instead.
 
@@ -1688,9 +2255,6 @@ email_validation_mode
 
 **type**: ``string`` **default**: ``loose``
 
-.. versionadded:: 4.1
-    The ``email_validation_mode`` option was introduced in Symfony 4.1.
-
 It controls the way email addresses are validated by the
 :doc:`/reference/constraints/Email` validator. The possible values are:
 
@@ -1843,9 +2407,6 @@ Use the application logger instead of the PHP logger for logging PHP errors.
 When an integer value is used, it also sets the log level. Those integer
 values must be the same used in the `error_reporting PHP option`_.
 
-.. versionadded:: 4.1
-    The support for integers in the ``log`` option was introduced in Symfony 4.1.
-
 throw
 .....
 
@@ -1869,15 +2430,12 @@ app
 The cache adapter used by the ``cache.app`` service. The FrameworkBundle
 ships with multiple adapters: ``cache.adapter.apcu``, ``cache.adapter.doctrine``,
 ``cache.adapter.system``, ``cache.adapter.filesystem``, ``cache.adapter.psr6``,
-``cache.adapter.redis`` and ``cache.adapter.memcached``.
+``cache.adapter.redis``, ``cache.adapter.memcached`` and ``cache.adapter.pdo``.
 
 There's also a special adapter called ``cache.adapter.array`` which stores
 contents in memory using a PHP array and it's used to disable caching (mostly on
 the ``dev`` environment).
 
-.. versionadded:: 4.1
-    The ``cache.adapter.array`` adapter was introduced in Symfony 4.1.
-
 .. tip::
 
     It might be tough to understand at the beginning, so to avoid confusion
@@ -1885,7 +2443,7 @@ the ``dev`` environment).
     given the adapter they are based on. Internally, a pool wraps the definition
     of an adapter.
 
-.. _reference-cache-systen:
+.. _reference-cache-system:
 
 system
 ......
@@ -1909,7 +2467,7 @@ default_doctrine_provider
 **type**: ``string``
 
 The service name to use as your default Doctrine provider. The provider is
-available as the ``cache.doctrine`` service.
+available as the ``cache.default_doctrine_provider`` service.
 
 default_psr6_provider
 .....................
@@ -1917,14 +2475,14 @@ default_psr6_provider
 **type**: ``string``
 
 The service name to use as your default PSR-6 provider. It is available as
-the ``cache.psr6`` service.
+the ``cache.default_psr6_provider`` service.
 
 default_redis_provider
 ......................
 
 **type**: ``string`` **default**: ``redis://localhost``
 
-The DSN to use by the Redis provider. The provider is available as the ``cache.redis``
+The DSN to use by the Redis provider. The provider is available as the ``cache.default_redis_provider``
 service.
 
 default_memcached_provider
@@ -1932,7 +2490,16 @@ default_memcached_provider
 
 **type**: ``string`` **default**: ``memcached://localhost``
 
-The DSN to use by the Memcached provider. The provider is available as the ``cache.memcached``
+The DSN to use by the Memcached provider. The provider is available as the ``cache.default_memcached_provider``
+service.
+
+default_pdo_provider
+....................
+
+**type**: ``string`` **default**: ``doctrine.dbal.default_connection``
+
+The service id of the database connection, which should be either a PDO or a
+Doctrine DBAL instance. The provider is available as the ``cache.default_pdo_provider``
 service.
 
 pools
@@ -1968,8 +2535,8 @@ To configure a Redis cache pool with a default lifetime of 1 hour, do the follow
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:cache>
@@ -2036,9 +2603,6 @@ tags
 
 **type**: ``boolean`` | ``string`` **default**: ``null``
 
-.. versionadded:: 4.2
-    The ``tags`` option was introduced in Symfony 4.2.
-
 Whether your service should be able to handle tags or not.
 Can also be the service id of another cache pool where tags will be stored.
 
@@ -2070,6 +2634,8 @@ The cache clearer used to clear your PSR-6 cache.
 
     For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer`.
 
+.. _reference-cache-prefix-seed:
+
 prefix_seed
 ...........
 
@@ -2095,6 +2661,157 @@ lock
 The default lock adapter. If not defined, the value is set to ``semaphore`` when
 available, or to ``flock`` otherwise. Store's DSN are also allowed.
 
+workflows
+~~~~~~~~~
+
+**type**: ``array``
+
+A list of workflows to be created by the framework extension:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/workflow.yaml
+        framework:
+            workflows:
+                my_workflow:
+                    # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/workflow.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:workflows>
+                    <framework:workflow
+                        name="my_workflow"/>
+                </framework:workflows>
+                <!-- ... -->
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/workflow.php
+        $container->loadFromExtension('framework', [
+            'workflows' => [
+                'my_workflow' => // ...
+            ],
+        ]);
+
+.. seealso::
+
+    See also the article about :doc:`using workflows in Symfony applications </workflow>`.
+
+.. _reference-workflows-enabled:
+
+enabled
+.......
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether to enable the support for workflows or not. This setting is
+automatically set to ``true`` when one of the child settings is configured.
+
+.. _reference-workflows-name:
+
+name
+....
+
+**type**: ``prototype``
+
+Name of the workflow you want to create.
+
+audit_trail
+"""""""""""
+
+**type**: ``bool``
+
+If set to ``true``, the :class:`Symfony\\Component\\Workflow\\EventListener\\AuditTrailListener`
+will be enabled.
+
+initial_marking
+"""""""""""""""
+
+**type**: ``string`` | ``array``
+
+One of the ``places`` or ``empty``. If not null and the supported object is not
+already initialized via the workflow, this place will be set.
+
+marking_store
+"""""""""""""
+
+**type**: ``array``
+
+Each marking store can define any of these options:
+
+* ``arguments`` (**type**: ``array``)
+* ``service`` (**type**: ``string``)
+* ``type`` (**type**: ``string`` **allow value**: ``'method'``)
+
+metadata
+""""""""
+
+**type**: ``array``
+
+Metadata available for the workflow configuration.
+Note that ``places`` and ``transitions`` can also have their own
+``metadata`` entry.
+
+places
+""""""
+
+**type**: ``array``
+
+All available places (**type**: ``string``) for the workflow configuration.
+
+supports
+""""""""
+
+**type**: ``string`` | ``array``
+
+The FQCN (fully-qualified class name) of the object supported by the workflow
+configuration or an array of FQCN if multiple objects are supported.
+
+support_strategy
+""""""""""""""""
+
+**type**: ``string``
+
+transitions
+"""""""""""
+
+**type**: ``array``
+
+Each marking store can define any of these options:
+
+* ``from`` (**type**: ``string`` or ``array``) value from the ``places``,
+  multiple values are allowed for both ``workflow`` and ``state_machine``;
+* ``guard`` (**type**: ``string``) an :doc:`ExpressionLanguage </components/expression_language>`
+  compatible expression to block the transition;
+* ``name`` (**type**: ``string``) the name of the transition;
+* ``to`` (**type**: ``string`` or ``array``) value from the ``places``,
+  multiple values are allowed only for ``workflow``.
+
+.. _reference-workflows-type:
+
+type
+""""
+
+**type**: ``string`` **possible values**: ``'workflow'`` or ``'state_machine'``
+
+Defines the kind of workflow that is going to be created, which can be either
+a normal workflow or a state machine. Read :doc:`this article </workflow/introduction>`
+to know their differences.
+
 .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html
 .. _`Security Advisory Blog post`: https://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning
 .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html
@@ -2106,3 +2823,12 @@ available, or to ``flock`` otherwise. Store's DSN are also allowed.
 .. _`gulp-rev`: https://www.npmjs.com/package/gulp-rev
 .. _`webpack-manifest-plugin`: https://www.npmjs.com/package/webpack-manifest-plugin
 .. _`error_reporting PHP option`: https://secure.php.net/manual/en/errorfunc.configuration.php#ini.error-reporting
+.. _`CSRF security attacks`: https://en.wikipedia.org/wiki/Cross-site_request_forgery
+.. _`session.sid_length PHP option`: https://php.net/manual/session.configuration.php#ini.session.sid-length
+.. _`session.sid_bits_per_character PHP option`: https://php.net/manual/session.configuration.php#ini.session.sid-bits-per-character
+.. _`X-Robots-Tag HTTP header`: https://developers.google.com/search/reference/robots_meta_tag
+.. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt
+.. _`default_socket_timeout`: https://php.net/manual/en/filesystem.configuration.php#ini.default-socket-timeout
+.. _`PEM formatted`: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
+.. _`haveibeenpwned.com`: https://haveibeenpwned.com/
+.. _`session.cache-limiter`: https://www.php.net/manual/en/session.configuration.php#ini.session.cache-limiter
diff --git a/reference/configuration/kernel.rst b/reference/configuration/kernel.rst
index 3a1adc0c594..08413ef59aa 100644
--- a/reference/configuration/kernel.rst
+++ b/reference/configuration/kernel.rst
@@ -16,15 +16,21 @@ Configuration
 * `Project Directory`_
 * `Cache Directory`_
 * `Log Directory`_
+* `Container Build Time`_
+
+.. _configuration-kernel-charset:
 
 Charset
 ~~~~~~~
 
 **type**: ``string`` **default**: ``UTF-8``
 
-This returns the charset that is used in the application. To change it,
-override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset`
-method and return another charset, for instance::
+This option defines the charset that is used in the application. This value is
+exposed via the ``kernel.charset`` configuration parameter and the
+:method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset` method.
+
+To change this value, override the ``getCharset()`` method and return another
+charset::
 
     // src/Kernel.php
     use Symfony\Component\HttpKernel\Kernel as BaseKernel;
@@ -44,25 +50,42 @@ Kernel Name
 **type**: ``string`` **default**: ``src`` (i.e. the directory name holding
 the kernel class)
 
-To change this setting, override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getName`
-method. Alternatively, move your kernel into a different directory. For
-example, if you moved the kernel into a ``foo/`` directory (instead of ``src/``),
-the kernel name will be ``foo``.
+.. deprecated:: 4.2
+
+    The ``kernel.name`` parameter and the ``Kernel::getName()`` method were
+    deprecated in Symfony 4.2. If you need a unique ID for your kernels use the
+    ``kernel.container_class`` parameter or the ``Kernel::getContainerClass()`` method.
 
 The name of the kernel isn't usually directly important - it's used in the
 generation of cache files - and you probably will only change it when
 :doc:`using applications with multiple kernels </configuration/multiple_kernels>`.
 
+This value is exposed via the ``kernel.name`` configuration parameter and the
+:method:`Symfony\\Component\\HttpKernel\\Kernel::getName` method.
+
+To change this setting, override the ``getName()`` method. Alternatively, move
+your kernel into a different directory. For example, if you moved the kernel
+into a ``foo/`` directory (instead of ``src/``), the kernel name will be ``foo``.
+
+.. _configuration-kernel-project-directory:
+
 Project Directory
 ~~~~~~~~~~~~~~~~~
 
 **type**: ``string`` **default**: the directory of the project ``composer.json``
 
-This returns the root directory of your Symfony project. It's calculated as
-the directory where the main ``composer.json`` file is stored.
+This returns the absolute path of the root directory of your Symfony project,
+which is used by applications to perform operations with file paths relative to
+the project's root directory.
+
+By default, its value is calculated automatically as the directory where the
+main ``composer.json`` file is stored. This value is exposed via the
+``kernel.project_dir`` configuration parameter and the
+:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method.
 
-If for some reason the ``composer.json`` file is not stored at the root of your
-project, you can override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir`
+If you don't use Composer, or have moved the ``composer.json`` file location or
+have deleted it entirely (for example in the production servers), you can
+override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir`
 method to return the right project directory::
 
     // src/Kernel.php
@@ -73,9 +96,9 @@ method to return the right project directory::
     {
         // ...
 
-        public function getProjectDir()
+        public function getProjectDir(): string
         {
-            return realpath(__DIR__.'/../');
+            return \dirname(__DIR__);
         }
     }
 
@@ -84,15 +107,83 @@ Cache Directory
 
 **type**: ``string`` **default**: ``$this->rootDir/cache/$this->environment``
 
-This returns the path to the cache directory. To change it, override the
-:method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. Read
-":ref:`override-cache-dir`" for more information.
+This returns the absolute path of the cache directory of your Symfony project.
+It's calculated automatically based on the current
+:ref:`environment <configuration-environments>`.
+
+This value is exposed via the ``kernel.cache_dir`` configuration parameter and
+the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. To
+change this setting, override the ``getCacheDir()`` method to return the right
+cache directory.
 
 Log Directory
 ~~~~~~~~~~~~~
 
 **type**: ``string`` **default**: ``$this->rootDir/log``
 
-This returns the path to the log directory. To change it, override the
-:method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. Read
-":ref:`override-logs-dir`" for more information.
+This returns the absolute path of the log directory of your Symfony project.
+It's calculated automatically based on the current
+:ref:`environment <configuration-environments>`.
+
+This value is exposed via the ``kernel.log_dir`` configuration parameter and
+the :method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. To
+change this setting, override the ``getLogDir()`` method to return the right
+log directory.
+
+Container Build Time
+~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: the result of executing ``time()``
+
+Symfony follows the `reproducible builds`_ philosophy, which ensures that the
+result of compiling the exact same source code doesn't produce different
+results. This helps checking that a given binary or executable code was compiled
+from some trusted source code.
+
+In practice, the compiled :doc:`service container </service_container>` of your
+application will always be the same if you don't change its source code. This is
+exposed via these configuration parameters:
+
+* ``container.build_hash``, a hash of the contents of all your source files;
+* ``container.build_time``, a timestamp of the moment when the container was
+  built (the result of executing PHP's :phpfunction:`time` function);
+* ``container.build_id``, the result of merging the two previous parameters and
+  encoding the result using CRC32.
+
+Since the ``container.build_time`` value will change every time you compile the
+application, the build will not be strictly reproducible. If you care about
+this, the solution is to use another configuration parameter called
+``kernel.container_build_time`` and set it to a non-changing build time to
+achieve a strict reproducible build:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        parameters:
+            # ...
+            kernel.container_build_time: '1234567890'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <parameters>
+                <!-- ... -->
+                <parameter key="kernel.container_build_time">1234567890</parameter>
+            </parameters>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+
+        // ...
+        $container->setParameter('kernel.container_build_time', '1234567890');
+
+.. _`reproducible builds`: https://en.wikipedia.org/wiki/Reproducible_builds
diff --git a/reference/configuration/monolog.rst b/reference/configuration/monolog.rst
index b231ae21bdd..cf6eb53e443 100644
--- a/reference/configuration/monolog.rst
+++ b/reference/configuration/monolog.rst
@@ -20,7 +20,7 @@ in your application configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/monolog``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/monolog/monolog-1.0.xsd``
+    ``https://symfony.com/schema/dic/monolog/monolog-1.0.xsd``
 
 .. tip::
 
diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst
index 635babcf4b5..82341f04cee 100644
--- a/reference/configuration/security.rst
+++ b/reference/configuration/security.rst
@@ -20,24 +20,411 @@ key in your application configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/security``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/services/services-1.0.xsd``
+    ``https://symfony.com/schema/dic/services/services-1.0.xsd``
 
-.. versionadded:: 4.1
-    The ``providers`` option is optional starting from Symfony 4.1.
+Configuration
+-------------
+
+**Basic Options**:
+
+* `access_denied_url`_
+* `always_authenticate_before_granting`_
+* `erase_credentials`_
+* `hide_user_not_found`_
+* `session_fixation_strategy`_
+
+**Advanced Options**:
+
+Some of these options define tens of sub-options and they are explained in
+separate articles:
+
+* `access_control`_
+* `encoders`_
+* `firewalls`_
+* `providers`_
+* `role_hierarchy`_
+
+access_denied_url
+~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+Defines the URL where the user is redirected after a ``403`` HTTP error (unless
+you define a custom access deny handler). Example: ``/no-permission``
+
+always_authenticate_before_granting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+If ``true``, the user is asked to authenticate before each call to the
+``isGranted()`` method in services and controllers or ``is_granted()`` from
+templates.
+
+erase_credentials
+~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+If ``true``, the ``eraseCredentials()`` method of the user object is called
+after authentication.
+
+hide_user_not_found
+~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+If ``true``, when a user is not found a generic exception of type
+:class:`Symfony\\Component\\Security\\Core\\Exception\\BadCredentialsException`
+is thrown with the message "Bad credentials".
+
+If ``false``, the exception thrown is of type
+:class:`Symfony\\Component\\Security\\Core\\Exception\\UsernameNotFoundException`
+and it includes the given not found username.
+
+session_fixation_strategy
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``SessionAuthenticationStrategy::MIGRATE``
+
+`Session Fixation`_ is a security attack that permits an attacker to hijack a
+valid user session. Applications that don't assign new session IDs when
+authenticating users are vulnerable to this attack.
+
+The possible values of this option are:
+
+* ``NONE`` constant from :class:`Symfony\\Component\\Security\\Http\\Session\\SessionAuthenticationStrategy`
+  Don't change the session after authentication. This is **not recommended**.
+* ``MIGRATE`` constant from :class:`Symfony\\Component\\Security\\Http\\Session\\SessionAuthenticationStrategy`
+  The session ID is updated, but the rest of session attributes are kept.
+* ``INVALIDATE`` constant from :class:`Symfony\\Component\\Security\\Http\\Session\\SessionAuthenticationStrategy`
+  The entire session is regenerated, so the session ID is updated but all the
+  other session attributes are lost.
+
+access_control
+--------------
+
+Defines the security protection of the URLs of your application. It's used for
+example to trigger the user authentication when trying to access to the backend
+and to allow anonymous users to the login form page.
+
+This option is explained in detail in :doc:`/security/access_control`.
+
+encoders
+--------
+
+This option defines the algorithm used to *encode* the password of the users.
+Although Symfony calls it *"password encoding"* for historical reasons, this is
+in fact, *"password hashing"*.
+
+If your app defines more than one user class, each of them can define its own
+encoding algorithm. Also, each algorithm defines different config options:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            encoders:
+                # bcrypt encoder with default options
+                App\Entity\User: 'bcrypt'
+
+                # bcrypt encoder with custom options
+                App\Entity\User:
+                    algorithm: 'bcrypt'
+                    cost:      15
+
+                # Sodium encoder with default options
+                App\Entity\User: 'sodium'
+
+                # Sodium encoder with custom options
+                App\Entity\User:
+                    algorithm:   'sodium'
+                    memory_cost:  16384 # Amount in KiB. (16384 = 16 MiB)
+                    time_cost:    2     # Number of iterations
+                    threads:      4     # Number of parallel threads
+
+                # PBKDF2 encoder using SHA512 hashing with default options
+                App\Entity\User: 'sha512'
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" charset="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <!-- bcrypt encoder with default options -->
+                <encoder
+                    class="App\Entity\User"
+                    algorithm="bcrypt"
+                />
+
+                <!-- bcrypt encoder with custom options -->
+                <encoder
+                    class="App\Entity\User"
+                    algorithm="bcrypt"
+                    cost="15"
+                />
+
+                <!-- Sodium encoder with default options -->
+                <encoder
+                    class="App\Entity\User"
+                    algorithm="sodium"
+                />
+
+                <!-- Sodium encoder with custom options -->
+                <!-- memory_cost: amount in KiB. (16384 = 16 MiB)
+                     time_cost: number of iterations
+                     threads: number of parallel threads -->
+                <encoder
+                    class="App\Entity\User"
+                    algorithm="sodium"
+                    memory_cost="16384"
+                    time_cost="2"
+                    threads="4"
+                />
+
+                <!-- PBKDF2 encoder using SHA512 hashing with default options -->
+                <encoder
+                    class="App\Entity\User"
+                    algorithm="sha512"
+                />
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Entity\User;
+
+        $container->loadFromExtension('security', [
+            // ...
+            'encoders' => [
+                // bcrypt encoder with default options
+                User::class => [
+                    'algorithm' => 'bcrypt',
+                ],
+
+                // bcrypt encoder with custom options
+                User::class => [
+                    'algorithm' => 'bcrypt',
+                    'cost'      => 15,
+                ],
+
+                // Sodium encoder with default options
+                User::class => [
+                    'algorithm' => 'sodium',
+                ],
+
+                // Sodium encoder with custom options
+                User::class => [
+                    'algorithm' => 'sodium',
+                    'memory_cost' => 16384, // Amount in KiB. (16384 = 16 MiB)
+                    'time_cost' => 2,       // Number of iterations
+                    'threads' => 4,         // Number of parallel threads
+                ],
+
+                // PBKDF2 encoder using SHA512 hashing with default options
+                User::class => [
+                    'algorithm' => 'sha512',
+                ],
+            ],
+        ]);
+
+.. deprecated:: 4.3
+
+    The ``threads`` configuration option was deprecated in Symfony 4.3. No
+    alternative is provided because starting from Symfony 5.0 this value will be
+    hardcoded to ``1`` (one thread).
+
+.. versionadded:: 4.3
+
+    The ``sodium`` algorithm was introduced in Symfony 4.3. In previous Symfony
+    versions it was called ``argon2i``.
+
+.. tip::
+
+    You can also create your own password encoders as services and you can even
+    select a different password encoder for each user instance. Read
+    :doc:`this article </security/named_encoders>` for more details.
+
+.. _reference-security-sodium:
+.. _using-the-argon2i-password-encoder:
+
+Using the Sodium Password Encoder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.3
+
+    The ``SodiumPasswordEncoder`` was introduced in Symfony 4.3. In previous
+    Symfony versions it was called ``Argon2iPasswordEncoder``.
+
+It uses the `Argon2 key derivation function`_ and it's the encoder recommended
+by Symfony. Argon2 support was introduced in PHP 7.2, but if you use an earlier
+PHP version, you can install the `libsodium`_ PHP extension.
+
+The encoded passwords are ``96`` characters long, but due to the hashing
+requirements saved in the resulting hash this may change in the future, so make
+sure to allocate enough space for them to be persisted. Also, passwords include
+the `cryptographic salt`_ inside them (it's generated automatically for each new
+password) so you don't have to deal with it.
+
+.. _reference-security-bcrypt:
+
+Using the BCrypt Password Encoder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It uses the `bcrypt password hashing function`_ and it's recommended to use it
+when it's not possible to use Sodium. The encoded passwords are ``60``
+characters long, so make sure to allocate enough space for them to be persisted.
+Also, passwords include the `cryptographic salt`_ inside them (it's generated
+automatically for each new password) so you don't have to deal with it.
+
+Its only configuration option is ``cost``, which is an integer in the range of
+``4-31`` (by default, ``13``). Each single increment of the cost **doubles the
+time** it takes to encode a password. It's designed this way so the password
+strength can be adapted to the future improvements in computation power.
+
+You can change the cost at any time — even if you already have some passwords
+encoded using a different cost. New passwords will be encoded using the new
+cost, while the already encoded ones will be validated using a cost that was
+used back when they were encoded.
+
+.. tip::
+
+    A simple technique to make tests much faster when using BCrypt is to set
+    the cost to ``4``, which is the minimum value allowed, in the ``test``
+    environment configuration.
+
+.. _reference-security-pbkdf2:
+
+Using the PBKDF2 Encoder
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using the `PBKDF2`_ encoder is no longer recommended since PHP added support for
+Sodium and bcrypt. Legacy application still using it are encouraged to upgrade
+to those newer encoding algorithms.
+
+firewalls
+---------
+
+This is arguably the most important option of the security config file. It
+defines the authentication mechanism used for each URL (or URL pattern) of your
+application:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+            firewalls:
+                # 'main' is the name of the firewall (can be chosen freely)
+                main:
+                    # 'pattern' is a regular expression matched against the incoming
+                    # request URL. If there's a match, authentication is triggered
+                    pattern: ^/admin
+                    # the rest of options depend on the authentication mechanism
+                    # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+
+                <!-- 'pattern' is a regular expression matched against the incoming
+                     request URL. If there's a match, authentication is triggered -->
+                <firewall name="main" pattern="^/admin">
+                    <!-- the rest of options depend on the authentication mechanism -->
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+
+        // ...
+        $container->loadFromExtension('security', [
+            'firewalls' => [
+                // 'main' is the name of the firewall (can be chosen freely)
+                'main' => [
+                    // 'pattern' is a regular expression matched against the incoming
+                    // request URL. If there's a match, authentication is triggered
+                    'pattern' => '^/admin',
+                    // the rest of options depend on the authentication mechanism
+                    // ...
+                ],
+            ],
+        ]);
+
+.. seealso::
+
+    Read :doc:`this article </security/firewall_restriction>` to learn about how
+    to restrict firewalls by host and HTTP methods.
+
+In addition to some common config options, the most important firewall options
+depend on the authentication mechanism, which can be any of these:
+
+.. code-block:: yaml
+
+    # config/packages/security.yaml
+    security:
+        # ...
+        firewalls:
+            main:
+                # ...
+                    x509:
+                        # ...
+                    remote_user:
+                        # ...
+                    simple_preauth:
+                        # ...
+                    guard:
+                        # ...
+                    form_login:
+                        # ...
+                    form_login_ldap:
+                        # ...
+                    json_login:
+                        # ...
+                    simple_form:
+                        # ...
+                    http_basic:
+                        # ...
+                    http_basic_ldap:
+                        # ...
+                    http_digest:
+                        # ...
 
 .. _reference-security-firewall-form-login:
 
-Form Login Configuration
-------------------------
+``form_login`` Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When using the ``form_login`` authentication listener beneath a firewall,
 there are several common options for configuring the "form login" experience.
-
 For even more details, see :doc:`/security/form_login`.
 
-The Login Form and Process
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 login_path
 ..........
 
@@ -97,8 +484,7 @@ By default, you must submit your login form to the ``check_path`` URL as
 a POST request. By setting this option to ``false``, you can send a GET
 request to the ``check_path`` URL.
 
-Redirecting after Login
-~~~~~~~~~~~~~~~~~~~~~~~
+**Options Related to Redirecting after Login**
 
 always_use_default_target_path
 ..............................
@@ -139,10 +525,7 @@ redirected to the ``default_target_path`` to avoid a redirection loop.
     For historical reasons, and to match the misspelling of the HTTP standard,
     the option is called ``use_referer`` instead of ``use_referrer``.
 
-.. _reference-security-pbkdf2:
-
-Logout Configuration
---------------------
+**Options Related to Logout Configuration**
 
 invalidate_session
 ~~~~~~~~~~~~~~~~~~
@@ -162,7 +545,7 @@ logout_on_user_change
 
 **type**: ``boolean`` **default**: ``true``
 
-.. versionadded:: 4.1
+.. deprecated:: 4.1
 
     The ``logout_on_user_change`` option was deprecated in Symfony 4.1.
 
@@ -184,24 +567,48 @@ success_handler
 The service ID used for handling a successful logout. The service must implement
 :class:`Symfony\\Component\\Security\\Http\\Logout\\LogoutSuccessHandlerInterface`.
 
+.. _reference-security-logout-csrf:
+
+csrf_parameter
+~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``'_csrf_token'``
+
+The name of the parameter that stores the CSRF token value.
+
+csrf_token_generator
+~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+The ``id`` of the service used to generate the CSRF tokens. Symfony provides a
+default service whose ID is ``security.csrf.token_manager``.
+
+csrf_token_id
+~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``'logout'``
+
+An arbitrary string used to generate the token value (and check its validity
+afterwards).
+
 .. _reference-security-ldap:
 
-LDAP functionality
-------------------
+LDAP Authentication
+~~~~~~~~~~~~~~~~~~~
 
 There are several options for connecting against an LDAP server,
-using the ``form_login_ldap`` and ``http_basic_ldap`` authentication
+using the ``form_login_ldap``, ``http_basic_ldap`` and ``json_login_ldap`` authentication
 providers or the ``ldap`` user provider.
 
 For even more details, see :doc:`/security/ldap`.
 
-Authentication
-~~~~~~~~~~~~~~
+**Authentication**
 
 You can authenticate to an LDAP server using the LDAP variants of the
-``form_login`` and ``http_basic`` authentication providers. Simply use
-``form_login_ldap`` and ``http_basic_ldap``, which will attempt to
-``bind`` against a LDAP server instead of using password comparison.
+``form_login``, ``http_basic`` and ``json_login`` authentication providers. Use
+``form_login_ldap``, ``http_basic_ldap`` and ``json_login_ldap``, which will
+attempt to ``bind`` against an LDAP server instead of using password comparison.
 
 Both authentication providers have the same arguments as their normal
 counterparts, with the addition of two configuration keys:
@@ -234,200 +641,17 @@ Depending on your LDAP server's configuration, you will need to override
 this value. This setting is only necessary if the user's DN cannot be derived
 statically using the ``dn_string`` config option.
 
-User provider
-~~~~~~~~~~~~~
-
-Users will still be fetched from the configured user provider. If you
-wish to fetch your users from a LDAP server, you will need to use the
-``ldap`` user provider, in addition to one of the two authentication
-providers (``form_login_ldap`` or ``http_basic_ldap``).
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/security.yaml
-        security:
-            # ...
-
-            providers:
-                my_ldap_users:
-                    ldap:
-                        service: ldap
-                        base_dn: 'dc=symfony,dc=com'
-                        search_dn: '%ldap.search_dn%'
-                        search_password: '%ldap.search_password%'
-                        default_roles: ''
-                        uid_key: 'uid'
-                        filter: '(&({uid_key}={username})(objectclass=person)(ou=Users))'
-
-Using the PBKDF2 Encoder: Security and Speed
---------------------------------------------
-
-The `PBKDF2`_ encoder provides a high level of Cryptographic security, as
-recommended by the National Institute of Standards and Technology (NIST).
-
-You can see an example of the ``pbkdf2`` encoder in the YAML block on this
-page.
-
-But using PBKDF2 also warrants a warning: using it (with a high number
-of iterations) slows down the process. Thus, PBKDF2 should be used with
-caution and care.
-
-A good configuration lies around at least 1000 iterations and sha512
-for the hash algorithm.
-
-.. _reference-security-bcrypt:
-
-Using the BCrypt Password Encoder
----------------------------------
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/security.yaml
-        security:
-            # ...
-
-            encoders:
-                Symfony\Component\Security\Core\User\User:
-                    algorithm: bcrypt
-                    cost:      15
-
-    .. code-block:: xml
-
-        <!-- config/packages/security.xml -->
-        <?xml version="1.0" charset="UTF-8" ?>
-        <srv:container xmlns="http://symfony.com/schema/dic/security"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:srv="http://symfony.com/schema/dic/services"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <config>
-                <!-- ... -->
-                <encoder
-                    class="Symfony\Component\Security\Core\User\User"
-                    algorithm="bcrypt"
-                    cost="15"
-                />
-            </config>
-        </srv:container>
-
-    .. code-block:: php
-
-        // app/config/security.php
-        use Symfony\Component\Security\Core\User\User;
-
-        $container->loadFromExtension('security', [
-            // ...
-            'encoders' => [
-                User::class => [
-                    'algorithm' => 'bcrypt',
-                    'cost'      => 15,
-                ],
-            ],
-        ]);
-
-The ``cost`` can be in the range of ``4-31`` and determines how long a password
-will be encoded. Each increment of ``cost`` *doubles* the time it takes
-to encode a password.
-
-If you don't provide the ``cost`` option, the default cost of ``13`` is
-used.
-
-.. note::
-
-    You can change the cost at any time — even if you already have some
-    passwords encoded using a different cost. New passwords will be encoded
-    using the new cost, while the already encoded ones will be validated
-    using a cost that was used back when they were encoded.
-
-A salt for each new password is generated automatically and need not be
-persisted. Since an encoded password contains the salt used to encode it,
-persisting the encoded password alone is enough.
-
-.. note::
-
-    BCrypt encoded passwords are ``60`` characters long, so make sure to
-    allocate enough space for them to be persisted.
-
-.. tip::
-
-    A simple technique to make tests much faster when using BCrypt is to set
-    the cost to ``4``, which is the minimum value allowed, in the ``test``
-    environment configuration.
-
-.. _reference-security-argon2i:
+**User provider**
 
-Using the Argon2i Password Encoder
-----------------------------------
-
-.. caution::
-
-    To use this encoder, you either need to use PHP version 7.2 or install
-    the `libsodium`_ extension.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/security.yaml
-        security:
-            # ...
-
-            encoders:
-                Symfony\Component\Security\Core\User\User:
-                    algorithm: argon2i
-                    memory_cost:          16384 # Amount in KiB. 16 MiB
-                    time_cost:            2 # Number of iterations
-                    threads:              4 # Number of parallel threads
-
-    .. code-block:: xml
-
-        <!-- config/packages/security.xml -->
-        <config>
-            <!-- ... -->
-            <encoder
-                class="Symfony\Component\Security\Core\User\User"
-                algorithm="argon2i"
-                memory_cost="16384"
-                time_cost="2"
-                threads="4"
-            />
-        </config>
-
-    .. code-block:: php
-
-        // config/packages/security.php
-        use Symfony\Component\Security\Core\User\User;
-
-        $container->loadFromExtension('security', [
-            // ...
-            'encoders' => [
-                User::class => [
-                    'algorithm' => 'argon2i',
-                    'memory_cost' => 16384,
-                    'time_cost' => 2,
-                    'threads' => 4,
-                ],
-            ],
-        ]);
-
-A salt for each new password is generated automatically and need not be
-persisted. Since an encoded password contains the salt used to encode it,
-persisting the encoded password alone is enough.
-
-.. note::
-
-    Argon2i encoded passwords are ``96`` characters long, but due to the hashing
-    requirements saved in the resulting hash this may change in the future.
+Users will still be fetched from the configured user provider. If you wish to
+fetch your users from an LDAP server, you will need to use the
+:doc:`LDAP User Provider </security/ldap>` and any of these authentication
+providers: ``form_login_ldap`` or ``http_basic_ldap`` or ``json_login_ldap``.
 
 .. _reference-security-firewall-context:
 
 Firewall Context
-----------------
+~~~~~~~~~~~~~~~~
 
 Most applications will only need one :ref:`firewall <security-firewalls>`.
 But if your application *does* use multiple firewalls, you'll notice that
@@ -464,7 +688,7 @@ multiple firewalls, the "context" could actually be shared:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="somename" context="my_context">
@@ -500,7 +724,7 @@ multiple firewalls, the "context" could actually be shared:
     same time.
 
 User Checkers
--------------
+~~~~~~~~~~~~~
 
 During the authentication of a user, additional checks might be required to
 verify if the identified user is allowed to log in. Each firewall can include
@@ -508,6 +732,28 @@ a ``user_checker`` option to define the service used to perform those checks.
 
 Learn more about user checkers in :doc:`/security/user_checkers`.
 
+providers
+---------
+
+This options defines how the application users are loaded (from a database,
+an LDAP server, a configuration file, etc.) Read the following articles to learn
+more about each of those providers:
+
+* :ref:`Load users from a database <security-entity-user-provider>`
+* :ref:`Load users from an LDAP server <security-ldap-user-provider>`
+* :ref:`Load users from a configuration file <security-memory-user-provider>`
+* :ref:`Create your own user provider <custom-user-provider>`
+
+role_hierarchy
+--------------
+
+Instead of associating many roles to users, this option allows you to define
+role inheritance rules by creating a role hierarchy, as explained in
+:ref:`security-role-hierarchy`.
+
 .. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
-.. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat
 .. _`libsodium`: https://pecl.php.net/package/libsodium
+.. _`Session Fixation`: https://www.owasp.org/index.php/Session_fixation
+.. _`Argon2 key derivation function`: https://en.wikipedia.org/wiki/Argon2
+.. _`bcrypt password hashing function`: https://en.wikipedia.org/wiki/Bcrypt
+.. _`cryptographic salt`: https://en.wikipedia.org/wiki/Salt_(cryptography)
diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst
index 5546b77f8e3..42bea0dc659 100644
--- a/reference/configuration/swiftmailer.rst
+++ b/reference/configuration/swiftmailer.rst
@@ -20,7 +20,7 @@ to :doc:`send emails </email>`. All these options are configured under the
 
     When using XML, you must use the ``http://symfony.com/schema/dic/swiftmailer``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd``
+    ``https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd``
 
 Configuration
 -------------
@@ -157,7 +157,7 @@ values are ``plain``, ``login``, ``cram-md5``, or ``null``.
 spool
 ~~~~~
 
-For details on email spooling, see :doc:`/email/spool`.
+For details on email spooling, see :doc:`/mailer`.
 
 type
 ....
@@ -253,11 +253,10 @@ the information will be available in the profiler.
 
 .. tip::
 
-    The following options can be set via environment variables using the
-    ``%env()%`` syntax: ``url``, ``transport``, ``username``, ``password``,
-    ``host``, ``port``, ``timeout``, ``source_ip``, ``local_domain``,
-    ``encryption``, ``auth_mode``.
-    For details, see the :doc:`/configuration/external_parameters` article.
+    The following options can be set via environment variables: ``url``,
+    ``transport``, ``username``, ``password``, ``host``, ``port``, ``timeout``,
+    ``source_ip``, ``local_domain``, ``encryption``, ``auth_mode``. For details,
+    see: :ref:`config-env-vars`.
 
 Using Multiple Mailers
 ----------------------
@@ -284,9 +283,9 @@ key (the default mailer is identified by the ``default_mailer`` option):
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/swiftmailer
-                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+                https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
             <swiftmailer:config default-mailer="second_mailer">
                 <swiftmailer:mailer name="first_mailer"/>
@@ -358,7 +357,7 @@ alternatives based on the :ref:`service binding <services-binding>` feature:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <defaults autowire="true" autoconfigure="true" public="false">
@@ -381,14 +380,15 @@ alternatives based on the :ref:`service binding <services-binding>` feature:
 
         // config/services.php
         use App\Some\Service;
-        use Symfony\Component\DependencyInjection\Reference;
         use Psr\Log\LoggerInterface;
+        use Symfony\Component\DependencyInjection\Reference;
+
 
         $container->register(Service::class)
             ->setPublic(true)
             ->setBindings([
                 // this injects the second mailer when this service type-hints constructor arguments with \Swift_Mailer
-                \Swift_Mailer => '@swiftmailer.mailer.second_mailer',
+                \Swift_Mailer::class => '@swiftmailer.mailer.second_mailer',
                 // this injects the second mailer when this service has a constructor argument called $specialMailer
                 '$specialMailer' => '@swiftmailer.mailer.second_mailer',
             ])
diff --git a/reference/configuration/twig.rst b/reference/configuration/twig.rst
index f840a52c0af..aa5f1a032fb 100644
--- a/reference/configuration/twig.rst
+++ b/reference/configuration/twig.rst
@@ -20,7 +20,7 @@ the ``twig`` key in your application configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/twig``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/twig/twig-1.0.xsd``
+    ``https://symfony.com/schema/dic/twig/twig-1.0.xsd``
 
 Configuration
 -------------
@@ -56,7 +56,7 @@ Configuration
 auto_reload
 ~~~~~~~~~~~
 
-**type**: ``boolean`` **default**: ``'%kernel.debug%'``
+**type**: ``boolean`` **default**: ``%kernel.debug%``
 
 If ``true``, whenever a template is rendered, Symfony checks first if its source
 code has changed since it was compiled. If it has changed, the template is
@@ -112,7 +112,7 @@ called to determine the default escaping applied to the template.
 base_template_class
 ~~~~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``'Twig\\Template'``
+**type**: ``string`` **default**: ``'Twig\Template'``
 
 Twig templates are compiled into PHP classes before using them to render
 contents. This option defines the base class from which all the template classes
@@ -176,7 +176,7 @@ specific timezone is passed as argument.
 debug
 ~~~~~
 
-**type**: ``boolean`` **default**: ``'%kernel.debug%'``
+**type**: ``boolean`` **default**: ``%kernel.debug%``
 
 If ``true``, the compiled templates include a ``__toString()`` method that can
 be used to display their nodes.
@@ -224,8 +224,8 @@ all the forms of the application:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <twig:form-theme>bootstrap_4_layout.html.twig</twig:form-theme>
@@ -301,6 +301,8 @@ on. Set it to ``0`` to disable all the optimizations. You can even enable or
 disable these optimizations selectively, as explained in the Twig documentation
 about `the optimizer extension`_.
 
+.. _config-twig-default-path:
+
 default_path
 ~~~~~~~~~~~~
 
@@ -315,6 +317,12 @@ paths
 
 **type**: ``array`` **default**: ``null``
 
+.. deprecated:: 4.2
+
+    Using the ``src/Resources/views/`` directory to store templates was
+    deprecated in Symfony 4.2. Use instead the directory defined in the
+    ``default_path`` option (which is ``templates/`` by default).
+
 This option defines the directories where Symfony will look for Twig templates
 in addition to the default locations. Symfony looks for the templates in the
 following order:
@@ -344,8 +352,8 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <!-- ... -->
@@ -388,8 +396,8 @@ for that directory:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <!-- ... -->
diff --git a/reference/configuration/web_profiler.rst b/reference/configuration/web_profiler.rst
index cc7671f58c1..c97280f6f32 100644
--- a/reference/configuration/web_profiler.rst
+++ b/reference/configuration/web_profiler.rst
@@ -21,7 +21,7 @@ under the ``web_profiler`` key in your application configuration.
 
     When using XML, you must use the ``http://symfony.com/schema/dic/webprofiler``
     namespace and the related XSD schema is available at:
-    ``http://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd``
+    ``https://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd``
 
 .. caution::
 
@@ -41,10 +41,10 @@ excluded_ajax_paths
 
 **type**: ``string`` **default**: ``'^/((index|app(_[\w]+)?)\.php/)?_wdt'``
 
-When the toolbar logs Ajax requests, it matches their URLs against this regular
+When the toolbar logs AJAX requests, it matches their URLs against this regular
 expression. If the URL matches, the request is not displayed in the toolbar. This
-is useful when the application makes lots of Ajax requests or they are heavy and
-you want to exclude some of them.
+is useful when the application makes lots of AJAX requests, or if they are heavy
+and you want to exclude some of them.
 
 .. _intercept_redirects:
 
diff --git a/reference/constraints.rst b/reference/constraints.rst
index ef3b3db5876..317a836e396 100644
--- a/reference/constraints.rst
+++ b/reference/constraints.rst
@@ -19,6 +19,7 @@ Validation Constraints Reference
    constraints/Regex
    constraints/Ip
    constraints/Uuid
+   constraints/Json
 
    constraints/EqualTo
    constraints/NotEqualTo
@@ -29,10 +30,18 @@ Validation Constraints Reference
    constraints/GreaterThan
    constraints/GreaterThanOrEqual
    constraints/Range
+   constraints/DivisibleBy
+   constraints/Unique
+
+   constraints/Positive
+   constraints/PositiveOrZero
+   constraints/Negative
+   constraints/NegativeOrZero
 
    constraints/Date
    constraints/DateTime
    constraints/Time
+   constraints/Timezone
 
    constraints/Choice
    constraints/Collection
@@ -57,7 +66,9 @@ Validation Constraints Reference
    constraints/Expression
    constraints/All
    constraints/UserPassword
+   constraints/NotCompromisedPassword
    constraints/Valid
+   constraints/Traverse
 
 The Validator is designed to validate objects against *constraints*.
 In real life, a constraint could be: "The cake must not be burned". In
diff --git a/reference/constraints/All.rst b/reference/constraints/All.rst
index 3f00523dcce..c6aee2e7bee 100644
--- a/reference/constraints/All.rst
+++ b/reference/constraints/All.rst
@@ -4,16 +4,14 @@ All
 When applied to an array (or Traversable object), this constraint allows
 you to apply a collection of constraints to each element of the array.
 
-+----------------+-------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`            |
-+----------------+-------------------------------------------------------------------+
-| Options        | - `constraints`_                                                  |
-|                | - `payload`_                                                      |
-+----------------+-------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\All`          |
-+----------------+-------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\AllValidator` |
-+----------------+-------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `constraints`_
+            - `groups`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\All`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\AllValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -38,7 +36,7 @@ entry in that array:
              *     @Assert\Length(min=5)
              * })
              */
-             protected $favoriteColors = [];
+            protected $favoriteColors = [];
         }
 
     .. code-block:: yaml
@@ -58,13 +56,13 @@ entry in that array:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="favoriteColors">
                     <constraint name="All">
                         <option name="constraints">
-                            <constraint name="NotBlank" />
+                            <constraint name="NotBlank"/>
                             <constraint name="Length">
                                 <option name="min">5</option>
                             </constraint>
@@ -79,8 +77,8 @@ entry in that array:
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
@@ -109,4 +107,6 @@ constraints
 This required option is the array of validation constraints that you want
 to apply to each element of the underlying array.
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Bic.rst b/reference/constraints/Bic.rst
index 3ca8de78237..e12aacbaf63 100644
--- a/reference/constraints/Bic.rst
+++ b/reference/constraints/Bic.rst
@@ -3,23 +3,25 @@ Bic
 
 This constraint is used to ensure that a value has the proper format of a
 `Business Identifier Code (BIC)`_. BIC is an internationally agreed means to
-uniquely identify both financial and non-financial institutions.
-
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Bic`              |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\BicValidator`     |
-+----------------+-----------------------------------------------------------------------+
+uniquely identify both financial and non-financial institutions. You may also
+check that the BIC is associated with a given IBAN.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `iban`_
+            - `ibanMessage`_
+            - `ibanPropertyPath`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Bic`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\BicValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
-To use the Bic validator, simply apply it to a property on an object that
+To use the Bic validator, apply it to a property on an object that
 will contain a Business Identifier Code (BIC).
 
 .. configuration-block::
@@ -53,11 +55,11 @@ will contain a Business Identifier Code (BIC).
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Transaction">
                 <property name="businessIdentifierCode">
-                    <constraint name="Bic" />
+                    <constraint name="Bic"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -67,13 +69,11 @@ will contain a Business Identifier Code (BIC).
         // src/Entity/Transaction.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Transaction
         {
-            protected $businessIdentifierCode;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('businessIdentifierCode', new Assert\Bic());
@@ -85,6 +85,45 @@ will contain a Business Identifier Code (BIC).
 Available Options
 -----------------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+iban
+~~~~
+
+**type**: ``string`` **default**: ``null``
+
+.. versionadded:: 4.3
+
+    The ``iban`` option was introduced in Symfony 4.3.
+
+An IBAN value to validate that the BIC is associated with it.
+
+ibanMessage
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``This Business Identifier Code (BIC) is not associated with IBAN {{ iban }}.``
+
+.. versionadded:: 4.3
+
+    The ``ibanMessage`` option was introduced in Symfony 4.3.
+
+The default message supplied when the value does not pass the combined BIC/IBAN check.
+
+ibanPropertyPath
+~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+.. versionadded:: 4.3
+
+    The ``ibanPropertyPath`` option was introduced in Symfony 4.3.
+
+It defines the object property whose value stores the IBAN used to check the BIC with.
+
+For example, if you want to compare the ``$bic`` property of some object
+with regard to the ``$iban`` property of the same object, use
+``propertyPath="iban"`` in the comparison constraint of ``$bic``.
+
 message
 ~~~~~~~
 
@@ -94,11 +133,11 @@ The default message supplied when the value does not pass the BIC check.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) BIC value                |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) BIC value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/Blank.rst b/reference/constraints/Blank.rst
index 05dfad84459..35310298499 100644
--- a/reference/constraints/Blank.rst
+++ b/reference/constraints/Blank.rst
@@ -13,16 +13,14 @@ To force that a value strictly be equal to ``null``, see the
 To force that a value is *not* blank, see :doc:`/reference/constraints/NotBlank`.
 But be careful as ``NotBlank`` is *not* strictly the opposite of ``Blank``.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `message`_                                                        |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Blank`          |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\BlankValidator` |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Blank`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\BlankValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -61,11 +59,11 @@ of an ``Author`` class were blank, you could do the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
-                    <constraint name="Blank" />
+                    <constraint name="Blank"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -75,8 +73,8 @@ of an ``Author`` class were blank, you could do the following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -89,6 +87,8 @@ of an ``Author`` class were blank, you could do the following:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -98,10 +98,10 @@ This is the message that will be shown if the value is not blank.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Callback.rst b/reference/constraints/Callback.rst
index f8bc2c90b29..a9a87c89051 100644
--- a/reference/constraints/Callback.rst
+++ b/reference/constraints/Callback.rst
@@ -3,9 +3,9 @@ Callback
 
 The purpose of the Callback constraint is to create completely custom
 validation rules and to assign any validation errors to specific fields
-on your object. If you're using validation with forms, this means that you
-can make these custom errors display next to a specific field, instead of
-simply at the top of your form.
+on your object. If you're using validation with forms, this means that
+instead of displaying custom errors at the top of the form, you can
+display them next to the field they apply to.
 
 This process works by specifying one or more *callback* methods, each of
 which will be called during the validation process. Each of those methods
@@ -17,16 +17,14 @@ can do anything, including creating and assigning validation errors.
     as you'll see in the example, a callback method has the ability to directly
     add validator "violations".
 
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`class <validation-class-target>`                                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - :ref:`callback <callback-option>`                                    |
-|                | - `payload`_                                                           |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Callback`          |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CallbackValidator` |
-+----------------+------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`class <validation-class-target>` or :ref:`property/method <validation-property-target>`
+Options     - :ref:`callback <callback-option>`
+            - `groups`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Callback`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CallbackValidator`
+==========  ===================================================================
 
 Configuration
 -------------
@@ -65,7 +63,7 @@ Configuration
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <constraint name="Callback">validate</constraint>
@@ -77,8 +75,8 @@ Configuration
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -86,6 +84,11 @@ Configuration
             {
                 $metadata->addConstraint(new Assert\Callback('validate'));
             }
+
+            public function validate(ExecutionContextInterface $context, $payload)
+            {
+                // ...
+            }
         }
 
 The Callback Method
@@ -188,7 +191,7 @@ You can then use the following configuration to invoke this validator:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <constraint name="Callback">
@@ -204,8 +207,8 @@ You can then use the following configuration to invoke this validator:
         namespace App\Entity;
 
         use Acme\Validator;
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -232,10 +235,9 @@ constructor of the Callback constraint::
     // src/Entity/Author.php
     namespace App\Entity;
 
+    use Symfony\Component\Validator\Constraints as Assert;
     use Symfony\Component\Validator\Context\ExecutionContextInterface;
-
     use Symfony\Component\Validator\Mapping\ClassMetadata;
-    use Symfony\Component\Validator\Constraints as Assert;
 
     class Author
     {
@@ -275,4 +277,6 @@ Static or closure callbacks receive the validated object as the first argument
 and the :class:`Symfony\\Component\\Validator\\Context\\ExecutionContextInterface`
 instance as the second argument.
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/CardScheme.rst b/reference/constraints/CardScheme.rst
index c6b314cffc5..6362d9932ee 100644
--- a/reference/constraints/CardScheme.rst
+++ b/reference/constraints/CardScheme.rst
@@ -5,22 +5,20 @@ This constraint ensures that a credit card number is valid for a given credit
 card company. It can be used to validate the number before trying to initiate
 a payment through a payment gateway.
 
-+----------------+--------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                   |
-+----------------+--------------------------------------------------------------------------+
-| Options        | - `schemes`_                                                             |
-|                | - `message`_                                                             |
-|                | - `payload`_                                                             |
-+----------------+--------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\CardScheme`          |
-+----------------+--------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CardSchemeValidator` |
-+----------------+--------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `schemes`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\CardScheme`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CardSchemeValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
-To use the ``CardScheme`` validator, simply apply it to a property or method
+To use the ``CardScheme`` validator, apply it to a property or method
 on an object that will contain a credit card number.
 
 .. configuration-block::
@@ -59,7 +57,7 @@ on an object that will contain a credit card number.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Transaction">
                 <property name="cardNumber">
@@ -78,13 +76,11 @@ on an object that will contain a credit card number.
         // src/Entity/Transaction.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Transaction
         {
-            protected $cardNumber;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('cardNumber', new Assert\CardScheme([
@@ -101,6 +97,25 @@ on an object that will contain a credit card number.
 Available Options
 -----------------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``Unsupported card type or invalid card number.``
+
+The message shown when the value does not pass the ``CardScheme`` check.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
 schemes
 ~~~~~~~
 
@@ -119,26 +134,15 @@ Valid values are:
 * ``LASER``
 * ``MAESTRO``
 * ``MASTERCARD``
+* ``MIR``
+* ``UATP``
 * ``VISA``
 
-For more information about the used schemes, see
-`Wikipedia: Issuer identification number (IIN)`_.
-
-message
-~~~~~~~
+.. versionadded:: 4.3
 
-**type**: ``string`` **default**: ``Unsupported card type or invalid card number.``
+    The ``UATP`` and ``MIR`` number schemes were introduced in Symfony 4.3.
 
-The message shown when the value does not pass the ``CardScheme`` check.
-
-You can use the following parameters in this message:
-
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
-
-.. include:: /reference/constraints/_payload-option.rst.inc
+For more information about the used schemes, see
+`Wikipedia: Issuer identification number (IIN)`_.
 
 .. _`Wikipedia: Issuer identification number (IIN)`: https://en.wikipedia.org/wiki/Bank_card_number#Issuer_identification_number_.28IIN.29
diff --git a/reference/constraints/Choice.rst b/reference/constraints/Choice.rst
index 998259e546c..7cc8ae3ac1f 100644
--- a/reference/constraints/Choice.rst
+++ b/reference/constraints/Choice.rst
@@ -5,24 +5,22 @@ This constraint is used to ensure that the given value is one of a given
 set of *valid* choices. It can also be used to validate that each item in
 an array of items is one of those valid choices.
 
-+----------------+----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`               |
-+----------------+----------------------------------------------------------------------+
-| Options        | - `choices`_                                                         |
-|                | - `callback`_                                                        |
-|                | - `multiple`_                                                        |
-|                | - `min`_                                                             |
-|                | - `max`_                                                             |
-|                | - `message`_                                                         |
-|                | - `multipleMessage`_                                                 |
-|                | - `minMessage`_                                                      |
-|                | - `maxMessage`_                                                      |
-|                | - `payload`_                                                         |
-+----------------+----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Choice`          |
-+----------------+----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\ChoiceValidator` |
-+----------------+----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `callback`_
+            - `choices`_
+            - `groups`_
+            - `max`_
+            - `maxMessage`_
+            - `message`_
+            - `min`_
+            - `minMessage`_
+            - `multiple`_
+            - `multipleMessage`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Choice`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\ChoiceValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -45,13 +43,17 @@ If your valid choice list is simple, you can pass them in directly via the
 
         class Author
         {
+            const GENRES = ['fiction', 'non-fiction'];
+
             /**
              * @Assert\Choice({"New York", "Berlin", "Tokyo"})
              */
             protected $city;
 
             /**
-             * @Assert\Choice(choices={"fiction", "non-fiction"}, message="Choose a valid genre.")
+             * You can also directly provide an array constant to the "choices" option in the annotation
+             *
+             * @Assert\Choice(choices=Author::GENRES, message="Choose a valid genre.")
              */
             protected $genre;
         }
@@ -74,7 +76,7 @@ If your valid choice list is simple, you can pass them in directly via the
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="city">
@@ -101,13 +103,11 @@ If your valid choice list is simple, you can pass them in directly via the
         // src/EntityAuthor.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            protected $genre;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint(
@@ -127,8 +127,7 @@ Supplying the Choices with a Callback Function
 
 You can also use a callback function to specify your options. This is useful
 if you want to keep your choices in some central location so that, for example,
-you can easily access those choices for validation or for building a select
-form element::
+you can access those choices for validation or for building a select form element::
 
     // src/Entity/Author.php
     namespace App\Entity;
@@ -175,7 +174,7 @@ constraint.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="genre">
@@ -191,8 +190,8 @@ constraint.
         // src/EntityAuthor.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -206,7 +205,7 @@ constraint.
             }
         }
 
-If the callback is stored in a different class and is static, for example ``App\Entity\Genre``,
+If the callback is defined in a different class and is static, for example ``App\Entity\Genre``,
 you can pass the class name and the method as an array.
 
 .. configuration-block::
@@ -240,7 +239,7 @@ you can pass the class name and the method as an array.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="genre">
@@ -260,13 +259,11 @@ you can pass the class name and the method as an array.
         namespace App\Entity;
 
         use App\Entity\Genre;
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            protected $genre;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('genre', new Assert\Choice([
@@ -278,15 +275,6 @@ you can pass the class name and the method as an array.
 Available Options
 -----------------
 
-choices
-~~~~~~~
-
-**type**: ``array`` [:ref:`default option <validation-default-option>`]
-
-A required option (unless `callback`_ is specified) - this is the array
-of options that should be considered in the valid set. The input value
-will be matched against this array.
-
 callback
 ~~~~~~~~
 
@@ -296,25 +284,16 @@ This is a callback method that can be used instead of the `choices`_ option
 to return the choices array. See
 `Supplying the Choices with a Callback Function`_ for details on its usage.
 
-multiple
-~~~~~~~~
-
-**type**: ``boolean`` **default**: ``false``
-
-If this option is true, the input value is expected to be an array instead
-of a single, scalar value. The constraint will check that each value of
-the input array can be found in the array of valid choices. If even one
-of the input values cannot be found, the validation will fail.
+choices
+~~~~~~~
 
-min
-~~~
+**type**: ``array`` [:ref:`default option <validation-default-option>`]
 
-**type**: ``integer``
+A required option (unless `callback`_ is specified) - this is the array
+of options that should be considered in the valid set. The input value
+will be matched against this array.
 
-If the ``multiple`` option is true, then you can use the ``min`` option
-to force at least XX number of values to be selected. For example, if
-``min`` is 3, but the input array only contains 2 valid items, the validation
-will fail.
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 max
 ~~~
@@ -326,6 +305,27 @@ to force no more than XX number of values to be selected. For example, if
 ``max`` is 3, but the input array contains 4 valid items, the validation
 will fail.
 
+maxMessage
+~~~~~~~~~~
+
+**type**: ``string`` **default**: ``You must select at most {{ limit }} choices.``
+
+This is the validation error message that's displayed when the user chooses
+too many options per the `max`_ option.
+
+You can use the following parameters in this message:
+
+=================  ============================================================
+Parameter          Description
+=================  ============================================================
+``{{ choices }}``  A comma-separated list of available choices
+``{{ value }}``    The current (invalid) value
+=================  ============================================================
+
+.. versionadded:: 4.3
+
+    The ``{{ choices }}`` parameter was introduced in Symfony 4.3.
+
 message
 ~~~~~~~
 
@@ -337,28 +337,21 @@ choices.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
-
-multipleMessage
-~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``One or more of the given values is invalid.``
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
-This is the message that you will receive if the ``multiple`` option is
-set to ``true`` and one of the values on the underlying array being checked
-is not in the array of valid choices.
+min
+~~~
 
-You can use the following parameters in this message:
+**type**: ``integer``
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
+If the ``multiple`` option is true, then you can use the ``min`` option
+to force at least XX number of values to be selected. For example, if
+``min`` is 3, but the input array only contains 2 valid items, the validation
+will fail.
 
 minMessage
 ~~~~~~~~~~
@@ -370,26 +363,42 @@ too few choices per the `min`_ option.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ limit }}``  | The lower limit of choices                     |
-+------------------+------------------------------------------------+
+=================  ============================================================
+Parameter          Description
+=================  ============================================================
+``{{ choices }}``  A comma-separated list of available choices
+``{{ value }}``    The current (invalid) value
+=================  ============================================================
 
-maxMessage
-~~~~~~~~~~
+.. versionadded:: 4.3
 
-**type**: ``string`` **default**: ``You must select at most {{ limit }} choices.``
+    The ``{{ choices }}`` parameter was introduced in Symfony 4.3.
 
-This is the validation error message that's displayed when the user chooses
-too many options per the `max`_ option.
+multiple
+~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+If this option is true, the input value is expected to be an array instead
+of a single, scalar value. The constraint will check that each value of
+the input array can be found in the array of valid choices. If even one
+of the input values cannot be found, the validation will fail.
+
+multipleMessage
+~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``One or more of the given values is invalid.``
+
+This is the message that you will receive if the ``multiple`` option is
+set to ``true`` and one of the values on the underlying array being checked
+is not in the array of valid choices.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ limit }}``  | The upper limit of choices                     |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst
index e17c14f8da6..1baba93ecce 100644
--- a/reference/constraints/Collection.rst
+++ b/reference/constraints/Collection.rst
@@ -11,20 +11,23 @@ constraint.
 This constraint can also make sure that certain collection keys are present
 and that extra keys are not present.
 
-+----------------+--------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                   |
-+----------------+--------------------------------------------------------------------------+
-| Options        | - `fields`_                                                              |
-|                | - `allowExtraFields`_                                                    |
-|                | - `extraFieldsMessage`_                                                  |
-|                | - `allowMissingFields`_                                                  |
-|                | - `missingFieldsMessage`_                                                |
-|                | - `payload`_                                                             |
-+----------------+--------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Collection`          |
-+----------------+--------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CollectionValidator` |
-+----------------+--------------------------------------------------------------------------+
+.. seealso::
+
+    If you want to validate that all the elements of the collection are unique
+    use the :doc:`Unique constraint </reference/constraints/Unique>`.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `allowExtraFields`_
+            - `allowMissingFields`_
+            - `extraFieldsMessage`_
+            - `fields`_
+            - `groups`_
+            - `missingFieldsMessage`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Collection`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CollectionValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -79,10 +82,10 @@ following:
              *     allowMissingFields = true
              * )
              */
-             protected $profileData = [
-                 'personal_email' => '...',
-                 'short_bio' => '...',
-             ];
+            protected $profileData = [
+                'personal_email' => '...',
+                'short_bio' => '...',
+            ];
         }
 
     .. code-block:: yaml
@@ -93,7 +96,8 @@ following:
                 profileData:
                     - Collection:
                         fields:
-                            personal_email: Email
+                            personal_email: 
+                                - Email: ~
                             short_bio:
                                 - NotBlank: ~
                                 - Length:
@@ -107,17 +111,17 @@ following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="profileData">
                     <constraint name="Collection">
                         <option name="fields">
                             <value key="personal_email">
-                                <constraint name="Email" />
+                                <constraint name="Email"/>
                             </value>
                             <value key="short_bio">
-                                <constraint name="NotBlank" />
+                                <constraint name="NotBlank"/>
                                 <constraint name="Length">
                                     <option name="max">100</option>
                                     <option name="maxMessage">Your short bio is too long!</option>
@@ -135,13 +139,11 @@ following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            private $options = [];
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('profileData', new Assert\Collection([
@@ -163,7 +165,7 @@ following:
 Presence and Absence of Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By default, this constraint validates more than simply whether or not the
+By default, this constraint validates more than whether or not the
 individual fields in the collection pass their assigned constraints. In
 fact, if any keys of a collection are missing or if there are any unrecognized
 keys in the collection, validation errors will be thrown.
@@ -207,7 +209,7 @@ you can do the following:
              *     }
              * )
              */
-             protected $profileData = ['personal_email'];
+            protected $profileData = ['personal_email'];
         }
 
     .. code-block:: yaml
@@ -232,7 +234,7 @@ you can do the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="profile_data">
@@ -240,13 +242,13 @@ you can do the following:
                         <option name="fields">
                             <value key="personal_email">
                                 <constraint name="Required">
-                                    <constraint name="NotBlank" />
-                                    <constraint name="Email" />
+                                    <constraint name="NotBlank"/>
+                                    <constraint name="Email"/>
                                 </constraint>
                             </value>
                             <value key="alternate_email">
                                 <constraint name="Optional">
-                                    <constraint name="Email" />
+                                    <constraint name="Email"/>
                                 </constraint>
                             </value>
                         </option>
@@ -260,8 +262,8 @@ you can do the following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -271,9 +273,10 @@ you can do the following:
             {
                 $metadata->addPropertyConstraint('profileData', new Assert\Collection([
                     'fields' => [
-                        'personal_email'  => new Assert\Required(
-                            [new Assert\NotBlank(), new Assert\Email()]
-                        ),
+                        'personal_email'  => new Assert\Required([
+                            new Assert\NotBlank(),
+                            new Assert\Email(),
+                        ]),
                         'alternate_email' => new Assert\Optional(new Assert\Email()),
                     ],
                 ]));
@@ -289,15 +292,6 @@ the ``NotBlank`` constraint will still be applied (since it is wrapped in
 Options
 -------
 
-fields
-~~~~~~
-
-**type**: ``array`` [:ref:`default option <validation-default-option>`]
-
-This option is required and is an associative array defining all of the
-keys in the collection and, for each key, exactly which validator(s) should
-be executed against that element of the collection.
-
 allowExtraFields
 ~~~~~~~~~~~~~~~~
 
@@ -307,6 +301,16 @@ If this option is set to ``false`` and the underlying collection contains
 one or more elements that are not included in the `fields`_ option, a validation
 error will be returned. If set to ``true``, extra fields are ok.
 
+allowMissingFields
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: false
+
+If this option is set to ``false`` and one or more fields from the `fields`_
+option are not present in the underlying collection, a validation error
+will be returned. If set to ``true``, it's ok if some fields in the `fields`_
+option are not present in the underlying collection.
+
 extraFieldsMessage
 ~~~~~~~~~~~~~~~~~~
 
@@ -317,21 +321,22 @@ detected.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ field }}``  | The key of the extra field detected            |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ field }}``  The key of the extra field detected
+===============  ==============================================================
 
-allowMissingFields
-~~~~~~~~~~~~~~~~~~
+fields
+~~~~~~
 
-**type**: ``boolean`` **default**: false
+**type**: ``array`` [:ref:`default option <validation-default-option>`]
 
-If this option is set to ``false`` and one or more fields from the `fields`_
-option are not present in the underlying collection, a validation error
-will be returned. If set to ``true``, it's ok if some fields in the `fields`_
-option are not present in the underlying collection.
+This option is required and is an associative array defining all of the
+keys in the collection and, for each key, exactly which validator(s) should
+be executed against that element of the collection.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 missingFieldsMessage
 ~~~~~~~~~~~~~~~~~~~~
@@ -343,10 +348,10 @@ are missing from the underlying collection.
 
 You can use the following parameters in this message:
 
-+------------------+----------------------------------------------------+
-| Parameter        | Description                                        |
-+==================+====================================================+
-| ``{{ field }}``  | The key of the missing field defined in ``fields`` |
-+------------------+----------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ field }}``  The key of the missing field defined in ``fields``
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Count.rst b/reference/constraints/Count.rst
index 4449e90ecc7..42c164a3568 100644
--- a/reference/constraints/Count.rst
+++ b/reference/constraints/Count.rst
@@ -4,20 +4,18 @@ Count
 Validates that a given collection's (i.e. an array or an object that implements
 Countable) element count is *between* some minimum and maximum value.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `min`_                                                            |
-|                | - `max`_                                                            |
-|                | - `minMessage`_                                                     |
-|                | - `maxMessage`_                                                     |
-|                | - `exactMessage`_                                                   |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Count`          |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CountValidator` |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `exactMessage`_
+            - `groups`_
+            - `max`_
+            - `maxMessage`_
+            - `min`_
+            - `minMessage`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Count`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CountValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -44,7 +42,7 @@ you might add the following:
              *      maxMessage = "You cannot specify more than {{ limit }} emails"
              * )
              */
-             protected $emails = [];
+            protected $emails = [];
         }
 
     .. code-block:: yaml
@@ -65,7 +63,7 @@ you might add the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Participant">
                 <property name="emails">
@@ -84,16 +82,16 @@ you might add the following:
         // src/Entity/Participant.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Participant
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('emails', new Assert\Count([
-                    'min'        => 1,
-                    'max'        => 5,
+                    'min' => 1,
+                    'max' => 5,
                     'minMessage' => 'You must specify at least one email',
                     'maxMessage' => 'You cannot specify more than {{ limit }} emails',
                 ]));
@@ -103,13 +101,24 @@ you might add the following:
 Options
 -------
 
-min
-~~~
+exactMessage
+~~~~~~~~~~~~
 
-**type**: ``integer``
+**type**: ``string`` **default**: ``This collection should contain exactly {{ limit }} elements.``
 
-This required option is the "min" count value. Validation will fail if the
-given collection elements count is **less** than this min value.
+The message that will be shown if min and max values are equal and the underlying
+collection elements count is not exactly this value.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ count }}``  The current collection size
+``{{ limit }}``  The exact expected collection size
+===============  ==============================================================
+
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 max
 ~~~
@@ -119,24 +128,6 @@ max
 This required option is the "max" count value. Validation will fail if the
 given collection elements count is **greater** than this max value.
 
-minMessage
-~~~~~~~~~~
-
-**type**: ``string`` **default**: ``This collection should contain {{ limit }} elements or more.``
-
-The message that will be shown if the underlying collection elements count
-is less than the `min`_ option.
-
-You can use the following parameters in this message:
-
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ count }}``  | The current collection size                    |
-+------------------+------------------------------------------------+
-| ``{{ limit }}``  | The lower limit                                |
-+------------------+------------------------------------------------+
-
 maxMessage
 ~~~~~~~~~~
 
@@ -147,30 +138,36 @@ is more than the `max`_ option.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ count }}``  | The current collection size                    |
-+------------------+------------------------------------------------+
-| ``{{ limit }}``  | The upper limit                                |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ count }}``  The current collection size
+``{{ limit }}``  The upper limit
+===============  ==============================================================
 
-exactMessage
-~~~~~~~~~~~~
+min
+~~~
 
-**type**: ``string`` **default**: ``This collection should contain exactly {{ limit }} elements.``
+**type**: ``integer``
 
-The message that will be shown if min and max values are equal and the underlying
-collection elements count is not exactly this value.
+This required option is the "min" count value. Validation will fail if the
+given collection elements count is **less** than this min value.
+
+minMessage
+~~~~~~~~~~
+
+**type**: ``string`` **default**: ``This collection should contain {{ limit }} elements or more.``
+
+The message that will be shown if the underlying collection elements count
+is less than the `min`_ option.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ count }}``  | The current collection size                    |
-+------------------+------------------------------------------------+
-| ``{{ limit }}``  | The exact expected collection size             |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ count }}``  The current collection size
+``{{ limit }}``  The lower limit
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Country.rst b/reference/constraints/Country.rst
index b8721602dd3..3d18975d501 100644
--- a/reference/constraints/Country.rst
+++ b/reference/constraints/Country.rst
@@ -3,16 +3,14 @@ Country
 
 Validates that a value is a valid `ISO 3166-1 alpha-2`_ country code.
 
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `message`_                                                           |
-|                | - `payload`_                                                           |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Country`           |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CountryValidator`  |
-+----------------+------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Country`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CountryValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -31,7 +29,7 @@ Basic Usage
             /**
              * @Assert\Country
              */
-             protected $country;
+            protected $country;
         }
 
     .. code-block:: yaml
@@ -48,11 +46,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="country">
-                    <constraint name="Country" />
+                    <constraint name="Country"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -62,8 +60,8 @@ Basic Usage
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
@@ -78,6 +76,8 @@ Basic Usage
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -87,11 +87,11 @@ This message is shown if the string is not a valid country code.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) country code             |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) country code
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/Currency.rst b/reference/constraints/Currency.rst
index d0cb1c477a2..50782de0b16 100644
--- a/reference/constraints/Currency.rst
+++ b/reference/constraints/Currency.rst
@@ -3,16 +3,14 @@ Currency
 
 Validates that a value is a valid `3-letter ISO 4217`_ currency name.
 
-+----------------+---------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                     |
-+----------------+---------------------------------------------------------------------------+
-| Options        | - `message`_                                                              |
-|                | - `payload`_                                                              |
-+----------------+---------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Currency`             |
-+----------------+---------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CurrencyValidator`    |
-+----------------+---------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Currency`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CurrencyValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -51,11 +49,11 @@ a valid currency, you could do the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="currency">
-                    <constraint name="Currency" />
+                    <constraint name="Currency"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -65,8 +63,8 @@ a valid currency, you could do the following:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -81,6 +79,8 @@ a valid currency, you could do the following:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -90,11 +90,11 @@ This is the message that will be shown if the value is not a valid currency.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/Date.rst b/reference/constraints/Date.rst
index 5551a5a1a8f..b4c5bcbd3e2 100644
--- a/reference/constraints/Date.rst
+++ b/reference/constraints/Date.rst
@@ -1,20 +1,17 @@
 Date
 ====
 
-Validates that a value is a valid date, meaning either a ``DateTime`` object
-or a string (or an object that can be cast into a string) that follows a
-valid YYYY-MM-DD format.
-
-+----------------+--------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`             |
-+----------------+--------------------------------------------------------------------+
-| Options        | - `message`_                                                       |
-|                | - `payload`_                                                       |
-+----------------+--------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Date`          |
-+----------------+--------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\DateValidator` |
-+----------------+--------------------------------------------------------------------+
+Validates that a value is a valid date, meaning a string (or an object that can
+be cast into a string) that follows a valid ``YYYY-MM-DD`` format.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Date`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\DateValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -32,8 +29,9 @@ Basic Usage
         {
             /**
              * @Assert\Date
+             * @var string A "Y-m-d" formatted value
              */
-             protected $birthday;
+            protected $birthday;
         }
 
     .. code-block:: yaml
@@ -50,11 +48,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="birthday">
-                    <constraint name="Date" />
+                    <constraint name="Date"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -64,11 +62,16 @@ Basic Usage
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
+           /**
+            * @var string A "Y-m-d" formatted value
+            */
+            protected $birthday;
+
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('birthday', new Assert\Date());
@@ -80,6 +83,8 @@ Basic Usage
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -89,10 +94,10 @@ This message is shown if the underlying data is not a valid date.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/DateTime.rst b/reference/constraints/DateTime.rst
index 56ef2c38aea..c9b914a0609 100644
--- a/reference/constraints/DateTime.rst
+++ b/reference/constraints/DateTime.rst
@@ -1,21 +1,18 @@
 DateTime
 ========
 
-Validates that a value is a valid "datetime", meaning either a ``DateTime``
-object or a string (or an object that can be cast into a string) that follows
-a specific format.
-
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `format`_                                                            |
-|                | - `message`_                                                           |
-|                | - `payload`_                                                           |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\DateTime`          |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\DateTimeValidator` |
-+----------------+------------------------------------------------------------------------+
+Validates that a value is a valid "datetime", meaning a string (or an object
+that can be cast into a string) that follows a specific format.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `format`_
+            - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\DateTime`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\DateTimeValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -33,8 +30,9 @@ Basic Usage
         {
             /**
              * @Assert\DateTime
+             * @var string A "Y-m-d H:i:s" formatted value
              */
-             protected $createdAt;
+            protected $createdAt;
         }
 
     .. code-block:: yaml
@@ -51,11 +49,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="createdAt">
-                    <constraint name="DateTime" />
+                    <constraint name="DateTime"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -65,11 +63,16 @@ Basic Usage
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
+           /**
+            * @var string A "Y-m-d H:i:s" formatted value
+            */
+            protected $createdAt;
+
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('createdAt', new Assert\DateTime());
@@ -89,6 +92,8 @@ format
 This option allows to validate a custom date format. See
 :phpmethod:`DateTime::createFromFormat` for formatting options.
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -98,10 +103,10 @@ This message is shown if the underlying data is not a valid datetime.
 
 You can use the following parameters in this message:
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/DivisibleBy.rst b/reference/constraints/DivisibleBy.rst
new file mode 100644
index 00000000000..c93052a248a
--- /dev/null
+++ b/reference/constraints/DivisibleBy.rst
@@ -0,0 +1,120 @@
+DivisibleBy
+===========
+
+Validates that a value is divisible by another value, defined in the options.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\DivisibleBy`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\DivisibleByValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraints ensure that:
+
+* the ``weight`` of the ``Item`` is provided in increments of ``0.25``
+* the ``quantity`` of the ``Item`` must be divisible by ``5``
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Item.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Item
+        {
+
+            /**
+             * @Assert\DivisibleBy(0.25)
+             */
+            protected $weight;
+
+            /**
+             * @Assert\DivisibleBy(
+             *     value = 5
+             * )
+             */
+            protected $quantity;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Item:
+            properties:
+                weight:
+                    - DivisibleBy: 0.25
+                quantity:
+                    - DivisibleBy:
+                        value: 5
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\Item">
+                <property name="weight">
+                    <constraint name="DivisibleBy">
+                        <value>0.25</value>
+                    </constraint>
+                </property>
+                <property name="quantity">
+                    <constraint name="DivisibleBy">
+                        <option name="value">5</option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Item.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Item
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('weight', new Assert\DivisibleBy(0.25));
+
+                $metadata->addPropertyConstraint('quantity', new Assert\DivisibleBy([
+                    'value' => 5,
+                ]));
+            }
+        }
+
+Options
+-------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be a multiple of {{ compared_value }}.``
+
+This is the message that will be shown if the value is not divisible by the
+comparison value.
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+.. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
+
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
diff --git a/reference/constraints/Email.rst b/reference/constraints/Email.rst
index 8aa4056a75b..8b68f59bea2 100644
--- a/reference/constraints/Email.rst
+++ b/reference/constraints/Email.rst
@@ -4,19 +4,18 @@ Email
 Validates that a value is a valid email address. The underlying value is
 cast to a string before being validated.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `mode`_                                                           |
-|                | - `message`_                                                        |
-|                | - `checkMX`_                                                        |
-|                | - `checkHost`_                                                      |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Email`          |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\EmailValidator` |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `checkHost`_
+            - `checkMX`_
+            - `groups`_
+            - `message`_
+            - `mode`_
+            - `normalizer`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Email`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\EmailValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -38,7 +37,7 @@ Basic Usage
              *     checkMX = true
              * )
              */
-             protected $email;
+            protected $email;
         }
 
     .. code-block:: yaml
@@ -57,7 +56,7 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="email">
@@ -74,8 +73,8 @@ Basic Usage
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -93,6 +92,53 @@ Basic Usage
 Options
 -------
 
+checkHost
+~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. deprecated:: 4.2
+
+    This option was deprecated in Symfony 4.2.
+
+If true, then the :phpfunction:`checkdnsrr` PHP function will be used to
+check the validity of the MX *or* the A *or* the AAAA record of the host
+of the given email.
+
+checkMX
+~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. deprecated:: 4.2
+
+    This option was deprecated in Symfony 4.2.
+
+If true, then the :phpfunction:`checkdnsrr` PHP function will be used to
+check the validity of the MX record of the host of the given email.
+
+.. caution::
+
+    This option is not reliable because it depends on the network conditions
+    and some valid servers refuse to respond to those requests.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value is not a valid email address.``
+
+This message is shown if the underlying data is not a valid email address.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
 mode
 ~~~~
 
@@ -122,42 +168,7 @@ html5
 
 This matches the pattern used for the `HTML5 email input element`_.
 
-message
-~~~~~~~
-
-**type**: ``string`` **default**: ``This value is not a valid email address.``
-
-This message is shown if the underlying data is not a valid email address.
-
-You can use the following parameters in this message:
-
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ value }}``  | The current (invalid) value                    |
-+------------------+------------------------------------------------+
-
-checkMX
-~~~~~~~
-
-**type**: ``boolean`` **default**: ``false``
-
-If true, then the :phpfunction:`checkdnsrr` PHP function will be used to
-check the validity of the MX record of the host of the given email.
-
-.. caution::
-
-    This option is not reliable because it depends on the network conditions
-    and some valid servers refuse to respond to those requests.
-
-checkHost
-~~~~~~~~~
-
-**type**: ``boolean`` **default**: ``false``
-
-If true, then the :phpfunction:`checkdnsrr` PHP function will be used to
-check the validity of the MX *or* the A *or* the AAAA record of the host
-of the given email.
+.. include:: /reference/constraints/_normalizer-option.rst.inc
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/EqualTo.rst b/reference/constraints/EqualTo.rst
index 4c5613f5575..f0b25952a1e 100644
--- a/reference/constraints/EqualTo.rst
+++ b/reference/constraints/EqualTo.rst
@@ -10,18 +10,16 @@ To force that a value is *not* equal, see :doc:`/reference/constraints/NotEqualT
     equal. Use :doc:`/reference/constraints/IdenticalTo` to compare with
     ``===``.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                 |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `value`_                                                            |
-|                | - `message`_                                                          |
-|                | - `payload`_                                                          |
-|                | - `propertyPath`_                                                     |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\EqualTo`          |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\EqualToValidator` |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\EqualTo`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\EqualToValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -70,7 +68,7 @@ and that the ``age`` is ``20``, you could do the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="firstName">
@@ -91,8 +89,8 @@ and that the ``age`` is ``20``, you could do the following:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -109,7 +107,7 @@ and that the ``age`` is ``20``, you could do the following:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -120,16 +118,16 @@ This is the message that will be shown if the value is not equal.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The expected value          |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The expected value
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
+
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
diff --git a/reference/constraints/Expression.rst b/reference/constraints/Expression.rst
index 05539dda9fc..9a400a487d1 100644
--- a/reference/constraints/Expression.rst
+++ b/reference/constraints/Expression.rst
@@ -6,18 +6,17 @@ for more complex, dynamic validation. See `Basic Usage`_ for an example.
 See :doc:`/reference/constraints/Callback` for a different constraint that
 gives you similar flexibility.
 
-+----------------+-----------------------------------------------------------------------------------------------+
-| Applies to     | :ref:`class <validation-class-target>` or :ref:`property/method <validation-property-target>` |
-+----------------+-----------------------------------------------------------------------------------------------+
-| Options        | - :ref:`expression <reference-constraint-expression-option>`                                  |
-|                | - `message`_                                                                                  |
-|                | - `payload`_                                                                                  |
-|                | - `values`_                                                                                   |
-+----------------+-----------------------------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Expression`                               |
-+----------------+-----------------------------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\ExpressionValidator`                      |
-+----------------+-----------------------------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`class <validation-class-target>`
+            or :ref:`property/method <validation-property-target>`
+Options     - :ref:`expression <reference-constraint-expression-option>`
+            - `groups`_
+            - `message`_
+            - `payload`_
+            - `values`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Expression`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\ExpressionValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -94,7 +93,7 @@ One way to accomplish this is with the Expression constraint:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
             <class name="App\Model\BlogPost">
                 <constraint name="Expression">
                     <option name="expression">
@@ -112,8 +111,8 @@ One way to accomplish this is with the Expression constraint:
         // src/Model/BlogPost.php
         namespace App\Model;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class BlogPost
         {
@@ -180,7 +179,7 @@ more about the expression language syntax, see
             <?xml version="1.0" encoding="UTF-8" ?>
             <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
                 <class name="App\Model\BlogPost">
                     <property name="isTechnicalPost">
@@ -246,6 +245,8 @@ in your expression:
 * ``value``: The value of the property being validated (only available when
   the constraint is applied directly to a property);
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -255,11 +256,11 @@ The default message supplied when the expression evaluates to false.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
@@ -268,9 +269,6 @@ values
 
 **type**: ``array`` **default**: ``[]``
 
-.. versionadded:: 4.1
-    The ``values`` option was introduced in Symfony 4.1.
-
 The values of the custom variables used in the expression. Values can be of any
 type (numeric, boolean, strings, null, etc.)
 
@@ -312,7 +310,7 @@ type (numeric, boolean, strings, null, etc.)
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Model\Analysis">
                 <property name="metric">
diff --git a/reference/constraints/File.rst b/reference/constraints/File.rst
index 000b220ef66..8a61619a9fd 100644
--- a/reference/constraints/File.rst
+++ b/reference/constraints/File.rst
@@ -16,31 +16,29 @@ form field.
     If the file you're validating is an image, try the :doc:`Image </reference/constraints/Image>`
     constraint.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `maxSize`_                                                        |
-|                | - `binaryFormat`_                                                   |
-|                | - `mimeTypes`_                                                      |
-|                | - `maxSizeMessage`_                                                 |
-|                | - `mimeTypesMessage`_                                               |
-|                | - `disallowEmptyMessage`_                                           |
-|                | - `notFoundMessage`_                                                |
-|                | - `notReadableMessage`_                                             |
-|                | - `uploadIniSizeErrorMessage`_                                      |
-|                | - `uploadFormSizeErrorMessage`_                                     |
-|                | - `uploadPartialErrorMessage`_                                      |
-|                | - `uploadNoFileErrorMessage`_                                       |
-|                | - `uploadNoTmpDirErrorMessage`_                                     |
-|                | - `uploadCantWriteErrorMessage`_                                    |
-|                | - `uploadExtensionErrorMessage`_                                    |
-|                | - `uploadErrorMessage`_                                             |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\File`           |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\FileValidator`  |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `binaryFormat`_
+            - `disallowEmptyMessage`_
+            - `groups`_
+            - `maxSize`_
+            - `maxSizeMessage`_
+            - `mimeTypes`_
+            - `mimeTypesMessage`_
+            - `notFoundMessage`_
+            - `notReadableMessage`_
+            - `payload`_
+            - `uploadCantWriteErrorMessage`_
+            - `uploadErrorMessage`_
+            - `uploadExtensionErrorMessage`_
+            - `uploadFormSizeErrorMessage`_
+            - `uploadIniSizeErrorMessage`_
+            - `uploadNoFileErrorMessage`_
+            - `uploadNoTmpDirErrorMessage`_
+            - `uploadPartialErrorMessage`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\File`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\FileValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -112,7 +110,7 @@ below a certain file size and a valid PDF, add the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioFile">
@@ -133,8 +131,8 @@ below a certain file size and a valid PDF, add the following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -160,6 +158,38 @@ have been specified.
 Options
 -------
 
+binaryFormat
+~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``null``
+
+When ``true``, the sizes will be displayed in messages with binary-prefixed
+units (KiB, MiB). When ``false``, the sizes will be displayed with SI-prefixed
+units (kB, MB). When ``null``, then the binaryFormat will be guessed from
+the value defined in the ``maxSize`` option.
+
+For more information about the difference between binary and SI prefixes,
+see `Wikipedia: Binary prefix`_.
+
+disallowEmptyMessage
+~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``An empty file is not allowed.``
+
+This constraint checks if the uploaded file is empty (i.e. 0 bytes). If it is,
+this message is displayed.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ file }}``   Absolute file path
+``{{ name }}``   Base file name
+===============  ==============================================================
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 maxSize
 ~~~~~~~
 
@@ -169,35 +199,37 @@ If set, the size of the underlying file must be below this file size in
 order to be valid. The size of the file can be given in one of the following
 formats:
 
-+--------+-----------+-----------------+------+
-| Suffix | Unit Name |      value      | e.g. |
-+========+===========+=================+======+
-|        | byte      |          1 byte | 4096 |
-+--------+-----------+-----------------+------+
-| k      | kilobyte  |     1,000 bytes | 200k |
-+--------+-----------+-----------------+------+
-| M      | megabyte  | 1,000,000 bytes |   2M |
-+--------+-----------+-----------------+------+
-| Ki     | kibibyte  |     1,024 bytes | 32Ki |
-+--------+-----------+-----------------+------+
-| Mi     | mebibyte  | 1,048,576 bytes |  8Mi |
-+--------+-----------+-----------------+------+
+======  =========  ===============  ========
+Suffix  Unit Name  Value            Example
+======  =========  ===============  ========
+(none)  byte       1 byte           ``4096``
+``k``   kilobyte   1,000 bytes      ``200k``
+``M``   megabyte   1,000,000 bytes  ``2M``
+``Ki``  kibibyte   1,024 bytes      ``32Ki``
+``Mi``  mebibyte   1,048,576 bytes  ``8Mi``
+======  =========  ===============  ========
 
 For more information about the difference between binary and SI prefixes,
 see `Wikipedia: Binary prefix`_.
 
-binaryFormat
-~~~~~~~~~~~~
+maxSizeMessage
+~~~~~~~~~~~~~~
 
-**type**: ``boolean`` **default**: ``null``
+**type**: ``string`` **default**: ``The file is too large ({{ size }} {{ suffix }}). Allowed maximum size is {{ limit }} {{ suffix }}.``
 
-When ``true``, the sizes will be displayed in messages with binary-prefixed
-units (KiB, MiB). When ``false``, the sizes will be displayed with SI-prefixed
-units (kB, MB). When ``null``, then the binaryFormat will be guessed from
-the value defined in the ``maxSize`` option.
+The message displayed if the file is larger than the `maxSize`_ option.
 
-For more information about the difference between binary and SI prefixes,
-see `Wikipedia: Binary prefix`_.
+You can use the following parameters in this message:
+
+================  =============================================================
+Parameter         Description
+================  =============================================================
+``{{ file }}``    Absolute file path
+``{{ limit }}``   Maximum file size allowed
+``{{ name }}``    Base file name
+``{{ size }}``    File size of the given file
+``{{ suffix }}``  Suffix for the used file size unit (see above)
+================  =============================================================
 
 mimeTypes
 ~~~~~~~~~
@@ -210,27 +242,6 @@ of given mime types (if an array).
 
 You can find a list of existing mime types on the `IANA website`_.
 
-maxSizeMessage
-~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``The file is too large ({{ size }} {{ suffix }}). Allowed maximum size is {{ limit }} {{ suffix }}.``
-
-The message displayed if the file is larger than the `maxSize`_ option.
-
-You can use the following parameters in this message:
-
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ size }}``   | File size of the given file                    |
-+------------------+------------------------------------------------+
-| ``{{ limit }}``  | Maximum file size allowed                      |
-+------------------+------------------------------------------------+
-| ``{{ suffix }}`` | Suffix for the used file size unit (see above) |
-+------------------+------------------------------------------------+
-| ``{{ file }}``   | Absolute file path                             |
-+------------------+------------------------------------------------+
-
 mimeTypesMessage
 ~~~~~~~~~~~~~~~~
 
@@ -241,31 +252,14 @@ per the `mimeTypes`_ option.
 
 You can use the following parameters in this message:
 
-+-----------------+----------------------------------------+
-| Parameter       | Description                            |
-+=================+========================================+
-| ``{{ type }}``  | The MIME type of the given file        |
-+-----------------+----------------------------------------+
-| ``{{ types }}`` | The list of allowed MIME types         |
-+-----------------+----------------------------------------+
-| ``{{ file }}``  | Absolute file path                     |
-+-----------------+----------------------------------------+
-
-disallowEmptyMessage
-~~~~~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``An empty file is not allowed.``
-
-This constraint checks if the uploaded file is empty (i.e. 0 bytes). If it is,
-this message is displayed.
-
-You can use the following parameters in this message:
-
-+----------------+--------------------+
-| Parameter      | Description        |
-+================+====================+
-| ``{{ file }}`` | Absolute file path |
-+----------------+--------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ file }}``   Absolute file path
+``{{ name }}``   Base file name
+``{{ type }}``   The MIME type of the given file
+``{{ types }}``  The list of allowed MIME types
+===============  ==============================================================
 
 notFoundMessage
 ~~~~~~~~~~~~~~~
@@ -278,11 +272,11 @@ cannot be constructed with an invalid file path.
 
 You can use the following parameters in this message:
 
-+----------------+--------------------+
-| Parameter      | Description        |
-+================+====================+
-| ``{{ file }}`` | Absolute file path |
-+----------------+--------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ file }}``   Absolute file path
+===============  ==============================================================
 
 notReadableMessage
 ~~~~~~~~~~~~~~~~~~
@@ -294,29 +288,43 @@ fails when passed the path to the file.
 
 You can use the following parameters in this message:
 
-+----------------+--------------------+
-| Parameter      | Description        |
-+================+====================+
-| ``{{ file }}`` | Absolute file path |
-+----------------+--------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ file }}``   Absolute file path
+===============  ==============================================================
 
-uploadIniSizeErrorMessage
-~~~~~~~~~~~~~~~~~~~~~~~~~
+.. include:: /reference/constraints/_payload-option.rst.inc
 
-**type**: ``string`` **default**: ``The file is too large. Allowed maximum size is {{ limit }} {{ suffix }}.``
+uploadCantWriteErrorMessage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The message that is displayed if the uploaded file is larger than the ``upload_max_filesize``
-``php.ini`` setting.
+**type**: ``string`` **default**: ``Cannot write temporary file to disk.``
 
-You can use the following parameters in this message:
+The message that is displayed if the uploaded file can't be stored in the
+temporary folder.
+
+This message has no parameters.
+
+uploadErrorMessage
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``The file could not be uploaded.``
+
+The message that is displayed if the uploaded file could not be uploaded
+for some unknown reason.
+
+This message has no parameters.
 
-+------------------+------------------------------------------------+
-| Parameter        | Description                                    |
-+==================+================================================+
-| ``{{ limit }}``  | Maximum file size allowed                      |
-+------------------+------------------------------------------------+
-| ``{{ suffix }}`` | Suffix for the used file size unit (see above) |
-+------------------+------------------------------------------------+
+uploadExtensionErrorMessage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``A PHP extension caused the upload to fail.``
+
+The message that is displayed if a PHP extension caused the file upload to
+fail.
+
+This message has no parameters.
 
 uploadFormSizeErrorMessage
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -328,14 +336,22 @@ by the HTML file input field.
 
 This message has no parameters.
 
-uploadPartialErrorMessage
+uploadIniSizeErrorMessage
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``The file was only partially uploaded.``
+**type**: ``string`` **default**: ``The file is too large. Allowed maximum size is {{ limit }} {{ suffix }}.``
 
-The message that is displayed if the uploaded file is only partially uploaded.
+The message that is displayed if the uploaded file is larger than the ``upload_max_filesize``
+``php.ini`` setting.
 
-This message has no parameters.
+You can use the following parameters in this message:
+
+================  =============================================================
+Parameter         Description
+================  =============================================================
+``{{ limit }}``   Maximum file size allowed
+``{{ suffix }}``  Suffix for the used file size unit (see above)
+================  =============================================================
 
 uploadNoFileErrorMessage
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -356,37 +372,14 @@ missing.
 
 This message has no parameters.
 
-uploadCantWriteErrorMessage
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``Cannot write temporary file to disk.``
-
-The message that is displayed if the uploaded file can't be stored in the
-temporary folder.
-
-This message has no parameters.
-
-uploadExtensionErrorMessage
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``A PHP extension caused the upload to fail.``
-
-The message that is displayed if a PHP extension caused the file upload to
-fail.
-
-This message has no parameters.
-
-uploadErrorMessage
-~~~~~~~~~~~~~~~~~~
+uploadPartialErrorMessage
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``The file could not be uploaded.``
+**type**: ``string`` **default**: ``The file was only partially uploaded.``
 
-The message that is displayed if the uploaded file could not be uploaded
-for some unknown reason.
+The message that is displayed if the uploaded file is only partially uploaded.
 
 This message has no parameters.
 
-.. include:: /reference/constraints/_payload-option.rst.inc
-
 .. _`IANA website`: http://www.iana.org/assignments/media-types/index.html
 .. _`Wikipedia: Binary prefix`: http://en.wikipedia.org/wiki/Binary_prefix
diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst
index 3cce0725c90..5dc095bc8b4 100644
--- a/reference/constraints/GreaterThan.rst
+++ b/reference/constraints/GreaterThan.rst
@@ -6,18 +6,16 @@ force that a value is greater than or equal to another value, see
 :doc:`/reference/constraints/GreaterThanOrEqual`. To force a value is less
 than another value, see :doc:`/reference/constraints/LessThan`.
 
-+----------------+---------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                     |
-+----------------+---------------------------------------------------------------------------+
-| Options        | - `value`_                                                                |
-|                | - `message`_                                                              |
-|                | - `payload`_                                                              |
-|                | - `propertyPath`_                                                         |
-+----------------+---------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThan`          |
-+----------------+---------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanValidator` |
-+----------------+---------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThan`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -38,7 +36,6 @@ The following constraints ensure that:
 
         class Person
         {
-
             /**
              * @Assert\GreaterThan(5)
              */
@@ -69,7 +66,7 @@ The following constraints ensure that:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="siblings">
@@ -90,8 +87,8 @@ The following constraints ensure that:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -143,7 +140,7 @@ that a date must at least be the next day:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -157,8 +154,8 @@ that a date must at least be the next day:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -202,7 +199,7 @@ dates. If you want to fix the timezone, append it to the date string:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -216,8 +213,8 @@ dates. If you want to fix the timezone, append it to the date string:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -262,7 +259,7 @@ current time:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -276,8 +273,8 @@ current time:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -290,7 +287,7 @@ current time:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -302,18 +299,18 @@ comparison value.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The lower limit             |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The lower limit
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
 
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
+
 .. _`accepted by the DateTime constructor`: https://php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst
index 6ca05a948e0..7cc99f923a3 100644
--- a/reference/constraints/GreaterThanOrEqual.rst
+++ b/reference/constraints/GreaterThanOrEqual.rst
@@ -5,18 +5,16 @@ Validates that a value is greater than or equal to another value, defined in
 the options. To force that a value is greater than another value, see
 :doc:`/reference/constraints/GreaterThan`.
 
-+----------------+----------------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                            |
-+----------------+----------------------------------------------------------------------------------+
-| Options        | - `value`_                                                                       |
-|                | - `message`_                                                                     |
-|                | - `payload`_                                                                     |
-|                | - `propertyPath`_                                                                |
-+----------------+----------------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqual`          |
-+----------------+----------------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqualValidator` |
-+----------------+----------------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqual`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqualValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -67,7 +65,7 @@ The following constraints ensure that:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="siblings">
@@ -88,8 +86,8 @@ The following constraints ensure that:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -141,7 +139,7 @@ that a date must at least be the current day:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -155,8 +153,8 @@ that a date must at least be the current day:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -200,7 +198,7 @@ dates. If you want to fix the timezone, append it to the date string:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -214,8 +212,8 @@ dates. If you want to fix the timezone, append it to the date string:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -260,7 +258,7 @@ current time:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -274,8 +272,8 @@ current time:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -288,7 +286,7 @@ current time:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -300,18 +298,18 @@ to the comparison value.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The lower limit             |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The lower limit
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
 
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
+
 .. _`accepted by the DateTime constructor`: https://php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/Iban.rst b/reference/constraints/Iban.rst
index bbc0c63794e..cbb4253c834 100644
--- a/reference/constraints/Iban.rst
+++ b/reference/constraints/Iban.rst
@@ -6,21 +6,19 @@ format of an `International Bank Account Number (IBAN)`_. IBAN is an
 internationally agreed means of identifying bank accounts across national
 borders with a reduced risk of propagating transcription errors.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                 |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Iban`             |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IbanValidator`    |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Iban`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IbanValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
-To use the Iban validator, simply apply it to a property on an object that
+To use the Iban validator, apply it to a property on an object that
 will contain an International Bank Account Number.
 
 .. configuration-block::
@@ -57,7 +55,7 @@ will contain an International Bank Account Number.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Transaction">
                 <property name="bankAccountNumber">
@@ -75,8 +73,8 @@ will contain an International Bank Account Number.
         // src/Entity/Transaction.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Transaction
         {
@@ -95,6 +93,8 @@ will contain an International Bank Account Number.
 Available Options
 -----------------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -104,11 +104,11 @@ The default message supplied when the value does not pass the Iban check.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/IdenticalTo.rst b/reference/constraints/IdenticalTo.rst
index 6a5feab562f..481cc60580b 100644
--- a/reference/constraints/IdenticalTo.rst
+++ b/reference/constraints/IdenticalTo.rst
@@ -11,18 +11,16 @@ To force that a value is *not* identical, see
     considered equal. Use :doc:`/reference/constraints/EqualTo` to compare
     with ``==``.
 
-+----------------+--------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                    |
-+----------------+--------------------------------------------------------------------------+
-| Options        | - `value`_                                                               |
-|                | - `message`_                                                             |
-|                | - `payload`_                                                             |
-|                | - `propertyPath`_                                                        |
-+----------------+--------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\IdenticalTo`         |
-+----------------+--------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IdenticalToValidator`|
-+----------------+--------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\IdenticalTo`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IdenticalToValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -73,7 +71,7 @@ The following constraints ensure that:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="firstName">
@@ -94,8 +92,8 @@ The following constraints ensure that:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -112,7 +110,7 @@ The following constraints ensure that:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -123,16 +121,16 @@ This is the message that will be shown if the value is not identical.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The expected value          |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The expected value
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
+
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
diff --git a/reference/constraints/Image.rst b/reference/constraints/Image.rst
index 2c9a6f725f5..57db19c8e93 100644
--- a/reference/constraints/Image.rst
+++ b/reference/constraints/Image.rst
@@ -11,38 +11,40 @@ of the image.
 See the :doc:`File </reference/constraints/File>` constraint for the bulk
 of the documentation on this constraint.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `mimeTypes`_                                                        |
-|                | - `minWidth`_                                                         |
-|                | - `maxWidth`_                                                         |
-|                | - `maxHeight`_                                                        |
-|                | - `minHeight`_                                                        |
-|                | - `maxRatio`_                                                         |
-|                | - `minRatio`_                                                         |
-|                | - `allowSquare`_                                                      |
-|                | - `allowLandscape`_                                                   |
-|                | - `allowPortrait`_                                                    |
-|                | - `detectCorrupted`_                                                  |
-|                | - `mimeTypesMessage`_                                                 |
-|                | - `sizeNotDetectedMessage`_                                           |
-|                | - `maxWidthMessage`_                                                  |
-|                | - `minWidthMessage`_                                                  |
-|                | - `maxHeightMessage`_                                                 |
-|                | - `minHeightMessage`_                                                 |
-|                | - `maxRatioMessage`_                                                  |
-|                | - `minRatioMessage`_                                                  |
-|                | - `allowSquareMessage`_                                               |
-|                | - `allowLandscapeMessage`_                                            |
-|                | - `allowPortraitMessage`_                                             |
-|                | - `corruptedMessage`_                                                 |
-|                | - See :doc:`File </reference/constraints/File>` for inherited options |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Image`            |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\ImageValidator`   |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `allowLandscape`_
+            - `allowLandscapeMessage`_
+            - `allowPortrait`_
+            - `allowPortraitMessage`_
+            - `allowSquare`_
+            - `allowSquareMessage`_
+            - `corruptedMessage`_
+            - `detectCorrupted`_
+            - `groups`_
+            - `maxHeight`_
+            - `maxHeightMessage`_
+            - `maxPixels`_
+            - `maxPixelsMessage`_
+            - `maxRatio`_
+            - `maxRatioMessage`_
+            - `maxWidth`_
+            - `maxWidthMessage`_
+            - `mimeTypes`_
+            - `mimeTypesMessage`_
+            - `minHeight`_
+            - `minHeightMessage`_
+            - `minPixels`_
+            - `minPixelsMessage`_
+            - `minRatio`_
+            - `minRatioMessage`_
+            - `minWidth`_
+            - `minWidthMessage`_
+            - `sizeNotDetectedMessage`_
+            - See :doc:`File </reference/constraints/File>` for inherited options
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Image`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\ImageValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -116,7 +118,7 @@ that it is between a certain size, add the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="headshot">
@@ -135,8 +137,8 @@ that it is between a certain size, add the following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -205,18 +207,16 @@ following code:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            // ...
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('headshot', new Assert\Image([
-                    'allowLandscape'    => false,
-                    'allowPortrait'     => false,
+                    'allowLandscape' => false,
+                    'allowPortrait' => false,
                 ]));
             }
         }
@@ -230,41 +230,100 @@ This constraint shares all of its options with the :doc:`File </reference/constr
 constraint. It does, however, modify two of the default option values and
 add several other options.
 
-mimeTypes
-~~~~~~~~~
+allowLandscape
+~~~~~~~~~~~~~~
 
-**type**: ``array`` or ``string`` **default**: ``image/*``
+**type**: ``Boolean`` **default**: ``true``
 
-You can find a list of existing image mime types on the `IANA website`_.
+If this option is false, the image cannot be landscape oriented.
 
-mimeTypesMessage
-~~~~~~~~~~~~~~~~
+allowLandscapeMessage
+~~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This file is not a valid image.``
+**type**: ``string`` **default**: ``The image is landscape oriented ({{ width }}x{{ height }}px).
+Landscape oriented images are not allowed``
 
-minWidth
-~~~~~~~~
+The error message if the image is landscape oriented and you set `allowLandscape`_ to ``false``.
 
-**type**: ``integer``
+You can use the following parameters in this message:
 
-If set, the width of the image file must be greater than or equal to this
-value in pixels.
+================  =============================================================
+Parameter         Description
+================  =============================================================
+``{{ height }}``  The current height
+``{{ width }}``   The current width
+================  =============================================================
 
-maxWidth
-~~~~~~~~
+allowPortrait
+~~~~~~~~~~~~~
 
-**type**: ``integer``
+**type**: ``Boolean`` **default**: ``true``
 
-If set, the width of the image file must be less than or equal to this
-value in pixels.
+If this option is false, the image cannot be portrait oriented.
 
-minHeight
-~~~~~~~~~
+allowPortraitMessage
+~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``integer``
+**type**: ``string`` **default**: ``The image is portrait oriented ({{ width }}x{{ height }}px).
+Portrait oriented images are not allowed``
 
-If set, the height of the image file must be greater than or equal to this
-value in pixels.
+The error message if the image is portrait oriented and you set `allowPortrait`_ to ``false``.
+
+You can use the following parameters in this message:
+
+================  =============================================================
+Parameter         Description
+================  =============================================================
+``{{ height }}``  The current height
+``{{ width }}``   The current width
+================  =============================================================
+
+allowSquare
+~~~~~~~~~~~
+
+**type**: ``Boolean`` **default**: ``true``
+
+If this option is false, the image cannot be a square. If you want to force
+a square image, then leave this option as its default ``true`` value
+and set `allowLandscape`_ and `allowPortrait`_ both to ``false``.
+
+allowSquareMessage
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``The image is square ({{ width }}x{{ height }}px).
+Square images are not allowed``
+
+The error message if the image is square and you set `allowSquare`_ to ``false``.
+
+You can use the following parameters in this message:
+
+================  =============================================================
+Parameter         Description
+================  =============================================================
+``{{ height }}``  The current height
+``{{ width }}``   The current width
+================  =============================================================
+
+corruptedMessage
+~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``The image file is corrupted.``
+
+The error message when the `detectCorrupted`_ option is enabled and the image
+is corrupted.
+
+This message has no parameters.
+
+detectCorrupted
+~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+If this option is true, the image contents are validated to ensure that the
+image is not corrupted. This validation is done with PHP's :phpfunction:`imagecreatefromstring`
+function, which requires the `PHP GD extension`_ to be enabled.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 maxHeight
 ~~~~~~~~~
@@ -274,13 +333,22 @@ maxHeight
 If set, the height of the image file must be less than or equal to this
 value in pixels.
 
-minPixels
-~~~~~~~~~
+maxHeightMessage
+~~~~~~~~~~~~~~~~
 
-**type**: ``integer``
+**type**: ``string`` **default**: ``The image height is too big ({{ height }}px).
+Allowed maximum height is {{ max_height }}px.``
 
-If set, the amount of pixels of the image file must be greater than or equal to this
-value.
+The error message if the height of the image exceeds `maxHeight`_.
+
+You can use the following parameters in this message:
+
+====================  =========================================================
+Parameter             Description
+====================  =========================================================
+``{{ height }}``      The current (invalid) height
+``{{ max_height }}``  The maximum allowed height
+====================  =========================================================
 
 maxPixels
 ~~~~~~~~~
@@ -290,64 +358,57 @@ maxPixels
 If set, the amount of pixels of the image file must be less than or equal to this
 value.
 
-maxRatio
-~~~~~~~~
+maxPixelsMessage
+~~~~~~~~~~~~~~~~
 
-**type**: ``float``
+**type**: ``string`` **default**: ``The image has to many pixels ({{ pixels }} pixels).
+Maximum amount expected is {{ max_pixels }} pixels.``
 
-If set, the aspect ratio (``width / height``) of the image file must be less
-than or equal to this value.
+The error message if the amount of pixels of the image exceeds `maxPixels`_.
 
-minRatio
+You can use the following parameters in this message:
+
+====================  =========================================================
+Parameter             Description
+====================  =========================================================
+``{{ height }}``      The current image height
+``{{ max_pixels }}``  The maximum allowed amount of pixels
+``{{ pixels }}``      The current amount of pixels
+``{{ width }}``       The current image width
+====================  =========================================================
+
+maxRatio
 ~~~~~~~~
 
 **type**: ``float``
 
-If set, the aspect ratio (``width / height``) of the image file must be greater
+If set, the aspect ratio (``width / height``) of the image file must be less
 than or equal to this value.
 
-allowSquare
-~~~~~~~~~~~
-
-**type**: ``Boolean`` **default**: ``true``
-
-If this option is false, the image cannot be a square. If you want to force
-a square image, then leave this option as its default ``true`` value
-and set `allowLandscape`_ and `allowPortrait`_ both to ``false``.
-
-allowLandscape
-~~~~~~~~~~~~~~
-
-**type**: ``Boolean`` **default**: ``true``
-
-If this option is false, the image cannot be landscape oriented.
-
-allowPortrait
-~~~~~~~~~~~~~
-
-**type**: ``Boolean`` **default**: ``true``
-
-If this option is false, the image cannot be portrait oriented.
-
-detectCorrupted
+maxRatioMessage
 ~~~~~~~~~~~~~~~
 
-**type**: ``boolean`` **default**: ``false``
+**type**: ``string`` **default**: ``The image ratio is too big ({{ ratio }}).
+Allowed maximum ratio is {{ max_ratio }}``
 
-If this option is true, the image contents are validated to ensure that the
-image is not corrupted. This validation is done with PHP's :phpfunction:`imagecreatefromstring`
-function, which requires the `PHP GD extension`_ to be enabled.
+The error message if the aspect ratio of the image exceeds `maxRatio`_.
 
-sizeNotDetectedMessage
-~~~~~~~~~~~~~~~~~~~~~~
+You can use the following parameters in this message:
 
-**type**: ``string`` **default**: ``The size of the image could not be detected.``
+===================  ==========================================================
+Parameter            Description
+===================  ==========================================================
+``{{ max_ratio }}``  The maximum required ratio
+``{{ ratio }}``      The current (invalid) ratio
+===================  ==========================================================
 
-If the system is unable to determine the size of the image, this error will
-be displayed. This will only occur when at least one of the size constraint
-options has been set.
+maxWidth
+~~~~~~~~
 
-This message has no parameters.
+**type**: ``integer``
+
+If set, the width of the image file must be less than or equal to this
+value in pixels.
 
 maxWidthMessage
 ~~~~~~~~~~~~~~~
@@ -359,49 +420,32 @@ The error message if the width of the image exceeds `maxWidth`_.
 
 You can use the following parameters in this message:
 
-+---------------------+-----------------------------+
-| Parameter           | Description                 |
-+=====================+=============================+
-| ``{{ width }}``     | The current (invalid) width |
-+---------------------+-----------------------------+
-| ``{{ max_width }}`` | The maximum allowed width   |
-+---------------------+-----------------------------+
-
-minWidthMessage
-~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``The image width is too small ({{ width }}px).
-Minimum width expected is {{ min_width }}px.``
+===================  ==========================================================
+Parameter            Description
+===================  ==========================================================
+``{{ max_width }}``  The maximum allowed width
+``{{ width }}``      The current (invalid) width
+===================  ==========================================================
 
-The error message if the width of the image is less than `minWidth`_.
+mimeTypes
+~~~~~~~~~
 
-You can use the following parameters in this message:
+**type**: ``array`` or ``string`` **default**: ``image/*``
 
-+---------------------+-----------------------------+
-| Parameter           | Description                 |
-+=====================+=============================+
-| ``{{ width }}``     | The current (invalid) width |
-+---------------------+-----------------------------+
-| ``{{ min_width }}`` | The minimum required width  |
-+---------------------+-----------------------------+
+You can find a list of existing image mime types on the `IANA website`_.
 
-maxHeightMessage
+mimeTypesMessage
 ~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``The image height is too big ({{ height }}px).
-Allowed maximum height is {{ max_height }}px.``
+**type**: ``string`` **default**: ``This file is not a valid image.``
 
-The error message if the height of the image exceeds `maxHeight`_.
+minHeight
+~~~~~~~~~
 
-You can use the following parameters in this message:
+**type**: ``integer``
 
-+----------------------+------------------------------+
-| Parameter            | Description                  |
-+======================+==============================+
-| ``{{ height }}``     | The current (invalid) height |
-+----------------------+------------------------------+
-| ``{{ max_height }}`` | The maximum allowed height   |
-+----------------------+------------------------------+
+If set, the height of the image file must be greater than or equal to this
+value in pixels.
 
 minHeightMessage
 ~~~~~~~~~~~~~~~~
@@ -413,35 +457,20 @@ The error message if the height of the image is less than `minHeight`_.
 
 You can use the following parameters in this message:
 
-+----------------------+------------------------------+
-| Parameter            | Description                  |
-+======================+==============================+
-| ``{{ height }}``     | The current (invalid) height |
-+----------------------+------------------------------+
-| ``{{ min_height }}`` | The minimum required height  |
-+----------------------+------------------------------+
-
-maxPixelsMessage
-~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``The image has to many pixels ({{ pixels }} pixels).
-Maximum amount expected is {{ max_pixels }} pixels.``
+====================  =========================================================
+Parameter             Description
+====================  =========================================================
+``{{ height }}``      The current (invalid) height
+``{{ min_height }}``  The minimum required height
+====================  =========================================================
 
-The error message if the amount of pixels of the image exceeds `maxPixels`_.
+minPixels
+~~~~~~~~~
 
-You can use the following parameters in this message:
+**type**: ``integer``
 
-+----------------------+---------------------------------------+
-| Parameter            | Description                           |
-+======================+=======================================+
-| ``{{ pixels }}``     | The current amount of pixels          |
-+----------------------+---------------------------------------+
-| ``{{ max_pixels }}`` | The maximum allowed amount of pixels  |
-+----------------------+---------------------------------------+
-| ``{{ height }}``     | The current image height              |
-+----------------------+---------------------------------------+
-| ``{{ width }}``      | The current image width               |
-+----------------------+---------------------------------------+
+If set, the amount of pixels of the image file must be greater than or equal to this
+value.
 
 minPixelsMessage
 ~~~~~~~~~~~~~~~~
@@ -453,35 +482,22 @@ The error message if the amount of pixels of the image is less than `minPixels`_
 
 You can use the following parameters in this message:
 
-+----------------------+---------------------------------------+
-| Parameter            | Description                           |
-+======================+=======================================+
-| ``{{ pixels }}``     | The current amount of pixels          |
-+----------------------+---------------------------------------+
-| ``{{ min_pixels }}`` | The minimum required amount of pixels |
-+----------------------+---------------------------------------+
-| ``{{ height }}``     | The current image height              |
-+----------------------+---------------------------------------+
-| ``{{ width }}``      | The current image width               |
-+----------------------+---------------------------------------+
+====================  =========================================================
+Parameter             Description
+====================  =========================================================
+``{{ height }}``      The current image height
+``{{ min_pixels }}``  The minimum required amount of pixels
+``{{ pixels }}``      The current amount of pixels
+``{{ width }}``       The current image width
+====================  =========================================================
 
-maxRatioMessage
-~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``The image ratio is too big ({{ ratio }}).
-Allowed maximum ratio is {{ max_ratio }}``
-
-The error message if the aspect ratio of the image exceeds `maxRatio`_.
+minRatio
+~~~~~~~~
 
-You can use the following parameters in this message:
+**type**: ``float``
 
-+---------------------+-----------------------------+
-| Parameter           | Description                 |
-+=====================+=============================+
-| ``{{ ratio }}``     | The current (invalid) ratio |
-+---------------------+-----------------------------+
-| ``{{ max_ratio }}`` | The maximum allowed ratio   |
-+---------------------+-----------------------------+
+If set, the aspect ratio (``width / height``) of the image file must be greater
+than or equal to this value.
 
 minRatioMessage
 ~~~~~~~~~~~~~~~
@@ -493,75 +509,46 @@ The error message if the aspect ratio of the image is less than `minRatio`_.
 
 You can use the following parameters in this message:
 
-+---------------------+-----------------------------+
-| Parameter           | Description                 |
-+=====================+=============================+
-| ``{{ ratio }}``     | The current (invalid) ratio |
-+---------------------+-----------------------------+
-| ``{{ min_ratio }}`` | The minimum required ratio  |
-+---------------------+-----------------------------+
-
-allowSquareMessage
-~~~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``The image is square ({{ width }}x{{ height }}px).
-Square images are not allowed``
-
-The error message if the image is square and you set `allowSquare`_ to ``false``.
-
-You can use the following parameters in this message:
-
-+------------------+--------------------+
-| Parameter        | Description        |
-+==================+====================+
-| ``{{ width }}``  | The current width  |
-+------------------+--------------------+
-| ``{{ height }}`` | The current height |
-+------------------+--------------------+
+===================  ==========================================================
+Parameter            Description
+===================  ==========================================================
+``{{ min_ratio }}``  The minimum required ratio
+``{{ ratio }}``      The current (invalid) ratio
+===================  ==========================================================
 
-allowLandscapeMessage
-~~~~~~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``The image is landscape oriented ({{ width }}x{{ height }}px).
-Landscape oriented images are not allowed``
-
-The error message if the image is landscape oriented and you set `allowLandscape`_ to ``false``.
+minWidth
+~~~~~~~~
 
-You can use the following parameters in this message:
+**type**: ``integer``
 
-+------------------+--------------------+
-| Parameter        | Description        |
-+==================+====================+
-| ``{{ width }}``  | The current width  |
-+------------------+--------------------+
-| ``{{ height }}`` | The current height |
-+------------------+--------------------+
+If set, the width of the image file must be greater than or equal to this
+value in pixels.
 
-allowPortraitMessage
-~~~~~~~~~~~~~~~~~~~~
+minWidthMessage
+~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``The image is portrait oriented ({{ width }}x{{ height }}px).
-Portrait oriented images are not allowed``
+**type**: ``string`` **default**: ``The image width is too small ({{ width }}px).
+Minimum width expected is {{ min_width }}px.``
 
-The error message if the image is portrait oriented and you set `allowPortrait`_ to ``false``.
+The error message if the width of the image is less than `minWidth`_.
 
 You can use the following parameters in this message:
 
-+------------------+--------------------+
-| Parameter        | Description        |
-+==================+====================+
-| ``{{ width }}``  | The current width  |
-+------------------+--------------------+
-| ``{{ height }}`` | The current height |
-+------------------+--------------------+
+===================  ==========================================================
+Parameter            Description
+===================  ==========================================================
+``{{ min_width }}``  The minimum required width
+``{{ width }}``      The current (invalid) width
+===================  ==========================================================
 
-corruptedMessage
-~~~~~~~~~~~~~~~~
+sizeNotDetectedMessage
+~~~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``The image file is corrupted.``
+**type**: ``string`` **default**: ``The size of the image could not be detected.``
 
-The error message when the `detectCorrupted`_ option is enabled and the image
-is corrupted.
+If the system is unable to determine the size of the image, this error will
+be displayed. This will only occur when at least one of the size constraint
+options has been set.
 
 This message has no parameters.
 
diff --git a/reference/constraints/Ip.rst b/reference/constraints/Ip.rst
index 228f8cdcd62..60865c024bc 100644
--- a/reference/constraints/Ip.rst
+++ b/reference/constraints/Ip.rst
@@ -5,17 +5,16 @@ Validates that a value is a valid IP address. By default, this will validate
 the value as IPv4, but a number of different options exist to validate as
 IPv6 and many other combinations.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `version`_                                                        |
-|                | - `message`_                                                        |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Ip`             |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IpValidator`    |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `normalizer`_
+            - `payload`_
+            - `version`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Ip`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IpValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -34,7 +33,7 @@ Basic Usage
             /**
              * @Assert\Ip
              */
-             protected $ipAddress;
+            protected $ipAddress;
         }
 
     .. code-block:: yaml
@@ -51,11 +50,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="ipAddress">
-                    <constraint name="Ip" />
+                    <constraint name="Ip"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -65,8 +64,8 @@ Basic Usage
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -81,6 +80,27 @@ Basic Usage
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This is not a valid IP address.``
+
+This message is shown if the string is not a valid IP address.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_normalizer-option.rst.inc
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
 version
 ~~~~~~~
 
@@ -124,20 +144,3 @@ of a variety of different values:
     Validates for IPv6 but without private and reserved ranges
 ``all_public``
     Validates for all IP formats but without private and reserved ranges
-
-message
-~~~~~~~
-
-**type**: ``string`` **default**: ``This is not a valid IP address.``
-
-This message is shown if the string is not a valid IP address.
-
-You can use the following parameters in this message:
-
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-
-.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/IsFalse.rst b/reference/constraints/IsFalse.rst
index 365b858e6eb..6a8e948177b 100644
--- a/reference/constraints/IsFalse.rst
+++ b/reference/constraints/IsFalse.rst
@@ -7,16 +7,14 @@ string "``0``".
 
 Also see :doc:`IsTrue <IsTrue>`.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\IsFalse`          |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IsFalseValidator` |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\IsFalse`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IsFalseValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -54,10 +52,10 @@ method returns **false**:
              *     message = "You've entered an invalid state."
              * )
              */
-             public function isStateInvalid()
-             {
+            public function isStateInvalid()
+            {
                 // ...
-             }
+            }
         }
 
     .. code-block:: yaml
@@ -75,7 +73,7 @@ method returns **false**:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <getter property="stateInvalid">
@@ -91,20 +89,29 @@ method returns **false**:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addGetterConstraint('stateInvalid', new Assert\IsFalse());
+                $metadata->addGetterConstraint('stateInvalid', new Assert\IsFalse([
+                    'message' => 'You've entered an invalid state.',
+                ]));
             }
         }
 
+        public function isStateInvalid()
+        {
+            // ...
+        }
+
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -114,10 +121,10 @@ This message is shown if the underlying data is not false.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/IsNull.rst b/reference/constraints/IsNull.rst
index 5c11b362053..466e6d33beb 100644
--- a/reference/constraints/IsNull.rst
+++ b/reference/constraints/IsNull.rst
@@ -2,21 +2,19 @@ IsNull
 ======
 
 Validates that a value is exactly equal to ``null``. To force that a property
-is simply blank (blank string or ``null``), see the  :doc:`/reference/constraints/Blank`
+is blank (blank string or ``null``), see the  :doc:`/reference/constraints/Blank`
 constraint. To ensure that a property is not null, see :doc:`/reference/constraints/NotNull`.
 
 Also see :doc:`NotNull <NotNull>`.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\IsNull`           |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IsNullValidator`  |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\IsNull`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IsNullValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -55,11 +53,11 @@ of an ``Author`` class exactly equal to ``null``, you could do the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
-                    <constraint name="IsNull" />
+                    <constraint name="IsNull"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -69,8 +67,8 @@ of an ``Author`` class exactly equal to ``null``, you could do the following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -83,6 +81,8 @@ of an ``Author`` class exactly equal to ``null``, you could do the following:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -92,10 +92,10 @@ This is the message that will be shown if the value is not ``null``.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/IsTrue.rst b/reference/constraints/IsTrue.rst
index f7bd1ff0832..d00c75dbcac 100644
--- a/reference/constraints/IsTrue.rst
+++ b/reference/constraints/IsTrue.rst
@@ -7,16 +7,14 @@ string "``1``".
 
 Also see :doc:`IsFalse <IsFalse>`.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `message`_                                                        |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\IsTrue`         |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IsTrueValidator`|
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\IsTrue`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IsTrueValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -55,7 +53,7 @@ Then you can constrain this method with ``IsTrue``.
             protected $token;
 
             /**
-             * @Assert\IsTrue(message="The token is invalid")
+             * @Assert\IsTrue(message="The token is invalid.")
              */
             public function isTokenValid()
             {
@@ -74,11 +72,11 @@ Then you can constrain this method with ``IsTrue``.
 
     .. code-block:: xml
 
-        <!-- src/Acme/Blogbundle/Resources/config/validation.xml -->
+        <!-- config/validator/validation.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <getter property="tokenValid">
@@ -94,13 +92,11 @@ Then you can constrain this method with ``IsTrue``.
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints\IsTrue;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            protected $token;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addGetterConstraint('tokenValid', new IsTrue([
@@ -119,6 +115,8 @@ If the ``isTokenValid()`` returns false, the validation will fail.
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -128,10 +126,10 @@ This message is shown if the underlying data is not true.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Isbn.rst b/reference/constraints/Isbn.rst
index 26d91f1e6db..d2ad1e2c909 100644
--- a/reference/constraints/Isbn.rst
+++ b/reference/constraints/Isbn.rst
@@ -4,25 +4,23 @@ Isbn
 This constraint validates that an `International Standard Book Number (ISBN)`_
 is either a valid ISBN-10 or a valid ISBN-13.
 
-+----------------+----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                |
-+----------------+----------------------------------------------------------------------+
-| Options        | - `type`_                                                            |
-|                | - `message`_                                                         |
-|                | - `isbn10Message`_                                                   |
-|                | - `isbn13Message`_                                                   |
-|                | - `bothIsbnMessage`_                                                 |
-|                | - `payload`_                                                         |
-+----------------+----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Isbn`            |
-+----------------+----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IsbnValidator`   |
-+----------------+----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `bothIsbnMessage`_
+            - `groups`_
+            - `isbn10Message`_
+            - `isbn13Message`_
+            - `message`_
+            - `payload`_
+            - `type`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Isbn`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IsbnValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
-To use the ``Isbn`` validator, simply apply it to a property or method
+To use the ``Isbn`` validator, apply it to a property or method
 on an object that will contain an ISBN.
 
 .. configuration-block::
@@ -61,7 +59,7 @@ on an object that will contain an ISBN.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Book">
                 <property name="isbn">
@@ -78,17 +76,15 @@ on an object that will contain an ISBN.
         // src/Entity/Book.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Book
         {
-            protected $isbn;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('isbn', new Assert\Isbn([
-                    'type'    => 'isbn10',
+                    'type' => 'isbn10',
                     'message' => 'This value is not valid.',
                 ]));
             }
@@ -99,29 +95,23 @@ on an object that will contain an ISBN.
 Available Options
 -----------------
 
-type
-~~~~
-
-**type**: ``string`` **default**: ``null``
-
-The type of ISBN to validate against. Valid values are ``isbn10``, ``isbn13``
-and ``null`` to accept any kind of ISBN.
-
-message
-~~~~~~~
+bothIsbnMessage
+~~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``null``
+**type**: ``string`` **default**: ``This value is neither a valid ISBN-10 nor a valid ISBN-13.``
 
-The message that will be shown if the value is not valid. If not ``null``,
-this message has priority over all the other messages.
+The message that will be shown if the `type`_ option is ``null`` and the given
+value does not pass any of the ISBN checks.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 isbn10Message
 ~~~~~~~~~~~~~
@@ -133,11 +123,11 @@ value does not pass the ISBN-10 check.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 isbn13Message
 ~~~~~~~~~~~~~
@@ -149,28 +139,36 @@ value does not pass the ISBN-13 check.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
-bothIsbnMessage
-~~~~~~~~~~~~~~~
+message
+~~~~~~~
 
-**type**: ``string`` **default**: ``This value is neither a valid ISBN-10 nor a valid ISBN-13.``
+**type**: ``string`` **default**: ``null``
 
-The message that will be shown if the `type`_ option is ``null`` and the given
-value does not pass any of the ISBN checks.
+The message that will be shown if the value is not valid. If not ``null``,
+this message has priority over all the other messages.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
+type
+~~~~
+
+**type**: ``string`` **default**: ``null``
+
+The type of ISBN to validate against. Valid values are ``isbn10``, ``isbn13``
+and ``null`` to accept any kind of ISBN.
+
 .. _`International Standard Book Number (ISBN)`: https://en.wikipedia.org/wiki/Isbn
diff --git a/reference/constraints/Issn.rst b/reference/constraints/Issn.rst
index d3f8fbe17bb..374cc7d2751 100644
--- a/reference/constraints/Issn.rst
+++ b/reference/constraints/Issn.rst
@@ -4,18 +4,16 @@ Issn
 Validates that a value is a valid
 `International Standard Serial Number (ISSN)`_.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                 |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `caseSensitive`_                                                    |
-|                | - `requireHyphen`_                                                    |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Issn`             |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\IssnValidator`    |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `caseSensitive`_
+            - `groups`_
+            - `message`_
+            - `payload`_
+            - `requireHyphen`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Issn`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\IssnValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -34,7 +32,7 @@ Basic Usage
             /**
              * @Assert\Issn
              */
-             protected $issn;
+            protected $issn;
         }
 
     .. code-block:: yaml
@@ -51,11 +49,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Journal">
                 <property name="issn">
-                    <constraint name="Issn" />
+                    <constraint name="Issn"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -65,8 +63,8 @@ Basic Usage
         // src/Entity/Journal.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Journal
         {
@@ -81,28 +79,32 @@ Basic Usage
 Options
 -------
 
+caseSensitive
+~~~~~~~~~~~~~
+
+**type**: ``boolean`` default: ``false``
+
+The validator will allow ISSN values to end with a lower case 'x' by default.
+When switching this to ``true``, the validator requires an upper case 'X'.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
-**type**: ``String`` default: ``This value is not a valid ISSN.``
+**type**: ``string`` default: ``This value is not a valid ISSN.``
 
 The message shown if the given value is not a valid ISSN.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
-caseSensitive
-~~~~~~~~~~~~~
-
-**type**: ``boolean`` default: ``false``
-
-The validator will allow ISSN values to end with a lower case 'x' by default.
-When switching this to ``true``, the validator requires an upper case 'X'.
+.. include:: /reference/constraints/_payload-option.rst.inc
 
 requireHyphen
 ~~~~~~~~~~~~~
@@ -112,6 +114,4 @@ requireHyphen
 The validator will allow non hyphenated ISSN values by default. When switching
 this to ``true``, the validator requires a hyphenated ISSN value.
 
-.. include:: /reference/constraints/_payload-option.rst.inc
-
 .. _`International Standard Serial Number (ISSN)`: https://en.wikipedia.org/wiki/Issn
diff --git a/reference/constraints/Json.rst b/reference/constraints/Json.rst
new file mode 100644
index 00000000000..beac690c4f9
--- /dev/null
+++ b/reference/constraints/Json.rst
@@ -0,0 +1,97 @@
+Json
+====
+
+Validates that a value has valid `JSON`_ syntax.
+
++----------------+-----------------------------------------------------------------------+
+| Applies to     | :ref:`property or method <validation-property-target>`                |
++----------------+-----------------------------------------------------------------------+
+| Options        | - `message`_                                                          |
+|                | - `payload`_                                                          |
++----------------+-----------------------------------------------------------------------+
+| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Json`             |
++----------------+-----------------------------------------------------------------------+
+| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\JsonValidator`    |
++----------------+-----------------------------------------------------------------------+
+
+Basic Usage
+-----------
+
+The ``Json`` constraint can be applied to a property or a "getter" method:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Book.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Book
+        {
+            /**
+             * @Assert\Json(
+             *     message = "You've entered an invalid Json."
+             * )
+             */
+            private $chapters;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Book:
+            properties:
+                chapters:
+                    - Json:
+                        message: You've entered an invalid Json.
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\Book">
+                <property name="chapters">
+                    <constraint name="Json">
+                        <option name="message">You've entered an invalid Json.</option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Book.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Book
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('chapters', new Assert\Json([
+                    'message' => 'You\'ve entered an invalid Json.',
+                ]));
+            }
+        }
+
+Options
+-------
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be valid JSON.``
+
+This message is shown if the underlying data is not a valid JSON value.
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+.. _`JSON`: https://en.wikipedia.org/wiki/JSON
diff --git a/reference/constraints/Language.rst b/reference/constraints/Language.rst
index f12fc44498e..af2b8ce98f9 100644
--- a/reference/constraints/Language.rst
+++ b/reference/constraints/Language.rst
@@ -4,16 +4,14 @@ Language
 Validates that a value is a valid language *Unicode language identifier*
 (e.g. ``fr`` or ``zh-Hant``).
 
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `message`_                                                           |
-|                | - `payload`_                                                           |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Language`          |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LanguageValidator` |
-+----------------+------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Language`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LanguageValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -32,7 +30,7 @@ Basic Usage
             /**
              * @Assert\Language
              */
-             protected $preferredLanguage;
+            protected $preferredLanguage;
         }
 
     .. code-block:: yaml
@@ -49,11 +47,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="preferredLanguage">
-                    <constraint name="Language" />
+                    <constraint name="Language"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -63,8 +61,8 @@ Basic Usage
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
@@ -79,6 +77,8 @@ Basic Usage
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -88,10 +88,10 @@ This message is shown if the string is not a valid language code.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Length.rst b/reference/constraints/Length.rst
index 3cb47d4470b..88ef1040b70 100644
--- a/reference/constraints/Length.rst
+++ b/reference/constraints/Length.rst
@@ -9,22 +9,21 @@ Validates that a given string length is *between* some minimum and maximum value
     also add the :doc:`/reference/constraints/NotBlank` or :doc:`/reference/constraints/NotNull`
     constraints to validate against these.
 
-+----------------+----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`               |
-+----------------+----------------------------------------------------------------------+
-| Options        | - `min`_                                                             |
-|                | - `max`_                                                             |
-|                | - `charset`_                                                         |
-|                | - `minMessage`_                                                      |
-|                | - `maxMessage`_                                                      |
-|                | - `exactMessage`_                                                    |
-|                | - `charsetMessage`_                                                  |
-|                | - `payload`_                                                         |
-+----------------+----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Length`          |
-+----------------+----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LengthValidator` |
-+----------------+----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `charset`_
+            - `charsetMessage`_
+            - `exactMessage`_
+            - `groups`_
+            - `max`_
+            - `maxMessage`_
+            - `min`_
+            - `minMessage`_
+            - `normalizer`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Length`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LengthValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -51,7 +50,7 @@ and "50", you might add the following:
              *      maxMessage = "Your first name cannot be longer than {{ limit }} characters"
              * )
              */
-             protected $firstName;
+            protected $firstName;
         }
 
     .. code-block:: yaml
@@ -72,7 +71,7 @@ and "50", you might add the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Participant">
                 <property name="firstName">
@@ -95,16 +94,16 @@ and "50", you might add the following:
         // src/Entity/Participant.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Participant
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('firstName', new Assert\Length([
-                    'min'        => 2,
-                    'max'        => 50,
+                    'min' => 2,
+                    'max' => 50,
                     'minMessage' => 'Your first name must be at least {{ limit }} characters long',
                     'maxMessage' => 'Your first name cannot be longer than {{ limit }} characters',
                 ]));
@@ -116,53 +115,57 @@ and "50", you might add the following:
 Options
 -------
 
-min
-~~~
+charset
+~~~~~~~
 
-**type**: ``integer``
+**type**: ``string``  **default**: ``UTF-8``
 
-This required option is the "min" length value. Validation will fail if
-the given value's length is **less** than this min value.
+The charset to be used when computing value's length with the
+:phpfunction:`mb_check_encoding` and :phpfunction:`mb_strlen`
+PHP functions.
 
-It is important to notice that NULL values and empty strings are considered
-valid no matter if the constraint required a minimum length. Validators
-are triggered only if the value is not blank.
+charsetMessage
+~~~~~~~~~~~~~~
 
-max
-~~~
+**type**: ``string`` **default**: ``This value does not match the expected {{ charset }} charset.``
 
-**type**: ``integer``
+The message that will be shown if the value is not using the given `charset`_.
 
-This required option is the "max" length value. Validation will fail if
-the given value's length is **greater** than this max value.
+You can use the following parameters in this message:
 
-charset
-~~~~~~~
+=================  ============================================================
+Parameter          Description
+=================  ============================================================
+``{{ charset }}``  The expected charset
+``{{ value }}``    The current (invalid) value
+=================  ============================================================
 
-**type**: ``string``  **default**: ``UTF-8``
+exactMessage
+~~~~~~~~~~~~
 
-The charset to be used when computing value's length. The
-:phpfunction:`grapheme_strlen` PHP function is used if available. If not,
-the :phpfunction:`mb_strlen` PHP function is used if available. If neither
-are available, the :phpfunction:`strlen` PHP function is used.
+**type**: ``string`` **default**: ``This value should have exactly {{ limit }} characters.``
 
-minMessage
-~~~~~~~~~~
+The message that will be shown if min and max values are equal and the underlying
+value's length is not exactly this value.
 
-**type**: ``string`` **default**: ``This value is too short. It should have {{ limit }} characters or more.``
+You can use the following parameters in this message:
 
-The message that will be shown if the underlying value's length is less
-than the `min`_ option.
+=================  ============================================================
+Parameter          Description
+=================  ============================================================
+``{{ limit }}``    The exact expected length
+``{{ value }}``    The current (invalid) value
+=================  ============================================================
 
-You can use the following parameters in this message:
+.. include:: /reference/constraints/_groups-option.rst.inc
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-| ``{{ limit }}`` | The expected minimum length |
-+-----------------+-----------------------------+
+max
+~~~
+
+**type**: ``integer``
+
+This required option is the "max" length value. Validation will fail if
+the given value's length is **greater** than this max value.
 
 maxMessage
 ~~~~~~~~~~
@@ -174,47 +177,42 @@ than the `max`_ option.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-| ``{{ limit }}`` | The expected maximum length |
-+-----------------+-----------------------------+
+=================  ============================================================
+Parameter          Description
+=================  ============================================================
+``{{ limit }}``    The expected maximum length
+``{{ value }}``    The current (invalid) value
+=================  ============================================================
 
-exactMessage
-~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``This value should have exactly {{ limit }} characters.``
+min
+~~~
 
-The message that will be shown if min and max values are equal and the underlying
-value's length is not exactly this value.
+**type**: ``integer``
 
-You can use the following parameters in this message:
+This required option is the "min" length value. Validation will fail if
+the given value's length is **less** than this min value.
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-| ``{{ limit }}`` | The exact expected length   |
-+-----------------+-----------------------------+
+It is important to notice that NULL values and empty strings are considered
+valid no matter if the constraint required a minimum length. Validators
+are triggered only if the value is not blank.
 
-charsetMessage
-~~~~~~~~~~~~~~
+minMessage
+~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value does not match the expected {{ charset }} charset.``
+**type**: ``string`` **default**: ``This value is too short. It should have {{ limit }} characters or more.``
 
-The message that will be shown if the value is not using the given `charset`_.
+The message that will be shown if the underlying value's length is less
+than the `min`_ option.
 
 You can use the following parameters in this message:
 
-+-------------------+-----------------------------+
-| Parameter         | Description                 |
-+===================+=============================+
-| ``{{ value }}``   | The current (invalid) value |
-+-------------------+-----------------------------+
-| ``{{ charset }}`` | The expected charset        |
-+-------------------+-----------------------------+
+=================  ============================================================
+Parameter          Description
+=================  ============================================================
+``{{ limit }}``    The expected minimum length
+``{{ value }}``    The current (invalid) value
+=================  ============================================================
+
+.. include:: /reference/constraints/_normalizer-option.rst.inc
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst
index 29efd83455b..950d3afbc68 100644
--- a/reference/constraints/LessThan.rst
+++ b/reference/constraints/LessThan.rst
@@ -6,18 +6,16 @@ force that a value is less than or equal to another value, see
 :doc:`/reference/constraints/LessThanOrEqual`. To force a value is greater
 than another value, see :doc:`/reference/constraints/GreaterThan`.
 
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                  |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `value`_                                                             |
-|                | - `message`_                                                           |
-|                | - `payload`_                                                           |
-|                | - `propertyPath`_                                                      |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\LessThan`          |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LessThanValidator` |
-+----------------+------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\LessThan`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LessThanValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -38,7 +36,6 @@ The following constraints ensure that:
 
         class Person
         {
-
             /**
              * @Assert\LessThan(5)
              */
@@ -69,7 +66,7 @@ The following constraints ensure that:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="siblings">
@@ -90,8 +87,8 @@ The following constraints ensure that:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -143,7 +140,7 @@ that a date must be in the past like this:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="dateOfBirth">
@@ -157,8 +154,8 @@ that a date must be in the past like this:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -202,7 +199,7 @@ dates. If you want to fix the timezone, append it to the date string:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="dateOfBirth">
@@ -216,8 +213,8 @@ dates. If you want to fix the timezone, append it to the date string:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -261,7 +258,7 @@ can check that a person must be at least 18 years old like this:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="dateOfBirth">
@@ -275,8 +272,8 @@ can check that a person must be at least 18 years old like this:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -289,7 +286,7 @@ can check that a person must be at least 18 years old like this:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -301,18 +298,18 @@ comparison value.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The upper limit             |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The upper limit
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
 
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
+
 .. _`accepted by the DateTime constructor`: https://php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst
index 8a18b826fc4..af818380b35 100644
--- a/reference/constraints/LessThanOrEqual.rst
+++ b/reference/constraints/LessThanOrEqual.rst
@@ -5,18 +5,16 @@ Validates that a value is less than or equal to another value, defined in the
 options. To force that a value is less than another value, see
 :doc:`/reference/constraints/LessThan`.
 
-+----------------+-------------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                         |
-+----------------+-------------------------------------------------------------------------------+
-| Options        | - `value`_                                                                    |
-|                | - `message`_                                                                  |
-|                | - `payload`_                                                                  |
-|                | - `propertyPath`_                                                             |
-+----------------+-------------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqual`          |
-+----------------+-------------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqualValidator` |
-+----------------+-------------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqual`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqualValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -67,7 +65,7 @@ The following constraints ensure that:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="siblings">
@@ -88,8 +86,8 @@ The following constraints ensure that:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -124,7 +122,7 @@ that a date must be today or in the past like this:
             /**
              * @Assert\LessThanOrEqual("today")
              */
-            protected $age;
+            protected $dateOfBirth;
         }
 
     .. code-block:: yaml
@@ -132,7 +130,7 @@ that a date must be today or in the past like this:
         # config/validator/validation.yaml
         App\Entity\Person:
             properties:
-                age:
+                dateOfBirth:
                     - LessThanOrEqual: today
 
     .. code-block:: xml
@@ -141,10 +139,10 @@ that a date must be today or in the past like this:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
-                <property name="age">
+                <property name="dateOfBirth">
                     <constraint name="LessThanOrEqual">today</constraint>
                 </property>
             </class>
@@ -155,14 +153,14 @@ that a date must be today or in the past like this:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('today'));
+                $metadata->addPropertyConstraint('dateOfBirth', new Assert\LessThanOrEqual('today'));
             }
         }
 
@@ -183,7 +181,7 @@ dates. If you want to fix the timezone, append it to the date string:
             /**
              * @Assert\LessThanOrEqual("today UTC")
              */
-            protected $age;
+            protected $dateOfBirth;
         }
 
     .. code-block:: yaml
@@ -191,7 +189,7 @@ dates. If you want to fix the timezone, append it to the date string:
         # config/validator/validation.yaml
         App\Entity\Person:
             properties:
-                age:
+                dateOfBirth:
                     - LessThanOrEqual: today UTC
 
     .. code-block:: xml
@@ -200,10 +198,10 @@ dates. If you want to fix the timezone, append it to the date string:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
-                <property name="age">
+                <property name="dateOfBirth">
                     <constraint name="LessThanOrEqual">today UTC</constraint>
                 </property>
             </class>
@@ -214,14 +212,14 @@ dates. If you want to fix the timezone, append it to the date string:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('today UTC'));
+                $metadata->addPropertyConstraint('dateOfBirth', new Assert\LessThanOrEqual('today UTC'));
             }
         }
 
@@ -242,7 +240,7 @@ can check that a person must be at least 18 years old like this:
             /**
              * @Assert\LessThanOrEqual("-18 years")
              */
-            protected $age;
+            protected $dateOfBirth;
         }
 
     .. code-block:: yaml
@@ -250,7 +248,7 @@ can check that a person must be at least 18 years old like this:
         # config/validator/validation.yaml
         App\Entity\Person:
             properties:
-                age:
+                dateOfBirth:
                     - LessThanOrEqual: -18 years
 
     .. code-block:: xml
@@ -259,10 +257,10 @@ can check that a person must be at least 18 years old like this:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
-                <property name="age">
+                <property name="dateOfBirth">
                     <constraint name="LessThanOrEqual">-18 years</constraint>
                 </property>
             </class>
@@ -273,21 +271,21 @@ can check that a person must be at least 18 years old like this:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('-18 years'));
+                $metadata->addPropertyConstraint('dateOfBirth', new Assert\LessThanOrEqual('-18 years'));
             }
         }
 
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -299,18 +297,18 @@ to the comparison value.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The upper limit             |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The upper limit
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
 
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
+
 .. _`accepted by the DateTime constructor`: https://php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/Locale.rst b/reference/constraints/Locale.rst
index ef53e6e9c1d..8887124a153 100644
--- a/reference/constraints/Locale.rst
+++ b/reference/constraints/Locale.rst
@@ -8,17 +8,15 @@ the two letter `ISO 639-1`_ *language* code (e.g. ``fr``), or the language code
 followed by an underscore (``_``) and the `ISO 3166-1 alpha-2`_ *country* code
 (e.g. ``fr_FR`` for French/France).
 
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `message`_                                                           |
-|                | - `payload`_                                                           |
-|                | - `canonicalize`_                                                      |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Locale`            |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LocaleValidator`   |
-+----------------+------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `canonicalize`_
+            - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Locale`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LocaleValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -39,7 +37,7 @@ Basic Usage
              *     canonicalize = true
              * )
              */
-             protected $locale;
+            protected $locale;
         }
 
     .. code-block:: yaml
@@ -57,7 +55,7 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="locale">
@@ -73,14 +71,16 @@ Basic Usage
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addPropertyConstraint('locale', new Assert\Locale(['canonicalize' => true]));
+                $metadata->addPropertyConstraint('locale', new Assert\Locale([
+                    'canonicalize' => true,
+                ]));
             }
         }
 
@@ -89,6 +89,21 @@ Basic Usage
 Options
 -------
 
+canonicalize
+~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. deprecated:: 4.1
+
+    Using this option with value ``false`` was deprecated in Symfony 4.1 and it
+    will throw an exception in Symfony 5.0. Use ``true`` instead.
+
+If ``true``, the :phpmethod:`Locale::canonicalize` method will be applied before checking
+the validity of the given locale (e.g. ``FR-fr.utf8`` is transformed into ``fr_FR``).
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -98,26 +113,14 @@ This message is shown if the string is not a valid locale.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
-canonicalize
-~~~~~~~~~~~~
-
-**type**: ``boolean`` **default**: ``false``
-
-.. versionadded:: 4.1
-    Using this option with value ``false`` was deprecated in Symfony 4.1 and it
-    will throw an exception in Symfony 5.0. Use ``true`` instead.
-
-If ``true``, the :phpmethod:`Locale::canonicalize` method will be applied before checking
-the validity of the given locale (e.g. ``FR-fr.utf8`` is transformed into ``fr_FR``).
-
 .. _`ICU format locale IDs`: http://userguide.icu-project.org/locale
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
diff --git a/reference/constraints/Luhn.rst b/reference/constraints/Luhn.rst
index 7fee5047299..39139d360d3 100644
--- a/reference/constraints/Luhn.rst
+++ b/reference/constraints/Luhn.rst
@@ -5,21 +5,19 @@ This constraint is used to ensure that a credit card number passes the
 `Luhn algorithm`_. It is useful as a first step to validating a credit
 card: before communicating with a payment gateway.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Luhn`             |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LuhnValidator`    |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Luhn`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LuhnValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
-To use the Luhn validator, simply apply it to a property on an object that
+To use the Luhn validator, apply it to a property on an object that
 will contain a credit card number.
 
 .. configuration-block::
@@ -54,7 +52,7 @@ will contain a credit card number.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Transaction">
                 <property name="cardNumber">
@@ -70,13 +68,11 @@ will contain a credit card number.
         // src/Entity/Transaction.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Transaction
         {
-            protected $cardNumber;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('cardNumber', new Assert\Luhn([
@@ -90,6 +86,8 @@ will contain a credit card number.
 Available Options
 -----------------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -99,11 +97,11 @@ The default message supplied when the value does not pass the Luhn check.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/Negative.rst b/reference/constraints/Negative.rst
new file mode 100644
index 00000000000..4e3edee87f2
--- /dev/null
+++ b/reference/constraints/Negative.rst
@@ -0,0 +1,105 @@
+Negative
+========
+
+.. versionadded:: 4.3
+
+    The ``Negative`` constraint was introduced in Symfony 4.3.
+
+Validates that a value is a negative number. Zero is neither positive nor
+negative, so you must use :doc:`/reference/constraints/NegativeOrZero` if you
+want to allow zero as value.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Negative`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LesserThanValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraint ensures that the ``withdraw`` of a  bank account
+``TransferItem`` is a negative number (lesser than zero):
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/TransferItem.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class TransferItem
+        {
+            /**
+             * @Assert\Negative
+             */
+            protected $withdraw;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\TransferItem:
+            properties:
+                withdraw:
+                    - Negative: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\TransferItem">
+                <property name="withdraw">
+                    <constraint name="Negative"></constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/TransferItem.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class TransferItem
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('withdraw', new Assert\Negative());
+            }
+        }
+
+Available Options
+-----------------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be negative.``
+
+The default message supplied when the value is not less than zero.
+
+You can use the following parameters in this message:
+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       Always zero
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/NegativeOrZero.rst b/reference/constraints/NegativeOrZero.rst
new file mode 100644
index 00000000000..5a77a36ab67
--- /dev/null
+++ b/reference/constraints/NegativeOrZero.rst
@@ -0,0 +1,104 @@
+NegativeOrZero
+==============
+
+.. versionadded:: 4.3
+
+    The ``NegativeOrZero`` constraint was introduced in Symfony 4.3.
+
+Validates that a value is a negative number or equal to zero. If you don't
+want to allow zero as value, use :doc:`/reference/constraints/Negative` instead.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\NegativeOrZero`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\LesserThanOrEqualValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraint ensures that the ``level`` of a ``UnderGroundGarage``
+is a negative number or equal to zero:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/TransferItem.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class UnderGroundGarage
+        {
+            /**
+             * @Assert\NegativeOrZero
+             */
+            protected $level;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\UnderGroundGarage:
+            properties:
+                level:
+                    - NegativeOrZero: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\UnderGroundGarage">
+                <property name="level">
+                    <constraint name="NegativeOrZero"></constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/UnderGroundGarage.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class UnderGroundGarage
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('level', new Assert\NegativeOrZero());
+            }
+        }
+
+Available Options
+-----------------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be either negative or zero.``
+
+The default message supplied when the value is not less than or equal to zero.
+
+You can use the following parameters in this message:
+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       Always zero
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/NotBlank.rst b/reference/constraints/NotBlank.rst
index 3c030abb927..83b2713d225 100644
--- a/reference/constraints/NotBlank.rst
+++ b/reference/constraints/NotBlank.rst
@@ -2,25 +2,20 @@ NotBlank
 ========
 
 Validates that a value is not blank - meaning not equal to a blank string,
-a blank array, ``null`` or ``false``::
-
-    if (false === $value || (empty($value) && '0' != $value)) {
-        // validation will fail
-    }
-
-To force that a value is simply not equal to ``null``, see the
+a blank array, ``false`` or ``null`` (null behavior is configurable). To check
+that a value is not equal to ``null``, see the
 :doc:`/reference/constraints/NotNull` constraint.
 
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `message`_                                                           |
-|                | - `payload`_                                                           |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\NotBlank`          |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\NotBlankValidator` |
-+----------------+------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `allowNull`_
+            - `groups`_
+            - `message`_
+            - `normalizer`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\NotBlank`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\NotBlankValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -59,11 +54,11 @@ class were not blank, you could do the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -73,8 +68,8 @@ class were not blank, you could do the following:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -87,6 +82,20 @@ class were not blank, you could do the following:
 Options
 -------
 
+allowNull
+~~~~~~~~~
+
+**type**: ``bool`` **default**: ``false``
+
+If set to ``true``, ``null`` values are considered valid and won't trigger a
+constraint violation.
+
+.. versionadded:: 4.3
+
+    The ``allowNull`` option was introduced in Symfony 4.3.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -96,10 +105,12 @@ This is the message that will be shown if the value is blank.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_normalizer-option.rst.inc
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/NotCompromisedPassword.rst b/reference/constraints/NotCompromisedPassword.rst
new file mode 100644
index 00000000000..ffa9fe99d8d
--- /dev/null
+++ b/reference/constraints/NotCompromisedPassword.rst
@@ -0,0 +1,137 @@
+NotCompromisedPassword
+======================
+
+.. versionadded:: 4.3
+
+    The ``NotCompromisedPassword`` constraint was introduced in Symfony 4.3.
+
+Validates that the given password has not been compromised by checking that it is
+not included in any of the public data breaches tracked by `haveibeenpwned.com`_.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `skipOnError`_
+            - `threshold`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\NotCompromisedPassword`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\NotCompromisedPasswordValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraint ensures that the ``rawPassword`` property of the
+``User`` class doesn't store a compromised password:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/User.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class User
+        {
+            /**
+             * @Assert\NotCompromisedPassword
+             */
+            protected $rawPassword;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\User:
+            properties:
+                rawPassword:
+                    - NotCompromisedPassword
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\User">
+                <property name="rawPassword">
+                    <constraint name="NotCompromisedPassword"></constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/User.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class User
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('rawPassword', new Assert\NotCompromisedPassword());
+            }
+        }
+
+In order to make the password validation, this constraint doesn't send the raw
+password value to the ``haveibeenpwned.com`` API. Instead, it follows a secure
+process known as `k-anonimity password validation`_.
+
+In practice, the raw password is hashed using SHA-1 and only the first bytes of
+the hash are sent. Then, the ``haveibeenpwned.com`` API compares those bytes
+with the SHA-1 hashes of all leaked passwords and returns the list of hashes
+that start with those same bytes. That's how the constraint can check if the
+password has been compromised without fully disclosing it.
+
+For example, if the password is ``test``, the entire SHA-1 hash is
+``a94a8fe5ccb19ba61c4c0873d391e987982fbbd3`` but the validator only sends
+``a94a8`` to the ``haveibeenpwned.com`` API.
+
+.. seealso::
+
+    When using this constraint inside a Symfony application, define the
+    :ref:`not_compromised_password <reference-validation-not-compromised-password>`
+    option to avoid making HTTP requests in the ``dev`` and ``test`` environments.
+
+Available Options
+-----------------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This password has been leaked in a data breach, it must not be used. Please use another password.``
+
+The default message supplied when the password has been compromised.
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+skipOnError
+~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+When the HTTP request made to the ``haveibeenpwned.com`` API fails for any
+reason, an exception is thrown (no validation error is displayed). Set this
+option to ``true`` to not throw the exception and consider the password valid.
+
+threshold
+~~~~~~~~~
+
+**type**: ``integer`` **default**: ``1``
+
+This value defines the number of times a password should have been leaked
+publicly to consider it compromised. Think carefully before setting this option
+to a higher value because it could decrease the security of your application.
+
+.. _`haveibeenpwned.com`: https://haveibeenpwned.com/
+.. _`k-anonimity password validation`: https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/
diff --git a/reference/constraints/NotEqualTo.rst b/reference/constraints/NotEqualTo.rst
index c697f52b065..47b48726029 100644
--- a/reference/constraints/NotEqualTo.rst
+++ b/reference/constraints/NotEqualTo.rst
@@ -11,18 +11,16 @@ options. To force that a value is equal, see
     equal. Use :doc:`/reference/constraints/NotIdenticalTo` to compare with
     ``!==``.
 
-+----------------+-------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                   |
-+----------------+-------------------------------------------------------------------------+
-| Options        | - `value`_                                                              |
-|                | - `message`_                                                            |
-|                | - `payload`_                                                            |
-|                | - `propertyPath`_                                                       |
-+----------------+-------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\NotEqualTo`         |
-+----------------+-------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\NotEqualToValidator`|
-+----------------+-------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\NotEqualTo`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\NotEqualToValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -72,7 +70,7 @@ the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
                 <property name="firstName">
@@ -93,8 +91,8 @@ the following:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -111,7 +109,7 @@ the following:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -122,16 +120,16 @@ This is the message that will be shown if the value is equal.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The expected value          |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The expected value
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
+
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
diff --git a/reference/constraints/NotIdenticalTo.rst b/reference/constraints/NotIdenticalTo.rst
index 841d9cc4a62..eb2f3740554 100644
--- a/reference/constraints/NotIdenticalTo.rst
+++ b/reference/constraints/NotIdenticalTo.rst
@@ -11,18 +11,16 @@ the options. To force that a value is identical, see
     considered not equal. Use :doc:`/reference/constraints/NotEqualTo` to
     compare with ``!=``.
 
-+----------------+-----------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method<validation-property-target>`                       |
-+----------------+-----------------------------------------------------------------------------+
-| Options        | - `value`_                                                                  |
-|                | - `message`_                                                                |
-|                | - `payload`_                                                                |
-|                | - `propertyPath`_                                                           |
-+----------------+-----------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\NotIdenticalTo`         |
-+----------------+-----------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\NotIdenticalToValidator`|
-+----------------+-----------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - `propertyPath`_
+            - `value`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\NotIdenticalTo`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\NotIdenticalToValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -73,7 +71,7 @@ The following constraints ensure that:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Person">
             <property name="firstName">
@@ -94,8 +92,8 @@ The following constraints ensure that:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Person
         {
@@ -112,7 +110,7 @@ The following constraints ensure that:
 Options
 -------
 
-.. include:: /reference/constraints/_comparison-value-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 message
 ~~~~~~~
@@ -123,16 +121,16 @@ This is the message that will be shown if the value is identical.
 
 You can use the following parameters in this message:
 
-+-------------------------------+-----------------------------+
-| Parameter                     | Description                 |
-+===============================+=============================+
-| ``{{ value }}``               | The current (invalid) value |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value }}``      | The expected value          |
-+-------------------------------+-----------------------------+
-| ``{{ compared_value_type }}`` | The expected value type     |
-+-------------------------------+-----------------------------+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       The expected value
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. include:: /reference/constraints/_comparison-propertypath-option.rst.inc
+
+.. include:: /reference/constraints/_comparison-value-option.rst.inc
diff --git a/reference/constraints/NotNull.rst b/reference/constraints/NotNull.rst
index 3c59f24192a..28e9897d01e 100644
--- a/reference/constraints/NotNull.rst
+++ b/reference/constraints/NotNull.rst
@@ -2,19 +2,17 @@ NotNull
 =======
 
 Validates that a value is not strictly equal to ``null``. To ensure that
-a value is simply not blank (not a blank string), see the  :doc:`/reference/constraints/NotBlank`
+a value is not blank (not a blank string), see the  :doc:`/reference/constraints/NotBlank`
 constraint.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\NotNull`          |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\NotNullValidator` |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\NotNull`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\NotNullValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -53,11 +51,11 @@ class were not strictly equal to ``null``, you would:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
-                    <constraint name="NotNull" />
+                    <constraint name="NotNull"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -67,8 +65,8 @@ class were not strictly equal to ``null``, you would:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -81,6 +79,8 @@ class were not strictly equal to ``null``, you would:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -90,10 +90,10 @@ This is the message that will be shown if the value is ``null``.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Positive.rst b/reference/constraints/Positive.rst
new file mode 100644
index 00000000000..bfed77a763c
--- /dev/null
+++ b/reference/constraints/Positive.rst
@@ -0,0 +1,106 @@
+Positive
+========
+
+.. versionadded:: 4.3
+
+    The ``Positive`` constraint was introduced in Symfony 4.3.
+
+Validates that a value is a positive number. Zero is neither positive nor
+negative, so you must use :doc:`/reference/constraints/PositiveOrZero` if you
+want to allow zero as value.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Positive`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraint ensures that the ``income`` of an ``Employee`` is a
+positive number (greater than zero):
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Employee.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Employee
+        {
+            /**
+             * @Assert\Positive
+             */
+            protected $income;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Employee:
+            properties:
+                income:
+                    - Positive: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\Employee">
+                <property name="income">
+                    <constraint name="Positive"></constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Employee.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+
+        class Employee
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('income', new Assert\Positive());
+            }
+        }
+
+Available Options
+-----------------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be positive.``
+
+The default message supplied when the value is not greater than zero.
+
+You can use the following parameters in this message:
+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       Always zero
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/PositiveOrZero.rst b/reference/constraints/PositiveOrZero.rst
new file mode 100644
index 00000000000..cc592f824c6
--- /dev/null
+++ b/reference/constraints/PositiveOrZero.rst
@@ -0,0 +1,104 @@
+PositiveOrZero
+==============
+
+.. versionadded:: 4.3
+
+    The ``PositiveOrZero`` constraint was introduced in Symfony 4.3.
+
+Validates that a value is a positive number or equal to zero. If you don't
+want to allow zero as value, use :doc:`/reference/constraints/Positive` instead.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\PositiveOrZero`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqualValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraint ensures that the number of ``siblings`` of a ``Person``
+is positive or zero:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Person.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\PositiveOrZero
+             */
+            protected $siblings;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Person:
+            properties:
+                siblings:
+                    - PositiveOrZero: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\Person">
+                <property name="siblings">
+                    <constraint name="PositiveOrZero"></constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Person.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('siblings', new Assert\PositiveOrZero());
+            }
+        }
+
+Available Options
+-----------------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be either positive or zero.``
+
+The default message supplied when the value is not greater than or equal to zero.
+
+You can use the following parameters in this message:
+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ compared_value }}``       Always zero
+``{{ compared_value_type }}``  The expected value type
+``{{ value }}``                The current (invalid) value
+=============================  ================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst
index bb31c0c11e7..9b8fab33d69 100644
--- a/reference/constraints/Range.rst
+++ b/reference/constraints/Range.rst
@@ -3,20 +3,18 @@ Range
 
 Validates that a given number or ``DateTime`` object is *between* some minimum and maximum.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `min`_                                                            |
-|                | - `max`_                                                            |
-|                | - `minMessage`_                                                     |
-|                | - `maxMessage`_                                                     |
-|                | - `invalidMessage`_                                                 |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Range`          |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\RangeValidator` |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `invalidMessage`_
+            - `max`_
+            - `maxMessage`_
+            - `min`_
+            - `minMessage`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Range`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\RangeValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -43,7 +41,7 @@ you might add the following:
              *      maxMessage = "You cannot be taller than {{ limit }}cm to enter"
              * )
              */
-             protected $height;
+            protected $height;
         }
 
     .. code-block:: yaml
@@ -64,7 +62,7 @@ you might add the following:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Participant">
                 <property name="height">
@@ -83,16 +81,16 @@ you might add the following:
         // src/Entity/Participant.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Participant
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('height', new Assert\Range([
-                    'min'        => 120,
-                    'max'        => 180,
+                    'min' => 120,
+                    'max' => 180,
                     'minMessage' => 'You must be at least {{ limit }}cm tall to enter',
                     'maxMessage' => 'You cannot be taller than {{ limit }}cm to enter',
                 ]));
@@ -143,7 +141,7 @@ date must lie within the current year like this:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Event">
                 <property name="startDate">
@@ -160,8 +158,8 @@ date must lie within the current year like this:
         // src/Entity/Event.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Event
         {
@@ -213,7 +211,7 @@ dates. If you want to fix the timezone, append it to the date string:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Event">
                 <property name="startDate">
@@ -230,8 +228,8 @@ dates. If you want to fix the timezone, append it to the date string:
         // src/Entity/Person.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Event
         {
@@ -283,7 +281,7 @@ can check that a delivery date starts within the next five hours like this:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Order">
                 <property name="deliveryDate">
@@ -300,8 +298,8 @@ can check that a delivery date starts within the next five hours like this:
         // src/Entity/Order.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Order
         {
@@ -317,13 +315,23 @@ can check that a delivery date starts within the next five hours like this:
 Options
 -------
 
-min
-~~~
+.. include:: /reference/constraints/_groups-option.rst.inc
 
-**type**: ``number`` or ``string`` (date format)
+invalidMessage
+~~~~~~~~~~~~~~
 
-This required option is the "min" value. Validation will fail if the given
-value is **less** than this min value.
+**type**: ``string`` **default**: ``This value should be a valid number.``
+
+The message that will be shown if the underlying value is not a number (per
+the `is_numeric`_ PHP function).
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 max
 ~~~
@@ -333,24 +341,6 @@ max
 This required option is the "max" value. Validation will fail if the given
 value is **greater** than this max value.
 
-minMessage
-~~~~~~~~~~
-
-**type**: ``string`` **default**: ``This value should be {{ limit }} or more.``
-
-The message that will be shown if the underlying value is less than the
-`min`_ option.
-
-You can use the following parameters in this message:
-
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-| ``{{ limit }}`` | The lower limit             |
-+-----------------+-----------------------------+
-
 maxMessage
 ~~~~~~~~~~
 
@@ -361,29 +351,37 @@ The message that will be shown if the underlying value is more than the
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-| ``{{ limit }}`` | The upper limit             |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ limit }}``  The upper limit
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
-invalidMessage
-~~~~~~~~~~~~~~
+min
+~~~
 
-**type**: ``string`` **default**: ``This value should be a valid number.``
+**type**: ``number`` or ``string`` (date format)
 
-The message that will be shown if the underlying value is not a number (per
-the `is_numeric`_ PHP function).
+This required option is the "min" value. Validation will fail if the given
+value is **less** than this min value.
+
+minMessage
+~~~~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be {{ limit }} or more.``
+
+The message that will be shown if the underlying value is less than the
+`min`_ option.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ limit }}``  The lower limit
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
 
diff --git a/reference/constraints/Regex.rst b/reference/constraints/Regex.rst
index ebbbb460cdd..d7e3c8f2ebd 100644
--- a/reference/constraints/Regex.rst
+++ b/reference/constraints/Regex.rst
@@ -3,19 +3,18 @@ Regex
 
 Validates that a value matches a regular expression.
 
-+----------------+-----------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                |
-+----------------+-----------------------------------------------------------------------+
-| Options        | - `pattern`_                                                          |
-|                | - `htmlPattern`_                                                      |
-|                | - `match`_                                                            |
-|                | - `message`_                                                          |
-|                | - `payload`_                                                          |
-+----------------+-----------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Regex`            |
-+----------------+-----------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\RegexValidator`   |
-+----------------+-----------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `htmlPattern`_
+            - `match`_
+            - `message`_
+            - `pattern`_
+            - `normalizer`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Regex`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\RegexValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -56,7 +55,7 @@ more word characters at the beginning of your string:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="description">
@@ -72,8 +71,8 @@ more word characters at the beginning of your string:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -128,7 +127,7 @@ it a custom message:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
@@ -146,8 +145,8 @@ it a custom message:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -155,7 +154,7 @@ it a custom message:
             {
                 $metadata->addPropertyConstraint('firstName', new Assert\Regex([
                     'pattern' => '/\d/',
-                    'match'   => false,
+                    'match' => false,
                     'message' => 'Your name cannot contain a number',
                 ]));
             }
@@ -166,16 +165,7 @@ it a custom message:
 Options
 -------
 
-pattern
-~~~~~~~
-
-**type**: ``string`` [:ref:`default option <validation-default-option>`]
-
-This required option is the regular expression pattern that the input will
-be matched against. By default, this validator will fail if the input string
-does *not* match this regular expression (via the :phpfunction:`preg_match`
-PHP function). However, if `match`_ is set to false, then validation will
-fail if the input string *does* match this pattern.
+.. include:: /reference/constraints/_groups-option.rst.inc
 
 htmlPattern
 ~~~~~~~~~~~
@@ -229,7 +219,7 @@ need to specify the HTML5 compatible pattern in the ``htmlPattern`` option:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="name">
@@ -246,15 +236,15 @@ need to specify the HTML5 compatible pattern in the ``htmlPattern`` option:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('name', new Assert\Regex([
-                    'pattern'     => '/^[a-z]+$/i',
+                    'pattern' => '/^[a-z]+$/i',
                     'htmlPattern' => '^[a-zA-Z]+$',
                 ]));
             }
@@ -281,10 +271,23 @@ This is the message that will be shown if this validator fails.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+pattern
+~~~~~~~
+
+**type**: ``string`` [:ref:`default option <validation-default-option>`]
+
+This required option is the regular expression pattern that the input will
+be matched against. By default, this validator will fail if the input string
+does *not* match this regular expression (via the :phpfunction:`preg_match`
+PHP function). However, if `match`_ is set to false, then validation will
+fail if the input string *does* match this pattern.
+
+.. include:: /reference/constraints/_normalizer-option.rst.inc
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Time.rst b/reference/constraints/Time.rst
index bb3b29e4ef3..b8665cbe735 100644
--- a/reference/constraints/Time.rst
+++ b/reference/constraints/Time.rst
@@ -1,25 +1,22 @@
 Time
 ====
 
-Validates that a value is a valid time, meaning an object implementing
-``DateTimeInterface`` or a string (or an object that can be cast into a string)
-that follows a valid ``HH:MM:SS`` format.
-
-+----------------+------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                 |
-+----------------+------------------------------------------------------------------------+
-| Options        | - `message`_                                                           |
-|                | - `payload`_                                                           |
-+----------------+------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Time`              |
-+----------------+------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\TimeValidator`     |
-+----------------+------------------------------------------------------------------------+
+Validates that a value is a valid time, meaning a string (or an object that can
+be cast into a string) that follows a valid ``HH:MM:SS`` format.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Time`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\TimeValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
-Suppose you have an Event class, with a ``startAt`` field that is the time
+Suppose you have an Event class, with a ``startsAt`` field that is the time
 of the day when the event starts:
 
 .. configuration-block::
@@ -35,8 +32,9 @@ of the day when the event starts:
         {
             /**
              * @Assert\Time
+             * @var string A "H:i:s" formatted value
              */
-             protected $startsAt;
+            protected $startsAt;
         }
 
     .. code-block:: yaml
@@ -53,11 +51,11 @@ of the day when the event starts:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Event">
                 <property name="startsAt">
-                    <constraint name="Time" />
+                    <constraint name="Time"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -67,11 +65,16 @@ of the day when the event starts:
         // src/Entity/Event.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Event
         {
+           /**
+            * @var string A "H:i:s" formatted value
+            */
+            protected $startsAt;
+
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('startsAt', new Assert\Time());
@@ -83,6 +86,8 @@ of the day when the event starts:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -92,10 +97,10 @@ This message is shown if the underlying data is not a valid time.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst
new file mode 100644
index 00000000000..d14352a118f
--- /dev/null
+++ b/reference/constraints/Timezone.rst
@@ -0,0 +1,162 @@
+Timezone
+========
+
+.. versionadded:: 4.3
+
+    The ``Timezone`` constraint was introduced in Symfony 4.3.
+
+Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``).
+
+==========  ======================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `countryCode`_
+            - `groups`_
+            - `intlCompatible`_
+            - `message`_
+            - `payload`_
+            - `zone`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Timezone`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator`
+==========  ======================================================================
+
+Basic Usage
+-----------
+
+Suppose you have a ``UserSettings`` class, with a ``timezone`` field that is a
+string which contains any of the `PHP timezone identifiers`_ (e.g. ``America/New_York``):
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/UserSettings.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class UserSettings
+        {
+            /**
+             * @Assert\Timezone
+             */
+            protected $timezone;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\UserSettings:
+            properties:
+                timezone:
+                    - Timezone: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\UserSettings">
+                <property name="timezone">
+                    <constraint name="Timezone"/>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/UserSettings.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class UserSettings
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('timezone', new Assert\Timezone());
+            }
+        }
+
+.. include:: /reference/constraints/_empty-values-are-valid.rst.inc
+
+Options
+-------
+
+countryCode
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+If the ``zone`` option is set to ``\DateTimeZone::PER_COUNTRY``, this option
+restricts the valid timezone identifiers to the ones that belong to the given
+country.
+
+The value of this option must be a valid `ISO 3166-1 alpha-2`_ country code
+(e.g. ``CN`` for China).
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+intlCompatible
+~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+This constraint considers valid both the `PHP timezone identifiers`_ and the
+:ref:`ICU timezones <component-intl-timezones>` provided by Symfony's
+:doc:`Intl component </components/intl>`
+
+However, the timezones provided by the Intl component can be different from the
+timezones provided by PHP's Intl extension (because they use different ICU
+versions). If this option is set to ``true``, this constraint only considers
+valid the values created with the PHP ``\IntlTimeZone::createTimeZone()`` method.
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value is not a valid timezone.``
+
+This message is shown if the underlying data is not a valid timezone identifier.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+zone
+~~~~
+
+**type**: ``string`` **default**: ``\DateTimeZone::ALL``
+
+Set this option to any of the following constants to restrict the valid timezone
+identifiers to the ones that belong to that geographical zone:
+
+* ``\DateTimeZone::AFRICA``
+* ``\DateTimeZone::AMERICA``
+* ``\DateTimeZone::ANTARCTICA``
+* ``\DateTimeZone::ARCTIC``
+* ``\DateTimeZone::ASIA``
+* ``\DateTimeZone::ATLANTIC``
+* ``\DateTimeZone::AUSTRALIA``
+* ``\DateTimeZone::EUROPE``
+* ``\DateTimeZone::INDIAN``
+* ``\DateTimeZone::PACIFIC``
+
+In addition, there are some special zone values:
+
+* ``\DateTimeZone::ALL`` accepts any timezone excluding deprecated timezones;
+* ``\DateTimeZone::ALL_WITH_BC`` accepts any timezone including deprecated
+  timezones;
+* ``\DateTimeZone::PER_COUNTRY`` restricts the valid timezones to a certain
+  country (which is defined using the ``countryCode`` option).
+
+.. _`PHP timezone identifiers`: https://www.php.net/manual/en/timezones.php
+.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
diff --git a/reference/constraints/Traverse.rst b/reference/constraints/Traverse.rst
new file mode 100644
index 00000000000..d2b8aedfe07
--- /dev/null
+++ b/reference/constraints/Traverse.rst
@@ -0,0 +1,98 @@
+Traverse
+========
+
+Objects do not validate nested objects by default unless explicitly using
+this constraint.
+If only specific nested objects should be validated by cascade, consider
+using the :doc:`/reference/constraints/Valid` instead.
+
++----------------+-------------------------------------------------------------------------------------+
+| Applies to     | :ref:`class <validation-class-target>`                                              |
++----------------+-------------------------------------------------------------------------------------+
+| Options        | - `payload`_                                                                        |
++----------------+-------------------------------------------------------------------------------------+
+| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Traverse`                       |
++----------------+-------------------------------------------------------------------------------------+
+
+Basic Usage
+-----------
+
+In the following example, create three classes ``Book``, ``Author`` and
+``Editor`` that all have constraints on their properties. Furthermore,
+``Book`` stores an ``Author`` and an ``Editor`` instance that must be
+valid too. Instead of adding the ``Valid`` constraint to both fields,
+configure the ``Traverse`` constraint on the ``Book`` class.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Book.php
+        namespace App\Entity;
+
+        use Doctrine\ORM\Mapping as ORM;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        /**
+         * @ORM\Entity
+         * @Assert\Traverse
+         */
+        class Book
+        {
+            /**
+             * @var Author
+             *
+             * @ORM\ManyToOne(targetEntity="App\Entity\Author")
+             */
+            protected $author;
+
+            /**
+             * @var Editor
+             *
+             * @ORM\ManyToOne(targetEntity="App\Entity\Editor")
+             */
+            protected $editor;
+
+            // ...
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Book:
+            constraints:
+                - Symfony\Component\Validator\Constraints\Traverse: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\Book">
+                <constraint name="Symfony\Component\Validator\Constraints\Traverse"/>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Book.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Book
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addConstraint(new Assert\Traverse());
+            }
+        }
+
+Options
+-------
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/Type.rst b/reference/constraints/Type.rst
index e163ec6cba6..0355176f880 100644
--- a/reference/constraints/Type.rst
+++ b/reference/constraints/Type.rst
@@ -5,17 +5,15 @@ Validates that a value is of a specific data type. For example, if a variable
 should be an array, you can use this constraint with the ``array`` type
 option to validate this.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - :ref:`type <reference-constraint-type-type>`                      |
-|                | - `message`_                                                        |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Type`           |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\TypeValidator`  |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+            - :ref:`type <reference-constraint-type-type>`
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Type`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\TypeValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -67,7 +65,7 @@ This will check if ``firstName`` is of type ``string`` and that ``age`` is an
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
@@ -89,8 +87,8 @@ This will check if ``firstName`` is of type ``string`` and that ``age`` is an
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -99,7 +97,7 @@ This will check if ``firstName`` is of type ``string`` and that ``age`` is an
                 $metadata->addPropertyConstraint('firstName', new Assert\Type('string'));
 
                 $metadata->addPropertyConstraint('age', new Assert\Type([
-                    'type'    => 'integer',
+                    'type' => 'integer',
                     'message' => 'The value {{ value }} is not a valid {{ type }}.',
                 ]));
             }
@@ -108,6 +106,26 @@ This will check if ``firstName`` is of type ``string`` and that ``age`` is an
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be of type {{ type }}.``
+
+The message if the underlying data is not of the given type.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ type }}``   The expected type
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
 .. _reference-constraint-type-type:
 
 type
@@ -153,24 +171,5 @@ Also, you can use ``ctype_()`` functions from corresponding
 Make sure that the proper :phpfunction:`locale <setlocale>` is set before
 using one of these.
 
-message
-~~~~~~~
-
-**type**: ``string`` **default**: ``This value should be of type {{ type }}.``
-
-The message if the underlying data is not of the given type.
-
-You can use the following parameters in this message:
-
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
-| ``{{ type }}``  | The expected type           |
-+-----------------+-----------------------------+
-
-.. include:: /reference/constraints/_payload-option.rst.inc
-
-.. _built-in PHP extension: https://php.net/book.ctype.php
-.. _a list of ctype functions: https://php.net/ref.ctype.php
+.. _built-in PHP extension: https://php.net/book.ctype
+.. _a list of ctype functions: https://php.net/ref.ctype
diff --git a/reference/constraints/Unique.rst b/reference/constraints/Unique.rst
new file mode 100644
index 00000000000..97cb6ff8602
--- /dev/null
+++ b/reference/constraints/Unique.rst
@@ -0,0 +1,113 @@
+Unique
+======
+
+Validates that all the elements of the given collection are unique (none of them
+is present more than once). Elements are compared strictly, so ``'7'`` and ``7``
+are considered different elements (a string and an integer, respectively).
+
+.. seealso::
+
+    If you want to apply different validation constraints to the elements of a
+    collection or want to make sure that certain collection keys are present,
+    use the :doc:`Collection constraint </reference/constraints/Collection>`.
+
+.. seealso::
+
+    If you want to validate that the value of an entity property is unique among
+    all entities of the same type (e.g. the registration email of all users) use
+    the :doc:`UniqueEntity constraint </reference/constraints/UniqueEntity>`.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Unique`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\UniqueValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+This constraint can be applied to any property of type ``array`` or
+``\Traversable``. In the following example, ``$contactEmails`` is an array of
+strings:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Person.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\Unique
+             */
+            protected $contactEmails;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Person:
+            properties:
+                contactEmails:
+                    - Unique: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\Person">
+                <property name="contactEmails">
+                    <constraint name="Unique"/>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Person.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('contactEmails', new Assert\Unique());
+            }
+        }
+
+Options
+-------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This collection should contain only unique elements.``
+
+This is the message that will be shown if at least one element is repeated in
+the collection.
+
+You can use the following parameters in this message:
+
+=============================  ================================================
+Parameter                      Description
+=============================  ================================================
+``{{ value }}``                The repeated value
+=============================  ================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst
index a9f180fd52b..0980dee821f 100644
--- a/reference/constraints/UniqueEntity.rst
+++ b/reference/constraints/UniqueEntity.rst
@@ -5,22 +5,25 @@ Validates that a particular field (or fields) in a Doctrine entity is (are)
 unique. This is commonly used, for example, to prevent a new user to register
 using an email address that already exists in the system.
 
-+----------------+-------------------------------------------------------------------------------------+
-| Applies to     | :ref:`class <validation-class-target>`                                              |
-+----------------+-------------------------------------------------------------------------------------+
-| Options        | - `fields`_                                                                         |
-|                | - `message`_                                                                        |
-|                | - `em`_                                                                             |
-|                | - `repositoryMethod`_                                                               |
-|                | - `entityClass`_                                                                    |
-|                | - `errorPath`_                                                                      |
-|                | - `ignoreNull`_                                                                     |
-|                | - `payload`_                                                                        |
-+----------------+-------------------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Bridge\\Doctrine\\Validator\\Constraints\\UniqueEntity`            |
-+----------------+-------------------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Bridge\\Doctrine\\Validator\\Constraints\\UniqueEntityValidator`   |
-+----------------+-------------------------------------------------------------------------------------+
+.. seealso::
+
+    If you want to validate that all the elements of the collection are unique
+    use the :doc:`Unique constraint </reference/constraints/Unique>`.
+
+==========  ===================================================================
+Applies to  :ref:`class <validation-class-target>`
+Options     - `em`_
+            - `entityClass`_
+            - `errorPath`_
+            - `fields`_
+            - `groups`_
+            - `ignoreNull`_
+            - `message`_
+            - `payload`_
+            - `repositoryMethod`_
+Class       :class:`Symfony\\Bridge\\Doctrine\\Validator\\Constraints\\UniqueEntity`
+Validator   :class:`Symfony\\Bridge\\Doctrine\\Validator\\Constraints\\UniqueEntityValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -33,36 +36,33 @@ between all of the constraints in your user table:
 
     .. code-block:: php-annotations
 
-        // src/Entity/Author.php
+        // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Constraints as Assert;
         use Doctrine\ORM\Mapping as ORM;
 
-        // DON'T forget this use statement!!!
+        // DON'T forget the following use statement!!!
         use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
 
+        use Symfony\Component\Validator\Constraints as Assert;
+
         /**
          * @ORM\Entity
          * @UniqueEntity("email")
          */
-        class Author
+        class User
         {
             /**
-             * @var string $email
-             *
              * @ORM\Column(name="email", type="string", length=255, unique=true)
              * @Assert\Email
              */
             protected $email;
-
-            // ...
         }
 
     .. code-block:: yaml
 
         # config/validator/validation.yaml
-        App\Entity\Author:
+        App\Entity\User:
             constraints:
                 - Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity: email
             properties:
@@ -75,34 +75,34 @@ between all of the constraints in your user table:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
-            <class name="App\Entity\Author">
+            <class name="App\Entity\User">
                 <constraint name="Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity">
                     <option name="fields">email</option>
                 </constraint>
                 <property name="email">
-                    <constraint name="Email" />
+                    <constraint name="Email"/>
                 </property>
             </class>
         </constraint-mapping>
 
     .. code-block:: php
 
-        // src/Entity/Author.php
+        // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Constraints as Assert;
-
-        // DON'T forget this use statement!!!
+        // DON'T forget the following use statement!!!
         use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
 
-        class Author
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class User
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addConstraint(new UniqueEntity([
-                    'fields'  => 'email',
+                    'fields' => 'email',
                 ]));
 
                 $metadata->addPropertyConstraint('email', new Assert\Email());
@@ -116,45 +116,14 @@ between all of the constraints in your user table:
     this validation has passed and before this entity is actually persisted in
     the database.
 
-Options
--------
-
-fields
-~~~~~~
-
-**type**: ``array`` | ``string`` [:ref:`default option <validation-default-option>`]
-
-This required option is the field (or list of fields) on which this entity
-should be unique. For example, if you specified both the ``email`` and ``name``
-field in a single ``UniqueEntity`` constraint, then it would enforce that
-the combination value is unique (e.g. two users could have the same email,
-as long as they don't have the same name also).
-
-If you need to require two fields to be individually unique (e.g. a unique
-``email`` *and* a unique ``username``), you use two ``UniqueEntity`` entries,
-each with a single field.
-
-message
-~~~~~~~
-
-**type**: ``string`` **default**: ``This value is already used.``
-
-The message that's displayed when this constraint fails. This message is always
-mapped to the first field causing the violation, even when using multiple fields
-in the constraint.
-
-Messages can include the ``{{ value }}`` placeholder to display a string
-representation of the invalid entity. If the entity doesn't define the
-``__toString()`` method, the following generic value will be used: *"Object of
-class __CLASS__ identified by <comma separated IDs>"*
+.. caution::
 
-You can use the following parameters in this message:
+    This constraint cannot deal with duplicates found in a collection of items
+    that haven't been persisted as entities yet. You'll need to create your own
+    validator to handle that case.
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+Options
+-------
 
 em
 ~~
@@ -166,15 +135,6 @@ the uniqueness. If it's left blank, the correct entity manager will be
 determined for this class. For that reason, this option should probably
 not need to be used.
 
-repositoryMethod
-~~~~~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``findBy()``
-
-The name of the repository method to use for making the query to determine
-the uniqueness. If it's left blank, the ``findBy()`` method will be used.
-This method should return a countable result.
-
 entityClass
 ~~~~~~~~~~~
 
@@ -244,7 +204,7 @@ Consider this example:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Service">
                 <constraint name="Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity">
@@ -264,8 +224,8 @@ Consider this example:
         // src/Entity/Service.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Service
         {
@@ -275,15 +235,32 @@ Consider this example:
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addConstraint(new UniqueEntity([
-                    'fields'    => ['host', 'port'],
+                    'fields' => ['host', 'port'],
                     'errorPath' => 'port',
-                    'message'   => 'This port is already in use on that host.',
+                    'message' => 'This port is already in use on that host.',
                 ]));
             }
         }
 
 Now, the message would be bound to the ``port`` field with this configuration.
 
+fields
+~~~~~~
+
+**type**: ``array`` | ``string`` [:ref:`default option <validation-default-option>`]
+
+This required option is the field (or list of fields) on which this entity
+should be unique. For example, if you specified both the ``email`` and ``name``
+field in a single ``UniqueEntity`` constraint, then it would enforce that
+the combination value is unique (e.g. two users could have the same email,
+as long as they don't have the same name also).
+
+If you need to require two fields to be individually unique (e.g. a unique
+``email`` *and* a unique ``username``), you use two ``UniqueEntity`` entries,
+each with a single field.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 ignoreNull
 ~~~~~~~~~~
 
@@ -294,6 +271,40 @@ entities to have a ``null`` value for a field without failing validation.
 If set to ``false``, only one ``null`` value is allowed - if a second entity
 also has a ``null`` value, validation would fail.
 
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value is already used.``
+
+The message that's displayed when this constraint fails. This message is always
+mapped to the first field causing the violation, even when using multiple fields
+in the constraint.
+
+Messages can include the ``{{ value }}`` placeholder to display a string
+representation of the invalid entity. If the entity doesn't define the
+``__toString()`` method, the following generic value will be used: *"Object of
+class __CLASS__ identified by <comma separated IDs>"*
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
 .. include:: /reference/constraints/_payload-option.rst.inc
 
+repositoryMethod
+~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``findBy``
+
+The name of the repository method used to determine the uniqueness. If it's left
+blank, ``findBy()`` will be used. The method receives as its argument a
+``fieldName => value`` associative array (where ``fieldName`` is each of the
+fields configured in the ``fields`` option). The method should return a
+`countable PHP variable`_.
+
 .. _`race conditions`: https://en.wikipedia.org/wiki/Race_condition
+.. _`countable PHP variable`: https://php.net/manual/function.is-countable.php
diff --git a/reference/constraints/Url.rst b/reference/constraints/Url.rst
index 628e291cdce..4c9885d0147 100644
--- a/reference/constraints/Url.rst
+++ b/reference/constraints/Url.rst
@@ -3,20 +3,19 @@ Url
 
 Validates that a value is a valid URL string.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `message`_                                                        |
-|                | - `protocols`_                                                      |
-|                | - `payload`_                                                        |
-|                | - `checkDNS`_                                                       |
-|                | - `dnsMessage`_                                                     |
-|                | - `relativeProtocol`_                                               |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Url`            |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\UrlValidator`   |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `checkDNS`_
+            - `dnsMessage`_
+            - `groups`_
+            - `message`_
+            - `normalizer`_
+            - `payload`_
+            - `protocols`_
+            - `relativeProtocol`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Url`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\UrlValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -35,7 +34,7 @@ Basic Usage
             /**
              * @Assert\Url
              */
-             protected $bioUrl;
+            protected $bioUrl;
         }
 
     .. code-block:: yaml
@@ -52,11 +51,11 @@ Basic Usage
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioUrl">
-                    <constraint name="Url" />
+                    <constraint name="Url"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -66,8 +65,8 @@ Basic Usage
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -82,20 +81,22 @@ Basic Usage
 Options
 -------
 
-message
-~~~~~~~
+checkDNS
+~~~~~~~~
 
-**type**: ``string`` **default**: ``This value is not a valid URL.``
+**type**: ``boolean`` **default**: ``false``
 
-This message is shown if the URL is invalid.
+.. deprecated:: 4.1
 
-You can use the following parameters in this message:
+    This option was deprecated in Symfony 4.1 and will be removed in Symfony 5.0,
+    because checking the DNS records is not reliable enough to validate the
+    existence of the host. Use the :phpfunction:`checkdnsrr` PHP function if you
+    still want to use this kind of validation.
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+By default, this constraint just validates the syntax of the given URL. If you
+also need to check whether the associated host exists, set the ``checkDNS``
+option to the value of any of the ``CHECK_DNS_TYPE_*`` constants in the
+:class:`Symfony\\Component\\Validator\\Constraints\\Url` class:
 
 .. configuration-block::
 
@@ -110,7 +111,7 @@ You can use the following parameters in this message:
         {
             /**
              * @Assert\Url(
-             *    message = "The url '{{ value }}' is not a valid url",
+             *    checkDNS = "ANY"
              * )
              */
              protected $bioUrl;
@@ -122,8 +123,7 @@ You can use the following parameters in this message:
         App\Entity\Author:
             properties:
                 bioUrl:
-                    - Url:
-                        message: The url "{{ value }}" is not a valid url.
+                    - Url: { checkDNS: 'ANY' }
 
     .. code-block:: xml
 
@@ -131,12 +131,12 @@ You can use the following parameters in this message:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioUrl">
                     <constraint name="Url">
-                        <option name="message">The url "{{ value }}" is not a valid url.</option>
+                        <option name="checkDNS">ANY</option>
                     </constraint>
                 </property>
             </class>
@@ -147,27 +147,36 @@ You can use the following parameters in this message:
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('bioUrl', new Assert\Url([
-                    'message' => 'The url "{{ value }}" is not a valid url.',
+                    'checkDNS'  => Assert\Url::CHECK_DNS_TYPE_ANY,
                 ]));
             }
         }
 
-protocols
-~~~~~~~~~
+This option uses the :phpfunction:`checkdnsrr` PHP function to check the validity
+of the DNS record corresponding to the host associated with the given URL.
 
-**type**: ``array`` **default**: ``['http', 'https']``
+dnsMessage
+~~~~~~~~~~
 
-The protocols considered to be valid for the URL. For example, if you also consider
-the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
-``http``, ``https``, and also ``ftp``.
+**type**: ``string`` **default**: ``The host could not be resolved.``
+
+.. deprecated:: 4.1
+
+    This option was deprecated in Symfony 4.1 and will be removed in Symfony 5.0,
+    because checking the DNS records is not reliable enough to validate the
+    existence of the host. Use the :phpfunction:`checkdnsrr` PHP function if you
+    still want to use this kind of validation.
+
+This message is shown when the ``checkDNS`` option is set to ``true`` and the
+DNS check failed.
 
 .. configuration-block::
 
@@ -182,10 +191,10 @@ the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
         {
             /**
              * @Assert\Url(
-             *    protocols = {"http", "https", "ftp"}
+             *    dnsMessage = "The host '{{ value }}' could not be resolved."
              * )
              */
-             protected $bioUrl;
+            protected $bioUrl;
         }
 
     .. code-block:: yaml
@@ -194,7 +203,7 @@ the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
         App\Entity\Author:
             properties:
                 bioUrl:
-                    - Url: { protocols: [http, https, ftp] }
+                    - Url: { dnsMessage: 'The host "{{ value }}" could not be resolved.' }
 
     .. code-block:: xml
 
@@ -202,16 +211,12 @@ the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioUrl">
                     <constraint name="Url">
-                        <option name="protocols">
-                            <value>http</value>
-                            <value>https</value>
-                            <value>ftp</value>
-                        </option>
+                        <option name="dnsMessage">The host "{{ value }}" could not be resolved.</option>
                     </constraint>
                 </property>
             </class>
@@ -222,36 +227,35 @@ the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('bioUrl', new Assert\Url([
-                    'protocols' => ['http', 'https', 'ftp'],
+                     'dnsMessage' => 'The host "{{ value }}" could not be resolved.',
                 ]));
             }
         }
 
-.. include:: /reference/constraints/_payload-option.rst.inc
+.. include:: /reference/constraints/_groups-option.rst.inc
 
-checkDNS
-~~~~~~~~
+message
+~~~~~~~
 
-**type**: ``boolean`` **default**: ``false``
+**type**: ``string`` **default**: ``This value is not a valid URL.``
 
-.. versionadded:: 4.1
-    This option was deprecated in Symfony 4.1 and will be removed in Symfony 5.0,
-    because checking the DNS records is not reliable enough to validate the
-    existence of the host. Use the :phpfunction:`checkdnsrr` PHP function if you
-    still want to use this kind of validation.
+This message is shown if the URL is invalid.
 
-By default, this constraint just validates the syntax of the given URL. If you
-also need to check whether the associated host exists, set the ``checkDNS``
-option to the value of any of the ``CHECK_DNS_TYPE_*`` constants in the
-:class:`Symfony\\Component\\Validator\\Constraints\\Url` class:
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
 
 .. configuration-block::
 
@@ -266,10 +270,10 @@ option to the value of any of the ``CHECK_DNS_TYPE_*`` constants in the
         {
             /**
              * @Assert\Url(
-             *    checkDNS = "ANY"
+             *    message = "The url '{{ value }}' is not a valid url",
              * )
              */
-             protected $bioUrl;
+            protected $bioUrl;
         }
 
     .. code-block:: yaml
@@ -278,7 +282,8 @@ option to the value of any of the ``CHECK_DNS_TYPE_*`` constants in the
         App\Entity\Author:
             properties:
                 bioUrl:
-                    - Url: { checkDNS: 'ANY' }
+                    - Url:
+                        message: The url "{{ value }}" is not a valid url.
 
     .. code-block:: xml
 
@@ -286,12 +291,12 @@ option to the value of any of the ``CHECK_DNS_TYPE_*`` constants in the
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioUrl">
                     <constraint name="Url">
-                        <option name="checkDNS">ANY</option>
+                        <option name="message">The url "{{ value }}" is not a valid url.</option>
                     </constraint>
                 </property>
             </class>
@@ -302,35 +307,31 @@ option to the value of any of the ``CHECK_DNS_TYPE_*`` constants in the
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('bioUrl', new Assert\Url([
-                    'checkDNS'  => Assert\Url::CHECK_DNS_TYPE_ANY,
+                    'message' => 'The url "{{ value }}" is not a valid url.',
                 ]));
             }
         }
 
-This option uses the :phpfunction:`checkdnsrr` PHP function to check the validity
-of the DNS record corresponding to the host associated with the given URL.
+.. include:: /reference/constraints/_normalizer-option.rst.inc
 
-dnsMessage
-~~~~~~~~~~
+.. include:: /reference/constraints/_payload-option.rst.inc
 
-**type**: ``string`` **default**: ``The host could not be resolved.``
+protocols
+~~~~~~~~~
 
-.. versionadded:: 4.1
-    This option was deprecated in Symfony 4.1 and will be removed in Symfony 5.0,
-    because checking the DNS records is not reliable enough to validate the
-    existence of the host. Use the :phpfunction:`checkdnsrr` PHP function if you
-    still want to use this kind of validation.
+**type**: ``array`` **default**: ``['http', 'https']``
 
-This message is shown when the ``checkDNS`` option is set to ``true`` and the
-DNS check failed.
+The protocols considered to be valid for the URL. For example, if you also consider
+the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
+``http``, ``https``, and also ``ftp``.
 
 .. configuration-block::
 
@@ -345,10 +346,10 @@ DNS check failed.
         {
             /**
              * @Assert\Url(
-             *    dnsMessage = "The host '{{ value }}' could not be resolved."
+             *    protocols = {"http", "https", "ftp"}
              * )
              */
-             protected $bioUrl;
+            protected $bioUrl;
         }
 
     .. code-block:: yaml
@@ -357,7 +358,7 @@ DNS check failed.
         App\Entity\Author:
             properties:
                 bioUrl:
-                    - Url: { dnsMessage: 'The host "{{ value }}" could not be resolved.' }
+                    - Url: { protocols: [http, https, ftp] }
 
     .. code-block:: xml
 
@@ -365,12 +366,16 @@ DNS check failed.
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioUrl">
                     <constraint name="Url">
-                        <option name="dnsMessage">The host "{{ value }}" could not be resolved.</option>
+                        <option name="protocols">
+                            <value>http</value>
+                            <value>https</value>
+                            <value>ftp</value>
+                        </option>
                     </constraint>
                 </property>
             </class>
@@ -381,15 +386,15 @@ DNS check failed.
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('bioUrl', new Assert\Url([
-                     'dnsMessage' => 'The host "{{ value }}" could not be resolved.',
+                    'protocols' => ['http', 'https', 'ftp'],
                 ]));
             }
         }
@@ -399,9 +404,6 @@ relativeProtocol
 
 **type**: ``boolean`` **default**: ``false``
 
-.. versionadded:: 4.1
-    The ``relativeProtocol`` option was introduced in Symfony 4.1.
-
 If ``true``, the protocol is considered optional when validating the syntax of
 the given URL. This means that both ``http://`` and ``https://`` are valid but
 also relative URLs that contain no protocol (e.g. ``//example.com``).
@@ -422,7 +424,7 @@ also relative URLs that contain no protocol (e.g. ``//example.com``).
              *    relativeProtocol = true
              * )
              */
-             protected $bioUrl;
+            protected $bioUrl;
         }
 
     .. code-block:: yaml
@@ -439,7 +441,7 @@ also relative URLs that contain no protocol (e.g. ``//example.com``).
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="bioUrl">
@@ -455,8 +457,8 @@ also relative URLs that contain no protocol (e.g. ``//example.com``).
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
diff --git a/reference/constraints/UserPassword.rst b/reference/constraints/UserPassword.rst
index 5bdbea1ef4a..ff7dff2660b 100644
--- a/reference/constraints/UserPassword.rst
+++ b/reference/constraints/UserPassword.rst
@@ -10,16 +10,14 @@ password, but needs to enter their old password for security.
     This should **not** be used to validate a login form, since this is
     done automatically by the security system.
 
-+----------------+--------------------------------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`                                     |
-+----------------+--------------------------------------------------------------------------------------------+
-| Options        | - `message`_                                                                               |
-|                | - `payload`_                                                                               |
-+----------------+--------------------------------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Security\\Core\\Validator\\Constraints\\UserPassword`          |
-+----------------+--------------------------------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Security\\Core\\Validator\\Constraints\\UserPasswordValidator` |
-+----------------+--------------------------------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Security\\Core\\Validator\\Constraints\\UserPassword`
+Validator   :class:`Symfony\\Component\\Security\\Core\\Validator\\Constraints\\UserPasswordValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
@@ -45,7 +43,7 @@ the user's current password:
              *     message = "Wrong value for your current password"
              * )
              */
-             protected $oldPassword;
+            protected $oldPassword;
         }
 
     .. code-block:: yaml
@@ -63,7 +61,7 @@ the user's current password:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Form\Model\ChangePassword">
                 <property name="oldPassword">
@@ -81,8 +79,8 @@ the user's current password:
         // src/Form/Model/ChangePassword.php
         namespace App\Form\Model;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Security\Core\Validator\Constraints as SecurityAssert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class ChangePassword
         {
@@ -100,6 +98,8 @@ the user's current password:
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
diff --git a/reference/constraints/Uuid.rst b/reference/constraints/Uuid.rst
index c51add21c2d..aad14472dfe 100644
--- a/reference/constraints/Uuid.rst
+++ b/reference/constraints/Uuid.rst
@@ -6,32 +6,23 @@ By default, this will validate the format according to the RFC's guidelines, but
 be relaxed to accept non-standard UUIDs that other systems (like PostgreSQL) accept.
 UUID versions can also be restricted using a whitelist.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `message`_                                                        |
-|                | - `strict`_                                                         |
-|                | - `versions`_                                                       |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Uuid`           |
-+----------------+---------------------------------------------------------------------+
-| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\UuidValidator`  |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `message`_
+            - `normalizer`_
+            - `payload`_
+            - `strict`_
+            - `versions`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Uuid`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\UuidValidator`
+==========  ===================================================================
 
 Basic Usage
 -----------
 
 .. configuration-block::
 
-    .. code-block:: yaml
-
-        # config/validator/validation.yaml
-        App\Entity\File:
-            properties:
-                identifier:
-                    - Uuid: ~
-
     .. code-block:: php-annotations
 
         // src/Entity/File.php
@@ -44,20 +35,28 @@ Basic Usage
             /**
              * @Assert\Uuid
              */
-             protected $identifier;
+            protected $identifier;
         }
 
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\File:
+            properties:
+                identifier:
+                    - Uuid: ~
+
     .. code-block:: xml
 
         <!-- config/validator/validation.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\File">
                 <property name="identifier">
-                    <constraint name="Uuid" />
+                    <constraint name="Uuid"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -67,8 +66,8 @@ Basic Usage
         // src/Entity/File.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class File
         {
@@ -83,6 +82,8 @@ Basic Usage
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
 message
 ~~~~~~~
 
@@ -92,11 +93,15 @@ This message is shown if the string is not a valid UUID.
 
 You can use the following parameters in this message:
 
-+-----------------+-----------------------------+
-| Parameter       | Description                 |
-+=================+=============================+
-| ``{{ value }}`` | The current (invalid) value |
-+-----------------+-----------------------------+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ value }}``  The current (invalid) value
+===============  ==============================================================
+
+.. include:: /reference/constraints/_normalizer-option.rst.inc
+
+.. include:: /reference/constraints/_payload-option.rst.inc
 
 strict
 ~~~~~~
@@ -127,8 +132,6 @@ The following PHP constants can also be used:
 
 All five versions are allowed by default.
 
-.. include:: /reference/constraints/_payload-option.rst.inc
-
 .. _`Universally unique identifier (UUID)`: http://en.wikipedia.org/wiki/Universally_unique_identifier
 .. _`RFC 4122`: http://tools.ietf.org/html/rfc4122
 .. _`UUID versions`: http://en.wikipedia.org/wiki/Universally_unique_identifier#Variants_and_versions
diff --git a/reference/constraints/Valid.rst b/reference/constraints/Valid.rst
index 2fe266dbe68..329fd624349 100644
--- a/reference/constraints/Valid.rst
+++ b/reference/constraints/Valid.rst
@@ -5,14 +5,13 @@ This constraint is used to enable validation on objects that are embedded
 as properties on an object being validated. This allows you to validate
 an object and all sub-objects associated with it.
 
-+----------------+---------------------------------------------------------------------+
-| Applies to     | :ref:`property or method <validation-property-target>`              |
-+----------------+---------------------------------------------------------------------+
-| Options        | - `traverse`_                                                       |
-|                | - `payload`_                                                        |
-+----------------+---------------------------------------------------------------------+
-| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Valid`          |
-+----------------+---------------------------------------------------------------------+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `groups`_
+            - `payload`_
+            - `traverse`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Valid`
+==========  ===================================================================
 
 .. include:: /reference/forms/types/options/_error_bubbling_hint.rst.inc
 
@@ -115,14 +114,14 @@ stores an ``Address`` instance in the ``$address`` property::
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Address">
                 <property name="street">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
                 <property name="zipCode">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                     <constraint name="Length">
                         <option name="max">5</option>
                     </constraint>
@@ -131,13 +130,13 @@ stores an ``Address`` instance in the ``$address`` property::
 
             <class name="App\Entity\Author">
                 <property name="firstName">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                     <constraint name="Length">
                         <option name="min">4</option>
                     </constraint>
                 </property>
                 <property name="lastName">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -147,14 +146,11 @@ stores an ``Address`` instance in the ``$address`` property::
         // src/Entity/Address.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Address
         {
-            protected $street;
-            protected $zipCode;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('street', new Assert\NotBlank());
@@ -166,15 +162,11 @@ stores an ``Address`` instance in the ``$address`` property::
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            protected $firstName;
-            protected $lastName;
-            protected $address;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('firstName', new Assert\NotBlank());
@@ -218,11 +210,11 @@ an invalid address. To prevent that, add the ``Valid`` constraint to the
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="address">
-                    <constraint name="Valid" />
+                    <constraint name="Valid"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -232,13 +224,11 @@ an invalid address. To prevent that, add the ``Valid`` constraint to the
         // src/Entity/Author.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
-            protected $address;
-
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('address', new Assert\Valid());
@@ -256,13 +246,15 @@ the validation of the ``Address`` fields failed.
 Options
 -------
 
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
 traverse
 ~~~~~~~~
 
 **type**: ``boolean`` **default**: ``true``
 
-If this constraint is applied to a property that holds an array of objects,
-then each object in that array will be validated only if this option is
-set to ``true``.
-
-.. include:: /reference/constraints/_payload-option.rst.inc
+If this constraint is applied to a ``Traversable``, then all containing values
+will be validated if this option is set to ``true``. This option is ignored on
+arrays: Arrays are traversed in either case. Keys are not validated.
diff --git a/reference/constraints/_groups-option.rst.inc b/reference/constraints/_groups-option.rst.inc
new file mode 100644
index 00000000000..f385b060477
--- /dev/null
+++ b/reference/constraints/_groups-option.rst.inc
@@ -0,0 +1,7 @@
+groups
+~~~~~~
+
+**type**: ``array`` | ``string``
+
+It defines the validation group or groups this constraint belongs to. Read more
+about :doc:`validation groups </validation/groups>`.
diff --git a/reference/constraints/_normalizer-option.rst.inc b/reference/constraints/_normalizer-option.rst.inc
new file mode 100644
index 00000000000..784f915ff95
--- /dev/null
+++ b/reference/constraints/_normalizer-option.rst.inc
@@ -0,0 +1,13 @@
+normalizer
+~~~~~~~~~~
+
+**type**: a `PHP callable`_ **default**: ``null``
+
+This option allows to define the PHP callable applied to the given value before
+checking if it is valid.
+
+For example, you may want to pass the ``'trim'`` string to apply the
+:phpfunction:`trim` PHP function in order to ignore leading and trailing
+whitespace during validation.
+
+.. _`PHP callable`: https://www.php.net/callable
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
index a7229c53b79..337798c51da 100644
--- a/reference/constraints/map.rst.inc
+++ b/reference/constraints/map.rst.inc
@@ -20,7 +20,10 @@ String Constraints
 * :doc:`Url </reference/constraints/Url>`
 * :doc:`Regex </reference/constraints/Regex>`
 * :doc:`Ip </reference/constraints/Ip>`
+* :doc:`Json</reference/constraints/Json>`
 * :doc:`Uuid</reference/constraints/Uuid>`
+* :doc:`UserPassword </reference/constraints/UserPassword>`
+* :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`
 
 Comparison Constraints
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -34,6 +37,15 @@ Comparison Constraints
 * :doc:`GreaterThan </reference/constraints/GreaterThan>`
 * :doc:`GreaterThanOrEqual </reference/constraints/GreaterThanOrEqual>`
 * :doc:`Range </reference/constraints/Range>`
+* :doc:`DivisibleBy </reference/constraints/DivisibleBy>`
+* :doc:`Unique </reference/constraints/Unique>`
+
+Number Constraints
+~~~~~~~~~~~~~~~~~~
+* :doc:`Positive </reference/constraints/Positive>`
+* :doc:`PositiveOrZero </reference/constraints/PositiveOrZero>`
+* :doc:`Negative </reference/constraints/Negative>`
+* :doc:`NegativeOrZero </reference/constraints/NegativeOrZero>`
 
 Date Constraints
 ~~~~~~~~~~~~~~~~
@@ -41,14 +53,12 @@ Date Constraints
 * :doc:`Date </reference/constraints/Date>`
 * :doc:`DateTime </reference/constraints/DateTime>`
 * :doc:`Time </reference/constraints/Time>`
+* :doc:`Timezone </reference/constraints/Timezone>`
 
-Collection Constraints
-~~~~~~~~~~~~~~~~~~~~~~
+Choice Constraints
+~~~~~~~~~~~~~~~~~~
 
 * :doc:`Choice </reference/constraints/Choice>`
-* :doc:`Collection </reference/constraints/Collection>`
-* :doc:`Count </reference/constraints/Count>`
-* :doc:`UniqueEntity </reference/constraints/UniqueEntity>`
 * :doc:`Language </reference/constraints/Language>`
 * :doc:`Locale </reference/constraints/Locale>`
 * :doc:`Country </reference/constraints/Country>`
@@ -76,5 +86,8 @@ Other Constraints
 * :doc:`Callback </reference/constraints/Callback>`
 * :doc:`Expression </reference/constraints/Expression>`
 * :doc:`All </reference/constraints/All>`
-* :doc:`UserPassword </reference/constraints/UserPassword>`
 * :doc:`Valid </reference/constraints/Valid>`
+* :doc:`Traverse </reference/constraints/Traverse>`
+* :doc:`Collection </reference/constraints/Collection>`
+* :doc:`Count </reference/constraints/Count>`
+* :doc:`UniqueEntity </reference/constraints/UniqueEntity>`
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
index 99cff00927f..73a735c736e 100644
--- a/reference/dic_tags.rst
+++ b/reference/dic_tags.rst
@@ -25,6 +25,8 @@ Tag Name                                  Usage
 `kernel.event_listener`_                  Listen to different events/hooks in Symfony
 `kernel.event_subscriber`_                To subscribe to a set of different events/hooks in Symfony
 `kernel.fragment_renderer`_               Add new HTTP content rendering strategies
+`kernel.reset`_                           Allows to clean up services between requests
+`mime.mime_type_guesser`_                 Add your own logic for guessing MIME types
 `monolog.logger`_                         Logging with a custom logging channel
 `monolog.processor`_                      Add a custom processor for logging
 `routing.loader`_                         Register a custom service that loads routes
@@ -75,15 +77,15 @@ services:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="app.mysql_lock" public="false"
-                         class="App\Lock\MysqlLock" />
+                    class="App\Lock\MysqlLock"/>
                 <service id="app.postgresql_lock" public="false"
-                         class="App\Lock\PostgresqlLock" />
+                    class="App\Lock\PostgresqlLock"/>
                 <service id="app.sqlite_lock" public="false"
-                         class="App\Lock\SqliteLock" />
+                    class="App\Lock\SqliteLock"/>
             </services>
         </container>
 
@@ -126,18 +128,18 @@ the generic ``app.lock`` service can be defined as follows:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="app.mysql_lock" public="false"
-                         class="App\Lock\MysqlLock" />
+                    class="App\Lock\MysqlLock"/>
                 <service id="app.postgresql_lock" public="false"
-                         class="App\Lock\PostgresqlLock" />
+                    class="App\Lock\PostgresqlLock"/>
                 <service id="app.sqlite_lock" public="false"
-                         class="App\Lock\SqliteLock" />
+                    class="App\Lock\SqliteLock"/>
 
                 <service id="app.lock">
-                    <tag name="auto_alias" format="app.%database_type%_lock" />
+                    <tag name="auto_alias" format="app.%database_type%_lock"/>
                 </service>
             </services>
         </container>
@@ -238,7 +240,7 @@ form.type_guesser
 
 **Purpose**: Add your own logic for "form type guessing"
 
-This tag allows you to add your own logic to the :ref:`form guessing <forms-field-guessing>`
+This tag allows you to add your own logic to the :ref:`form guessing <form-type-guessing>`
 process. By default, form guessing is done by "guessers" based on the validation
 metadata and Doctrine metadata (if you're using Doctrine) or Propel metadata
 (if you're using Propel).
@@ -292,11 +294,11 @@ can also register it manually:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Cache\MyClearer">
-                    <tag name="kernel.cache_clearer" />
+                    <tag name="kernel.cache_clearer"/>
                 </service>
             </services>
         </container>
@@ -369,11 +371,11 @@ can also register it manually:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Cache\MyCustomWarmer">
-                    <tag name="kernel.cache_warmer" priority="0" />
+                    <tag name="kernel.cache_warmer" priority="0"/>
                 </service>
             </services>
         </container>
@@ -450,6 +452,36 @@ To add a new rendering strategy - in addition to the core strategies like
 :class:`Symfony\\Component\\HttpKernel\\Fragment\\FragmentRendererInterface`,
 register it as a service, then tag it with ``kernel.fragment_renderer``.
 
+kernel.reset
+------------
+
+**Purpose**: Clean up services between requests
+
+During the ``kernel.terminate`` event, Symfony looks for any service tagged
+with the ``kernel.reset`` tag to reinitialize their state. This is done by
+calling to the method whose name is configured in the ``method`` argument of
+the tag.
+
+This is mostly useful when running your projects in application servers that
+reuse the Symfony application between requests to improve performance. This tag
+is applied for example to the built-in :doc:`data collectors </profiler/data_collector>`
+of the profiler to delete all their information.
+
+.. _dic_tags-mime:
+
+mime.mime_type_guesser
+----------------------
+
+**Purpose**: Add your own logic for guessing MIME types
+
+This tag is used to register your own :ref:`MIME type guessers <components-mime-type-guess>`
+in case the guessers provided by the :doc:`Mime component </components/mime>`
+don't fit your needs.
+
+.. versionadded:: 4.3
+
+    The ``mime.mime_type_guesser`` tag was introduced in Symfony 4.3.
+
 .. _dic_tags-monolog:
 
 monolog.logger
@@ -477,12 +509,12 @@ channel when injecting the logger in a service.
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Log\CustomLogger">
-                    <argument type="service" id="logger" />
-                    <tag name="monolog.logger" channel="app" />
+                    <argument type="service" id="logger"/>
+                    <tag name="monolog.logger" channel="app"/>
                 </service>
             </services>
         </container>
@@ -533,11 +565,11 @@ You can add a processor globally:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Monolog\Processor\IntrospectionProcessor">
-                    <tag name="monolog.processor" />
+                    <tag name="monolog.processor"/>
                 </service>
             </services>
         </container>
@@ -574,11 +606,11 @@ attribute:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Monolog\Processor\IntrospectionProcessor">
-                    <tag name="monolog.processor" handler="firephp" />
+                    <tag name="monolog.processor" handler="firephp"/>
                 </service>
             </services>
         </container>
@@ -611,11 +643,11 @@ You can also add a processor for a specific logging channel by using the
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Monolog\Processor\IntrospectionProcessor">
-                    <tag name="monolog.processor" channel="security" />
+                    <tag name="monolog.processor" channel="security"/>
                 </service>
             </services>
         </container>
@@ -656,11 +688,11 @@ of your configuration and tag it with ``routing.loader``:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Routing\CustomLoader">
-                    <tag name="routing.loader" />
+                    <tag name="routing.loader"/>
                 </service>
             </services>
         </container>
@@ -778,6 +810,11 @@ templating.helper
 
 **Purpose**: Make your service available in PHP templates
 
+.. deprecated:: 4.3
+
+    The ``templating.helper`` tag is deprecated since version 4.3 and will be
+    removed in 5.0; use Twig instead.
+
 To enable a custom template helper, add it as a regular service in one
 of your configuration, tag it with ``templating.helper`` and define an
 ``alias`` attribute (the helper will be accessible via this alias in the
@@ -798,11 +835,11 @@ templates):
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Templating\AppHelper">
-                    <tag name="templating.helper" alias="alias_name" />
+                    <tag name="templating.helper" alias="alias_name"/>
                 </service>
             </services>
         </container>
@@ -847,11 +884,11 @@ Now, register your loader as a service and tag it with ``translation.loader``:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Translation\MyCustomLoader">
-                    <tag name="translation.loader" alias="bin" />
+                    <tag name="translation.loader" alias="bin"/>
                 </service>
             </services>
         </container>
@@ -941,11 +978,11 @@ required option: ``alias``, which defines the name of the extractor::
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Translation\CustomExtractor">
-                    <tag name="translation.extractor" alias="foo" />
+                    <tag name="translation.extractor" alias="foo"/>
                 </service>
             </services>
         </container>
@@ -998,11 +1035,11 @@ This is the name that's used to determine which dumper should be used.
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Translation\JsonFileDumper">
-                    <tag name="translation.dumper" alias="json" />
+                    <tag name="translation.dumper" alias="json"/>
                 </service>
             </services>
         </container>
@@ -1051,23 +1088,23 @@ the service is auto-registered and auto-tagged. But, you can also register it ma
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Twig\AppExtension">
-                    <tag name="twig.extension" />
+                    <tag name="twig.extension"/>
                 </service>
 
                 <service id="App\Twig\AnotherExtension">
-                    <tag name="twig.extension" priority="-100" />
+                    <tag name="twig.extension" priority="-100"/>
                 </service>
             </services>
         </container>
 
     .. code-block:: php
 
-        use App\Twig\AppExtension;
         use App\Twig\AnotherExtension;
+        use App\Twig\AppExtension;
 
         $container
             ->register(AppExtension::class)
@@ -1078,10 +1115,6 @@ the service is auto-registered and auto-tagged. But, you can also register it ma
             ->addTag('twig.extension', ['priority' => -100])
         ;
 
-.. versionadded:: 4.1
-    The ``priority`` attribute of the ``twig.extension`` tag was introduced in
-    Symfony 4.1.
-
 For information on how to create the actual Twig Extension class, see
 `Twig's documentation`_ on the topic or read the
 :doc:`/templating/twig_extension` article.
@@ -1106,11 +1139,11 @@ also have to be added as regular services:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Twig\Extensions\IntlExtension">
-                    <tag name="twig.extension" />
+                    <tag name="twig.extension"/>
                 </service>
             </services>
         </container>
@@ -1151,11 +1184,11 @@ also register it manually:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Twig\CustomLoader">
-                    <tag name="twig.loader" priority="0" />
+                    <tag name="twig.loader" priority="0"/>
                 </service>
             </services>
         </container>
@@ -1200,11 +1233,11 @@ the service is auto-registered and auto-tagged. But, you can also register it ma
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Twig\AppExtension">
-                    <tag name="twig.runtime" />
+                    <tag name="twig.runtime"/>
                 </service>
             </services>
         </container>
@@ -1212,7 +1245,6 @@ the service is auto-registered and auto-tagged. But, you can also register it ma
     .. code-block:: php
 
         use App\Twig\AppExtension;
-        use App\Twig\AnotherExtension;
 
         $container
             ->register(AppExtension::class)
@@ -1248,6 +1280,5 @@ Bridge.
 
 .. _`Twig's documentation`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
 .. _`Twig official extension repository`: https://github.com/fabpot/Twig-extensions
-.. _`KernelEvents`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/KernelEvents.php
 .. _`SwiftMailer's Plugin Documentation`: http://swiftmailer.org/docs/plugins.html
 .. _`Twig Loader`: https://twig.symfony.com/doc/2.x/api.html#loaders
diff --git a/reference/events.rst b/reference/events.rst
index 8c7d83f2148..6e4aab42441 100644
--- a/reference/events.rst
+++ b/reference/events.rst
@@ -28,7 +28,7 @@ following information:
 ``kernel.request``
 ~~~~~~~~~~~~~~~~~~
 
-**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\RequestEvent`
 
 This event is dispatched very early in Symfony, before the controller is
 determined. It's useful to add information to the Request or return a Response
@@ -48,16 +48,16 @@ their priorities:
 ``kernel.controller``
 ~~~~~~~~~~~~~~~~~~~~~
 
-**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent`
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\ControllerEvent`
 
 This event is dispatched after the controller to be executed has been resolved
 but before executing it. It's useful to initialize things later needed by the
 controller, such as `param converters`_, and even to change the controller
 entirely::
 
-    use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
+    use Symfony\Component\HttpKernel\Event\ControllerEvent;
 
-    public function onKernelController(FilterControllerEvent $event)
+    public function onKernelController(ControllerEvent $event)
     {
         // ...
 
@@ -76,20 +76,50 @@ their priorities:
 
     $ php bin/console debug:event-dispatcher kernel.controller
 
+``kernel.controller_arguments``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\ControllerArgumentsEvent`
+
+This event is dispatched just before a controller is called. It's useful to
+configure the arguments that are going to be passed to the controller.
+Typically, this is used to map URL routing parameters to their corresponding
+named arguments; or pass the current request when the ``Request`` type-hint is
+found::
+
+    public function onKernelControllerArguments(ControllerArgumentsEvent $event)
+    {
+        // ...
+
+        // get controller and request arguments
+        $namedArguments = $event->getRequest()->attributes->all();
+        $controllerArguments = $event->getArguments();
+
+        // set the controller arguments to modify the original arguments or add new ones
+        $event->setArguments($newArguments);
+    }
+
+Execute this command to find out which listeners are registered for this event and
+their priorities:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:event-dispatcher kernel.controller_arguments
+
 ``kernel.view``
 ~~~~~~~~~~~~~~~
 
-**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForControllerResultEvent`
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\ViewEvent`
 
 This event is dispatched after the controller has been executed but *only* if
 the controller does *not* return a :class:`Symfony\\Component\\HttpFoundation\\Response`
 object. It's useful to transform the returned value (e.g. a string with some
 HTML contents) into the ``Response`` object needed by Symfony::
 
-    use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\ViewEvent;
 
-    public function onKernelView(GetResponseForControllerResultEvent $event)
+    public function onKernelView(ViewEvent $event)
     {
         $value = $event->getControllerResult();
         $response = new Response();
@@ -113,13 +143,13 @@ their priorities:
 ``kernel.response``
 ~~~~~~~~~~~~~~~~~~~
 
-**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\ResponseEvent`
 
 This event is dispatched after the controller or any ``kernel.view`` listener
 returns a ``Response`` object. It's useful to modify or replace the response
 before sending it back (e.g. add/modify HTTP headers, add cookies, etc.)::
 
-    public function onKernelResponse(FilterResponseEvent $event)
+    public function onKernelResponse(ResponseEvent $event)
     {
         $response = $event->getResponse();
 
@@ -142,10 +172,9 @@ their priorities:
 
 **Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\FinishRequestEvent`
 
-This event is dispatched after a :ref:`sub request <http-kernel-sub-requests>`
-has finished. It's useful to reset the global state of the application (for
-example, the translator listener resets the translator's locale to the one of
-the parent request)::
+This event is dispatched after the ``kernel.response`` event. It's useful to reset
+the global state of the application (for example, the translator listener resets
+the translator's locale to the one of the parent request)::
 
     public function onKernelFinishRequest(FinishRequestEvent $event)
     {
@@ -167,7 +196,7 @@ their priorities:
 ``kernel.terminate``
 ~~~~~~~~~~~~~~~~~~~~
 
-**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\PostResponseEvent`
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\TerminateEvent`
 
 This event is dispatched after the response has been sent (after the execution
 of the :method:`Symfony\\Component\\HttpKernel\\HttpKernel::handle` method).
@@ -190,16 +219,16 @@ their priorities:
 ``kernel.exception``
 ~~~~~~~~~~~~~~~~~~~~
 
-**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`
+**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`
 
 This event is dispatched as soon as an error occurs during the handling of the
 HTTP request. It's useful to recover from errors or modify the exception details
 sent as response::
 
-    use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\ExceptionEvent;
 
-    public function onKernelException(GetResponseForExceptionEvent $event)
+    public function onKernelException(ExceptionEvent $event)
     {
         $exception = $event->getException();
         $response = new Response();
@@ -236,7 +265,7 @@ response:
 
     If you want to overwrite the status code of the exception response, which
     you should not without a good reason, call
-    ``GetResponseForExceptionEvent::allowCustomResponseCode()`` first and then
+    ``ExceptionEvent::allowCustomResponseCode()`` first and then
     set the status code on the response::
 
         $event->allowCustomResponseCode();
diff --git a/reference/forms/types/birthday.rst b/reference/forms/types/birthday.rst
index 6112a416a39..540035bec8a 100644
--- a/reference/forms/types/birthday.rst
+++ b/reference/forms/types/birthday.rst
@@ -29,6 +29,7 @@ option defaults to 120 years ago to the current year.
 |                      | - `placeholder`_                                                              |
 |                      | - `format`_                                                                   |
 |                      | - `input`_                                                                    |
+|                      | - `input_format`_                                                             |
 |                      | - `model_timezone`_                                                           |
 |                      | - `months`_                                                                   |
 |                      | - `view_timezone`_                                                            |
@@ -39,6 +40,8 @@ option defaults to 120 years ago to the current year.
 |                      | - `data`_                                                                     |
 |                      | - `disabled`_                                                                 |
 |                      | - `help`_                                                                     |
+|                      | - `help_attr`_                                                                |
+|                      | - `help_html`_                                                                |
 |                      | - `inherit_data`_                                                             |
 |                      | - `invalid_message`_                                                          |
 |                      | - `invalid_message_parameters`_                                               |
@@ -49,6 +52,8 @@ option defaults to 120 years ago to the current year.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\BirthdayType`        |
 +----------------------+-------------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Overridden Options
 ------------------
 
@@ -95,6 +100,8 @@ values for the year, month and day fields::
 
 .. include:: /reference/forms/types/options/date_input.rst.inc
 
+.. include:: /reference/forms/types/options/date_input_format.rst.inc
+
 .. include:: /reference/forms/types/options/model_timezone.rst.inc
 
 .. include:: /reference/forms/types/options/months.rst.inc
@@ -111,6 +118,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
diff --git a/reference/forms/types/button.rst b/reference/forms/types/button.rst
index 62e76989a80..d009b80235e 100644
--- a/reference/forms/types/button.rst
+++ b/reference/forms/types/button.rst
@@ -10,8 +10,10 @@ A simple, non-responsive button.
 | Rendered as          | ``button`` tag                                                       |
 +----------------------+----------------------------------------------------------------------+
 | Inherited            | - `attr`_                                                            |
-| options              | - `disabled`_                                                        |
+| options              | - `attr_translation_parameters`_                                     |
+|                      | - `disabled`_                                                        |
 |                      | - `label`_                                                           |
+|                      | - `label_translation_parameters`_                                    |
 |                      | - `translation_domain`_                                              |
 +----------------------+----------------------------------------------------------------------+
 | Parent type          | none                                                                 |
@@ -19,6 +21,8 @@ A simple, non-responsive button.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ButtonType` |
 +----------------------+----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -49,3 +53,41 @@ as a key. This can be useful when you need to set a custom class for the button:
 .. include:: /reference/forms/types/options/button_label.rst.inc
 
 .. include:: /reference/forms/types/options/button_translation_domain.rst.inc
+
+label_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+.. versionadded:: 4.3
+
+    The ``label_translation_parameters`` option was introduced in Symfony 4.3.
+
+The content of the `label`_ option is translated before displaying it, so it
+can contain :ref:`translation placeholders <component-translation-placeholders>`.
+This option defines the values used to replace those placeholders.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yaml
+    form.order.submit_to_company: 'Send an order to %company%'
+
+You can specify the placeholder values as follows::
+
+    use Symfony\Component\Form\Extension\Core\Type\ButtonType;
+    // ...
+
+    $builder->add('send', ButtonType::class, [
+        'label' => 'form.order.submit_to_company',
+        'label_translation_parameters' => [
+            '%company%' => 'ACME Inc.',
+        ],
+    ]);
+
+The ``label_translation_parameters`` option of buttons is merged with the same
+option of its parents, so buttons can reuse and/or override any of the parent
+placeholders.
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
diff --git a/reference/forms/types/checkbox.rst b/reference/forms/types/checkbox.rst
index f0fbba52979..e5b23ab68a1 100644
--- a/reference/forms/types/checkbox.rst
+++ b/reference/forms/types/checkbox.rst
@@ -25,6 +25,8 @@ if you want to handle submitted values like "0" or "false").
 |             | - `error_bubbling`_                                                    |
 |             | - `error_mapping`_                                                     |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -36,6 +38,8 @@ if you want to handle submitted values like "0" or "false").
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\CheckboxType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Example Usage
 -------------
 
@@ -83,6 +87,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
index e4e728e37fc..fdcf71647a7 100644
--- a/reference/forms/types/choice.rst
+++ b/reference/forms/types/choice.rst
@@ -36,6 +36,8 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
 |             | - `disabled`_                                                                |
 |             | - `error_mapping`_                                                           |
 |             | - `help`_                                                                    |
+|             | - `help_attr`_                                                               |
+|             | - `help_html`_                                                               |
 |             | - `inherit_data`_                                                            |
 |             | - `label`_                                                                   |
 |             | - `label_attr`_                                                              |
@@ -43,17 +45,23 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
 |             | - `mapped`_                                                                  |
 |             | - `required`_                                                                |
 |             | - `translation_domain`_                                                      |
+|             | - `label_translation_parameters`_                                            |
+|             | - `attr_translation_parameters`_                                             |
+|             | - `help_translation_parameters`_                                             |
 +-------------+------------------------------------------------------------------------------+
 | Parent type | :doc:`FormType </reference/forms/types/form>`                                |
 +-------------+------------------------------------------------------------------------------+
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ChoiceType`         |
 +-------------+------------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Example Usage
 -------------
 
-The easiest way to use this field is to specify the choices directly via
-the ``choices`` option::
+The easiest way to use this field is to define the ``choices`` option to specify
+the choices as an associative array where the keys are the labels displayed to
+end users and the array values are the internal values used in the form field::
 
     use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
     // ...
@@ -94,18 +102,17 @@ method::
             new Category('Cat3'),
             new Category('Cat4'),
         ],
-        'choice_label' => function($category, $key, $value) {
-            /** @var Category $category */
+        'choice_label' => function(Category $category, $key, $value) {
             return strtoupper($category->getName());
         },
-        'choice_attr' => function($category, $key, $value) {
+        'choice_attr' => function(Category $category, $key, $value) {
             return ['class' => 'category_'.strtolower($category->getName())];
         },
-        'group_by' => function($category, $key, $value) {
+        'group_by' => function(Category $category, $key, $value) {
             // randomly assign things into 2 groups
             return rand(0, 1) == 1 ? 'Group A' : 'Group B';
         },
-        'preferred_choices' => function($category, $key, $value) {
+        'preferred_choices' => function(Category $category, $key, $value) {
             return $category->getName() == 'Cat2' || $category->getName() == 'Cat3';
         },
     ]);
@@ -275,6 +282,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/label.rst.inc
@@ -289,6 +300,12 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc
 
+.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
+
 Field Variables
 ---------------
 
diff --git a/reference/forms/types/collection.rst b/reference/forms/types/collection.rst
index b441cdba35b..c0ca2e993ae 100644
--- a/reference/forms/types/collection.rst
+++ b/reference/forms/types/collection.rst
@@ -28,6 +28,8 @@ photos).
 |             | - `error_bubbling`_                                                         |
 |             | - `error_mapping`_                                                          |
 |             | - `help`_                                                                   |
+|             | - `help_attr`_                                                              |
+|             | - `help_html`_                                                              |
 |             | - `label`_                                                                  |
 |             | - `label_attr`_                                                             |
 |             | - `label_format`_                                                           |
@@ -39,6 +41,8 @@ photos).
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\CollectionType`    |
 +-------------+-----------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 .. note::
 
     If you are working with a collection of Doctrine entities, pay special
@@ -112,8 +116,8 @@ your form):
 
 .. code-block:: html
 
-    <input type="email" id="form_emails_0" name="form[emails][0]" value="foo@foo.com" />
-    <input type="email" id="form_emails_1" name="form[emails][1]" value="bar@bar.com" />
+    <input type="email" id="form_emails_0" name="form[emails][0]" value="foo@foo.com"/>
+    <input type="email" id="form_emails_1" name="form[emails][1]" value="bar@bar.com"/>
 
 To allow your user to add another email, just set `allow_add`_ to ``true``
 and - via JavaScript - render another field with the name ``form[emails][2]``
@@ -146,9 +150,9 @@ you need is this JavaScript code:
     // add-collection-widget.js
     jQuery(document).ready(function () {
         jQuery('.add-another-collection-widget').click(function (e) {
-            var list = jQuery(jQuery(this).attr('data-list'));
+            var list = jQuery(jQuery(this).attr('data-list-selector'));
             // Try to find the counter of the list or use the length of the list
-            var counter = list.data('widget-counter') | list.children().length;
+            var counter = list.data('widget-counter') || list.children().length;
 
             // grab the prototype template
             var newWidget = list.attr('data-prototype');
@@ -177,7 +181,8 @@ And update the template as follows:
         {# store the prototype on the data-prototype attribute #}
         <ul id="email-fields-list"
             data-prototype="{{ form_widget(form.emails.vars.prototype)|e }}"
-            data-widget-tags="{{ '<li></li>'|e }}">
+            data-widget-tags="{{ '<li></li>'|e }}"
+            data-widget-counter="{{ form.children|length }}">
         {% for emailField in form.emails %}
             <li>
                 {{ form_errors(emailField) }}
@@ -188,7 +193,7 @@ And update the template as follows:
 
         <button type="button"
             class="add-another-collection-widget"
-            data-list="#email-fields-list">Add another email</button>
+            data-list-selector="#email-fields-list">Add another email</button>
 
         {# ... #}
     {{ form_end(form) }}
@@ -236,9 +241,9 @@ allow_delete
 
 If set to ``true``, then if an existing item is not contained in the submitted
 data, it will be correctly absent from the final array of items. This means
-that you can implement a "delete" button via JavaScript which simply removes
-a form element from the DOM. When the user submits the form, its absence
-from the submitted data will mean that it's removed from the final array.
+that you can implement a "delete" button via JavaScript which removes a form
+element from the DOM. When the user submits the form, its absence from the
+submitted data will mean that it's removed from the final array.
 
 For more information, see :ref:`form-collections-remove`.
 
@@ -300,11 +305,11 @@ as your `entry_type`_ option (e.g. for a collection of drop-down menus),
 then you'd need to at least pass the ``choices`` option to the underlying
 type::
 
-    use Symfony\Component\Form\Extension\Core\Type\CollectionType;
     use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
+    use Symfony\Component\Form\Extension\Core\Type\CollectionType;
     // ...
 
-    $builder->add('favorite_cities', CollectionType::class, [
+    $builder->add('favoriteCities', CollectionType::class, [
         'entry_type'   => ChoiceType::class,
         'entry_options'  => [
             'choices'  => [
@@ -319,7 +324,7 @@ type::
 entry_type
 ~~~~~~~~~~
 
-**type**: ``string`` **default**: ``Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType``
+**type**: ``string`` **default**: ``'Symfony\Component\Form\Extension\Core\Type\TextType'``
 
 This is the field type for each item in this collection (e.g. ``TextType``,
 ``ChoiceType``, etc). For example, if you have an array of email addresses,
@@ -367,9 +372,7 @@ prototype_data
 
 Allows you to define specific data for the prototype. Each new row added will
 initially contain the data set by this option. By default, the data configured
-for all entries with the `entry_options`_ option will be used.
-
-.. code-block:: php
+for all entries with the `entry_options`_ option will be used::
 
     use Symfony\Component\Form\Extension\Core\Type\CollectionType;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
@@ -420,6 +423,10 @@ error_bubbling
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/color.rst b/reference/forms/types/color.rst
index 799d826538b..e601f1e6932 100644
--- a/reference/forms/types/color.rst
+++ b/reference/forms/types/color.rst
@@ -23,6 +23,8 @@ element.
 |             | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `label_format`_                                                   |
@@ -35,6 +37,8 @@ element.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ColorType` |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -58,6 +62,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/country.rst b/reference/forms/types/country.rst
index 8e2f37042c7..423d49e4224 100644
--- a/reference/forms/types/country.rst
+++ b/reference/forms/types/country.rst
@@ -42,6 +42,8 @@ the option manually, but then you should just use the ``ChoiceType`` directly.
 |             | - `disabled`_                                                         |
 |             | - `empty_data`_                                                       |
 |             | - `help`_                                                             |
+|             | - `help_attr`_                                                        |
+|             | - `help_html`_                                                        |
 |             | - `label`_                                                            |
 |             | - `label_attr`_                                                       |
 |             | - `label_format`_                                                     |
@@ -53,6 +55,8 @@ the option manually, but then you should just use the ``ChoiceType`` directly.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\CountryType` |
 +-------------+-----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -113,6 +117,10 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst
index e6a4a1a1ec7..15f94ec5b6b 100644
--- a/reference/forms/types/currency.rst
+++ b/reference/forms/types/currency.rst
@@ -34,6 +34,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 |             | - `disabled`_                                                          |
 |             | - `empty_data`_                                                        |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -45,6 +47,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\CurrencyType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -102,6 +106,10 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/date.rst b/reference/forms/types/date.rst
index 466dc26ef97..6e2be4140e3 100644
--- a/reference/forms/types/date.rst
+++ b/reference/forms/types/date.rst
@@ -21,6 +21,7 @@ and can understand a number of different input formats via the `input`_ option.
 |                      | - `format`_                                                                 |
 |                      | - `html5`_                                                                  |
 |                      | - `input`_                                                                  |
+|                      | - `input_format`_                                                           |
 |                      | - `model_timezone`_                                                         |
 |                      | - `months`_                                                                 |
 |                      | - `view_timezone`_                                                          |
@@ -36,6 +37,8 @@ and can understand a number of different input formats via the `input`_ option.
 | options              | - `disabled`_                                                               |
 |                      | - `error_mapping`_                                                          |
 |                      | - `help`_                                                                   |
+|                      | - `help_attr`_                                                              |
+|                      | - `help_html`_                                                              |
 |                      | - `inherit_data`_                                                           |
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
@@ -46,11 +49,13 @@ and can understand a number of different input formats via the `input`_ option.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateType`          |
 +----------------------+-----------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Basic Usage
 -----------
 
-This field type is highly configurable, but easy to use. The most important
-options are ``input`` and ``widget``.
+This field type is highly configurable. The most important options
+are ``input`` and ``widget``.
 
 Suppose that you have a ``publishedAt`` field whose underlying date is a
 ``DateTime`` object. The following configures the ``date`` type for that
@@ -63,8 +68,13 @@ field as **three different choice fields**::
         'widget' => 'choice',
     ]);
 
-If your underlying date is *not* a ``DateTime`` object (e.g. it's a unix timestamp),
-configure the `input`_ option.
+If your underlying date is *not* a ``DateTime`` object (e.g. it's a unix
+timestamp or a ``DateTimeImmutable`` object), configure the `input`_ option::
+
+    $builder->add('publishedAt', DateType::class, [
+        'widget' => 'choice',
+        'input'  => 'datetime_immutable'
+    ]);
 
 Rendering a single HTML5 Textbox
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -161,12 +171,19 @@ values for the year, month and day fields::
 
 .. include:: /reference/forms/types/options/date_format.rst.inc
 
+.. deprecated:: 4.3
+
+    Using the ``format`` option when the ``html5`` option is enabled is deprecated
+    since Symfony 4.3.
+
 .. include:: /reference/forms/types/options/html5.rst.inc
 
 .. _form-reference-date-input:
 
 .. include:: /reference/forms/types/options/date_input.rst.inc
 
+.. include:: /reference/forms/types/options/date_input_format.rst.inc
+
 .. include:: /reference/forms/types/options/model_timezone.rst.inc
 
 .. include:: /reference/forms/types/options/months.rst.inc
@@ -209,6 +226,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
diff --git a/reference/forms/types/dateinterval.rst b/reference/forms/types/dateinterval.rst
index 62287313b6f..f824df14877 100644
--- a/reference/forms/types/dateinterval.rst
+++ b/reference/forms/types/dateinterval.rst
@@ -40,6 +40,8 @@ or an array (see `input`_).
 | Inherited            | - `data`_                                                                        |
 | options              | - `disabled`_                                                                    |
 |                      | - `help`_                                                                        |
+|                      | - `help_attr`_                                                                   |
+|                      | - `help_html`_                                                                   |
 |                      | - `inherit_data`_                                                                |
 |                      | - `invalid_message`_                                                             |
 |                      | - `invalid_message_parameters`_                                                  |
@@ -50,11 +52,12 @@ or an array (see `input`_).
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateIntervalType`       |
 +----------------------+----------------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Basic Usage
 -----------
 
-This field type is highly configurable, but easy to use. The most important
-options are `input`_ and `widget`_.
+This field type is highly configurable. The most important options are `input`_ and `widget`_.
 
 You can configure *a lot* of different options, including exactly *which* range
 options to show (e.g. don't show "months", but *do* show "days")::
@@ -81,7 +84,11 @@ days
 List of days available to the days field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'days' => range(1, 31)
+    // values displayed to users range from 0 to 30 (both inclusive)
+    'days' => range(1, 31),
+
+    // values displayed to users range from 1 to 31 (both inclusive)
+    'days' => array_combine(range(1, 31), range(1, 31)),
 
 placeholder
 ~~~~~~~~~~~
@@ -110,7 +117,11 @@ hours
 List of hours available to the hours field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'hours' => range(1, 24)
+    // values displayed to users range from 0 to 23 (both inclusive)
+    'hours' => range(1, 24),
+
+    // values displayed to users range from 1 to 24 (both inclusive)
+    'hours' => array_combine(range(1, 24), range(1, 24)),
 
 input
 ~~~~~
@@ -140,6 +151,7 @@ are ``null``, so they display the "humanized version" of the child names (``Inve
         'invert' => null,
         'years' => null,
         'months' => null,
+        'weeks' => null,
         'days' => null,
         'hours' => null,
         'minutes' => null,
@@ -154,7 +166,11 @@ minutes
 List of minutes available to the minutes field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'minutes' => range(1, 60)
+    // values displayed to users range from 0 to 59 (both inclusive)
+    'minutes' => range(1, 60),
+
+    // values displayed to users range from 1 to 60 (both inclusive)
+    'minutes' => array_combine(range(1, 60), range(1, 60)),
 
 months
 ~~~~~~
@@ -164,7 +180,11 @@ months
 List of months available to the months field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'months' => range(1, 12)
+    // values displayed to users range from 0 to 11 (both inclusive)
+    'months' => range(1, 12),
+
+    // values displayed to users range from 1 to 12 (both inclusive)
+    'months' => array_combine(range(1, 12), range(1, 12)),
 
 seconds
 ~~~~~~~
@@ -174,7 +194,11 @@ seconds
 List of seconds available to the seconds field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'seconds' => range(1, 60)
+    // values displayed to users range from 0 to 59 (both inclusive)
+    'seconds' => range(1, 60),
+
+    // values displayed to users range from 1 to 60 (both inclusive)
+    'seconds' => array_combine(range(1, 60), range(1, 60)),
 
 weeks
 ~~~~~
@@ -184,7 +208,11 @@ weeks
 List of weeks available to the weeks field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'weeks' => range(1, 52)
+    // values displayed to users range from 0 to 51 (both inclusive)
+    'weeks' => range(1, 52),
+
+    // values displayed to users range from 1 to 52 (both inclusive)
+    'weeks' => array_combine(range(1, 52), range(1, 52)),
 
 widget
 ~~~~~~
@@ -297,7 +325,11 @@ years
 List of years available to the years field type. This option is only relevant
 when the ``widget`` option is set to ``choice``::
 
-    'years' => range(1, 100)
+    // values displayed to users range from 0 to 99 (both inclusive)
+    'years' => range(1, 100),
+
+    // values displayed to users range from 1 to 100 (both inclusive)
+    'years' => array_combine(range(1, 100), range(1, 100)),
 
 Inherited Options
 -----------------
@@ -310,6 +342,10 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
diff --git a/reference/forms/types/datetime.rst b/reference/forms/types/datetime.rst
index 26cb38a67dd..99fb9aa1722 100644
--- a/reference/forms/types/datetime.rst
+++ b/reference/forms/types/datetime.rst
@@ -17,6 +17,7 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 +----------------------+-----------------------------------------------------------------------------+
 | Options              | - `choice_translation_domain`_                                              |
 |                      | - `date_format`_                                                            |
+|                      | - `date_label`_                                                             |
 |                      | - `date_widget`_                                                            |
 |                      | - `days`_                                                                   |
 |                      | - `placeholder`_                                                            |
@@ -24,10 +25,12 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `hours`_                                                                  |
 |                      | - `html5`_                                                                  |
 |                      | - `input`_                                                                  |
+|                      | - `input_format`_                                                           |
 |                      | - `minutes`_                                                                |
 |                      | - `model_timezone`_                                                         |
 |                      | - `months`_                                                                 |
 |                      | - `seconds`_                                                                |
+|                      | - `time_label`_                                                             |
 |                      | - `time_widget`_                                                            |
 |                      | - `view_timezone`_                                                          |
 |                      | - `widget`_                                                                 |
@@ -43,6 +46,8 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 | Inherited            | - `data`_                                                                   |
 | options              | - `disabled`_                                                               |
 |                      | - `help`_                                                                   |
+|                      | - `help_attr`_                                                              |
+|                      | - `help_html`_                                                              |
 |                      | - `inherit_data`_                                                           |
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
@@ -53,6 +58,8 @@ the data can be a ``DateTime`` object, a string, a timestamp or an array.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateTimeType`      |
 +----------------------+-----------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -67,11 +74,35 @@ Defines the ``format`` option that will be passed down to the date field.
 See the :ref:`DateType's format option <reference-forms-type-date-format>`
 for more details.
 
+.. deprecated:: 4.3
+
+    Using the ``date_format`` option when the form is rendered as an HTML 5
+    datetime input is deprecated since Symfony 4.3.
+
+date_label
+~~~~~~~~~~
+
+**type**: ``string`` | ``null`` **default**: The label is "guessed" from the field name
+
+Sets the label that will be used when rendering the date widget. Setting it to
+``false`` will suppress the label::
+
+    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
+
+    $builder->add('startDateTime', DateTimeType::class, [
+        'date_label' => 'Starts On',
+    ]);
+
 date_widget
 ~~~~~~~~~~~
 
 .. include:: /reference/forms/types/options/date_widget_description.rst.inc
 
+.. deprecated:: 4.3
+
+    Using the ``date_widget`` option when the ``widget`` option is set to
+    ``single_text`` is deprecated since Symfony 4.3.
+
 .. include:: /reference/forms/types/options/days.rst.inc
 
 placeholder
@@ -113,6 +144,11 @@ used by the HTML5 ``datetime-local`` field. Keeping the default value will
 cause the field to be rendered as an ``input`` field with ``type="datetime-local"``.
 For more information on valid formats, see `Date/Time Format Syntax`_.
 
+.. deprecated:: 4.3
+
+    Using the ``format`` option when the ``html5`` option is enabled is deprecated
+    since Symfony 4.3.
+
 .. include:: /reference/forms/types/options/hours.rst.inc
 
 .. include:: /reference/forms/types/options/html5.rst.inc
@@ -136,6 +172,13 @@ this format.
 
 .. include:: /reference/forms/types/options/_date_limitation.rst.inc
 
+input_format
+~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``Y-m-d H:i:s``
+
+.. include:: /reference/forms/types/options/date_input_format_description.rst.inc
+
 .. include:: /reference/forms/types/options/minutes.rst.inc
 
 .. include:: /reference/forms/types/options/model_timezone.rst.inc
@@ -144,6 +187,20 @@ this format.
 
 .. include:: /reference/forms/types/options/seconds.rst.inc
 
+time_label
+~~~~~~~~~~
+
+**type**: ``string`` | ``null`` **default**: The label is "guessed" from the field name
+
+Sets the label that will be used when rendering the time widget. Setting it to
+``false`` will suppress the label::
+
+    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
+
+    $builder->add('startDateTime', DateTimeType::class, [
+        'time_label' => 'Starts On',
+    ]);
+
 time_widget
 ~~~~~~~~~~~
 
@@ -151,6 +208,11 @@ time_widget
 
 Defines the ``widget`` option for the :doc:`TimeType </reference/forms/types/time>`.
 
+.. deprecated:: 4.3
+
+    Using the ``time_widget`` option when the ``widget`` option is set to
+    ``single_text`` is deprecated since Symfony 4.3.
+
 .. include:: /reference/forms/types/options/view_timezone.rst.inc
 
 widget
@@ -198,6 +260,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
diff --git a/reference/forms/types/email.rst b/reference/forms/types/email.rst
index 67eb149506c..f2e694857a8 100644
--- a/reference/forms/types/email.rst
+++ b/reference/forms/types/email.rst
@@ -5,7 +5,7 @@ EmailType Field
 ===============
 
 The ``EmailType`` field is a text field that is rendered using the HTML5
-``<input type="email" />`` tag.
+``<input type="email"/>`` tag.
 
 +-------------+---------------------------------------------------------------------+
 | Rendered as | ``input`` ``email`` field (a text box)                              |
@@ -16,6 +16,8 @@ The ``EmailType`` field is a text field that is rendered using the HTML5
 |             | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `label_format`_                                                   |
@@ -28,6 +30,8 @@ The ``EmailType`` field is a text field that is rendered using the HTML5
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\EmailType` |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -51,6 +55,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
index 2005fc594c6..7415cfe5d48 100644
--- a/reference/forms/types/entity.rst
+++ b/reference/forms/types/entity.rst
@@ -36,23 +36,31 @@ objects from the database.
 |             |                                                                  |
 |             | from the :doc:`FormType </reference/forms/types/form>`:          |
 |             |                                                                  |
+|             | - `attr`_                                                        |
 |             | - `data`_                                                        |
 |             | - `disabled`_                                                    |
 |             | - `empty_data`_                                                  |
 |             | - `error_bubbling`_                                              |
 |             | - `error_mapping`_                                               |
 |             | - `help`_                                                        |
+|             | - `help_attr`_                                                   |
+|             | - `help_html`_                                                   |
 |             | - `label`_                                                       |
 |             | - `label_attr`_                                                  |
 |             | - `label_format`_                                                |
 |             | - `mapped`_                                                      |
 |             | - `required`_                                                    |
+|             | - `label_translation_parameters`_                                |
+|             | - `attr_translation_parameters`_                                 |
+|             | - `help_translation_parameters`_                                 |
 +-------------+------------------------------------------------------------------+
 | Parent type | :doc:`ChoiceType </reference/forms/types/choice>`                |
 +-------------+------------------------------------------------------------------+
 | Class       | :class:`Symfony\\Bridge\\Doctrine\\Form\\Type\\EntityType`       |
 +-------------+------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Basic Usage
 -----------
 
@@ -102,6 +110,13 @@ the `query_builder`_ option::
         'choice_label' => 'username',
     ]);
 
+.. note::
+
+    Using form collections may result in making too many database requests to
+    fetch related entities. This is known as the *"N + 1 query problem"* and it
+    can be solved by :ref:`joining related records <doctrine-associations-join-query>`
+    when querying for Doctrine associations.
+
 .. _reference-forms-entity-choices:
 
 Using Choices
@@ -169,14 +184,15 @@ more details, see the main :ref:`choice_label <reference-form-choice-label>` doc
     :doc:`PropertyAccessor component </components/property_access>`
 
     For example, if the translations property is actually an associative
-    array of objects, each with a name property, then you could do this::
+    array of objects, each with a ``name`` property, then you could do this::
 
+        use App\Entity\Genre;
         use Symfony\Bridge\Doctrine\Form\Type\EntityType;
         // ...
 
         $builder->add('genre', EntityType::class, [
-           'class' => 'App\Entity\Genre',
-           'choice_label' => 'translations[en].name',
+            'class' => Genre::class,
+            'choice_label' => 'translations[en].name',
         ]);
 
 class
@@ -212,12 +228,12 @@ loading all entities.
 
 .. caution::
 
-    The entity used in the ``FROM`` clause of the `query_builder`_ option
-    will always be validated against the class which you have specified with
-    the form's `class`_ option. If you return another entity instead of the
+    The entity used in the ``FROM`` clause of the ``query_builder`` option
+    will always be validated against the class which you have specified at the
+    `class`_ option. If you return another entity instead of the
     one used in your ``FROM`` clause (for instance if you return an entity
     from a joined table), it will break validation.
-    
+
 Overridden Options
 ------------------
 
@@ -282,7 +298,7 @@ This option allows you to move certain choices to the top of your list with a vi
 separator between them and the rest of the options. This option expects an array
 of entity objects::
 
-    use AppBundle\Entity\User;
+    use App\Entity\User;
     use Symfony\Bridge\Doctrine\Form\Type\EntityType;
     // ...
 
@@ -308,6 +324,8 @@ when rendering the field:
 These options inherit from the :doc:`form </reference/forms/types/form>`
 type:
 
+.. include:: /reference/forms/types/options/attr.rst.inc
+
 .. include:: /reference/forms/types/options/data.rst.inc
 
 .. include:: /reference/forms/types/options/disabled.rst.inc
@@ -330,6 +348,10 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
@@ -339,3 +361,9 @@ The actual default value of this option depends on other field options:
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc
+
+.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
diff --git a/reference/forms/types/file.rst b/reference/forms/types/file.rst
index d041f41f8d6..9c9c892a98c 100644
--- a/reference/forms/types/file.rst
+++ b/reference/forms/types/file.rst
@@ -19,6 +19,8 @@ The ``FileType`` represents a file input in your form.
 | options     | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `label_format`_                                                   |
@@ -30,6 +32,8 @@ The ``FileType`` represents a file input in your form.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FileType`  |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Basic Usage
 -----------
 
@@ -127,6 +131,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst
index 35c989131c5..9d38ab840cc 100644
--- a/reference/forms/types/form.rst
+++ b/reference/forms/types/form.rst
@@ -20,6 +20,9 @@ on all types for which ``FormType`` is the parent.
 |           | - `error_mapping`_                                                 |
 |           | - `extra_fields_message`_                                          |
 |           | - `help`_                                                          |
+|           | - `help_attr`_                                                     |
+|           | - `help_html`_                                                     |
+|           | - `help_translation_parameters`_                                   |
 |           | - `inherit_data`_                                                  |
 |           | - `invalid_message`_                                               |
 |           | - `invalid_message_parameters`_                                    |
@@ -36,15 +39,20 @@ on all types for which ``FormType`` is the parent.
 | Inherited | - `attr`_                                                          |
 | options   | - `auto_initialize`_                                               |
 |           | - `block_name`_                                                    |
+|           | - `block_prefix`_                                                  |
 |           | - `disabled`_                                                      |
 |           | - `label`_                                                         |
 |           | - `translation_domain`_                                            |
+|           | - `label_translation_parameters`_                                  |
+|           | - `attr_translation_parameters`_                                   |
 +-----------+--------------------------------------------------------------------+
 | Parent    | none                                                               |
 +-----------+--------------------------------------------------------------------+
 | Class     | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType` |
 +-----------+--------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -104,6 +112,12 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
+.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
@@ -151,8 +165,14 @@ of the form type tree (i.e. it cannot be used as a form type on its own).
 
 .. include:: /reference/forms/types/options/block_name.rst.inc
 
+.. include:: /reference/forms/types/options/block_prefix.rst.inc
+
 .. include:: /reference/forms/types/options/disabled.rst.inc
 
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/translation_domain.rst.inc
+
+.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
diff --git a/reference/forms/types/hidden.rst b/reference/forms/types/hidden.rst
index e211c526f63..df3a370b7db 100644
--- a/reference/forms/types/hidden.rst
+++ b/reference/forms/types/hidden.rst
@@ -9,7 +9,7 @@ The hidden type represents a hidden input field.
 +-------------+----------------------------------------------------------------------+
 | Rendered as | ``input`` ``hidden`` field                                           |
 +-------------+----------------------------------------------------------------------+
-| Overriden   | - `compound`_                                                        |
+| Overridden  | - `compound`_                                                        |
 | options     | - `error_bubbling`_                                                  |
 |             | - `required`_                                                        |
 +-------------+----------------------------------------------------------------------+
@@ -23,6 +23,8 @@ The hidden type represents a hidden input field.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\HiddenType` |
 +-------------+----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Overridden Options
 ------------------
 
diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst
index b7bdf0662e7..42d3ea9a4db 100644
--- a/reference/forms/types/integer.rst
+++ b/reference/forms/types/integer.rst
@@ -28,6 +28,8 @@ integers. By default, all non-integer values (e.g. 6.78) will round down
 |             | - `error_bubbling`_                                                   |
 |             | - `error_mapping`_                                                    |
 |             | - `help`_                                                             |
+|             | - `help_attr`_                                                        |
+|             | - `help_html`_                                                        |
 |             | - `invalid_message`_                                                  |
 |             | - `invalid_message_parameters`_                                       |
 |             | - `label`_                                                            |
@@ -41,6 +43,8 @@ integers. By default, all non-integer values (e.g. 6.78) will round down
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\IntegerType` |
 +-------------+-----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -85,9 +89,14 @@ scale
 
 **type**: ``integer`` **default**: ``0``
 
+.. deprecated:: 4.2
+
+    The ``scale`` option is deprecated since Symfony 4.2 and will be removed
+    in 5.0.
+
 This specifies how many decimals will be allowed until the field rounds the
 submitted value (via ``rounding_mode``). This option inherits from
-:doc:`number </reference/forms/types/number>` type and is overriden to ``0`` for
+:doc:`number </reference/forms/types/number>` type and is overridden to ``0`` for
 ``IntegerType``.
 
 Inherited Options
@@ -113,6 +122,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/language.rst b/reference/forms/types/language.rst
index 940f8ef90d0..013dbbb7430 100644
--- a/reference/forms/types/language.rst
+++ b/reference/forms/types/language.rst
@@ -44,6 +44,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 |             | - `disabled`_                                                          |
 |             | - `empty_data`_                                                        |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -55,6 +57,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\LanguageType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -115,6 +119,10 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/locale.rst b/reference/forms/types/locale.rst
index 9f001264776..bfe19e9e2c8 100644
--- a/reference/forms/types/locale.rst
+++ b/reference/forms/types/locale.rst
@@ -45,6 +45,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 |             | - `disabled`_                                                          |
 |             | - `empty_data`_                                                        |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -56,6 +58,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\LocaleType`   |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -116,6 +120,10 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst
index 445441d6619..a02b68b95a7 100644
--- a/reference/forms/types/money.rst
+++ b/reference/forms/types/money.rst
@@ -29,6 +29,8 @@ how the input and output of the data is handled.
 |             | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `invalid_message`_                                                |
 |             | - `invalid_message_parameters`_                                     |
 |             | - `label`_                                                          |
@@ -42,6 +44,8 @@ how the input and output of the data is handled.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\MoneyType` |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -121,6 +125,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst
index 5f6a4c19200..c5db2c7b092 100644
--- a/reference/forms/types/number.rst
+++ b/reference/forms/types/number.rst
@@ -12,6 +12,8 @@ that you want to use for your number.
 | Rendered as | ``input`` ``text`` field                                             |
 +-------------+----------------------------------------------------------------------+
 | Options     | - `grouping`_                                                        |
+|             | - `html5`_                                                           |
+|             | - `input`_                                                           |
 |             | - `scale`_                                                           |
 |             | - `rounding_mode`_                                                   |
 +-------------+----------------------------------------------------------------------+
@@ -24,6 +26,8 @@ that you want to use for your number.
 |             | - `error_bubbling`_                                                  |
 |             | - `error_mapping`_                                                   |
 |             | - `help`_                                                            |
+|             | - `help_attr`_                                                       |
+|             | - `help_html`_                                                       |
 |             | - `invalid_message`_                                                 |
 |             | - `invalid_message_parameters`_                                      |
 |             | - `label`_                                                           |
@@ -37,11 +41,40 @@ that you want to use for your number.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\NumberType` |
 +-------------+----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
 .. include:: /reference/forms/types/options/grouping.rst.inc
 
+html5
+~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 4.3
+
+    The ``html5`` option was introduced in Symfony 4.3.
+
+If set to ``true``, the HTML input will be rendered as a native HTML5 ``type="number"``
+form.
+
+input
+~~~~~
+
+**type**: ``string`` **default**: ``number``
+
+.. versionadded:: 4.3
+
+    The ``input`` option was introduced in Symfony 4.3.
+
+The format of the input data - i.e. the format that the number is stored on
+your underlying object. Valid values are ``number`` and ``string``. Setting
+this option to ``string`` can be useful if the underlying data is a string
+for precision reasons (for example, Doctrine uses strings for the ``decimal``
+type).
+
 scale
 ~~~~~
 
@@ -82,6 +115,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/options/_debug_form.rst.inc b/reference/forms/types/options/_debug_form.rst.inc
new file mode 100644
index 00000000000..8db828a9236
--- /dev/null
+++ b/reference/forms/types/options/_debug_form.rst.inc
@@ -0,0 +1,9 @@
+.. tip::
+
+    The full list of options defined and inherited by this form type is
+    available running this command in your app:
+
+    .. code-block:: terminal
+
+        # replace 'FooType' by the class name of your form type
+        $ php bin/console debug:form FooType
diff --git a/reference/forms/types/options/_error_bubbling_hint.rst.inc b/reference/forms/types/options/_error_bubbling_hint.rst.inc
index 743da6f8d0e..78d5186b9c0 100644
--- a/reference/forms/types/options/_error_bubbling_hint.rst.inc
+++ b/reference/forms/types/options/_error_bubbling_hint.rst.inc
@@ -1,6 +1,6 @@
 .. tip::
 
-    By default the ``error_bubbling`` option is enabled for the
+    By default, the ``error_bubbling`` option is enabled for the
     :doc:`collection Field Type </reference/forms/types/collection>`,
     which passes the errors to the parent form. If you want to attach
     the errors to the locations where they actually occur you have to
diff --git a/reference/forms/types/options/attr_translation_parameters.rst.inc b/reference/forms/types/options/attr_translation_parameters.rst.inc
new file mode 100644
index 00000000000..98326ba4abe
--- /dev/null
+++ b/reference/forms/types/options/attr_translation_parameters.rst.inc
@@ -0,0 +1,37 @@
+attr_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+.. versionadded:: 4.3
+
+    The ``attr_translation_parameters`` option was introduced in Symfony 4.3.
+
+The content of the ``title`` and ``placeholder`` values defined in the `attr`_
+option is translated before displaying it, so it can contain
+:ref:`translation placeholders <component-translation-placeholders>`. This
+option defines the values used to replace those placeholders.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yaml
+    form.order.id.placeholder: 'Enter unique identifier of the order to %company%'
+    form.order.id.title: 'This will be the reference in communications with %company%'
+
+You can specify the placeholder values as follows::
+
+    $builder->add('id', null, [
+        'attr' => [
+            'placeholder' => 'form.order.id.placeholder',
+            'title' => 'form.order.id.title',
+        ],
+        'attr_translation_parameters' => [
+            '%company%' => 'ACME Inc.',
+        ],
+    ]);
+
+The ``attr_translation_parameters`` option of children fields is merged with the
+same option of their parents, so children can reuse and/or override any of the
+parent placeholders.
diff --git a/reference/forms/types/options/block_name.rst.inc b/reference/forms/types/options/block_name.rst.inc
index 7d040ce85ed..f873c1014ad 100644
--- a/reference/forms/types/options/block_name.rst.inc
+++ b/reference/forms/types/options/block_name.rst.inc
@@ -4,6 +4,11 @@ block_name
 **type**: ``string`` **default**: the form's name (see :ref:`Knowing which
 block to customize <form-customization-sidebar>`)
 
-Allows you to override the block name used to render the form type.
-Useful for example if you have multiple instances of the same form and you
-need to personalize the rendering of the forms individually.
+Allows you to add a custom block name to the ones used by default to render the
+form type. Useful for example if you have multiple instances of the same form
+and you need to personalize the rendering of the forms individually.
+
+If you set for example this option to ``my_custom_name`` and the field is of
+type ``text``, Symfony will use the following names (and in this order) to find
+the block used to render the widget of the field: ``_my_custom_name_widget``,
+``text_widget`` and ``form_widget``.
diff --git a/reference/forms/types/options/block_prefix.rst.inc b/reference/forms/types/options/block_prefix.rst.inc
new file mode 100644
index 00000000000..f02feb0ce70
--- /dev/null
+++ b/reference/forms/types/options/block_prefix.rst.inc
@@ -0,0 +1,14 @@
+block_prefix
+~~~~~~~~~~~~
+
+**type**: ``string`` or ``null`` **default**: ``null`` (see :ref:`Knowing which
+block to customize <form-customization-sidebar>`)
+
+.. versionadded:: 4.3
+
+    The ``block_prefix`` option was introduced in Symfony 4.3.
+
+Allows you to add a custom block prefix and override the block name
+used to render the form type. Useful for example if you have multiple
+instances of the same form and you need to personalize the rendering
+of all of them without the need to create a new form type.
diff --git a/reference/forms/types/options/button_label.rst.inc b/reference/forms/types/options/button_label.rst.inc
index 28ec3d7edd1..b0f7146c7d0 100644
--- a/reference/forms/types/options/button_label.rst.inc
+++ b/reference/forms/types/options/button_label.rst.inc
@@ -8,7 +8,7 @@ be directly set inside the template:
 
 .. configuration-block::
 
-    .. code-block:: html+twig
+    .. code-block:: twig
 
         {{ form_widget(form.save, { 'label': 'Click me' }) }}
 
diff --git a/reference/forms/types/options/by_reference.rst.inc b/reference/forms/types/options/by_reference.rst.inc
index c3921c58a72..257c0c5a6e4 100644
--- a/reference/forms/types/options/by_reference.rst.inc
+++ b/reference/forms/types/options/by_reference.rst.inc
@@ -10,9 +10,9 @@ called in all cases.
 
 To explain this further, here's a simple example::
 
-    use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\EmailType;
     use Symfony\Component\Form\Extension\Core\Type\FormType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
     // ...
 
     $builder = $this->createFormBuilder($article);
diff --git a/reference/forms/types/options/checkbox_compound.rst.inc b/reference/forms/types/options/checkbox_compound.rst.inc
index bf328936647..e8e8a9c13ac 100644
--- a/reference/forms/types/options/checkbox_compound.rst.inc
+++ b/reference/forms/types/options/checkbox_compound.rst.inc
@@ -4,4 +4,4 @@ compound
 **type**: ``boolean`` **default**: ``false``
 
 This option specifies if a form is compound. As it's not the case for checkbox,
-by default the value is overridden with the ``false`` value.
+by default, the value is overridden with the ``false`` value.
diff --git a/reference/forms/types/options/checkbox_empty_data.rst.inc b/reference/forms/types/options/checkbox_empty_data.rst.inc
index 324489f13fb..0c1c62609d3 100644
--- a/reference/forms/types/options/checkbox_empty_data.rst.inc
+++ b/reference/forms/types/options/checkbox_empty_data.rst.inc
@@ -5,4 +5,4 @@ empty_data
 
 This option determines what value the field will return when the ``placeholder``
 choice is selected. In the checkbox and the radio type, the value of ``empty_data``
-is overriden by the value returned by the data transformer (see :doc:`/form/data_transformers`).
+is overridden by the value returned by the data transformer (see :doc:`/form/data_transformers`).
diff --git a/reference/forms/types/options/choice_attr.rst.inc b/reference/forms/types/options/choice_attr.rst.inc
index 87c467f7773..c400a83a5d9 100644
--- a/reference/forms/types/options/choice_attr.rst.inc
+++ b/reference/forms/types/options/choice_attr.rst.inc
@@ -19,7 +19,7 @@ If an array, the keys of the ``choices`` array must be used as keys::
             'No' => false,
             'Maybe' => null,
         ],
-        'choice_attr' => function($choiceValue, $key, $value) {
+        'choice_attr' => function($choice, $key, $value) {
             // adds a class like attending_yes, attending_no, etc
             return ['class' => 'attending_'.strtolower($key)];
         },
diff --git a/reference/forms/types/options/choice_label.rst.inc b/reference/forms/types/options/choice_label.rst.inc
index 8935757b7e0..acc909dba7e 100644
--- a/reference/forms/types/options/choice_label.rst.inc
+++ b/reference/forms/types/options/choice_label.rst.inc
@@ -16,8 +16,8 @@ more control::
             'no' => false,
             'maybe' => null,
         ],
-        'choice_label' => function ($choiceValue, $key, $value) {
-            if ($value == $choiceValue) {
+        'choice_label' => function ($choice, $key, $value) {
+            if (true === $choice) {
                 return 'Definitely!';
             }
 
@@ -28,9 +28,9 @@ more control::
         },
     ]);
 
-This method is called for *each* choice, passing you the choice ``$value`` and the
-``$key`` from the choices array (``$index`` is related to `choice_value`_). This
-will give you:
+This method is called for *each* choice, passing you the ``$choice`` and
+``$key`` from the choices array (additional ``$value`` is related to `choice_value`_).
+This will give you:
 
 .. image:: /_images/reference/form/choice-example2.png
    :align: center
diff --git a/reference/forms/types/options/choice_name.rst.inc b/reference/forms/types/options/choice_name.rst.inc
index 341e0a686fb..b1f09f79e82 100644
--- a/reference/forms/types/options/choice_name.rst.inc
+++ b/reference/forms/types/options/choice_name.rst.inc
@@ -9,3 +9,10 @@ of the choice views in the template.
 
 This can be a callable or a property path. See `choice_label`_ for similar usage.
 If ``null`` is used, an incrementing integer is used as the name.
+
+.. caution::
+
+    The configured value must be a valid form name. Make sure to only return
+    valid names when using a callable. Valid form names must be composed of
+    letters, digits, underscores, dashes and colons and must not start with
+    a dash or a colon.
diff --git a/reference/forms/types/options/choice_type_translation_domain.rst.inc b/reference/forms/types/options/choice_type_translation_domain.rst.inc
index 87cd76cff9a..c22125ea844 100644
--- a/reference/forms/types/options/choice_type_translation_domain.rst.inc
+++ b/reference/forms/types/options/choice_type_translation_domain.rst.inc
@@ -5,4 +5,4 @@ translation_domain
 
 In case `choice_translation_domain`_ is set to ``true`` or ``null``, this
 configures the exact translation domain that will be used for any labels or
-options that are rendered for this field
+options that are rendered for this field.
diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc
index 9698ff822a6..507d54315ca 100644
--- a/reference/forms/types/options/data.rst.inc
+++ b/reference/forms/types/options/data.rst.inc
@@ -19,6 +19,6 @@ an individual field, you can set it in the data option::
 .. caution::
 
     The ``data`` option *always* overrides the value taken from the domain data
-    (object) when rendering. This means the object value is also overriden when
+    (object) when rendering. This means the object value is also overridden when
     the form edits an already persisted object, causing it to lose its
     persisted value when the form is submitted.
diff --git a/reference/forms/types/options/date_format.rst.inc b/reference/forms/types/options/date_format.rst.inc
index 961a8ef63ae..ad1c2a9c718 100644
--- a/reference/forms/types/options/date_format.rst.inc
+++ b/reference/forms/types/options/date_format.rst.inc
@@ -16,7 +16,7 @@ For more information on valid formats, see `Date/Time Format Syntax`_::
     use Symfony\Component\Form\Extension\Core\Type\DateType;
     // ...
 
-    $builder->add('date_created', DateType::class, [
+    $builder->add('dateCreated', DateType::class, [
         'widget' => 'single_text',
         // this is actually the default format for single_text
         'format' => 'yyyy-MM-dd',
diff --git a/reference/forms/types/options/date_input_format.rst.inc b/reference/forms/types/options/date_input_format.rst.inc
new file mode 100644
index 00000000000..ead92072642
--- /dev/null
+++ b/reference/forms/types/options/date_input_format.rst.inc
@@ -0,0 +1,6 @@
+input_format
+~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``Y-m-d``
+
+.. include:: /reference/forms/types/options/date_input_format_description.rst.inc
diff --git a/reference/forms/types/options/date_input_format_description.rst.inc b/reference/forms/types/options/date_input_format_description.rst.inc
new file mode 100644
index 00000000000..4cd9b353e31
--- /dev/null
+++ b/reference/forms/types/options/date_input_format_description.rst.inc
@@ -0,0 +1,8 @@
+.. versionadded:: 4.3
+
+    The ``input_format`` option was introduced in Symfony 4.3.
+
+If the ``input`` option is set to ``string``, this option specifies the format
+of the date. This must be a valid `PHP date format`_.
+
+.. _`PHP date format`: https://secure.php.net/manual/en/function.date.php
diff --git a/reference/forms/types/options/error_mapping.rst.inc b/reference/forms/types/options/error_mapping.rst.inc
index ce50f2f1126..5b1122dd5ab 100644
--- a/reference/forms/types/options/error_mapping.rst.inc
+++ b/reference/forms/types/options/error_mapping.rst.inc
@@ -26,12 +26,12 @@ Here are the rules for the left and the right side of the mapping:
 
 * The left side contains property paths;
 * If the violation is generated on a property or method of a class, its
-  path is simply ``propertyName``;
+  path is the ``propertyName``;
 * If the violation is generated on an entry of an ``array`` or ``ArrayAccess``
   object, the property path is ``[indexName]``;
 * You can construct nested property paths by concatenating them, separating
   properties by dots. For example: ``addresses[work].matchingCityAndZipCode``;
-* The right side contains simply the names of fields in the form.
+* The right side contains the names of fields in the form.
 
 By default, errors for any property that is not mapped will bubble up to the
 parent form. You can use the dot (``.``) on the left side to map errors of all
diff --git a/reference/forms/types/options/group_by.rst.inc b/reference/forms/types/options/group_by.rst.inc
index 563ebbfee03..021d3156d6d 100644
--- a/reference/forms/types/options/group_by.rst.inc
+++ b/reference/forms/types/options/group_by.rst.inc
@@ -1,7 +1,7 @@
 group_by
 ~~~~~~~~
 
-**type**: ``array``, ``callable`` or ``string`` **default**: ``null``
+**type**: ``string`` or ``callable`` **default**: ``null``
 
 You can group the ``<option>`` elements of a ``<select>`` into ``<optgroup>``
 by passing a multi-dimensional array to ``choices``. See the
@@ -22,8 +22,8 @@ Take the following example::
             '1 week' => new \DateTime('+1 week'),
             '1 month' => new \DateTime('+1 month'),
         ],
-        'group_by' => function($choiceValue, $key, $value) {
-            if ($choiceValue <= new \DateTime('+3 days')) {
+        'group_by' => function($choice, $key, $value) {
+            if ($choice <= new \DateTime('+3 days')) {
                 return 'Soon';
             } else {
                 return 'Later';
diff --git a/reference/forms/types/options/grouping.rst.inc b/reference/forms/types/options/grouping.rst.inc
index 4362678e339..0ebd339b2e8 100644
--- a/reference/forms/types/options/grouping.rst.inc
+++ b/reference/forms/types/options/grouping.rst.inc
@@ -1,7 +1,7 @@
 grouping
 ~~~~~~~~
 
-**type**: ``integer`` **default**: ``false``
+**type**: ``boolean`` **default**: ``false``
 
 This value is used internally as the ``NumberFormatter::GROUPING_USED``
 value when using PHP's ``NumberFormatter`` class. Its documentation is
diff --git a/reference/forms/types/options/help.rst.inc b/reference/forms/types/options/help.rst.inc
index e2e86ca385a..ded87842d8e 100644
--- a/reference/forms/types/options/help.rst.inc
+++ b/reference/forms/types/options/help.rst.inc
@@ -4,10 +4,8 @@ help
 **type**: ``string`` **default**: null
 
 Allows you to define a help message for the form field, which by default is
-rendered below the field.
+rendered below the field::
 
-.. code-block:: php
-
-    $builder->add('zip_code', null, [
+    $builder->add('zipCode', null, [
         'help' => 'The ZIP/Postal code for your credit card\'s billing address.',
     ]);
diff --git a/reference/forms/types/options/help_attr.rst.inc b/reference/forms/types/options/help_attr.rst.inc
new file mode 100644
index 00000000000..71e086e0235
--- /dev/null
+++ b/reference/forms/types/options/help_attr.rst.inc
@@ -0,0 +1,14 @@
+help_attr
+~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+Sets the HTML attributes for the element used to display the help message of the
+form field. Its value is an associative array with HTML attribute names as keys.
+These attributes can also be set in the template:
+
+.. code-block:: twig
+
+    {{ form_help(form.name, 'Your name', {
+        'help_attr': {'class': 'CUSTOM_LABEL_CLASS'}
+    }) }}
diff --git a/reference/forms/types/options/help_html.rst.inc b/reference/forms/types/options/help_html.rst.inc
new file mode 100644
index 00000000000..83bbe583ca6
--- /dev/null
+++ b/reference/forms/types/options/help_html.rst.inc
@@ -0,0 +1,8 @@
+help_html
+~~~~~~~~~
+
+**type**: ``bool`` **default**: ``false``
+
+By default, the contents of the ``help`` option are escaped before rendering
+them in the template. Set this option to ``true`` to not escape them, which is
+useful when the help contains HTML elements.
diff --git a/reference/forms/types/options/help_translation_parameters.rst.inc b/reference/forms/types/options/help_translation_parameters.rst.inc
new file mode 100644
index 00000000000..4294fb2b185
--- /dev/null
+++ b/reference/forms/types/options/help_translation_parameters.rst.inc
@@ -0,0 +1,32 @@
+help_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+.. versionadded:: 4.3
+
+    The ``help_translation_parameters`` option was introduced in Symfony 4.3.
+
+The content of the `help`_ option is translated before displaying it, so it
+can contain :ref:`translation placeholders <component-translation-placeholders>`.
+This option defines the values used to replace those placeholders.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yaml
+    form.order.id.help: 'This will be the reference in communications with %company%'
+
+You can specify the placeholder values as follows::
+
+    $builder->add('id', null, [
+        'help' => 'form.order.id.help',
+        'help_translation_parameters' => [
+            '%company%' => 'ACME Inc.',
+        ],
+    ]);
+
+The ``help_translation_parameters`` option of children fields is merged with the
+same option of their parents, so children can reuse and/or override any of the
+parent placeholders.
diff --git a/reference/forms/types/options/invalid_message_parameters.rst.inc b/reference/forms/types/options/invalid_message_parameters.rst.inc
index aadc9817428..f4527da75c0 100644
--- a/reference/forms/types/options/invalid_message_parameters.rst.inc
+++ b/reference/forms/types/options/invalid_message_parameters.rst.inc
@@ -7,7 +7,7 @@ When setting the ``invalid_message`` option, you may need to
 include some variables in the string. This can be done by adding placeholders
 to that option and including the variables in this option::
 
-    $builder->add('some_field', SomeFormType::class, [
+    $builder->add('someField', SomeFormType::class, [
         // ...
         'invalid_message' => 'You entered an invalid value, it should include %num% letters',
         'invalid_message_parameters' => ['%num%' => 6],
diff --git a/reference/forms/types/options/label_attr.rst.inc b/reference/forms/types/options/label_attr.rst.inc
index 48e0dfa9191..026a9a3ef68 100644
--- a/reference/forms/types/options/label_attr.rst.inc
+++ b/reference/forms/types/options/label_attr.rst.inc
@@ -13,7 +13,7 @@ template:
     .. code-block:: twig
 
         {{ form_label(form.name, 'Your name', {
-               'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}
+            'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}
         }) }}
 
     .. code-block:: php
diff --git a/reference/forms/types/options/label_translation_parameters.rst.inc b/reference/forms/types/options/label_translation_parameters.rst.inc
new file mode 100644
index 00000000000..443c6706f14
--- /dev/null
+++ b/reference/forms/types/options/label_translation_parameters.rst.inc
@@ -0,0 +1,32 @@
+label_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+.. versionadded:: 4.3
+
+    The ``label_translation_parameters`` option was introduced in Symfony 4.3.
+
+The content of the `label`_ option is translated before displaying it, so it
+can contain :ref:`translation placeholders <component-translation-placeholders>`.
+This option defines the values used to replace those placeholders.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yaml
+    form.order.id: 'Identifier of the order to %company%'
+
+You can specify the placeholder values as follows::
+
+    $builder->add('id', null, [
+        'label' => 'form.order.id',
+        'label_translation_parameters' => [
+            '%company%' => 'ACME Inc.',
+        ],
+    ]);
+
+The ``label_translation_parameters`` option of children fields is merged with
+the same option of their parents, so children can reuse and/or override any of
+the parent placeholders.
diff --git a/reference/forms/types/options/method.rst.inc b/reference/forms/types/options/method.rst.inc
index 0d86d1f47a0..b20fbc3f026 100644
--- a/reference/forms/types/options/method.rst.inc
+++ b/reference/forms/types/options/method.rst.inc
@@ -19,7 +19,7 @@ is used to decide whether to process the form submission in the
     When the method is PUT, PATCH, or DELETE, Symfony will automatically
     render a ``_method`` hidden field in your form. This is used to "fake"
     these HTTP methods, as they're not supported on standard browsers. This can
-    be useful when using :ref:`method routing requirements <routing-method-requirement>`.
+    be useful when :ref:`matching routes by HTTP method <routing-matching-http-methods>`.
 
 .. note::
 
diff --git a/reference/forms/types/options/preferred_choices.rst.inc b/reference/forms/types/options/preferred_choices.rst.inc
index 2bba5366921..3d5d8567543 100644
--- a/reference/forms/types/options/preferred_choices.rst.inc
+++ b/reference/forms/types/options/preferred_choices.rst.inc
@@ -33,9 +33,9 @@ be especially useful if your values are objects::
             '1 week' => new \DateTime('+1 week'),
             '1 month' => new \DateTime('+1 month'),
         ],
-        'preferred_choices' => function ($value, $key) {
+        'preferred_choices' => function ($choice, $key, $value) {
             // prefer options within 3 days
-            return $value <= new \DateTime('+3 days');
+            return $choice <= new \DateTime('+3 days');
         },
     ]);
 
@@ -61,5 +61,5 @@ when rendering the field:
     .. code-block:: php
 
         <?= $view['form']->widget($form['publishAt'], [
-                  'separator' => '====='
+            'separator' => '=====',
         ]) ?>
diff --git a/reference/forms/types/options/required.rst.inc b/reference/forms/types/options/required.rst.inc
index 6d9b09319b1..f7712114b08 100644
--- a/reference/forms/types/options/required.rst.inc
+++ b/reference/forms/types/options/required.rst.inc
@@ -6,7 +6,7 @@ required
 If true, an `HTML5 required attribute`_ will be rendered. The corresponding
 ``label`` will also render with a ``required`` class.
 
-This is superficial and independent from validation. At best, if you let
+This is superficial and independent of validation. At best, if you let
 Symfony guess your field type, then the value of this option will be guessed
 from your validation information.
 
diff --git a/reference/forms/types/options/select_how_rendered.rst.inc b/reference/forms/types/options/select_how_rendered.rst.inc
index b131971ffff..4206c1eb237 100644
--- a/reference/forms/types/options/select_how_rendered.rst.inc
+++ b/reference/forms/types/options/select_how_rendered.rst.inc
@@ -1,7 +1,7 @@
 Select Tag, Checkboxes or Radio Buttons
 ---------------------------------------
 
-This field may be rendered as one of several different HTML fields, depending
+This field may be rendered as one of several HTML fields, depending
 on the ``expanded`` and ``multiple`` options:
 
 ========================================  =========  =========
diff --git a/reference/forms/types/options/validation_groups.rst.inc b/reference/forms/types/options/validation_groups.rst.inc
index 7dc2d1ca208..edff4f733f1 100644
--- a/reference/forms/types/options/validation_groups.rst.inc
+++ b/reference/forms/types/options/validation_groups.rst.inc
@@ -62,8 +62,8 @@ like when you pass multiple groups in an array, but with the difference that
 a group is only validated if the previous groups pass without errors.
 Here's an example::
 
-    use Symfony\Component\Validator\Constraints\GroupSequence;
     use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Validator\Constraints\GroupSequence;
     // ...
 
     class MyType extends AbstractType
diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst
index ea42aa6ffde..75f2a595701 100644
--- a/reference/forms/types/password.rst
+++ b/reference/forms/types/password.rst
@@ -19,6 +19,8 @@ The ``PasswordType`` field renders an input password text box.
 |             | - `error_bubbling`_                                                    |
 |             | - `error_mapping`_                                                     |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -30,6 +32,8 @@ The ``PasswordType`` field renders an input password text box.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\PasswordType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -42,9 +46,8 @@ If set to true, the field will *always* render blank, even if the corresponding
 field has a value. When set to false, the password field will be rendered
 with the ``value`` attribute set to its true value only upon submission.
 
-Put simply, if for some reason you want to render your password field
-*with* the password value already entered into the box, set this to false
-and submit the form.
+If you want to render your password field *with* the password value already
+entered into the box, set this to false and submit the form.
 
 Overridden Options
 ------------------
@@ -80,6 +83,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst
index 554f06b9046..87ad13ac4e9 100644
--- a/reference/forms/types/percent.rst
+++ b/reference/forms/types/percent.rst
@@ -9,12 +9,14 @@ percentage data. If your percentage data is stored as a decimal (e.g. ``0.95``),
 you can use this field out-of-the-box. If you store your data as a number
 (e.g. ``95``), you should set the ``type`` option to ``integer``.
 
-This field adds a percentage sign "``%``" after the input box.
+When ``symbol`` is not ``false``, the field will render the given string after
+the input.
 
 +-------------+-----------------------------------------------------------------------+
 | Rendered as | ``input`` ``text`` field                                              |
 +-------------+-----------------------------------------------------------------------+
 | Options     | - `scale`_                                                            |
+|             | - `symbol`_                                                           |
 |             | - `type`_                                                             |
 +-------------+-----------------------------------------------------------------------+
 | Overridden  | - `compound`_                                                         |
@@ -26,6 +28,8 @@ This field adds a percentage sign "``%``" after the input box.
 |             | - `error_bubbling`_                                                   |
 |             | - `error_mapping`_                                                    |
 |             | - `help`_                                                             |
+|             | - `help_attr`_                                                        |
+|             | - `help_html`_                                                        |
 |             | - `invalid_message`_                                                  |
 |             | - `invalid_message_parameters`_                                       |
 |             | - `label`_                                                            |
@@ -39,6 +43,8 @@ This field adds a percentage sign "``%``" after the input box.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\PercentType` |
 +-------------+-----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -50,6 +56,20 @@ scale
 By default, the input numbers are rounded. To allow for more decimal places,
 use this option.
 
+symbol
+~~~~~~
+
+**type**: ``boolean`` or ``string`` **default**: ``%``
+
+.. versionadded:: 4.3
+
+    The ``symbol`` option was introduced in Symfony 4.3.
+
+By default, fields are rendered with a percentage sign ``%`` after the input.
+Setting the value to ``false`` will not display the percentage sign. Setting the
+value to a ``string`` (e.g. ``‱``), will show that string instead of the default
+``%`` sign.
+
 type
 ~~~~
 
@@ -98,6 +118,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst
index e53a19aae12..868168be35f 100644
--- a/reference/forms/types/radio.rst
+++ b/reference/forms/types/radio.rst
@@ -28,6 +28,8 @@ If you want to have a boolean field, use :doc:`CheckboxType </reference/forms/ty
 |             | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `label_format`_                                                   |
@@ -39,6 +41,8 @@ If you want to have a boolean field, use :doc:`CheckboxType </reference/forms/ty
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RadioType` |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -60,6 +64,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/range.rst b/reference/forms/types/range.rst
index 96924471658..3b23aa0e0ff 100644
--- a/reference/forms/types/range.rst
+++ b/reference/forms/types/range.rst
@@ -5,7 +5,7 @@ RangeType Field
 ===============
 
 The ``RangeType`` field is a slider that is rendered using the HTML5
-``<input type="range" />`` tag.
+``<input type="range"/>`` tag.
 
 +-------------+---------------------------------------------------------------------+
 | Rendered as | ``input`` ``range`` field (slider in HTML5 supported browser)       |
@@ -17,6 +17,8 @@ The ``RangeType`` field is a slider that is rendered using the HTML5
 |             | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `mapped`_                                                         |
@@ -28,6 +30,8 @@ The ``RangeType`` field is a slider that is rendered using the HTML5
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RangeType` |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Basic Usage
 -----------
 
@@ -68,6 +72,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/repeated.rst b/reference/forms/types/repeated.rst
index 34ce3dbd424..5a334610a0c 100644
--- a/reference/forms/types/repeated.rst
+++ b/reference/forms/types/repeated.rst
@@ -25,6 +25,8 @@ accuracy.
 | Inherited   | - `data`_                                                              |
 | options     | - `error_mapping`_                                                     |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `invalid_message`_                                                   |
 |             | - `invalid_message_parameters`_                                        |
 |             | - `mapped`_                                                            |
@@ -34,13 +36,15 @@ accuracy.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RepeatedType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Example Usage
 -------------
 
 .. code-block:: php
 
-    use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
     use Symfony\Component\Form\Extension\Core\Type\PasswordType;
+    use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
     // ...
 
     $builder->add('password', RepeatedType::class, [
@@ -184,6 +188,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc
diff --git a/reference/forms/types/reset.rst b/reference/forms/types/reset.rst
index 4e5053957ef..a9639e03bc7 100644
--- a/reference/forms/types/reset.rst
+++ b/reference/forms/types/reset.rst
@@ -10,8 +10,10 @@ A button that resets all fields to their original values.
 | Rendered as          | ``input`` ``reset`` tag                                             |
 +----------------------+---------------------------------------------------------------------+
 | Inherited            | - `attr`_                                                           |
-| options              | - `disabled`_                                                       |
+| options              | - `attr_translation_parameters`_                                    |
+|                      | - `disabled`_                                                       |
 |                      | - `label`_                                                          |
+|                      | - `label_translation_parameters`_                                   |
 |                      | - `translation_domain`_                                             |
 +----------------------+---------------------------------------------------------------------+
 | Parent type          | :doc:`ButtonType </reference/forms/types/button>`                   |
@@ -19,6 +21,8 @@ A button that resets all fields to their original values.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ResetType` |
 +----------------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -43,3 +47,37 @@ as a key. This can be useful when you need to set a custom class for the button:
 .. include:: /reference/forms/types/options/button_label.rst.inc
 
 .. include:: /reference/forms/types/options/button_translation_domain.rst.inc
+
+label_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+The content of the `label`_ option is translated before displaying it, so it
+can contain :ref:`translation placeholders <component-translation-placeholders>`.
+This option defines the values used to replace those placeholders.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yaml
+    form.order.reset: 'Reset an order to %company%'
+
+You can specify the placeholder values as follows::
+
+    use Symfony\Component\Form\Extension\Core\Type\ResetType;
+    // ...
+
+    $builder->add('send', ResetType::class, [
+        'label' => 'form.order.reset',
+        'label_translation_parameters' => [
+            '%company%' => 'ACME Inc.',
+        ],
+    ]);
+
+The ``label_translation_parameters`` option of buttons is merged with the same
+option of its parents, so buttons can reuse and/or override any of the parent
+placeholders.
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst
index 9bac82be97c..378c0dddd99 100644
--- a/reference/forms/types/search.rst
+++ b/reference/forms/types/search.rst
@@ -4,7 +4,7 @@
 SearchType Field
 ================
 
-This renders an ``<input type="search" />`` field, which is a text box with
+This renders an ``<input type="search"/>`` field, which is a text box with
 special functionality supported by some browsers.
 
 Read about the input search field at `DiveIntoHTML5.info`_
@@ -17,6 +17,8 @@ Read about the input search field at `DiveIntoHTML5.info`_
 |             | - `error_bubbling`_                                                  |
 |             | - `error_mapping`_                                                   |
 |             | - `help`_                                                            |
+|             | - `help_attr`_                                                       |
+|             | - `help_html`_                                                       |
 |             | - `label`_                                                           |
 |             | - `label_attr`_                                                      |
 |             | - `label_format`_                                                    |
@@ -29,6 +31,8 @@ Read about the input search field at `DiveIntoHTML5.info`_
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SearchType` |
 +-------------+----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -50,6 +54,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/submit.rst b/reference/forms/types/submit.rst
index 488224d2309..7a0672ea6c2 100644
--- a/reference/forms/types/submit.rst
+++ b/reference/forms/types/submit.rst
@@ -10,9 +10,11 @@ A submit button.
 | Rendered as          | ``button`` ``submit`` tag                                            |
 +----------------------+----------------------------------------------------------------------+
 | Inherited            | - `attr`_                                                            |
-| options              | - `disabled`_                                                        |
+| options              | - `attr_translation_parameters`_                                     |
+|                      | - `disabled`_                                                        |
 |                      | - `label`_                                                           |
 |                      | - `label_format`_                                                    |
+|                      | - `label_translation_parameters`_                                    |
 |                      | - `translation_domain`_                                              |
 |                      | - `validation_groups`_                                               |
 +----------------------+----------------------------------------------------------------------+
@@ -21,6 +23,8 @@ A submit button.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SubmitType` |
 +----------------------+----------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 The Submit button has an additional method
 :method:`Symfony\\Component\\Form\\ClickableInterface::isClicked` that lets
 you check whether this button was used to submit the form. This is especially
@@ -57,6 +61,40 @@ as a key. This can be useful when you need to set a custom class for the button:
 
 .. include:: /reference/forms/types/options/button_translation_domain.rst.inc
 
+label_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+The content of the `label`_ option is translated before displaying it, so it
+can contain :ref:`translation placeholders <component-translation-placeholders>`.
+This option defines the values used to replace those placeholders.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yaml
+    form.order.submit_to_company: 'Send an order to %company%'
+
+You can specify the placeholder values as follows::
+
+    use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    // ...
+
+    $builder->add('send', SubmitType::class, [
+        'label' => 'form.order.submit_to_company',
+        'label_translation_parameters' => [
+            '%company%' => 'ACME Inc.',
+        ],
+    ]);
+
+The ``label_translation_parameters`` option of buttons is merged with the same
+option of its parents, so buttons can reuse and/or override any of the parent
+placeholders.
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
+
 validation_groups
 ~~~~~~~~~~~~~~~~~
 
diff --git a/reference/forms/types/tel.rst b/reference/forms/types/tel.rst
index 4f08adfaed4..ca5920ea3c6 100644
--- a/reference/forms/types/tel.rst
+++ b/reference/forms/types/tel.rst
@@ -9,7 +9,7 @@ The ``TelType`` field is a text field that is rendered using the HTML5
 of this type is not validated in any way, because formats for telephone numbers
 vary too much depending on each country.
 
-Nevertheless it may be useful to use this type in web applications because some
+Nevertheless, it may be useful to use this type in web applications because some
 browsers (e.g. smartphone browsers) adapt the input keyboard to make it easier
 to input phone numbers.
 
@@ -22,6 +22,8 @@ to input phone numbers.
 |             | - `error_bubbling`_                                                 |
 |             | - `error_mapping`_                                                  |
 |             | - `help`_                                                           |
+|             | - `help_attr`_                                                      |
+|             | - `help_html`_                                                      |
 |             | - `label`_                                                          |
 |             | - `label_attr`_                                                     |
 |             | - `label_format`_                                                   |
@@ -34,6 +36,8 @@ to input phone numbers.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TelType`   |
 +-------------+---------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -57,6 +61,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/text.rst b/reference/forms/types/text.rst
index a951094769e..7dc5ddf5554 100644
--- a/reference/forms/types/text.rst
+++ b/reference/forms/types/text.rst
@@ -16,6 +16,8 @@ The TextType field represents the most basic input text field.
 |             | - `error_bubbling`_                                                |
 |             | - `error_mapping`_                                                 |
 |             | - `help`_                                                          |
+|             | - `help_attr`_                                                     |
+|             | - `help_html`_                                                     |
 |             | - `label`_                                                         |
 |             | - `label_attr`_                                                    |
 |             | - `label_format`_                                                  |
@@ -31,6 +33,8 @@ The TextType field represents the most basic input text field.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TextType` |
 +-------------+--------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Inherited Options
 -----------------
 
@@ -58,6 +62,10 @@ an empty string, explicitly set the ``empty_data`` option to an empty string.
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst
index 3b4d50d3c4d..2e79fbdbc0d 100644
--- a/reference/forms/types/textarea.rst
+++ b/reference/forms/types/textarea.rst
@@ -16,6 +16,8 @@ Renders a ``textarea`` HTML element.
 |             | - `error_bubbling`_                                                    |
 |             | - `error_mapping`_                                                     |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -28,10 +30,12 @@ Renders a ``textarea`` HTML element.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TextareaType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 .. tip::
 
     If you prefer to use an **advanced WYSIWYG editor** instead of a plain
-    textarea, consider using the IvoryCKEditorBundle community bundle. Read
+    textarea, consider using the FOSCKEditorBundle community bundle. Read
     `its documentation`_ to learn how to integrate it in your Symfony application.
 
 Inherited Options
@@ -59,6 +63,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
@@ -71,4 +79,4 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/trim.rst.inc
 
-.. _`its documentation`: https://symfony.com/doc/current/bundles/IvoryCKEditorBundle/index.html
+.. _`its documentation`: https://symfony.com/doc/current/bundles/FOSCKEditorBundle/index.html
diff --git a/reference/forms/types/time.rst b/reference/forms/types/time.rst
index 15b57b5f9c8..0636f34fb5b 100644
--- a/reference/forms/types/time.rst
+++ b/reference/forms/types/time.rst
@@ -20,6 +20,7 @@ stored as a ``DateTime`` object, a string, a timestamp or an array.
 |                      | - `hours`_                                                                  |
 |                      | - `html5`_                                                                  |
 |                      | - `input`_                                                                  |
+|                      | - `input_format`_                                                           |
 |                      | - `minutes`_                                                                |
 |                      | - `model_timezone`_                                                         |
 |                      | - `seconds`_                                                                |
@@ -37,6 +38,8 @@ stored as a ``DateTime`` object, a string, a timestamp or an array.
 | Options              | - `disabled`_                                                               |
 |                      | - `error_mapping`_                                                          |
 |                      | - `help`_                                                                   |
+|                      | - `help_attr`_                                                              |
+|                      | - `help_html`_                                                              |
 |                      | - `inherit_data`_                                                           |
 |                      | - `invalid_message`_                                                        |
 |                      | - `invalid_message_parameters`_                                             |
@@ -47,11 +50,12 @@ stored as a ``DateTime`` object, a string, a timestamp or an array.
 | Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TimeType`          |
 +----------------------+-----------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Basic Usage
 -----------
 
-This field type is highly configurable, but easy to use. The most important
-options are ``input`` and ``widget``.
+The most important options are ``input`` and ``widget``.
 
 Suppose that you have a ``startTime`` field whose underlying time data is
 a ``DateTime`` object. The following configures the ``TimeType`` for that
@@ -128,6 +132,18 @@ on your underlying object. Valid values are:
 The value that comes back from the form will also be normalized back into
 this format.
 
+input_format
+~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``H:i:s``
+
+.. versionadded:: 4.3
+
+    The ``input_format`` option was introduced in Symfony 4.3.
+
+If the ``input`` option is set to ``string``, this option specifies the format
+of the time. This must be a valid `PHP time format`_.
+
 .. include:: /reference/forms/types/options/minutes.rst.inc
 
 .. include:: /reference/forms/types/options/model_timezone.rst.inc
@@ -196,6 +212,10 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
@@ -219,3 +239,5 @@ Form Variables
 | type         | ``string``  | Only present when widget is ``single_text`` and HTML5 is activated,  |
 |              |             | contains the input type to use (``datetime``, ``date`` or ``time``). |
 +--------------+-------------+----------------------------------------------------------------------+
+
+.. _`PHP time format`: https://secure.php.net/manual/en/function.date.php
diff --git a/reference/forms/types/timezone.rst b/reference/forms/types/timezone.rst
index a4696c2764c..f6d9bd3653d 100644
--- a/reference/forms/types/timezone.rst
+++ b/reference/forms/types/timezone.rst
@@ -18,6 +18,7 @@ manually, but then you should just use the ``ChoiceType`` directly.
 | Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)           |
 +-------------+------------------------------------------------------------------------+
 | Options     | - `input`_                                                             |
+|             | - `intl`_                                                              |
 |             | - `regions`_                                                           |
 +-------------+------------------------------------------------------------------------+
 | Overridden  | - `choices`_                                                           |
@@ -25,6 +26,7 @@ manually, but then you should just use the ``ChoiceType`` directly.
 +-------------+------------------------------------------------------------------------+
 | Inherited   | from the :doc:`ChoiceType </reference/forms/types/choice>`             |
 | options     |                                                                        |
+|             | - `choice_translation_domain`_                                         |
 |             | - `expanded`_                                                          |
 |             | - `multiple`_                                                          |
 |             | - `placeholder`_                                                       |
@@ -39,6 +41,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 |             | - `error_bubbling`_                                                    |
 |             | - `error_mapping`_                                                     |
 |             | - `help`_                                                              |
+|             | - `help_attr`_                                                         |
+|             | - `help_html`_                                                         |
 |             | - `label`_                                                             |
 |             | - `label_attr`_                                                        |
 |             | - `label_format`_                                                      |
@@ -50,6 +54,8 @@ manually, but then you should just use the ``ChoiceType`` directly.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TimezoneType` |
 +-------------+------------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -61,14 +67,45 @@ input
 The format of the *input* data - i.e. the format that the timezone is stored
 on your underlying object. Valid values are:
 
+* ``datetimezone`` (a ``\DateTimeZone`` object)
+* ``intltimezone`` (an ``\IntlTimeZone`` object)
 * ``string`` (e.g. ``America/New_York``)
-* ``datetimezone`` (a ``DateTimeZone`` object)
+
+.. versionadded:: 4.3
+
+    The ``intltimezone`` input type was introduced in Symfony 4.3.
+
+intl
+~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 4.3
+
+    This option was introduced in Symfony 4.3.
+
+If this option is set to ``true``, the timezone selector will display the
+timezones from the `ICU Project`_ via the :doc:`Intl component </components/intl>`
+instead of the regular PHP timezones.
+
+Although both sets of timezones are pretty similar, only the ones from the Intl
+component can be translated to any language. To do so, set the desired locale
+with the ``choice_translation_locale`` option.
+
+.. note::
+
+    The :doc:`Timezone constraint </reference/constraints/Timezone>` can validate
+    both timezone sets and adapts to the selected set automatically.
 
 regions
 ~~~~~~~
 
 **type**: ``int`` **default**: ``\DateTimeZone::ALL``
 
+.. deprecated:: 4.2
+
+    This option was deprecated in Symfony 4.2.
+
 The available regions in the timezone choice list. For example: ``DateTimeZone::AMERICA | DateTimeZone::EUROPE``
 
 Overridden Options
@@ -92,6 +129,8 @@ Inherited Options
 
 These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
 
+.. include:: /reference/forms/types/options/choice_translation_domain.rst.inc
+
 .. include:: /reference/forms/types/options/expanded.rst.inc
 
 .. include:: /reference/forms/types/options/multiple.rst.inc
@@ -126,6 +165,10 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
@@ -135,3 +178,5 @@ The actual default value of this option depends on other field options:
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc
+
+.. _`ICU Project`: http://site.icu-project.org/
diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst
index 38aa1732145..d9246467633 100644
--- a/reference/forms/types/url.rst
+++ b/reference/forms/types/url.rst
@@ -19,6 +19,8 @@ have a protocol.
 |             | - `error_bubbling`_                                               |
 |             | - `error_mapping`_                                                |
 |             | - `help`_                                                         |
+|             | - `help_attr`_                                                    |
+|             | - `help_html`_                                                    |
 |             | - `label`_                                                        |
 |             | - `label_attr`_                                                   |
 |             | - `label_format`_                                                 |
@@ -31,6 +33,8 @@ have a protocol.
 | Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\UrlType` |
 +-------------+-------------------------------------------------------------------+
 
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
 Field Options
 -------------
 
@@ -66,6 +70,10 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/help.rst.inc
 
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/label_attr.rst.inc
diff --git a/reference/index.rst b/reference/index.rst
index 1cffe82fdcd..82edbcc0130 100644
--- a/reference/index.rst
+++ b/reference/index.rst
@@ -22,6 +22,5 @@ Reference Documents
 
     dic_tags
     events
-    requirements
 
 .. include:: /reference/map.rst.inc
diff --git a/reference/map.rst.inc b/reference/map.rst.inc
index 552799df0a4..aa92cebc144 100644
--- a/reference/map.rst.inc
+++ b/reference/map.rst.inc
@@ -28,4 +28,3 @@
 
   * :doc:`/reference/dic_tags`
   * :doc:`/reference/events`
-  * :doc:`/reference/requirements`
diff --git a/reference/requirements.rst b/reference/requirements.rst
deleted file mode 100644
index 290eb21ee10..00000000000
--- a/reference/requirements.rst
+++ /dev/null
@@ -1,74 +0,0 @@
-.. index::
-   single: Requirements
-
-.. _requirements-for-running-symfony2:
-
-Requirements for Running Symfony
-================================
-
-These are the technical requirements to run Symfony 4 applications:
-
-* **PHP version**: 7.1.3 or higher
-* **PHP extensions**: (all of them are installed and enabled by default in PHP 7+)
-
-  * `Ctype`_
-  * `iconv`_
-  * `JSON`_
-  * `PCRE`_
-  * `Session`_
-  * `SimpleXML`_
-  * `Tokenizer`_
-
-* **Writable directories**: (must be writable by the web server)
-
-  * The project's cache directory (``var/cache/`` by default, but the app can
-    :ref:`override the cache dir <override-cache-dir>`)
-  * The project's log directory (``var/log/`` by default, but the app can
-    :ref:`override the logs dir <override-logs-dir>`)
-
-Checking Requirements Automatically
------------------------------------
-
-To make things simple, Symfony provides a tool to quickly check if your system
-meets these requirements. In addition, the tool provides recommendations if
-applicable.
-
-Run this command to install the tool:
-
-.. code-block:: terminal
-
-    $ cd your-project/
-    $ composer require symfony/requirements-checker
-
-Beware that PHP may use different configurations for the command console and
-the web server, so you need to check requirements in both environments.
-
-Checking Requirements for the Web Server
-----------------------------------------
-
-The requirements checker tool creates a file called ``check.php`` in the
-``public/`` directory of your project. Open that file with your browser to check
-the requirements.
-
-Once you've fixed all the reported issues, uninstall the requirements checker
-to avoid leaking internal information about your application to visitors:
-
-.. code-block:: terminal
-
-    $ cd your-project/
-    $ composer remove symfony/requirements-checker
-
-Checking Requirements for the Command Console
----------------------------------------------
-
-The requirements checker tool adds a script to your Composer configuration to
-check the requirements automatically. There's no need to execute any command; if
-there are any issues, you'll see them in the console output.
-
-.. _`iconv`: https://php.net/book.iconv
-.. _`JSON`: https://php.net/book.json
-.. _`Session`: https://php.net/book.session
-.. _`Ctype`: https://php.net/book.ctype
-.. _`Tokenizer`: https://php.net/book.tokenizer
-.. _`SimpleXML`: https://php.net/book.simplexml
-.. _`PCRE`: https://php.net/book.pcre
diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
index 17f2dd0563d..083583727e7 100644
--- a/reference/twig_reference.rst
+++ b/reference/twig_reference.rst
@@ -18,7 +18,7 @@ describe these extra features.
 
 .. tip::
 
-    Technically, most of the extensions live in the `Twig Bridge`_. That code
+    Technically, most of the extensions live in the `Twig Bridge`_. That code
     might give you some ideas when you need to write your own Twig extension
     as described in :doc:`/templating/twig_extension`.
 
@@ -30,7 +30,7 @@ describe these extra features.
 
 .. tip::
 
-    The `Twig Extensions repository`_ contains some additional Twig extensions
+    The `Twig Extensions repository`_ contains some additional Twig extensions
     that do not belong to the Twig core, so you might want to have a look at
     the `Twig Extensions documentation`_.
 
@@ -253,7 +253,7 @@ information in :ref:`templating-pages`.
 absolute_url
 ~~~~~~~~~~~~
 
-.. code-block:: jinja
+.. code-block:: twig
 
     {{ absolute_url(path) }}
 
@@ -264,7 +264,7 @@ Returns the absolute URL from the passed relative path. For example, assume
 you're on the following page in your app:
 ``http://example.com/products/hover-board``.
 
-.. code-block:: jinja
+.. code-block:: twig
 
     {{ absolute_url('/human.txt') }}
     {# http://example.com/human.txt #}
@@ -275,7 +275,7 @@ you're on the following page in your app:
 relative_path
 ~~~~~~~~~~~~~
 
-.. code-block:: jinja
+.. code-block:: twig
 
     {{ relative_path(path) }}
 
@@ -286,7 +286,7 @@ Returns the relative path from the passed absolute URL. For example, assume
 you're on the following page in your app:
 ``http://example.com/products/hover-board``.
 
-.. code-block:: jinja
+.. code-block:: twig
 
     {{ relative_path('http://example.com/human.txt') }}
     {# ../human.txt #}
@@ -359,6 +359,12 @@ Translates the text into the current language. More information in
 transchoice
 ~~~~~~~~~~~
 
+.. deprecated:: 4.2
+
+   The ``transchoice`` filter is deprecated since Symfony 4.2 and will be
+   removed in 5.0. Use the :doc:`ICU MessageFormat </translation/message_format>` with
+   the ``trans`` filter instead.
+
 .. code-block:: twig
 
     {{ message|transchoice(count, arguments = [], domain = null, locale = null) }}
@@ -496,7 +502,7 @@ format_file
 
 Generates the file path inside an ``<a>`` element. If the path is inside
 the kernel root directory, the kernel root directory path is replaced by
-``kernel.root_dir`` (showing the full path in a tooltip on hover).
+``kernel.project_dir`` (showing the full path in a tooltip on hover).
 
 format_file_from_text
 ~~~~~~~~~~~~~~~~~~~~~
@@ -525,6 +531,27 @@ file_link
 Generates a link to the provided file and line number using
 a preconfigured scheme.
 
+file_relative
+~~~~~~~~~~~~~
+
+.. code-block:: twig
+
+    {{ file|file_relative }}
+
+``file``
+    **type**: ``string``
+
+It transforms the given absolute file path into a new file path relative to
+project's root directory:
+
+.. code-block:: twig
+
+    {{ '/var/www/blog/templates/admin/index.html.twig'|file_relative }}
+    {# if project root dir is '/var/www/blog/', it returns 'templates/admin/index.html.twig' #}
+
+If the given file path is out of the project directory, a ``null`` value
+will be returned.
+
 .. _reference-twig-tags:
 
 Tags
@@ -567,6 +594,12 @@ Renders the translation of the content. More information in :ref:`translation-ta
 transchoice
 ~~~~~~~~~~~
 
+.. deprecated:: 4.2
+
+   The ``transchoice`` tag is deprecated since Symfony 4.2 and will be
+   removed in 5.0. Use the :doc:`ICU MessageFormat </translation/message_format>` with
+   the ``trans`` tag instead.
+
 .. code-block:: twig
 
     {% transchoice count with vars from domain into locale %}{% endtranschoice %}
@@ -598,7 +631,7 @@ This will set the default domain in the current template.
 stopwatch
 ~~~~~~~~~
 
-.. code-block:: jinja
+.. code-block:: twig
 
     {% stopwatch 'name' %}...{% endstopwatch %}
 
diff --git a/routing.rst b/routing.rst
index c37464b43a9..abc75e140fa 100644
--- a/routing.rst
+++ b/routing.rst
@@ -4,35 +4,31 @@
 Routing
 =======
 
-Beautiful URLs are a must for any serious web application. This means leaving behind
-ugly URLs like ``index.php?article_id=57`` in favor of something like ``/read/intro-to-symfony``.
-
-Having flexibility is even more important. What if you need to change the
-URL of a page from ``/blog`` to ``/news``? How many links would you need to
-hunt down and update to make the change? If you're using Symfony's router,
-the change is simple.
-
-.. index::
-   single: Routing; Basics
+When your application receives a request, it executes a
+:doc:`controller action </controller>` to generate the response. The routing
+configuration defines which action to run for each incoming URL. It also
+provides other useful features, like generating SEO-friendly URLs (e.g.
+``/read/intro-to-symfony`` instead of ``index.php?article_id=57``).
 
 .. _routing-creating-routes:
 
 Creating Routes
 ---------------
 
-A *route* is a map from a URL path to a controller. Suppose you want one route that
-matches ``/blog`` exactly and another more dynamic route that can match *any* URL
-like ``/blog/my-post`` or ``/blog/all-about-symfony``.
+Routes can be configured in YAML, XML, PHP or using annotations. All formats
+provide the same features and performance, so choose your favorite.
+:doc:`Symfony recommends annotations </best_practices/controllers>`
+because it's convenient to put the route and controller in the
+same place instead of dealing with multiple files.
 
-Routes can be configured in YAML, XML and PHP. All formats provide the same
-features and performance, so choose the one you prefer. If you choose PHP
-annotations, run this command once in your app to add support for them:
+If you choose annotations, run this command once in your application to add
+support for them:
 
 .. code-block:: terminal
 
     $ composer require annotations
 
-Now you can configure the routes:
+Suppose you want to define a route for the ``/blog`` URL in your application:
 
 .. configuration-block::
 
@@ -47,39 +43,25 @@ Now you can configure the routes:
         class BlogController extends AbstractController
         {
             /**
-             * Matches /blog exactly
-             *
              * @Route("/blog", name="blog_list")
              */
             public function list()
             {
                 // ...
             }
-
-            /**
-             * Matches /blog/*
-             *
-             * @Route("/blog/{slug}", name="blog_show")
-             */
-            public function show($slug)
-            {
-                // $slug will equal the dynamic part of the URL
-                // e.g. at /blog/yay-routing, then $slug='yay-routing'
-
-                // ...
-            }
         }
 
     .. code-block:: yaml
 
         # config/routes.yaml
         blog_list:
-            path:     /blog
+            path: /blog
+            # the controller value has the format 'controller_class::method_name'
             controller: App\Controller\BlogController::list
 
-        blog_show:
-            path:     /blog/{slug}
-            controller: App\Controller\BlogController::show
+            # if the action is implemented as the __invoke() method of the
+            # controller class, you can skip the '::method_name' part:
+            # controller: App\Controller\BlogController
 
     .. code-block:: xml
 
@@ -88,89 +70,169 @@ Now you can configure the routes:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="blog_list" controller="App\Controller\BlogController::list" path="/blog" >
-                <!-- settings -->
-            </route>
+            <!-- the controller value has the format 'controller_class::method_name' -->
+            <route id="blog_list" path="/blog"
+                   controller="App\Controller\BlogController::list"/>
 
-            <route id="blog_show" controller="App\Controller\BlogController::show" path="/blog/{slug}">
-                <!-- settings -->
-            </route>
+            <!-- if the action is implemented as the __invoke() method of the
+                 controller class, you can skip the '::method_name' part:
+                 controller="App\Controller\BlogController"/> -->
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
         use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('blog_list', new Route('/blog', [
-            '_controller' => [BlogController::class, 'list']
-        ]));
-        $routes->add('blog_show', new Route('/blog/{slug}', [
-            '_controller' => [BlogController::class, 'show']
-        ]));
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_list', '/blog')
+                // the controller value has the format [controller_class, method_name]
+                ->controller([BlogController::class, 'list'])
+
+                // if the action is implemented as the __invoke() method of the
+                // controller class, you can skip the ', method_name]' part:
+                // ->controller([BlogController::class])
+            ;
+        };
 
-        return $routes;
+This configuration defines a route called ``blog_list`` that matches when the
+user requests the ``/blog`` URL. When the match occurs, the application runs
+the ``list()`` method of the ``BlogController`` class.
+
+.. note::
 
-Thanks to these two routes:
+    The query string of a URL is not considered when matching routes. In this
+    example, URLs like ``/blog?foo=bar`` and ``/blog?foo=bar&bar=foo`` will
+    also match the ``blog_list`` route.
 
-* If the user goes to ``/blog``, the first route is matched and ``list()``
-  is executed;
+The route name (``blog_list``) is not important for now, but it will be essential later when
+:ref:`generating URLs <routing-generating-urls>`. You only have to keep in mind
+that each route name must be unique in the application.
 
-* If the user goes to ``/blog/*``, the second route is matched and ``show()``
-  is executed. Because the route path is ``/blog/{slug}``, a ``$slug`` variable is
-  passed to ``show()`` matching that value. For example, if the user goes to
-  ``/blog/yay-routing``, then ``$slug`` will equal ``yay-routing``.
+.. _routing-matching-http-methods:
 
-Whenever you have a ``{placeholder}`` in your route path, that portion becomes a
-wildcard: it matches *any* value. Your controller can now *also* have an argument
-called ``$placeholder`` (the wildcard and argument names *must* match).
+Matching HTTP Methods
+~~~~~~~~~~~~~~~~~~~~~
 
-Each route also has an internal name: ``blog_list`` and ``blog_show``. These can
-be anything (as long as each is unique) and don't have any meaning yet. You'll
-use them later to :ref:`generate URLs <routing-generate>`.
+By default, routes match any HTTP verb (``GET``, ``POST``, ``PUT``, etc.)
+Use the ``methods`` option to restrict the verbs each route should respond to:
 
-.. sidebar:: Routing in Other Formats
+.. configuration-block::
 
-    The ``@Route`` above each method is called an *annotation*. If you'd rather
-    configure your routes in YAML, XML or PHP, that's no problem! Create a new
-    routing file (e.g. ``routes.xml``) in the ``config/`` directory and Symfony
-    will automatically use it.
+    .. code-block:: php-annotations
 
-.. _i18n-routing:
+        // src/Controller/BlogApiController.php
+        namespace App\Controller;
 
-Localized Routing (i18n)
-------------------------
+        // ...
+
+        class BlogApiController extends AbstractController
+        {
+            /**
+             * @Route("/api/posts/{id}", methods={"GET","HEAD"})
+             */
+            public function show(int $id)
+            {
+                // ... return a JSON response with the post
+            }
+
+            /**
+             * @Route("/api/posts/{id}", methods={"PUT"})
+             */
+            public function edit(int $id)
+            {
+                // ... edit a post
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        api_post_show:
+            path:       /api/posts/{id}
+            controller: App\Controller\BlogApiController::show
+            methods:    GET|HEAD
+
+        api_post_edit:
+            path:       /api/posts/{id}
+            controller: App\Controller\BlogApiController::edit
+            methods:    PUT
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="api_post_show" path="/api/posts/{id}"
+                controller="App\Controller\BlogApiController::show"
+                methods="GET|HEAD"/>
+
+            <route id="api_post_edit" path="/api/posts/{id}"
+                controller="App\Controller\BlogApiController::edit"
+                methods="PUT"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\BlogApiController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('api_post_show', '/api/posts/{id}')
+                ->controller([BlogApiController::class, 'show'])
+                ->methods(['GET', 'HEAD'])
+            ;
+            $routes->add('api_post_edit', '/api/posts/{id}')
+                ->controller([BlogApiController::class, 'edit'])
+                ->methods(['PUT'])
+            ;
+        };
+
+.. tip::
 
-.. versionadded:: 4.1
-    The feature to localize routes was introduced in Symfony 4.1.
+    HTML forms only support ``GET`` and ``POST`` methods. If you're calling a
+    route with a different method from an HTML form, add a hidden field called
+    ``_method`` with the method to use (e.g. ``<input type="hidden" name="_method" value="PUT"/>``).
+    If you create your forms with :doc:`Symfony Forms </forms>` this is done
+    automatically for you.
 
-Routes can be localized to provide unique paths per :doc:`locale </translation/locale>`.
-Symfony provides a handy way to declare localized routes without duplication.
+Matching Expressions
+~~~~~~~~~~~~~~~~~~~~
+
+Use the ``condition`` option if you need some route to match based on some
+arbitrary matching logic:
 
 .. configuration-block::
 
     .. code-block:: php-annotations
 
-        // src/Controller/CompanyController.php
+        // src/Controller/DefaultController.php
         namespace App\Controller;
 
         use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
         use Symfony\Component\Routing\Annotation\Route;
 
-        class CompanyController extends AbstractController
+        class DefaultController extends AbstractController
         {
             /**
-             * @Route({
-             *     "nl": "/over-ons",
-             *     "en": "/about-us"
-             * }, name="about_us")
+             * @Route(
+             *     "/contact",
+             *     name="contact",
+             *     condition="context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
+             * )
+             *
+             * expressions can also include config parameters:
+             * condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
              */
-            public function about()
+            public function contact()
             {
                 // ...
             }
@@ -179,11 +241,12 @@ Symfony provides a handy way to declare localized routes without duplication.
     .. code-block:: yaml
 
         # config/routes.yaml
-        about_us:
-            path:
-                nl: /over-ons
-                en: /about-us
-            controller: App\Controller\CompanyController::about
+        contact:
+            path:       /contact
+            controller: 'App\Controller\DefaultController::contact'
+            condition:  "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
+            # expressions can also include config parameters:
+            # condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
 
     .. code-block:: xml
 
@@ -192,91 +255,193 @@ Symfony provides a handy way to declare localized routes without duplication.
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="about_us" controller="App\Controller\CompanyController::about">
-                <path locale="nl">/over-ons</path>
-                <path locale="en">/about-us</path>
+            <route id="contact" path="/contact" controller="App\Controller\DefaultController::contact">
+                <condition>context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'</condition>
+                <!-- expressions can also include config parameters: -->
+                <!-- <condition>request.headers.get('User-Agent') matches '%app.allowed_browsers%'</condition> -->
             </route>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        namespace Symfony\Component\Routing\Loader\Configurator;
+        use App\Controller\DefaultController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
         return function (RoutingConfigurator $routes) {
-            $routes->add('about_us', ['nl' => '/over-ons', 'en' => '/about-us'])
-                ->controller('App\Controller\CompanyController::about');
+            $routes->add('contact', '')
+                ->controller([DefaultController::class, 'contact'])
+                ->condition('context.getMethod() in ["GET", "HEAD"] and request.headers.get("User-Agent") matches "/firefox/i"')
+                // expressions can also include config parameters:
+                // 'request.headers.get("User-Agent") matches "%app.allowed_browsers%"'
+            ;
         };
 
-When a localized route is matched Symfony automatically knows which locale
-should be used during the request. Defining routes this way also eliminated the
-need for duplicate registration of routes which minimizes the risk for any bugs
-caused by definition inconsistency.
+The value of the ``condition`` option is any valid
+:doc:`ExpressionLanguage expression </components/expression_language/syntax>`
+and can use any of these variables created by Symfony:
 
-A common requirement for internationalized applications is to prefix all routes
-with a locale. This can be done by defining a different prefix for each locale
-(and setting an empty prefix for your default locale if you prefer it):
+``context``
+    An instance of :class:`Symfony\\Component\\Routing\\RequestContext`,
+    which holds the most fundamental information about the route being matched.
+
+``request``
+    The :ref:`Symfony Request <component-http-foundation-request>` object that
+    represents the current request.
+
+Behind the scenes, expressions are compiled down to raw PHP. Because of this,
+using the ``condition`` key causes no extra overhead beyond the time it takes
+for the underlying PHP to execute.
+
+.. caution::
+
+    Conditions are *not* taken into account when generating URLs (which is
+    explained later in this article).
+
+Debugging Routes
+~~~~~~~~~~~~~~~~
+
+As your application grows, you'll eventually have a *lot* of routes. Symfony
+includes some commands to help you debug routing issues. First, the ``debug:router``
+command lists all your application routes in the same order in which Symfony
+evaluates them:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:router
+
+    ----------------  -------  -------  -----  --------------------------------------------
+    Name              Method   Scheme   Host   Path
+    ----------------  -------  -------  -----  --------------------------------------------
+    homepage          ANY      ANY      ANY    /
+    contact           GET      ANY      ANY    /contact
+    contact_process   POST     ANY      ANY    /contact
+    article_show      ANY      ANY      ANY    /articles/{_locale}/{year}/{title}.{_format}
+    blog              ANY      ANY      ANY    /blog/{page}
+    blog_show         ANY      ANY      ANY    /blog/{slug}
+    ----------------  -------  -------  -----  --------------------------------------------
+
+Pass the name (or part of the name) of some route to this argument to print the
+route details:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:router app_lucky_number
+
+    +-------------+---------------------------------------------------------+
+    | Property    | Value                                                   |
+    +-------------+---------------------------------------------------------+
+    | Route Name  | app_lucky_number                                        |
+    | Path        | /lucky/number/{max}                                     |
+    | ...         | ...                                                     |
+    | Options     | compiler_class: Symfony\Component\Routing\RouteCompiler |
+    |             | utf8: true                                              |
+    +-------------+---------------------------------------------------------+
+
+The other command is called ``router:match`` and it shows which route will match
+the given URL. It's useful to find out why some URL is not executing the
+controller action that you expect:
+
+.. code-block:: terminal
+
+    $ php bin/console router:match /lucky/number/8
+
+      [OK] Route "app_lucky_number" matches
+
+Route Parameters
+----------------
+
+The previous examples defined routes where the URL never changes (e.g. ``/blog``).
+However, it's common to define routes where some parts are variable. For example,
+the URL to display some blog post will probably include the title or slug
+(e.g. ``/blog/my-first-post`` or ``/blog/all-about-symfony``).
+
+In Symfony routes, variable parts are wrapped in ``{ ... }`` and they must have
+a unique name. For example, the route to display the blog post contents is
+defined as ``/blog/{slug}``:
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        // src/Controller/BlogController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class BlogController extends AbstractController
+        {
+            // ...
+
+            /**
+             * @Route("/blog/{slug}", name="blog_show")
+             */
+            public function show(string $slug)
+            {
+                // $slug will equal the dynamic part of the URL
+                // e.g. at /blog/yay-routing, then $slug='yay-routing'
+
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
-        # config/routes/annotations.yaml
-        controllers:
-            resource: '../../src/Controller/'
-            type: annotation
-            prefix:
-                en: '' # don't prefix URLs for English, the default locale
-                nl: '/nl'
+        # config/routes.yaml
+        blog_show:
+            path:       /blog/{slug}
+            controller: App\Controller\BlogController::show
 
     .. code-block:: xml
 
-        <!-- config/routes/annotations.xml -->
+        <!-- config/routes.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <import resource="../src/Controller/" type="annotation">
-                <!-- don't prefix URLs for English, the default locale -->
-                <prefix locale="en"></prefix>
-                <prefix locale="nl">/nl</prefix>
-            </import>
+            <route id="blog_show" path="/blog/{slug}"
+                   controller="App\Controller\BlogController::show"/>
+            </route>
         </routes>
 
     .. code-block:: php
 
-        // config/routes/annotations.php
-        use Symfony\Component\Routing\RouteCollection;
+        // config/routes.php
+        use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = $loader->import('../src/Controller/', 'annotation');
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_show', '/blog/{slug}')
+                ->controller([BlogController::class, 'show'])
+            ;
+        };
 
-        // don't prefix URLs for English, the default locale
-        $app->addPrefix('/', ['_locale' => 'en']);
-        $app->addPrefix('/nl', ['_locale' => 'nl']);
+The name of the variable part (``{slug}`` in this example) is used to create a
+PHP variable where that route content is stored and passed to the controller.
+If a user visits the ``/blog/my-first-post`` URL, Symfony executes the ``show()``
+method in the ``BlogController`` class and passes a ``$slug = 'my-first-post'``
+argument to the ``show()`` method.
 
-        return $routes;
+Routes can define any number of parameters, but each of them can only be used
+once on each route (e.g. ``/blog/posts-about-{category}/page/{pageNumber}``).
 
 .. _routing-requirements:
 
-Adding {wildcard} Requirements
-------------------------------
-
-Imagine the ``blog_list`` route will contain a paginated list of blog posts, with
-URLs like ``/blog/2`` and ``/blog/3`` for pages 2 and 3. If you change the route's
-path to ``/blog/{page}``, you'll have a problem:
+Parameters Validation
+~~~~~~~~~~~~~~~~~~~~~
 
-* blog_list: ``/blog/{page}`` will match ``/blog/*``;
-* blog_show: ``/blog/{slug}`` will *also* match ``/blog/*``.
+Imagine that your application has a ``blog_show`` route (URL: ``/blog/{slug}``)
+and a ``blog_list`` route (URL: ``/blog/{page}``). Given that route parameters
+accept any value, there's no way to differentiate both routes.
 
-When two routes match the same URL, the *first* route that's loaded wins. Unfortunately,
-that means that ``/blog/yay-routing`` will match the ``blog_list``. No good!
-
-To fix this, add a *requirement* that the ``{page}`` wildcard can *only* match numbers
-(digits):
+If the user requests ``/blog/my-first-post``, both routes will match and Symfony
+will use the route which was defined first. To fix this, add some validation to
+the ``{page}`` parameter using the ``requirements`` option:
 
 .. configuration-block::
 
@@ -293,7 +458,7 @@ To fix this, add a *requirement* that the ``{page}`` wildcard can *only* match n
             /**
              * @Route("/blog/{page}", name="blog_list", requirements={"page"="\d+"})
              */
-            public function list($page)
+            public function list(int $page)
             {
                 // ...
             }
@@ -311,13 +476,14 @@ To fix this, add a *requirement* that the ``{page}`` wildcard can *only* match n
 
         # config/routes.yaml
         blog_list:
-            path:      /blog/{page}
+            path:       /blog/{page}
             controller: App\Controller\BlogController::list
             requirements:
                 page: '\d+'
 
         blog_show:
-            # ...
+            path:       /blog/{slug}
+            controller: App\Controller\BlogController::show
 
     .. code-block:: xml
 
@@ -326,44 +492,67 @@ To fix this, add a *requirement* that the ``{page}`` wildcard can *only* match n
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="blog_list" path="/blog/{page}" controller="App\Controller\BlogController::list">
                 <requirement key="page">\d+</requirement>
             </route>
 
-            <!-- ... -->
+            <route id="blog_show" path="/blog/{slug}"
+                   controller="App\Controller\BlogController::show"/>
+            </route>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
         use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('blog_list', new Route('/blog/{page}', [
-            '_controller' => [BlogController::class, 'list'],
-        ], [
-            'page' => '\d+'
-        ]));
-
-        // ...
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_list', '/blog/{page}')
+                ->controller([BlogController::class, 'list'])
+                ->requirements(['page' => '\d+'])
+            ;
+
+            $routes->add('blog_show', '/blog/{slug}')
+                ->controller([BlogController::class, 'show'])
+            ;
+            // ...
+        };
 
-The ``\d+`` is a regular expression that matches a *digit* of any length. Now:
+The ``requirements`` option defines the `PHP regular expressions`_ that route
+parameters must match for the entire route to match. In this example, ``\d+`` is
+a regular expression that matches a *digit* of any length. Now:
 
 ========================  =============  ===============================
 URL                       Route          Parameters
 ========================  =============  ===============================
 ``/blog/2``               ``blog_list``  ``$page`` = ``2``
-``/blog/yay-routing``     ``blog_show``  ``$slug`` = ``yay-routing``
+``/blog/my-first-post``   ``blog_show``  ``$slug`` = ``my-first-post``
 ========================  =============  ===============================
 
-If you prefer, requirements can be inlined in each placeholder using the syntax
-``{placeholder_name<requirements>}``. This feature makes configuration more
+.. tip::
+
+    Route requirements (and route paths too) can include
+    :ref:`container parameters <configuration-parameters>`, which is useful to
+    define complex regular expressions once and reuse them in multiple routes.
+
+.. tip::
+
+    Parameters also support `PCRE Unicode properties`_, which are escape
+    sequences that match generic character types. For example, ``\p{Lu}``
+    matches any uppercase character in any language, ``\p{Greek}`` matches any
+    Greek character, etc.
+
+.. note::
+
+    When using regular expressions in route parameters, you can set the ``utf8``
+    route option to ``true`` to make any ``.`` character match any UTF-8
+    characters instead of just a single byte.
+
+If you prefer, requirements can be inlined in each parameter using the syntax
+``{parameter_name<requirements>}``. This feature makes configuration more
 concise, but it can decrease route readability when requirements are complex:
 
 .. configuration-block::
@@ -381,7 +570,7 @@ concise, but it can decrease route readability when requirements are complex:
             /**
              * @Route("/blog/{page<\d+>}", name="blog_list")
              */
-            public function list($page)
+            public function list(int $page)
             {
                 // ...
             }
@@ -391,7 +580,7 @@ concise, but it can decrease route readability when requirements are complex:
 
         # config/routes.yaml
         blog_list:
-            path:      /blog/{page<\d+>}
+            path:       /blog/{page<\d+>}
             controller: App\Controller\BlogController::list
 
     .. code-block:: xml
@@ -401,10 +590,10 @@ concise, but it can decrease route readability when requirements are complex:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="blog_list" path="/blog/{page<\d+>}"
-                   controller="App\Controller\BlogController::list" />
+                   controller="App\Controller\BlogController::list"/>
 
             <!-- ... -->
         </routes>
@@ -412,35 +601,27 @@ concise, but it can decrease route readability when requirements are complex:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
         use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('blog_list', new Route('/blog/{page<\d+>}', [
-            '_controller' => [BlogController::class, 'list'],
-        ]));
-
-        // ...
-
-        return $routes;
-
-.. versionadded:: 4.1
-    The feature to inline requirements was introduced in Symfony 4.1.
-
-To learn about other route requirements - like HTTP method, hostname and dynamic
-expressions - see :doc:`/routing/requirements`.
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_list', '/blog/{page<\d+>}')
+                ->controller([BlogController::class, 'list'])
+            ;
+            // ...
+        };
 
-Giving {placeholders} a Default Value
--------------------------------------
+Optional Parameters
+~~~~~~~~~~~~~~~~~~~
 
-In the previous example, the ``blog_list`` has a path of ``/blog/{page}``. If
-the user visits ``/blog/1``, it will match. But if they visit ``/blog``, it
-will **not** match. As soon as you add a ``{placeholder}`` to a route, it
-*must* have a value.
+In the previous example, the URL of ``blog_list`` is ``/blog/{page}``. If users
+visit ``/blog/1``, it will match. But if they visit ``/blog``, it will **not**
+match. As soon as you add a parameter to a route, it must have a value.
 
-So how can you make ``blog_list`` once again match when the user visits
-``/blog``? By adding a *default* value:
+You can make ``blog_list`` once again match when the user visits ``/blog`` by
+adding a default value for the ``{page}`` parameter. When using annotations,
+default values are defined in the arguments of the controller action. In the
+other configuration formats they are defined with the ``defaults`` option:
 
 .. configuration-block::
 
@@ -457,7 +638,7 @@ So how can you make ``blog_list`` once again match when the user visits
             /**
              * @Route("/blog/{page}", name="blog_list", requirements={"page"="\d+"})
              */
-            public function list($page = 1)
+            public function list(int $page = 1)
             {
                 // ...
             }
@@ -467,7 +648,7 @@ So how can you make ``blog_list`` once again match when the user visits
 
         # config/routes.yaml
         blog_list:
-            path:      /blog/{page}
+            path:       /blog/{page}
             controller: App\Controller\BlogController::list
             defaults:
                 page: 1
@@ -484,7 +665,7 @@ So how can you make ``blog_list`` once again match when the user visits
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="blog_list" path="/blog/{page}" controller="App\Controller\BlogController::list">
                 <default key="page">1</default>
@@ -498,33 +679,45 @@ So how can you make ``blog_list`` once again match when the user visits
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
         use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('blog_list', new Route(
-            '/blog/{page}',
-            [
-                '_controller' => [BlogController::class, 'list'],
-                'page'        => 1,
-            ],
-            [
-                'page' => '\d+'
-            ]
-        ));
-
-        // ...
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_list', '/blog/{page}')
+                ->controller([BlogController::class, 'list'])
+                ->defaults(['page' => 1])
+                ->requirements(['page' => '\d+'])
+            ;
+        };
 
 Now, when the user visits ``/blog``, the ``blog_list`` route will match and
 ``$page`` will default to a value of ``1``.
 
+.. caution::
+
+    You can have more than one optional parameter (e.g. ``/blog/{slug}/{page}``),
+    but everything after an optional parameter must be optional. For example,
+    ``/{page}/blog`` is a valid path, but ``page`` will always be required
+    (i.e. ``/blog`` will not match this route).
+
+.. note::
+
+    Routes with optional parameters at the end will not match on requests
+    with a trailing slash (i.e. ``/blog/`` will not match, ``/blog`` will match).
+
+If you want to always include some default value in the generated URL (for
+example to force the generation of ``/blog/1`` instead of ``/blog`` in the
+previous example) add the ``!`` character before the parameter name: ``/blog/{!page}``
+
+.. versionadded:: 4.3
+
+    The feature to force the inclusion of default values in generated URLs was
+    introduced in Symfony 4.3.
+
 As it happens with requirements, default values can also be inlined in each
-placeholder using the syntax ``{placeholder_name?default_value}``. This feature
+parameter using the syntax ``{parameter_name?default_value}``. This feature
 is compatible with inlined requirements, so you can inline both in a single
-placeholder:
+parameter:
 
 .. configuration-block::
 
@@ -541,7 +734,7 @@ placeholder:
             /**
              * @Route("/blog/{page<\d+>?1}", name="blog_list")
              */
-            public function list($page)
+            public function list(int $page)
             {
                 // ...
             }
@@ -551,7 +744,7 @@ placeholder:
 
         # config/routes.yaml
         blog_list:
-            path:      /blog/{page<\d+>?1}
+            path:       /blog/{page<\d+>?1}
             controller: App\Controller\BlogController::list
 
     .. code-block:: xml
@@ -561,10 +754,10 @@ placeholder:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="blog_list" path="/blog/{page <\d+>?1}"
-                   controller="App\Controller\BlogController::list" />
+                   controller="App\Controller\BlogController::list"/>
 
             <!-- ... -->
         </routes>
@@ -572,53 +765,97 @@ placeholder:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
         use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('blog_list', new Route('/blog/{page<\d+>?1}', [
-            '_controller' => [BlogController::class, 'list'],
-        ]));
-
-        // ...
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_list', '/blog/{page<\d+>?1}')
+                ->controller([BlogController::class, 'list'])
+            ;
+        };
 
 .. tip::
 
-    To give a ``null`` default value to any placeholder, add nothing after the
+    To give a ``null`` default value to any parameter, add nothing after the
     ``?`` character (e.g. ``/blog/{page?}``).
 
-.. versionadded:: 4.1
-    The feature to inline default values was introduced in Symfony 4.1.
+Parameter Conversion
+~~~~~~~~~~~~~~~~~~~~
 
-Listing all of your Routes
---------------------------
+A common routing need is to convert the value stored in some parameter (e.g. an
+integer acting as the user ID) into another value (e.g. the object that
+represents the user). This feature is called "param converter" and is only
+available when using annotations to define routes.
 
-As your app grows, you'll eventually have a *lot* of routes! To see them all, run:
+In case you didn't run this command before, run it now to add support for
+annotations and "param converters":
 
 .. code-block:: terminal
 
-    $ php bin/console debug:router
+    $ composer require annotations
 
-    ------------------------------ -------- -------------------------------------
-     Name                           Method   Path
-    ------------------------------ -------- -------------------------------------
-     app_lucky_number              ANY    /lucky/number/{max}
-     ...
-    ------------------------------ -------- -------------------------------------
+Now, keep the previous route configuration, but change the arguments of the
+controller action. Instead of ``string $slug``, add ``BlogPost $post``::
 
-.. index::
-   single: Routing; Advanced example
-   single: Routing; _format parameter
+    // src/Controller/BlogController.php
+    namespace App\Controller;
 
-.. _advanced-routing-example:
+    use App\Entity\BlogPost;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Routing\Annotation\Route;
 
-Advanced Routing Example
-------------------------
+    class BlogController extends AbstractController
+    {
+        // ...
+
+        /**
+         * @Route("/blog/{slug}", name="blog_show")
+         */
+        public function show(BlogPost $post)
+        {
+            // $post is the object whose slug matches the routing parameter
+
+            // ...
+        }
+    }
+
+If your controller arguments include type-hints for objects (``BlogPost`` in
+this case), the "param converter" makes a database request to find the object
+using the request parameters (``slug`` in this case). If no object is found,
+Symfony generates a 404 response automatically.
 
-With all of this in mind, check out this advanced example:
+Read the `full param converter documentation`_ to learn about the converters
+provided by Symfony and how to configure them.
+
+Special Parameters
+~~~~~~~~~~~~~~~~~~
+
+In addition to your own parameters, routes can include any of the following
+special parameters created by Symfony:
+
+``_controller``
+    This parameter is used to determine which controller and action is executed
+    when the route is matched.
+
+.. _routing-format-parameter:
+
+``_format``
+    The matched value is used to set the "request format" of the ``Request`` object.
+    This is used for such things as setting the ``Content-Type`` of the response
+    (e.g. a ``json`` format translates into a ``Content-Type`` of ``application/json``).
+
+``_fragment``
+    Used to set the fragment identifier, which is the optional last part of a URL that
+    starts with a ``#`` character and is used to identify a portion of a document.
+
+.. _routing-locale-parameter:
+
+``_locale``
+    Used to set the :ref:`locale <translation-locale-url>` on the request.
+
+You can include these attributes (except ``_fragment``) both in individual routes
+and in route imports. Symfony defines some special attributes with the same name
+(except for the leading underscore) so you can define them easier:
 
 .. configuration-block::
 
@@ -631,16 +868,16 @@ With all of this in mind, check out this advanced example:
         {
             /**
              * @Route(
-             *     "/articles/{_locale}/{year}/{slug}.{_format}",
-             *     defaults={"_format": "html"},
+             *     "/articles/{_locale}/search.{_format}",
+             *     locale="en",
+             *     format="html",
              *     requirements={
              *         "_locale": "en|fr",
-             *         "_format": "html|rss",
-             *         "year": "\d+"
+             *         "_format": "html|xml",
              *     }
              * )
              */
-            public function show($_locale, $year, $slug)
+            public function search()
             {
             }
         }
@@ -648,15 +885,14 @@ With all of this in mind, check out this advanced example:
     .. code-block:: yaml
 
         # config/routes.yaml
-        article_show:
-          path:     /articles/{_locale}/{year}/{slug}.{_format}
-          controller: App\Controller\ArticleController::show
-          defaults:
-              _format: html
+        article_search:
+          path:        /articles/{_locale}/search.{_format}
+          controller:  App\Controller\ArticleController::search
+          locale:      en
+          format:      html
           requirements:
-              _locale:  en|fr
-              _format:  html|rss
-              year:     \d+
+              _locale: en|fr
+              _format: html|xml
 
     .. code-block:: xml
 
@@ -665,16 +901,16 @@ With all of this in mind, check out this advanced example:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="article_show"
-                path="/articles/{_locale}/{year}/{slug}.{_format}"
-                controller="App\Controller\ArticleController::show">
+            <route id="article_search"
+                path="/articles/{_locale}/search.{_format}"
+                controller="App\Controller\ArticleController::search"
+                locale="en"
+                format="html">
 
-                <default key="_format">html</default>
                 <requirement key="_locale">en|fr</requirement>
                 <requirement key="_format">html|rss</requirement>
-                <requirement key="year">\d+</requirement>
 
             </route>
         </routes>
@@ -682,155 +918,959 @@ With all of this in mind, check out this advanced example:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
+        namespace Symfony\Component\Routing\Loader\Configurator;
+
         use App\Controller\ArticleController;
 
-        $routes = new RouteCollection();
-        $routes->add(
-            'article_show',
-            new Route('/articles/{_locale}/{year}/{slug}.{_format}', [
-                '_controller' => [ArticleController::class, 'show'],
-                '_format'     => 'html',
-            ], [
-                '_locale' => 'en|fr',
-                '_format' => 'html|rss',
-                'year'    => '\d+',
-            ])
-        );
+        return function (RoutingConfigurator $routes) {
+            $routes->add('article_show', '/articles/{_locale}/search.{_format}')
+                ->controller([ArticleController::class, 'search'])
+                ->locale('en')
+                ->format('html')
+                ->requirements([
+                    '_locale' => 'en|fr',
+                    '_format' => 'html|rss',
+                ])
+            ;
+        };
 
-        return $routes;
+.. versionadded:: 4.3
 
-As you've seen, this route will only match if the ``{_locale}`` portion of
-the URL is either ``en`` or ``fr`` and if the ``{year}`` is a number. This
-route also shows how you can use a dot between placeholders instead of
-a slash. URLs matching this route might look like:
+    The special attributes were introduced in Symfony 4.3.
 
-* ``/articles/en/2010/my-post``
-* ``/articles/fr/2010/my-post.rss``
-* ``/articles/en/2013/my-latest-post.html``
+Extra Parameters
+~~~~~~~~~~~~~~~~
 
-.. _routing-format-param:
+In the ``defaults`` option of a route you can optionally define parameters not
+included in the route configuration. This is useful to pass extra arguments to
+the controllers of the routes:
 
-.. sidebar:: The Special ``_format`` Routing Parameter
+.. configuration-block::
 
-    This example also highlights the special ``_format`` routing parameter.
-    When using this parameter, the matched value becomes the "request format"
-    of the ``Request`` object.
+    .. code-block:: php-annotations
 
-    Ultimately, the request format is used for such things as setting the
-    ``Content-Type`` of the response (e.g. a ``json`` request format translates
-    into a ``Content-Type`` of ``application/json``).
+        use Symfony\Component\Routing\Annotation\Route;
 
-.. note::
+        class BlogController
+        {
+            /**
+             * @Route("/blog/{page}", name="blog_index", defaults={"page": 1, "title": "Hello world!"})
+             */
+            public function index(int $page, string $title)
+            {
+                // ...
+            }
+        }
 
-    Sometimes you want to make certain parts of your routes globally configurable.
-    Symfony provides you with a way to do this by leveraging service container
-    parameters. Read more about this in ":doc:`/routing/service_container_parameters`".
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        blog_index:
+            path:       /blog/{page}
+            controller: App\Controller\BlogController::index
+            defaults:
+                page: 1
+                title: "Hello world!"
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="blog_index" path="/blog/{page}" controller="App\Controller\BlogController::index">
+                <default key="page">1</default>
+                <default key="title">Hello world!</default>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\BlogController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('blog_index', '/blog/{page}')
+                ->controller([BlogController::class, 'index'])
+                ->defaults([
+                    'page'  => 1,
+                    'title' => 'Hello world!',
+                ])
+            ;
+        };
+
+.. _routing-slash-in-parameters:
+
+Slash Characters in Route Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Route parameters can contain any values except the ``/`` slash character,
+because that's the character used to separate the different parts of the URLs.
+For example, if the ``token`` value in the ``/share/{token}`` route contains a
+``/`` character, this route won't match.
+
+A possible solution is to change the parameter requirements to be more permissive:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class DefaultController
+        {
+            /**
+             * @Route("/share/{token}", name="share", requirements={"token"=".+"})
+             */
+            public function share($token)
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        share:
+            path:       /share/{token}
+            controller: App\Controller\DefaultController::share
+            requirements:
+                token: .+
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="share" path="/share/{token}" controller="App\Controller\DefaultController::share">
+                <requirement key="token">.+</requirement>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\DefaultController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('share', '/share/{token}')
+                ->controller([DefaultController::class, 'share'])
+                ->requirements([
+                    'token' => '.+',
+                ])
+            ;
+        };
+
+.. note::
+
+    If the route defines several parameter and you apply this permissive
+    regular expression to all of them, the results won't be the expected. For
+    example, if the route definition is ``/share/{path}/{token}`` and both
+    ``path`` and ``token`` accept ``/``, then ``path`` will contain its contents
+    and the token, and ``token`` will be empty.
+
+.. note::
+
+    If the route includes the special ``{_format}`` parameter, you shouldn't
+    use the ``.+`` requirement for the parameters that allow slashes. For example,
+    if the pattern is ``/share/{token}.{_format}`` and ``{token}`` allows any
+    character, the ``/share/foo/bar.json`` URL will consider ``foo/bar.json``
+    as the token and the format will be empty. This can be solved by replacing
+    the ``.+`` requirement by ``[^.]+`` to allow any character except dots.
+
+.. _routing-route-groups:
+
+Route Groups and Prefixes
+-------------------------
+
+It's common for a group of routes to share some options (e.g. all routes related
+to the blog start with ``/blog``) That's why Symfony includes a feature to share
+route configuration.
+
+When defining routes as annotations, put the common configuration in the
+``@Route`` annotation of the controller class. In other routing formats, define
+the common configuration using options when importing the routes.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        use Symfony\Component\Routing\Annotation\Route;
+
+        /**
+         * @Route("/blog", requirements={"locale": "en|es|fr"}, name="blog_")
+         */
+        class BlogController
+        {
+            /**
+             * @Route("/{_locale}", name="index")
+             */
+            public function index()
+            {
+                // ...
+            }
+
+            /**
+             * @Route("/{_locale}/posts/{slug}", name="post")
+             */
+            public function show(Post $post)
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes/annotations.yaml
+        controllers:
+            resource: '../src/Controller/'
+            type: annotation
+            # this is added to the beginning of all imported route URLs
+            prefix: '/blog'
+            # this is added to the beginning of all imported route names
+            name_prefix: 'blog_'
+            # these requirements are added to all imported routes
+            requirements:
+                locale: 'en|es|fr'
+            # An imported route with an empty URL will become "/blog/"
+            # Uncomment this option to make that URL "/blog" instead
+            # trailing_slash_on_root: false
+
+    .. code-block:: xml
+
+        <!-- config/routes/annotations.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <!--
+                the 'prefix' value is added to the beginning of all imported route URLs
+                the 'name-prefix' value is added to the beginning of all imported route names
+            -->
+            <import resource="../src/Controller/"
+                type="annotation"
+                prefix="/blog"
+                name-prefix="blog_">
+                <!-- these requirements are added to all imported routes -->
+                <requirement key="locale">en|es|fr</requirement>
+            </import>
+
+            <!-- An imported route with an empty URL will become "/blog/"
+                 Uncomment this option to make that URL "/blog" instead -->
+            <import resource="../src/Controller/" type="annotation"
+                    prefix="/blog"
+                    trailing-slash-on-root="false">
+                    <!-- ... -->
+            </import>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes/annotations.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->import('../src/Controller/', 'annotation')
+                // this is added to the beginning of all imported route URLs
+                ->prefix('/blog')
+                // An imported route with an empty URL will become "/blog/"
+                // Pass FALSE as the second argument to make that URL "/blog" instead
+                // ->prefix('/blog', false)
+                // this is added to the beginning of all imported route names
+                ->namePrefix('blog_')
+                // these requirements are added to all imported routes
+                ->requirements(['locale' => 'en|es|fr'])
+            ;
+        };
+
+In this example, the route of the ``index()`` action will be called ``blog_index``
+and its URL will be ``/blog/``. The route of the ``show()`` action will be called
+``blog_post`` and its URL will be ``/blog/{_locale}/posts/{slug}``. Both routes
+will also validate that the ``_locale`` parameter matches the regular expression
+defined in the class annotation.
+
+.. seealso::
+
+    Symfony can :doc:`import routes from different sources </routing/custom_route_loader>`
+    and you can even create your own route loader.
+
+Getting the Route Name and Parameters
+-------------------------------------
+
+The ``Request`` object created by Symfony stores all the route configuration
+(such as the name and parameters) in the "request attributes". You can get this
+information in a controller via the ``Request`` object::
+
+    // src/Controller/BlogController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\Routing\Annotation\Route;
+
+    class BlogController extends AbstractController
+    {
+        /**
+         * @Route("/blog", name="blog_list")
+         */
+        public function list(Request $request)
+        {
+            // ...
+
+            $routeName = $request->attributes->get('_route');
+            $routeParameters = $request->attributes->get('_route_params');
+
+            // use this to get all the available attributes (not only routing ones):
+            $allAttributes = $request->attributes->all();
+        }
+    }
+
+You can get this information in services too injecting the ``request_stack``
+service to :doc:`get the Request object in a service </service_container/request>`.
+In Twig templates, use the :ref:`global app object <reference-twig-global-app>`
+to get the request and its attributes:
+
+.. code-block:: twig
+
+    {% set route_name = app.request.attributes.get('_route') %}
+    {% set route_parameters = app.request.attributes.get('_route_params') %}
+
+    {# use this to get all the available attributes (not only routing ones) #}
+    {% set all_attributes = app.request.attributes.all %}
+
+Special Routes
+--------------
+
+Symfony defines some special controllers to render templates and redirect to
+other routes from the route configuration so you don't have to create a
+controller action.
+
+Rendering Templates
+~~~~~~~~~~~~~~~~~~~
+
+Use the ``TemplateController`` to render the template whose path is defined in
+the ``template`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        about_us:
+            path: /site/about-us
+            controller: Symfony\Bundle\FrameworkBundle\Controller\TemplateController::templateAction
+            defaults:
+                template: 'static_pages/about_us.html.twig'
+
+                # optionally you can define some arguments passed to the template
+                site_name: 'ACME'
+                theme: 'dark'
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="about_us" path="/site/about-us"
+                   controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController::templateAction">
+                <default key="template">static_pages/about_us.html.twig</default>
+
+                <!-- optionally you can define some arguments passed to the template -->
+                <default key="site_name">ACME</default>
+                <default key="theme">dark</default>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\DefaultController;
+        use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('about_us', '/site/about-us')
+                ->controller([TemplateController::class, 'templateAction'])
+                 ->defaults([
+                    'template' => 'static_pages/about_us.html.twig',
+                    // optionally you can define some arguments passed to the template
+                    'site_name' => 'ACME',
+                    'theme' => 'dark',
+                ])
+            ;
+        };
+
+Redirecting to URLs and Routes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the ``RedirectController`` to redirect to other routes (``redirectAction``)
+and URLs (``urlRedirectAction``):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        doc_shortcut:
+            path: /doc
+            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
+            defaults:
+                route: 'doc_page'
+                # optionally you can define some arguments passed to the route
+                page: 'index'
+                version: 'current'
+                # redirections are temporary by default (code 302) but you can make them permanent (code 301)
+                permanent: true
+                # add this to keep the original query string parameters when redirecting
+                keepQueryParams: true
+                # add this to keep the HTTP method when redirecting. The redirect status changes
+                # * for temporary redirects, it uses the 307 status code instead of 302
+                # * for permanent redirects, it uses the 308 status code instead of 301
+                keepRequestMethod: true
+
+        legacy_doc:
+            path: /legacy/doc
+            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction
+            defaults:
+                # this value can be an absolute path or an absolute URL
+                path: 'https://legacy.example.com/doc'
+                permanent: true
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="doc_shortcut" path="/doc"
+                   controller="Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction">
+                <default key="route">doc_page</default>
+                <!-- optionally you can define some arguments passed to the route -->
+                <default key="page">index</default>
+                <default key="version">current</default>
+                <!-- redirections are temporary by default (code 302) but you can make them permanent (code 301)-->
+                <default key="permanent">true</default>
+                <!-- add this to keep the original query string parameters when redirecting -->
+                <default key="keepQueryParams">true</default>
+                <!-- add this to keep the HTTP method when redirecting. The redirect status changes:
+                     * for temporary redirects, it uses the 307 status code instead of 302
+                     * for permanent redirects, it uses the 308 status code instead of 301 -->
+                <default key="keepRequestMethod">true</default>
+            </route>
+
+            <route id="legacy_doc" path="/legacy/doc"
+                   controller="Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction">
+                <!-- this value can be an absolute path or an absolute URL -->
+                <default key="path">https://legacy.example.com/doc</default>
+                <!-- redirections are temporary by default (code 302) but you can make them permanent (code 301)-->
+                <default key="permanent">true</default>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\DefaultController;
+        use Symfony\Bundle\FrameworkBundle\Controller\RedirectController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('doc_shortcut', '/doc')
+                ->controller([RedirectController::class, 'redirectAction'])
+                 ->defaults([
+                    'route' => 'doc_page',
+                    // optionally you can define some arguments passed to the template
+                    'page' => 'index',
+                    'version' => 'current',
+                    // redirections are temporary by default (code 302) but you can make them permanent (code 301)
+                    'permanent' => true,
+                    // add this to keep the original query string parameters when redirecting
+                    'keepQueryParams' => true,
+                    // add this to keep the HTTP method when redirecting. The redirect status changes:
+                    // * for temporary redirects, it uses the 307 status code instead of 302
+                    // * for permanent redirects, it uses the 308 status code instead of 301
+                    'keepRequestMethod' => true,
+                ])
+            ;
+
+            $routes->add('legacy_doc', '/legacy/doc')
+                ->controller([RedirectController::class, 'urlRedirectAction'])
+                 ->defaults([
+                    // this value can be an absolute path or an absolute URL
+                    'path' => 'https://legacy.example.com/doc',
+                    // redirections are temporary by default (code 302) but you can make them permanent (code 301)
+                    'permanent' => true,
+                ])
+            ;
+        };
+
+.. tip::
+
+    Symfony also provides some utilities to
+    :ref:`redirect inside controllers <controller-redirect>`
+
+.. _routing-trailing-slash-redirection:
+
+Redirecting URLs with Trailing Slashes
+......................................
+
+Historically, URLs have followed the UNIX convention of adding trailing slashes
+for directories (e.g. ``https://example.com/foo/``) and removing them to refer
+to files (``https://example.com/foo``). Although serving different contents for
+both URLs is OK, nowadays it's common to treat both URLs as the same URL and
+redirect between them.
+
+Symfony follows this logic to redirect between URLs with and without trailing
+slashes (but only for ``GET`` and ``HEAD`` requests):
+
+==========  ========================================  ==========================================
+Route URL   If the requested URL is ``/foo``          If the requested URL is ``/foo/``
+==========  ========================================  ==========================================
+``/foo``    It matches (``200`` status response)      It makes a ``301`` redirect to ``/foo``
+``/foo/``   It makes a ``301`` redirect to ``/foo/``  It matches (``200`` status response)
+==========  ========================================  ==========================================
+
+.. note::
+
+    If your application defines different routes for each path (``/foo`` and
+    ``/foo/``) this automatic redirection doesn't take place and the right
+    route is always matched.
+
+Sub-Domain Routing
+------------------
+
+Routes can configure a ``host`` option to require that the HTTP host of the
+incoming requests matches some specific value. In the following example, both
+routes match the same path (``/``) but one of them only responds to a specific
+host name:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/MainController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class MainController extends AbstractController
+        {
+            /**
+             * @Route("/", name="mobile_homepage", host="m.example.com")
+             */
+            public function mobileHomepage()
+            {
+                // ...
+            }
+
+            /**
+             * @Route("/", name="homepage")
+             */
+            public function homepage()
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        mobile_homepage:
+            path:       /
+            host:       m.example.com
+            controller: App\Controller\MainController::mobileHomepage
+
+        homepage:
+            path:       /
+            controller: App\Controller\MainController::homepage
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="mobile_homepage"
+                path="/"
+                host="m.example.com"
+                controller="App\Controller\MainController::mobileHomepage"/>
+
+            <route id="homepage" path="/" controller="App\Controller\MainController::homepage"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\MainController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('mobile_homepage', '/')
+                ->controller([MainController::class, 'mobileHomepage'])
+                ->host('m.example.com')
+            ;
+            $routes->add('homepage', '/')
+                ->controller([MainController::class, 'homepage'])
+            ;
+        };
+
+        return $routes;
+
+The value of the ``host`` option can include parameters (which is useful in
+multi-tenant applications) and these parameters can be validated too with
+``requirements``:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/MainController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class MainController extends AbstractController
+        {
+            /**
+             * @Route(
+             *     "/",
+             *     name="mobile_homepage",
+             *     host="{subdomain}.example.com",
+             *     defaults={"subdomain"="m"},
+             *     requirements={"subdomain"="m|mobile"}
+             * )
+             */
+            public function mobileHomepage()
+            {
+                // ...
+            }
+
+            /**
+             * @Route("/", name="homepage")
+             */
+            public function homepage()
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        mobile_homepage:
+            path:       /
+            host:       "{subdomain}.example.com"
+            controller: App\Controller\MainController::mobileHomepage
+            defaults:
+                subdomain: m
+            requirements:
+                subdomain: m|mobile
+
+        homepage:
+            path:       /
+            controller: App\Controller\MainController::homepage
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="mobile_homepage"
+                path="/"
+                host="{subdomain}.example.com"
+                controller="App\Controller\MainController::mobileHomepage">
+                <default key="subdomain">m</default>
+                <requirement key="subdomain">m|mobile</requirement>
+            </route>
+
+            <route id="homepage" path="/" controller="App\Controller\MainController::homepage"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\MainController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('mobile_homepage', '/')
+                ->controller([MainController::class, 'mobileHomepage'])
+                ->host('{subdomain}.example.com')
+                ->defaults([
+                    'subdomain' => 'm',
+                ])
+                ->requirements([
+                    'subdomain' => 'm|mobile',
+                ])
+            ;
+            $routes->add('homepage', '/')
+                ->controller([MainController::class, 'homepage'])
+            ;
+        };
+
+In the above example, the ``subdomain`` parameter defines a default value because
+otherwise you need to include a domain value each time you generate a URL using
+these routes.
+
+.. tip::
+
+    You can also set the ``host`` option when :ref:`importing routes <routing-route-groups>`
+    to make all of them require that host name.
+
+.. note::
+
+    When using sub-domain routing, you must set the ``Host`` HTTP headers in
+    :doc:`functional tests </testing>` or routes won't match::
+
+        $crawler = $client->request(
+            'GET',
+            '/',
+            [],
+            [],
+            ['HTTP_HOST' => 'm.example.com']
+            // or get the value from some container parameter:
+            // ['HTTP_HOST' => 'm.' . $client->getContainer()->getParameter('domain')]
+        );
+
+.. _i18n-routing:
+
+Localized Routes (i18n)
+-----------------------
+
+If your application is translated into multiple languages, each route can define
+a different URL per each :doc:`translation locale </translation/locale>`. This
+avoids the need for duplicating routes, which also reduces the potential bugs:
+
+.. configuration-block::
 
-Special Routing Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+    .. code-block:: php-annotations
 
-As you've seen, each routing parameter or default value is eventually available
-as an argument in the controller method. Additionally, there are four parameters
-that are special: each adds a unique piece of functionality inside your application:
+        // src/Controller/CompanyController.php
+        namespace App\Controller;
 
-``_controller``
-    As you've seen, this parameter is used to determine which controller is
-    executed when the route is matched.
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
 
-``_format``
-    Used to set the request format (:ref:`read more <routing-format-param>`).
+        class CompanyController extends AbstractController
+        {
+            /**
+             * @Route({
+             *     "en": "/about-us",
+             *     "nl": "/over-ons"
+             * }, name="about_us")
+             */
+            public function about()
+            {
+                // ...
+            }
+        }
 
-``_fragment``
-    Used to set the fragment identifier, the optional last part of a URL that
-    starts with a ``#`` character and is used to identify a portion of a document.
+    .. code-block:: yaml
 
-``_locale``
-    Used to set the locale on the request (:ref:`read more <translation-locale-url>`).
+        # config/routes.yaml
+        about_us:
+            path:
+                en: /about-us
+                nl: /over-ons
+            controller: App\Controller\CompanyController::about
 
-.. _routing-trailing-slash-redirection:
+    .. code-block:: xml
 
-Redirecting URLs with Trailing Slashes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-Historically, URLs have followed the UNIX convention of adding trailing slashes
-for directories (e.g. ``https://example.com/foo/``) and removing them to refer
-to files (``https://example.com/foo``). Although serving different contents for
-both URLs is OK, nowadays it's common to treat both URLs as the same URL and
-redirect between them.
+            <route id="about_us" controller="App\Controller\CompanyController::about">
+                <path locale="en">/about-us</path>
+                <path locale="nl">/over-ons</path>
+            </route>
+        </routes>
 
-Symfony follows this logic to redirect between URLs with and without trailing
-slashes (but only for ``GET`` and ``HEAD`` requests):
+    .. code-block:: php
 
-==========  ========================================  ==========================================
-Route path  If the requested URL is ``/foo``          If the requested URL is ``/foo/``
-----------  ----------------------------------------  ------------------------------------------
-``/foo``    It matches (``200`` status response)      It makes a ``301`` redirect to ``/foo``
-``/foo/``   It makes a ``301`` redirect to ``/foo/``  It matches (``200`` status response)
-==========  ========================================  ==========================================
+        // config/routes.php
+        use App\Controller\CompanyController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-.. note::
+        return function (RoutingConfigurator $routes) {
+            $routes->add('about_us', [
+                'en' => '/about-us',
+                'nl' => '/over-ons',
+            ])
+                ->controller([CompanyController::class, 'about'])
+            ;
+        };
 
-    If your application defines different routes for each path (``/foo`` and
-    ``/foo/``) this automatic redirection doesn't take place and the right
-    route is always matched.
+When a localized route is matched, Symfony uses the same locale automatically
+during the entire request.
+
+.. tip::
 
-.. versionadded:: 4.1
-    The automatic ``301`` redirection from ``/foo/`` to ``/foo`` was introduced
-    in Symfony 4.1. In previous Symfony versions this results in a ``404`` response.
+    When the application uses full "language + territory" locales (e.g. ``fr_FR``,
+    ``fr_BE``), if the URLs are the same in all related locales, routes can use
+    only the language part (e.g. ``fr``) to avoid repeating the same URLs.
 
-.. index::
-   single: Routing; Controllers
-   single: Controller; String naming format
+A common requirement for internationalized applications is to prefix all routes
+with a locale. This can be done by defining a different prefix for each locale
+(and setting an empty prefix for your default locale if you prefer it):
 
-.. _controller-string-syntax:
+.. configuration-block::
 
-Controller Naming Pattern
--------------------------
+    .. code-block:: yaml
 
-The ``controller`` value in your routes has the format ``CONTROLLER_CLASS::METHOD``.
+        # config/routes/annotations.yaml
+        controllers:
+            resource: '../src/Controller/'
+            type: annotation
+            prefix:
+                en: '' # don't prefix URLs for English, the default locale
+                nl: '/nl'
 
-.. tip::
+    .. code-block:: xml
 
-    To refer to an action that is implemented as the ``__invoke()`` method of a controller class,
-    you do not have to pass the method name, you can also use the fully qualified class name (e.g.
-    ``App\Controller\BlogController``).
+        <!-- config/routes/annotations.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-.. index::
-   single: Routing; Generating URLs
+            <import resource="../src/Controller/" type="annotation">
+                <!-- don't prefix URLs for English, the default locale -->
+                <prefix locale="en"></prefix>
+                <prefix locale="nl">/nl</prefix>
+            </import>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes/annotations.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-.. _routing-generate:
+        return function (RoutingConfigurator $routes) {
+            $routes->import('../src/Controller/', 'annotation')
+                ->prefix([
+                    // don't prefix URLs for English, the default locale
+                    'en' => '',
+                    'nl' => '/nl'
+                ])
+            ;
+        };
+
+.. _routing-generating-urls:
 
 Generating URLs
 ---------------
 
-The routing system can also generate URLs. In reality, routing is a bidirectional
-system: mapping the URL to a controller and also a route back to a URL.
+Routing systems are bidirectional: 1) they associate URLs with controllers (as
+explained in the previous sections); 2) they generate URLs for a given route.
+Generating URLs from routes allows you to not write the ``<a href="...">``
+values manually in your HTML templates. Also, if the URL of some route changes,
+you only have to update the route configuration and all links will be updated.
+
+To generate a URL, you need to specify the name of the route (e.g.
+``blog_show``) and the values of the parameters defined by the route (e.g.
+``slug = my-blog-post``).
+
+For that reason each route has an internal name that must be unique in the
+application. If you don't set the route name explicitly with the ``name``
+option, Symfony generates an automatic name based on the controller and action.
+
+Generating URLs in Controllers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your controller extends from the :ref:`AbstractController <the-base-controller-class-services>`,
+use the ``generateUrl()`` helper::
+
+    // src/Controller/BlogController.php
+    namespace App\Controller;
 
-To generate a URL, you need to specify the name of the route (e.g. ``blog_show``)
-and any wildcards (e.g. ``slug = my-blog-post``) used in the path for that
-route. With this information, an URL can be generated in a controller::
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Routing\Annotation\Route;
+    use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 
-    class MainController extends AbstractController
+    class BlogController extends AbstractController
     {
-        public function show($slug)
+        /**
+         * @Route("/blog", name="blog_list")
+         */
+        public function list()
         {
             // ...
 
-            // /blog/my-blog-post
-            $url = $this->generateUrl(
-                'blog_show',
-                ['slug' => 'my-blog-post']
-            );
+            // generate a URL with no route arguments
+            $signUpPage = $this->generateUrl('sign_up');
+
+            // generate a URL with route arguments
+            $userProfilePage = $this->generateUrl('user_profile', [
+                'username' => $user->getUsername(),
+            ]);
+
+            // generated URLs are "absolute paths" by default. Pass a third optional
+            // argument to generate different URLs (e.g. an "absolute URL")
+            $signUpPage = $this->generateUrl('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);
+
+            // when a route is localized, Symfony uses by default the current request locale
+            // pass a different '_locale' value if you want to set the locale explicitly
+            $signUpPageInDutch = $this->generateUrl('sign_up', ['_locale' => 'nl']);
         }
     }
 
-If you need to generate a URL from a service, type-hint the :class:`Symfony\\Component\\Routing\\Generator\\UrlGeneratorInterface`
-service::
+.. note::
 
-    // src/Service/SomeService.php
+    If you pass to the ``generateUrl()`` method some parameters that are not
+    part of the route definition, they are included in the generated URL as a
+    query string:::
+
+        $this->generateUrl('blog', ['page' => 2, 'category' => 'Symfony']);
+        // the 'blog' route only defines the 'page' parameter; the generated URL is:
+        // /blog/2?category=Symfony
+
+If your controller does not extend from ``AbstractController``, you'll need to
+:ref:`fetch services in your controller <controller-accessing-services>` and
+follow the instructions of the next section.
 
+.. _routing-generating-urls-in-services:
+
+Generating URLs in Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Inject the ``router`` Symfony service into your own services and use its
+``generate()`` method. When using :doc:`service autowiring </service_container/autowiring>`
+you only need to add an argument in the service constructor and type-hint it with
+the :class:`Symfony\\Component\\Routing\\Generator\\UrlGeneratorInterface` class::
+
+    // src/Service/SomeService.php
     use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 
     class SomeService
@@ -844,69 +1884,342 @@ service::
 
         public function someMethod()
         {
-            $url = $this->router->generate(
-                'blog_show',
-                ['slug' => 'my-blog-post']
-            );
             // ...
+
+            // generate a URL with no route arguments
+            $signUpPage = $this->router->generate('sign_up');
+
+            // generate a URL with route arguments
+            $userProfilePage = $this->router->generate('user_profile', [
+                'username' => $user->getUsername(),
+            ]);
+
+            // generated URLs are "absolute paths" by default. Pass a third optional
+            // argument to generate different URLs (e.g. an "absolute URL")
+            $signUpPage = $this->router->generate('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);
+
+            // when a route is localized, Symfony uses by default the current request locale
+            // pass a different '_locale' value if you want to set the locale explicitly
+            $signUpPageInDutch = $this->router->generate('sign_up', ['_locale' => 'nl']);
         }
     }
 
-.. index::
-   single: Routing; Generating URLs in a template
+Generating URLs in Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Generating URLs with Query Strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Twig template language used in :doc:`Symfony templates </templating>`
+provides some functions to generate both relative and absolute URLs:
 
-The ``generate()`` method takes an array of wildcard values to generate the URI.
-But if you pass extra ones, they will be added to the URI as a query string::
+.. code-block:: html+twig
 
-    $this->router->generate('blog', [
-        'page' => 2,
-        'category' => 'Symfony',
-    ]);
-    // /blog/2?category=Symfony
+    {# generates relative URLs #}
+    <a href="{{ path('sign_up') }}">Sign up</a>
+    <a href="{{ path('user_profile', {username: app.user.username}) }}">
+        View your profile
+    </a>
+    <a href="{{ path('user_profile', {username: app.user.username, _locale: 'es'}) }}">
+        Ver mi perfil
+    </a>
 
-Generating Localized URLs
-~~~~~~~~~~~~~~~~~~~~~~~~~
+    {# generates absolute URLs #}
+    <a href="{{ url('sign_up') }}">Sign up</a>
+    <a href="{{ url('user_profile', {username: app.user.username}) }}">
+        View your profile
+    </a>
+    <a href="{{ url('user_profile', {username: app.user.username, _locale: 'es'}) }}">
+        Ver mi perfil
+    </a>
 
-When a route is localized, Symfony uses by default the current request locale to
-generate the URL. In order to generate the URL for a different locale you must
-pass the ``_locale`` in the parameters array::
+Generating URLs in JavaScript
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    $this->router->generate('about_us', [
-        '_locale' => 'nl',
-    ]);
-    // generates: /over-ons
+If your JavaScript code is included in a Twig template, you can use the
+``path()`` and ``url()`` Twig functions to generate the URLs and store them in
+JavaScript variables. The ``escape()`` function is needed to escape any
+non-JavaScript-safe values:
 
-Generating URLs from a Template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. code-block:: html+twig
 
-To generate URLs inside Twig, see the templating article: :ref:`templating-pages`.
-If you also need to generate URLs in JavaScript, see :doc:`/routing/generate_url_javascript`.
+    <script>
+        const route = "{{ path('blog_show', {slug: 'my-blog-post'})|escape('js') }}";
+    </script>
 
-.. index::
-   single: Routing; Absolute URLs
+If you need to generate URLs dynamically or if you are using pure JavaScript
+code, this solution doesn't work. In those cases, consider using the
+`FOSJsRoutingBundle`_.
+
+Generating URLs in Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generating URLs in commands works the same as
+:ref:`generating URLs in services <routing-generating-urls-in-services>`. The
+only difference is that commands are not executed in the HTTP context, so they
+don't have access to HTTP requests. In practice, this means that if you generate
+absolute URLs, you'll get ``http://localhost/`` as the host name instead of your
+real host name.
+
+The solution is to configure "request context" used by commands when they
+generate URLs. This context can be configured globally for all commands:
+
+.. configuration-block::
 
-Generating Absolute URLs
-~~~~~~~~~~~~~~~~~~~~~~~~
+    .. code-block:: yaml
+
+        # config/services.yaml
+        parameters:
+            router.request_context.host: 'example.org'
+            router.request_context.base_url: 'my/path'
+            asset.request_context.base_path: '%router.request_context.base_url%'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+            <parameters>
+                <parameter key="router.request_context.host">example.org</parameter>
+                <parameter key="router.request_context.base_url">my/path</parameter>
+                <parameter key="asset.request_context.base_path">%router.request_context.base_url%</parameter>
+            </parameters>
+
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        $container->setParameter('router.request_context.host', 'example.org');
+        $container->setParameter('router.request_context.base_url', 'my/path');
+        $container->setParameter('asset.request_context.base_path', $container->getParameter('router.request_context.base_url'));
 
-By default, the router will generate relative URLs (e.g. ``/blog``). From
-a controller, pass ``UrlGeneratorInterface::ABSOLUTE_URL`` to the third argument of the ``generateUrl()``
-method::
+This information can be configured per command too::
 
+    // src/Command/SomeCommand.php
     use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+    use Symfony\Component\Routing\RouterInterface;
+    // ...
+
+    class SomeCommand extends Command
+    {
+        private $router;
+
+        public function __construct(RouterInterface $router)
+        {
+            parent::__construct();
+
+            $this->router = $router;
+        }
+
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+            // these values override any global configuration
+            $context = $this->router->getContext();
+            $context->setHost('example.com');
+            $context->setBaseUrl('my/path');
+
+            // generate a URL with no route arguments
+            $signUpPage = $this->router->generate('sign_up');
+
+            // generate a URL with route arguments
+            $userProfilePage = $this->router->generate('user_profile', [
+                'username' => $user->getUsername(),
+            ]);
+
+            // generated URLs are "absolute paths" by default. Pass a third optional
+            // argument to generate different URLs (e.g. an "absolute URL")
+            $signUpPage = $this->router->generate('sign_up', [], UrlGeneratorInterface::ABSOLUTE_URL);
+
+            // when a route is localized, Symfony uses by default the current request locale
+            // pass a different '_locale' value if you want to set the locale explicitly
+            $signUpPageInDutch = $this->router->generate('sign_up', ['_locale' => 'nl']);
+
+            // ...
+        }
+    }
+
+Checking if a Route Exists
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In highly dynamic applications, it may be necessary to check whether a route
+exists before using it to generate a URL. In those cases, don't use the
+:method:`Symfony\\Component\\Routing\\Router::getRouteCollection` method because
+that regenerates the routing cache and slows down the application.
+
+Instead, try to generate the URL and catch the
+:class:`Symfony\\Component\\Routing\\Exception\\RouteNotFoundException` thrown
+when the route doesn't exist::
+
+    use Symfony\Component\Routing\Exception\RouteNotFoundException;
+
+    // ...
+
+    try {
+        $url = $this->router->generate($routeName, $routeParameters);
+    } catch (RouteNotFoundException $e) {
+        // the route is not defined...
+    }
+
+.. _routing-force-https:
+
+Forcing HTTPS on Generated URLs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, generated URLs use the same HTTP scheme as the current request.
+In console commands, where there is no HTTP request, URLs use ``http`` by
+default. You can change this per command (via the router's ``getContext()``
+method) or globally with these configuration parameters:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        parameters:
+            router.request_context.scheme: 'https'
+            asset.request_context.secure: true
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+            <parameters>
+                <parameter key="router.request_context.scheme">https</parameter>
+                <parameter key="asset.request_context.secure">true</parameter>
+            </parameters>
+
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        $container->setParameter('router.request_context.scheme', 'https');
+        $container->setParameter('asset.request_context.secure', true);
+
+Outside of console commands, use the ``schemes`` option to define the scheme of
+each route explicitly:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/MainController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class SecurityController extends AbstractController
+        {
+            /**
+             * @Route("/login", name="login", schemes={"https"})
+             */
+            public function login()
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        login:
+            path:       /login
+            controller: App\Controller\SeurityController::login
+            schemes:    [https]
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="login" path="/login" schemes="https"
+                   controller="App\Controller\SecurityController::login"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\SecurityController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('login', '/login')
+                ->controller([SecurityController::class, 'login'])
+                ->schemes(['https'])
+            ;
+        };
+
+The URL generated for the ``login`` route will always use HTTPS. This means that
+when using the ``path()`` Twig function to generate URLs, you may get an
+absolute URL instead of a relative URL if the HTTP scheme of the original
+request is different from the scheme used by the route:
+
+.. code-block:: twig
+
+    {# if the current scheme is HTTPS, generates a relative URL: /login #}
+    {{ path('login') }}
+
+    {# if the current scheme is HTTP, generates an absolute URL to change
+       the scheme: https://example.com/login #}
+    {{ path('login') }}
 
-    $this->generateUrl('blog_show', ['slug' => 'my-blog-post'], UrlGeneratorInterface::ABSOLUTE_URL);
-    // http://www.example.com/blog/my-blog-post
+The scheme requirement is also enforced for incoming requests. If you try to
+access the ``/login`` URL with HTTP, you will automatically be redirected to the
+same URL, but with the HTTPS scheme.
+
+If you want to force a group of routes to use HTTPS, you can define the default
+scheme when importing them. The following example forces HTTPS on all routes
+defined as annotations:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes/annotations.yaml
+        controllers:
+            resource: '../src/Controller/'
+            type: annotation
+            defaults:
+                schemes: [https]
+
+    .. code-block:: xml
+
+        <!-- config/routes/annotations.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <import resource="../src/Controller/" type="annotation">
+                <default locale="schemes">HTTPS</prefix>
+            </import>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes/annotations.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->import('../src/Controller/', 'annotation')
+                ->schemes(['https'])
+            ;
+        };
 
 .. note::
 
-    The host that's used when generating an absolute URL is automatically
-    detected using the current ``Request`` object. When generating absolute
-    URLs from outside the web context (for instance in a console command) this
-    doesn't work. See :doc:`/console/request_context` to learn how to
-    solve this problem.
+    The Security component provides
+    :doc:`another way to enforce HTTP or HTTPS </security/force_https>`
+    via the ``requires_channel`` setting.
 
 Troubleshooting
 ---------------
@@ -920,30 +2233,25 @@ This happens when your controller method has an argument (e.g. ``$slug``)::
 
     public function show($slug)
     {
-        // ..
+        // ...
     }
 
-But your route path does *not* have a ``{slug}`` wildcard (e.g. it is ``/blog/show``).
-Add a ``{slug}`` to your route path: ``/blog/show/{slug}`` or give the argument
-a default value (i.e. ``$slug = null``).
+But your route path does *not* have a ``{slug}`` parameter (e.g. it is
+``/blog/show``). Add a ``{slug}`` to your route path: ``/blog/show/{slug}`` or
+give the argument a default value (i.e. ``$slug = null``).
 
     Some mandatory parameters are missing ("slug") to generate a URL for route
     "blog_show".
 
-This means that you're trying to generate a URL to the ``blog_show`` route but you
-are *not* passing a ``slug`` value (which is required, because it has a ``{slug}``)
-wildcard in the route path. To fix this, pass a ``slug`` value when generating the
-route::
+This means that you're trying to generate a URL to the ``blog_show`` route but
+you are *not* passing a ``slug`` value (which is required, because it has a
+``{slug}`` parameter in the route path). To fix this, pass a ``slug`` value when
+generating the route::
 
     $this->generateUrl('blog_show', ['slug' => 'slug-value']);
 
     // or, in Twig
-    // {{ path('blog_show', {'slug': 'slug-value'}) }}
-
-Keep Going!
------------
-
-Routing, check! Now, uncover the power of :doc:`controllers </controller>`.
+    // {{ path('blog_show', {slug: 'slug-value'}) }}
 
 Learn more about Routing
 ------------------------
@@ -959,5 +2267,7 @@ Learn more about Routing
 
     routing/*
 
-.. _`JMSI18nRoutingBundle`: https://github.com/schmittjoh/JMSI18nRoutingBundle
-.. _`BeSimpleI18nRoutingBundle`: https://github.com/BeSimple/BeSimpleI18nRoutingBundle
+.. _`PHP regular expressions`: https://www.php.net/manual/en/book.pcre.php
+.. _`PCRE Unicode properties`: http://php.net/manual/en/regexp.reference.unicode.php
+.. _`full param converter documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle
diff --git a/routing/conditions.rst b/routing/conditions.rst
deleted file mode 100644
index 76962a7d464..00000000000
--- a/routing/conditions.rst
+++ /dev/null
@@ -1,121 +0,0 @@
-.. index::
-    single: Routing; Conditions
-
-How to Restrict Route Matching through Conditions
-=================================================
-
-A route can be made to match only certain routing placeholders (via regular
-expressions), HTTP methods, or host names. If you need more flexibility to
-define arbitrary matching logic, use the ``conditions`` routing option:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/DefaultController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class DefaultController extends AbstractController
-        {
-            /**
-             * @Route(
-             *     "/contact",
-             *     name="contact",
-             *     condition="context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
-             * )
-             *
-             * expressions can also include config parameters
-             * condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
-             */
-            public function contact()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        contact:
-            path:       /contact
-            controller: 'App\Controller\DefaultController::contact'
-            condition:  "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
-            # expressions can also include config parameters
-            # condition: "request.headers.get('User-Agent') matches '%app.allowed_browsers%'"
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="contact" path="/contact">
-                <default key="_controller">App\Controller\DefaultController::contact</default>
-                <condition>context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'</condition>
-                <!-- expressions can also include config parameters -->
-                <!-- <condition>request.headers.get('User-Agent') matches '%app.allowed_browsers%'</condition> -->
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('contact', new Route(
-            '/contact', [
-                '_controller' => 'App\Controller\DefaultController::contact',
-            ],
-            [],
-            [],
-            '',
-            [],
-            [],
-            'context.getMethod() in ["GET", "HEAD"] and request.headers.get("User-Agent") matches "/firefox/i"'
-            // expressions can also include config parameters
-            // 'request.headers.get("User-Agent") matches "%app.allowed_browsers%"'
-        ));
-
-        return $collection;
-
-The ``condition`` is an expression, and you can learn more about its syntax
-here: :doc:`/components/expression_language/syntax`. With this, the route
-won't match unless the HTTP method is either GET or HEAD *and* if the ``User-Agent``
-header matches ``firefox``.
-
-You can do any complex logic you need in the expression by leveraging two
-variables that are passed into the expression:
-
-``context``
-    An instance of :class:`Symfony\\Component\\Routing\\RequestContext`,
-    which holds the most fundamental information about the route being matched.
-``request``
-    The Symfony :class:`Symfony\\Component\\HttpFoundation\\Request` object
-    (see :ref:`component-http-foundation-request`).
-
-.. caution::
-
-    Conditions are *not* taken into account when generating a URL.
-
-.. sidebar:: Expressions are Compiled to PHP
-
-    Behind the scenes, expressions are compiled down to raw PHP. Our example
-    would generate the following PHP in the cache directory::
-
-        if (rtrim($pathInfo, '/contact') === '' && (
-            in_array($context->getMethod(), [0 => "GET", 1 => "HEAD"])
-            && preg_match("/firefox/i", $request->headers->get("User-Agent"))
-        )) {
-            // ...
-        }
-
-    Because of this, using the ``condition`` key causes no extra overhead
-    beyond the time it takes for the underlying PHP to execute.
diff --git a/routing/custom_route_loader.rst b/routing/custom_route_loader.rst
index e2942ca0839..60202690f17 100644
--- a/routing/custom_route_loader.rst
+++ b/routing/custom_route_loader.rst
@@ -4,6 +4,90 @@
 How to Create a custom Route Loader
 ===================================
 
+Simple applications can define all their routes in a single configuration file -
+usually ``config/routes.yaml`` (see :ref:`routing-creating-routes`).
+However, in most applications it's common to import routes definitions from
+different resources: PHP annotations in controller files, YAML, XML or PHP
+files stored in some directory, etc.
+
+Built-in Route Loaders
+----------------------
+
+Symfony provides several route loaders for the most common needs:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        app_file:
+            # loads routes from the given routing file stored in some bundle
+            resource: '@AcmeBundle/Resources/config/routing.yaml'
+
+        app_annotations:
+            # loads routes from the PHP annotations of the controllers found in that directory
+            resource: '../src/Controller/'
+            type:     annotation
+
+        app_directory:
+            # loads routes from the YAML, XML or PHP files found in that directory
+            resource: '../legacy/routing/'
+            type:     directory
+
+        app_bundle:
+            # loads routes from the YAML, XML or PHP files found in some bundle directory
+            resource: '@AcmeOtherBundle/Resources/config/routing/'
+            type:     directory
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <!-- loads routes from the given routing file stored in some bundle -->
+            <import resource="@AcmeBundle/Resources/config/routing.yaml"/>
+
+            <!-- loads routes from the PHP annotations of the controllers found in that directory -->
+            <import resource="../src/Controller/" type="annotation"/>
+
+            <!-- loads routes from the YAML or XML files found in that directory -->
+            <import resource="../legacy/routing/" type="directory"/>
+
+            <!-- loads routes from the YAML or XML files found in some bundle directory -->
+            <import resource="@AcmeOtherBundle/Resources/config/routing/" type="directory"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            // loads routes from the given routing file stored in some bundle
+            $routes->import('@AcmeBundle/Resources/config/routing.yaml');
+
+            // loads routes from the PHP annotations of the controllers found in that directory
+            $routes->import('../src/Controller/', 'annotation');
+
+            // loads routes from the YAML or XML files found in that directory
+            $routes->import('../legacy/routing/', 'directory');
+
+            // loads routes from the YAML or XML files found in some bundle directory
+            $routes->import('@AcmeOtherBundle/Resources/config/routing/', 'directory');
+        };
+
+.. note::
+
+    When importing resources, the key (e.g. ``app_file``) is the name of collection.
+    Just be sure that it's unique per file so no other lines override it.
+
+If your application needs are different, you can create your own custom route
+loader as explained in the next section.
+
 What is a Custom Route Loader
 -----------------------------
 
@@ -38,12 +122,35 @@ and :method:`Symfony\\Component\\Config\\Loader\\LoaderInterface::load`.
 
 Take these lines from the ``routes.yaml``:
 
-.. code-block:: yaml
+.. configuration-block::
 
-    # config/routes.yaml
-    controllers:
-        resource: ../src/Controller/
-        type: annotation
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        controllers:
+            resource: ../src/Controller/
+            type: annotation
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <import resource="../src/Controller" type="annotation"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->import('../src/Controller', 'annotation');
+        };
 
 When the main loader parses this, it tries all registered delegate loaders and calls
 their :method:`Symfony\\Component\\Config\\Loader\\LoaderInterface::supports`
@@ -75,7 +182,7 @@ and configure the service and method to call:
 
         # config/routes.yaml
         admin_routes:
-            resource: 'admin_route_loader:loadRoutes'
+            resource: 'admin_route_loader::loadRoutes'
             type: service
 
     .. code-block:: xml
@@ -85,28 +192,40 @@ and configure the service and method to call:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <import resource="admin_route_loader:loadRoutes" type="service"/>
+            <import resource="admin_route_loader::loadRoutes" type="service"/>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-
-        $routes = new RouteCollection();
-        $routes->addCollection(
-            $loader->import("admin_route_loader:loadRoutes", "service")
-        );
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->import('admin_route_loader::loadRoutes', 'service');
+        };
 
-In this example, the routes are loaded by calling the ``loadRoutes()`` method of
-the service whose ID is ``admin_route_loader``. Your service doesn't have to
+In this example, the routes are loaded by calling the ``loadRoutes()`` method
+of the service whose ID is ``admin_route_loader``. Your service doesn't have to
 extend or implement any special class, but the called method must return a
 :class:`Symfony\\Component\\Routing\\RouteCollection` object.
 
+.. note::
+
+    The routes defined using service route loaders will be automatically
+    cached by the framework. So whenever your service should load new routes,
+    don't forget to clear the cache.
+
+.. tip::
+
+    If your service is invokable, you don't need to precise the method to use.
+
+.. versionadded:: 4.3
+
+    The support of the ``__invoke()`` method to create invokable service route
+    loaders was introduced in Symfony 4.3.
+
 Creating a custom Loader
 ------------------------
 
@@ -173,8 +292,8 @@ have to create an ``extra()`` method in the ``ExtraController``::
     // src/Controller/ExtraController.php
     namespace App\Controller;
 
-    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
 
     class ExtraController extends AbstractController
     {
@@ -204,13 +323,13 @@ Now define a service for the ``ExtraLoader``:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <service id="App\Routing\ExtraLoader">
-                    <tag name="routing.loader" />
+                    <tag name="routing.loader"/>
                 </service>
             </services>
         </container>
@@ -220,8 +339,7 @@ Now define a service for the ``ExtraLoader``:
         // config/services.php
         use App\Routing\ExtraLoader;
 
-        $container
-            ->autowire(ExtraLoader::class)
+        $container->autowire(ExtraLoader::class)
             ->addTag('routing.loader')
         ;
 
@@ -230,7 +348,7 @@ as potential route loaders and added as specialized route loaders to the
 ``routing.loader`` *service*, which is an instance of
 :class:`Symfony\\Bundle\\FrameworkBundle\\Routing\\DelegatingLoader`.
 
-Using the custom Loader
+Using the Custom Loader
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 If you did nothing else, your custom routing loader would *not* be called.
@@ -252,20 +370,19 @@ What remains to do is adding a few lines to the routing configuration:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <import resource="." type="extra" />
+            <import resource="." type="extra"/>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-
-        $routes = new RouteCollection();
-        $routes->addCollection($loader->import('.', 'extra'));
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->import('.', 'extra');
+        };
 
 The important part here is the ``type`` key. Its value should be ``extra`` as
 this is the type which the ``ExtraLoader`` supports and this will make sure
@@ -278,7 +395,7 @@ for the ``ExtraLoader``, so it is set to ``.`` (a single dot).
     cached by the framework. So whenever you change something in the loader
     class itself, don't forget to clear the cache.
 
-More advanced Loaders
+More Advanced Loaders
 ---------------------
 
 If your custom route loader extends from
diff --git a/routing/debug.rst b/routing/debug.rst
deleted file mode 100644
index 1c05149656e..00000000000
--- a/routing/debug.rst
+++ /dev/null
@@ -1,52 +0,0 @@
-.. index::
-    single: Routing; Debugging
-
-How to Visualize And Debug Routes
-=================================
-
-While adding and customizing routes, it's helpful to be able to visualize
-and get detailed information about your routes. A great way to see every
-route in your application is via the ``debug:router`` console command, which
-lists *all* the configured routes in your application:
-
-.. code-block:: terminal
-
-    $ php bin/console debug:router
-
-    ------------------ -------- -------- ------ ----------------------------------------------
-     Name               Method   Scheme   Host   Path
-    ------------------ -------- -------- ------ ----------------------------------------------
-     homepage           ANY      ANY      ANY    /
-     contact            GET      ANY      ANY    /contact
-     contact_process    POST     ANY      ANY    /contact
-     article_show       ANY      ANY      ANY    /articles/{_locale}/{year}/{title}.{_format}
-     blog               ANY      ANY      ANY    /blog/{page}
-     blog_show          ANY      ANY      ANY    /blog/{slug}
-    ------------------ -------- -------- ------ ----------------------------------------------
-
-You can also get very specific information on a single route by including
-the route name as the command argument:
-
-.. code-block:: terminal
-
-    $ php bin/console debug:router article_show
-
-    # or use part of the name to search for routes
-    $ php bin/console debug:router blo
-
-      Select one of the matching routes:
-      [0] blog
-      [1] blog_show
-
-.. versionadded:: 4.1
-    The feature to look for partial route names was introduced in Symfony 4.1.
-
-Likewise, if you want to test whether a URL matches a given route, use the
-``router:match`` command. This is useful to debug routing issues and find out
-which route is associated with the given URL:
-
-.. code-block:: terminal
-
-    $ php bin/console router:match /blog/my-latest-post
-
-    Route "blog_show" matches
diff --git a/routing/external_resources.rst b/routing/external_resources.rst
deleted file mode 100644
index 75c5185771b..00000000000
--- a/routing/external_resources.rst
+++ /dev/null
@@ -1,278 +0,0 @@
-.. index::
-    single: Routing; Importing routing resources
-
-How to Include External Routing Resources
-=========================================
-
-Simple applications can define all their routes in a single configuration file -
-usually ``config/routes.yaml`` (see :ref:`routing-creating-routes`).
-However, in most applications it's common to import routes definitions from
-different resources: PHP annotations in controller files, YAML or XML files
-stored in some directory, etc.
-
-This can be done by importing routing resources from the main routing file:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        app_file:
-            # loads routes from the given routing file stored in some bundle
-            resource: '@AcmeOtherBundle/Resources/config/routing.yml'
-
-        app_annotations:
-            # loads routes from the PHP annotations of the controllers found in that directory
-            resource: '../src/Controller/'
-            type:     annotation
-
-        app_directory:
-            # loads routes from the YAML or XML files found in that directory
-            resource: '../legacy/routing/'
-            type:     directory
-
-        app_bundle:
-            # loads routes from the YAML or XML files found in some bundle directory
-            resource: '@AppBundle/Resources/config/routing/public/'
-            type:     directory
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <!-- loads routes from the given routing file stored in some bundle -->
-            <import resource="@AcmeOtherBundle/Resources/config/routing.yml" />
-
-            <!-- loads routes from the PHP annotations of the controllers found in that directory -->
-            <import resource="../src/Controller/" type="annotation" />
-
-            <!-- loads routes from the YAML or XML files found in that directory -->
-            <import resource="../legacy/routing/" type="directory" />
-
-            <!-- loads routes from the YAML or XML files found in some bundle directory -->
-            <import resource="@AppBundle/Resources/config/routing/public/" type="directory" />
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-
-        $routes = new RouteCollection();
-        $routes->addCollection(
-            // loads routes from the given routing file stored in some bundle
-            $loader->import("@AcmeOtherBundle/Resources/config/routing.yml")
-
-            // loads routes from the PHP annotations of the controllers found in that directory
-            $loader->import("../src/Controller/", "annotation")
-
-            // loads routes from the YAML or XML files found in that directory
-            $loader->import("../legacy/routing/", "directory")
-
-            // loads routes from the YAML or XML files found in some bundle directory
-            $loader->import("@AppBundle/Resources/config/routing/public/", "directory")
-        );
-
-        return $routes;
-
-.. note::
-
-    When importing resources from YAML, the key (e.g. ``app_file``) is meaningless.
-    Just be sure that it's unique so no other lines override it.
-
-.. _prefixing-imported-routes:
-
-Prefixing the URLs of Imported Routes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can also choose to provide a "prefix" for the imported routes. For example,
-suppose you want to prefix all application routes with ``/site`` (e.g.
-``/site/blog/{slug}`` instead of ``/blog/{slug}``):
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        use Symfony\Component\Routing\Annotation\Route;
-
-        /**
-         * @Route("/site")
-         */
-        class DefaultController
-        {
-            // ...
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        controllers:
-            resource: '../src/Controller/'
-            type:     annotation
-            prefix:   /site
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <import
-                resource="../src/Controller/"
-                type="annotation"
-                prefix="/site" />
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-
-        $app = $loader->import('../src/Controller/', 'annotation');
-        $app->addPrefix('/site');
-
-        $routes = new RouteCollection();
-        $routes->addCollection($app);
-
-        return $routes;
-
-The path of each route being loaded from the new routing resource will now
-be prefixed with the string ``/site``.
-
-.. note::
-
-    If any of the prefixed routes defines an empty path, Symfony adds a trailing
-    slash to it. In the previous example, an empty path prefixed with ``/site``
-    will result in the ``/site/`` URL. If you want to avoid this behavior, set
-    the ``trailing_slash_on_root`` option to ``false``:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/routes.yaml
-            controllers:
-                resource: '../src/Controller/'
-                type:     annotation
-                prefix:   /site
-                trailing_slash_on_root: false
-
-        .. code-block:: xml
-
-            <!-- config/routes.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <routes xmlns="http://symfony.com/schema/routing"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/routing
-                    http://symfony.com/schema/routing/routing-1.0.xsd">
-
-                <import
-                    resource="../src/Controller/"
-                    type="annotation"
-                    prefix="/site"
-                    trailing-slash-on-root="false" />
-            </routes>
-
-        .. code-block:: php
-
-            // config/routes.php
-            use Symfony\Component\Routing\RouteCollection;
-
-            $app = $loader->import('../src/Controller/', 'annotation');
-            // the second argument is the $trailingSlashOnRoot option
-            $app->addPrefix('/site', false);
-            // ...
-
-    .. versionadded:: 4.1
-        The ``trailing_slash_on_root`` option was introduced in Symfony 4.1.
-
-Prefixing the Names of Imported Routes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You also have the possibility to prefix the names of all the routes defined in
-a controller class or imported from a configuration file:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        use Symfony\Component\Routing\Annotation\Route;
-
-        /**
-         * @Route(name="blog_")
-         */
-        class BlogController extends AbstractController
-        {
-            /**
-             * @Route("/blog", name="index")
-             */
-            public function index()
-            {
-                // ...
-            }
-
-            /**
-             * @Route("/blog/posts/{slug}", name="post")
-             */
-            public function show(Post $post)
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        controllers:
-            resource:    '../src/Controller/'
-            type:        annotation
-            name_prefix: 'blog_'
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <import
-                resource="../src/Controller/"
-                type="annotation"
-                name-prefix="blog_" />
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-
-        $app = $loader->import('../src/Controller/', 'annotation');
-        $app->addNamePrefix('blog_');
-
-        $collection = new RouteCollection();
-        $collection->addCollection($app);
-
-        return $collection;
-
-In this example, the names of the routes will be ``blog_index`` and ``blog_post``.
-
-.. versionadded:: 4.1
-    The option to prefix route names in YAML, XML and PHP files was introduced
-    in Symfony 4.1. Previously only the ``@Route()`` annotation supported this
-    feature.
-
-Adding a Host Requirement to Imported Routes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can set the host regex on imported routes. For more information, see
-:ref:`component-routing-host-imported`.
diff --git a/routing/extra_information.rst b/routing/extra_information.rst
deleted file mode 100644
index 295d7926ae8..00000000000
--- a/routing/extra_information.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. index::
-   single: Routing; Extra Information
-
-How to Pass Extra Information from a Route to a Controller
-==========================================================
-
-Parameters inside the ``defaults`` collection don't necessarily have to match
-a placeholder in the route ``path``. In fact, you can use the ``defaults``
-array to specify extra parameters that will then be accessible as arguments
-to your controller, and as attributes of the ``Request`` object:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        blog:
-            path:       /blog/{page}
-            controller: App\Controller\BlogController::index
-            defaults:
-                page: 1
-                title: "Hello world!"
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="blog" path="/blog/{page}">
-                <default key="_controller">App\Controller\BlogController::index</default>
-                <default key="page">1</default>
-                <default key="title">Hello world!</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('blog', new Route('/blog/{page}', [
-            '_controller' => 'App\Controller\BlogController::index',
-            'page'        => 1,
-            'title'       => 'Hello world!',
-        ]));
-
-        return $routes;
-
-Now, you can access this extra parameter in your controller, as an argument
-to the controller method::
-
-    public function index($page, $title)
-    {
-        // ...
-    }
-
-Alternatively, the title could be accessed through the ``Request`` object::
-
-    use Symfony\Component\HttpFoundation\Request;
-
-    public function index(Request $request, $page)
-    {
-        $title = $request->attributes->get('title');
-
-        // ...
-    }
-
-As you can see, the ``$title`` variable was never defined inside the route
-path, but you can still access its value from inside your controller, through
-the method's argument, or from the ``Request`` object's ``attributes`` bag.
diff --git a/routing/generate_url_javascript.rst b/routing/generate_url_javascript.rst
deleted file mode 100644
index b4e3721c519..00000000000
--- a/routing/generate_url_javascript.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-How to Generate Routing URLs in JavaScript
-==========================================
-
-If you're in a Twig template, you can use the same ``path()`` function to set JavaScript
-variables. The ``escape()`` function helps escape any non-JavaScript-safe values:
-
-.. code-block:: html+twig
-
-    <script>
-    var route = "{{ path('blog_show', {'slug': 'my-blog-post'})|escape('js') }}";
-    </script>
-
-But if you *actually* need to generate routes in pure JavaScript, consider using
-the `FOSJsRoutingBundle`_. It makes the following possible:
-
-.. code-block:: html+twig
-
-    <script>
-    var url = Routing.generate('blog_show', {
-        'slug': 'my-blog-post'
-    });
-    </script>
-
-.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle
diff --git a/routing/hostname_pattern.rst b/routing/hostname_pattern.rst
deleted file mode 100644
index d3ef58522a7..00000000000
--- a/routing/hostname_pattern.rst
+++ /dev/null
@@ -1,434 +0,0 @@
-.. index::
-   single: Routing; Matching on Hostname
-
-How to Match a Route Based on the Host
-======================================
-
-You can also match on the HTTP *host* of the incoming request.
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/MainController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class MainController extends AbstractController
-        {
-            /**
-             * @Route("/", name="mobile_homepage", host="m.example.com")
-             */
-            public function mobileHomepage()
-            {
-                // ...
-            }
-
-            /**
-             * @Route("/", name="homepage")
-             */
-            public function homepage()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        mobile_homepage:
-            path:       /
-            host:       m.example.com
-            controller: App\Controller\MainController::mobileHomepage
-
-        homepage:
-            path:       /
-            controller: App\Controller\MainController::homepage
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="mobile_homepage" path="/" host="m.example.com">
-                <default key="_controller">App\Controller\MainController::mobileHomepage</default>
-            </route>
-
-            <route id="homepage" path="/">
-                <default key="_controller">App\Controller\MainController::homepage</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('mobile_homepage', new Route('/', [
-            '_controller' => 'App\Controller\MainController::mobileHomepage',
-        ], [], [], 'm.example.com'));
-
-        $routes->add('homepage', new Route('/', [
-            '_controller' => 'App\Controller\MainController::homepage',
-        ]));
-
-        return $routes;
-
-Both routes match the same path ``/``, however the first one will match
-only if the host is ``m.example.com``.
-
-Using Placeholders
-------------------
-
-The host option uses the same syntax as the path matching system. This means
-you can use placeholders in your hostname:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/MainController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class MainController extends AbstractController
-        {
-            /**
-             * @Route("/", name="projects_homepage", host="{project_name}.example.com")
-             */
-            public function projectsHomepage()
-            {
-                // ...
-            }
-
-            /**
-             * @Route("/", name="homepage")
-             */
-            public function homepage()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        projects_homepage:
-            path:       /
-            host:       "{project_name}.example.com"
-            controller: App\Controller\MainController::projectsHomepage
-
-        homepage:
-            path:       /
-            controller: App\Controller\MainController::homepage
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="projects_homepage" path="/" host="{project_name}.example.com">
-                <default key="_controller">App\Controller\MainController::projectsHomepage</default>
-            </route>
-
-            <route id="homepage" path="/">
-                <default key="_controller">App\Controller\MainController::homepage</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('project_homepage', new Route('/', [
-            '_controller' => 'App\Controller\MainController::projectsHomepage',
-        ], [], [], '{project_name}.example.com'));
-
-        $routes->add('homepage', new Route('/', [
-            '_controller' => 'App\Controller\MainController::homepage',
-        ]));
-
-        return $routes;
-
-You can also set requirements and default options for these placeholders. For
-instance, if you want to match both ``m.example.com`` and
-``mobile.example.com``, you use this:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/MainController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class MainController extends AbstractController
-        {
-            /**
-             * @Route(
-             *     "/",
-             *     name="mobile_homepage",
-             *     host="{subdomain}.example.com",
-             *     defaults={"subdomain"="m"},
-             *     requirements={"subdomain"="m|mobile"}
-             * )
-             */
-            public function mobileHomepage()
-            {
-                // ...
-            }
-
-            /**
-             * @Route("/", name="homepage")
-             */
-            public function homepage()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        mobile_homepage:
-            path:       /
-            host:       "{subdomain}.example.com"
-            controller: App\Controller\MainController::mobileHomepage
-            defaults:
-                subdomain: m
-            requirements:
-                subdomain: m|mobile
-
-        homepage:
-            path:       /
-            controller: App\Controller\MainController::homepage
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="mobile_homepage" path="/" host="{subdomain}.example.com">
-                <default key="_controller">App\Controller\MainController::mobileHomepage</default>
-                <default key="subdomain">m</default>
-                <requirement key="subdomain">m|mobile</requirement>
-            </route>
-
-            <route id="homepage" path="/">
-                <default key="_controller">App\Controller\MainController::homepage</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('mobile_homepage', new Route('/', [
-            '_controller' => 'App\Controller\MainController::mobileHomepage',
-            'subdomain'   => 'm',
-        ], [
-            'subdomain' => 'm|mobile',
-        ], [], '{subdomain}.example.com'));
-
-        $routes->add('homepage', new Route('/', [
-            '_controller' => 'App\Controller\MainController::homepage',
-        ]));
-
-        return $routes;
-
-.. tip::
-
-    You can also use service parameters if you do not want to hardcode the
-    hostname:
-
-    .. configuration-block::
-
-        .. code-block:: php-annotations
-
-            // src/Controller/MainController.php
-            namespace App\Controller;
-
-            use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-            use Symfony\Component\Routing\Annotation\Route;
-
-            class MainController extends AbstractController
-            {
-                /**
-                 * @Route(
-                 *     "/",
-                 *     name="mobile_homepage",
-                 *     host="m.{domain}",
-                 *     defaults={"domain"="%domain%"},
-                 *     requirements={"domain"="%domain%"}
-                 * )
-                 */
-                public function mobileHomepage()
-                {
-                    // ...
-                }
-
-                /**
-                 * @Route("/", name="homepage")
-                 */
-                public function homepage()
-                {
-                    // ...
-                }
-            }
-
-        .. code-block:: yaml
-
-            # config/routes.yaml
-            mobile_homepage:
-                path:       /
-                host:       "m.{domain}"
-                controller: App\Controller\MainController::mobileHomepage
-                defaults:
-                    domain: '%domain%'
-                requirements:
-                    domain: '%domain%'
-
-            homepage:
-                path:       /
-                controller: App\Controller\MainController::homepage
-
-        .. code-block:: xml
-
-            <!-- config/routes.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <routes xmlns="http://symfony.com/schema/routing"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/routing
-                    http://symfony.com/schema/routing/routing-1.0.xsd">
-
-                <route id="mobile_homepage" path="/" host="m.{domain}">
-                    <default key="_controller">App\Controller\MainController::mobileHomepage</default>
-                    <default key="domain">%domain%</default>
-                    <requirement key="domain">%domain%</requirement>
-                </route>
-
-                <route id="homepage" path="/">
-                    <default key="_controller">App\Controller\MainController::homepage</default>
-                </route>
-            </routes>
-
-        .. code-block:: php
-
-            // config/routes.php
-            use Symfony\Component\Routing\RouteCollection;
-            use Symfony\Component\Routing\Route;
-
-            $routes = new RouteCollection();
-            $routes->add('mobile_homepage', new Route('/', [
-                '_controller' => 'App\Controller\MainController::mobileHomepage',
-                'domain' => '%domain%',
-            ], [
-                'domain' => '%domain%',
-            ], [], 'm.{domain}'));
-
-            $routes->add('homepage', new Route('/', [
-                '_controller' => 'App\Controller\MainController::homepage',
-            ]));
-
-            return $routes;
-
-.. tip::
-
-    Make sure you also include a default option for the ``domain`` placeholder,
-    otherwise you need to include a domain value each time you generate
-    a URL using the route.
-
-.. _component-routing-host-imported:
-
-Using Host Matching of Imported Routes
---------------------------------------
-
-You can also set the host option on imported routes:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/MainController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        /**
-         * @Route(host="hello.example.com")
-         */
-        class MainController extends AbstractController
-        {
-            // ...
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        app_hello:
-            resource: '@ThirdPartyBundle/Resources/config/routing.yaml'
-            host:     "hello.example.com"
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <import resource="@ThirdPartyBundle/Resources/config/routing.xml" host="hello.example.com" />
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        $routes = $loader->import("@ThirdPartyBundle/Resources/config/routing.php");
-        $routes->setHost('hello.example.com');
-
-        return $routes;
-
-The host ``hello.example.com`` will be set on each route loaded from the new
-routing resource.
-
-Testing your Controllers
-------------------------
-
-You need to set the Host HTTP header on your request objects if you want to get
-past url matching in your functional tests::
-
-    $crawler = $client->request(
-        'GET',
-        '/homepage',
-        [],
-        [],
-        ['HTTP_HOST' => 'm.' . $client->getContainer()->getParameter('domain')]
-    );
diff --git a/routing/optional_placeholders.rst b/routing/optional_placeholders.rst
deleted file mode 100644
index 76f3d4e245f..00000000000
--- a/routing/optional_placeholders.rst
+++ /dev/null
@@ -1,205 +0,0 @@
-.. index::
-    single: Routing; Optional Placeholders
-
-How to Define Optional Placeholders
-===================================
-
-To make things more exciting, add a new route that displays a list of all
-the available blog posts for this imaginary blog application:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/BlogController.php
-
-        // ...
-        class BlogController extends AbstractController
-        {
-            // ...
-
-            /**
-             * @Route("/blog")
-             */
-            public function index()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        blog:
-            path:       /blog
-            controller: App\Controller\BlogController::index
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="blog" path="/blog">
-                <default key="_controller">App\Controller\BlogController::index</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('blog', new Route('/blog', [
-            '_controller' => 'App\Controller\BlogController::index',
-        ]));
-
-        return $routes;
-
-So far, this route is as simple as possible - it contains no placeholders
-and will only match the exact URL ``/blog``. But what if you need this route
-to support pagination, where ``/blog/2`` displays the second page of blog
-entries? Update the route to have a new ``{page}`` placeholder:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/BlogController.php
-
-        // ...
-
-        /**
-         * @Route("/blog/{page}")
-         */
-        public function index($page)
-        {
-            // ...
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        blog:
-            path:       /blog/{page}
-            controller: App\Controller\BlogController::index
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="blog" path="/blog/{page}">
-                <default key="_controller">App\Controller\BlogController::index</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('blog', new Route('/blog/{page}', [
-            '_controller' => 'App\Controller\BlogController::index',
-        ]));
-
-        return $routes;
-
-Like the ``{slug}`` placeholder before, the value matching ``{page}`` will
-be available inside your controller. Its value can be used to determine which
-set of blog posts to display for the given page.
-
-But hold on! Since placeholders are required by default, this route will
-no longer match on simply ``/blog``. Instead, to see page 1 of the blog,
-you'd need to use the URL ``/blog/1``! Since that's no way for a rich web
-app to behave, modify the route to make the ``{page}`` parameter optional.
-This is done by including it in the ``defaults`` collection:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/BlogController.php
-
-        // ...
-
-        /**
-         * @Route("/blog/{page}", defaults={"page"=1})
-         */
-        public function index($page)
-        {
-            // ...
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        blog:
-            path:       /blog/{page}
-            controller: App\Controller\BlogController::index
-            defaults:   { page: 1 }
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="blog" path="/blog/{page}">
-                <default key="_controller">App\Controller\BlogController::index</default>
-                <default key="page">1</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('blog', new Route('/blog/{page}', [
-            '_controller' => 'App\Controller\BlogController::index',
-            'page'        => 1,
-        ]));
-
-        return $routes;
-
-By adding ``page`` to the ``defaults`` key, the ``{page}`` placeholder is
-no longer required. The URL ``/blog`` will match this route and the value
-of the ``page`` parameter will be set to ``1``. The URL ``/blog/2`` will
-also match, giving the ``page`` parameter a value of ``2``. Perfect.
-
-===========  ========  ==================
-URL          Route     Parameters
-===========  ========  ==================
-``/blog``    ``blog``  ``{page}`` = ``1``
-``/blog/1``  ``blog``  ``{page}`` = ``1``
-``/blog/2``  ``blog``  ``{page}`` = ``2``
-===========  ========  ==================
-
-.. caution::
-
-    You can have more than one optional placeholder (e.g. ``/blog/{slug}/{page}``),
-    but everything after an optional placeholder must be optional. For example,
-    ``/{page}/blog`` is a valid path, but ``page`` will always be required
-    (i.e. simply ``/blog`` will not match this route).
-
-.. tip::
-
-    Routes with optional parameters at the end will not match on requests
-    with a trailing slash (i.e. ``/blog/`` will not match, ``/blog`` will match).
diff --git a/routing/redirect_in_config.rst b/routing/redirect_in_config.rst
deleted file mode 100644
index 1d50120b7d0..00000000000
--- a/routing/redirect_in_config.rst
+++ /dev/null
@@ -1,268 +0,0 @@
-.. index::
-   single: Routing; Redirect using Framework:RedirectController
-
-How to Configure a Redirect without a custom Controller
-=======================================================
-
-Sometimes, a URL needs to redirect to another URL. You can do that by creating
-a new controller action whose only task is to redirect, but using the
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController` of
-the FrameworkBundle is even easier.
-
-You can redirect to a specific path (e.g. ``/about``) or to a specific route
-using its name (e.g. ``homepage``).
-
-Redirecting Using a Path
-------------------------
-
-Assume there is no default controller for the ``/`` path of your application
-and you want to redirect these requests to ``/app``. You will need to use the
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirectAction`
-action to redirect to this new url:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-
-        # load some routes - one should ultimately have the path "/app"
-        controllers:
-            resource: ../src/Controller/
-            type:     annotation
-            prefix:   /app
-
-        # redirecting the homepage
-        homepage:
-            path: /
-            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction
-            defaults:
-                path: /app
-                permanent: true
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <!-- load some routes - one should ultimately have the path "/app" -->
-            <import resource="../src/Controller/"
-                type="annotation"
-                prefix="/app"
-            />
-
-            <!-- redirecting the homepage -->
-            <route id="homepage" path="/">
-                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction</default>
-                <default key="path">/app</default>
-                <default key="permanent">true</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-
-        // load some routes - one should ultimately have the path "/app"
-        $appRoutes = $loader->import("../src/Controller/", "annotation");
-        $appRoutes->setPrefix('/app');
-
-        $routes->addCollection($appRoutes);
-
-        // redirecting the homepage
-        $routes->add('homepage', new Route('/', [
-            '_controller' => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
-            'path'        => '/app',
-            'permanent'   => true,
-        ]));
-
-        return $routes;
-
-In this example, you configured a route for the ``/`` path and let the
-``RedirectController`` redirect it to ``/app``. The ``permanent`` switch
-tells the action to issue a ``301`` HTTP status code instead of the default
-``302`` HTTP status code.
-
-Redirecting Using a Route
--------------------------
-
-Assume you are migrating your website from WordPress to Symfony, you want to
-redirect ``/wp-admin`` to the route ``sonata_admin_dashboard``. You don't know
-the path, only the route name. This can be achieved using the
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirectAction`
-action:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-
-        # ...
-
-        admin:
-            path: /wp-admin
-            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
-            defaults:
-                route: sonata_admin_dashboard
-                # make a permanent redirection...
-                permanent: true
-                # ...and keep the original query string parameters
-                keepQueryParams: true
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <!-- ... -->
-
-            <route id="admin" path="/wp-admin">
-                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction</default>
-                <default key="route">sonata_admin_dashboard</default>
-                <!-- make a permanent redirection... -->
-                <default key="permanent">true</default>
-                <!-- ...and keep the original query string parameters -->
-                <default key="keepQueryParams">true</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        // ...
-
-        $routes->add('admin', new Route('/wp-admin', [
-            '_controller' => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction',
-            'route'       => 'sonata_admin_dashboard',
-            // make a permanent redirection...
-            'permanent'   => true,
-            // ...and keep the original query string parameters
-            'keepQueryParams' => true,
-        ]));
-
-        return $routes;
-
-.. versionadded:: 4.1
-    The ``keepQueryParams`` option was introduced in Symfony 4.1.
-
-.. caution::
-
-    Because you are redirecting to a route instead of a path, the required
-    option is called ``route`` in the ``redirect()`` action, instead of ``path``
-    in the ``urlRedirect()`` action.
-
-Keeping the Request Method when Redirecting
--------------------------------------------
-
-.. versionadded:: 4.1
-    The feature to keep the request method when redirecting was introduced in
-    Symfony 4.1.
-
-The redirections performed in the previous examples use the ``301`` and ``302``
-HTTP status codes. For legacy reasons, these HTTP redirections change the method
-of ``POST`` requests to ``GET`` (because redirecting a ``POST`` request didn't
-work well in old browsers).
-
-However, in some scenarios it's either expected or required that the redirection
-request uses the same HTTP method. That's why the HTTP standard defines two
-additional status codes (``307`` and ``308``) to perform temporary/permanent
-redirects that maintain the original request method.
-
-The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirectAction`
-and :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirectAction`
-methods accept an additional argument called ``keepRequestMethod``. When it's
-set to ``true``, temporary redirects use ``307`` code instead of ``302`` and
-permanent redirects use ``308`` code instead of ``301``:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-
-        # redirects with the 308 status code
-        route_foo:
-            # ...
-            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
-            defaults:
-                # ...
-                permanent: true
-                keepRequestMethod: true
-
-        # redirects with the 307 status code
-        route_bar:
-            # ...
-            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
-            defaults:
-                # ...
-                permanent: false
-                keepRequestMethod: true
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <!-- redirects with the 308 status code -->
-            <route id="route_foo" path="...">
-                <!-- ... -->
-                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction</default>
-                <default key="permanent">true</default>
-                <default key="keepRequestMethod">true</default>
-            </route>
-
-            <!-- redirects with the 307 status code -->
-            <route id="route_bar" path="...">
-                <!-- ... -->
-                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction</default>
-                <default key="permanent">false</default>
-                <default key="keepRequestMethod">true</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $collection = new RouteCollection();
-
-        // redirects with the 308 status code
-        $collection->add('route_foo', new Route('...', [
-            // ...
-            '_controller'       => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
-            'permanent'         => true,
-            'keepRequestMethod' => true,
-        ]));
-
-        // redirects with the 307 status code
-        $collection->add('route_bar', new Route('...', [
-            // ...
-            '_controller'       => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
-            'permanent'         => false,
-            'keepRequestMethod' => true,
-        ]));
-
-        return $collection;
diff --git a/routing/redirect_trailing_slash.rst b/routing/redirect_trailing_slash.rst
deleted file mode 100644
index 9f17a8c0b07..00000000000
--- a/routing/redirect_trailing_slash.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. index::
-    single: Routing; Redirect URLs with a trailing slash
-
-Redirect URLs with a Trailing Slash
-===================================
-
-.. caution::
-
-    In Symfony 4.1 the automatic URL redirection was improved as explained in
-    :ref:`routing-trailing-slash-redirection`. That's why you no longer need to
-    do that redirection yourself and this article has been removed because it's
-    no longer needed.
diff --git a/routing/requirements.rst b/routing/requirements.rst
deleted file mode 100644
index 1c6df7c77ba..00000000000
--- a/routing/requirements.rst
+++ /dev/null
@@ -1,295 +0,0 @@
-.. index::
-    single: Routing; Requirements
-
-How to Define Route Requirements
-================================
-
-:ref:`Route requirements <routing-requirements>` can be used to make a specific route
-*only* match under specific conditions. The simplest example involves restricting
-a routing ``{wildcard}`` to only match some regular expression:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/BlogController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class BlogController extends AbstractController
-        {
-            /**
-             * @Route("/blog/{page}", name="blog_list", requirements={"page"="\d+"})
-             */
-            public function list($page)
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        blog_list:
-            path:      /blog/{page}
-            controller: App\Controller\BlogController::list
-            requirements:
-                page: '\d+'
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="blog_list" path="/blog/{page}">
-                <default key="_controller">App\Controller\BlogController::list</default>
-                <requirement key="page">\d+</requirement>
-            </route>
-
-            <!-- ... -->
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('blog_list', new Route('/blog/{page}', [
-            '_controller' => 'App\Controller\BlogController::list',
-        ], [
-            'page' => '\d+',
-        ]));
-
-        // ...
-
-        return $routes;
-
-Thanks to the ``\d+`` requirement (i.e. a "digit" of any length), ``/blog/2`` will
-match this route but ``/blog/some-string`` will *not* match.
-
-.. sidebar:: Earlier Routes Always Win
-
-    Why would you ever care about requirements? If a request matches *two* routes,
-    then the first route always wins. By adding requirements to the first route,
-    you can make each route match in just the right situations. See :ref:`routing-requirements`
-    for an example.
-
-Since the parameter requirements are regular expressions, the complexity
-and flexibility of each requirement is entirely up to you. Suppose the homepage
-of your application is available in two different languages, based on the
-URL:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/MainController.php
-
-        // ...
-        class MainController extends AbstractController
-        {
-            /**
-             * @Route("/{_locale}", defaults={"_locale"="en"}, requirements={
-             *     "_locale"="en|fr"
-             * })
-             */
-            public function homepage($_locale)
-            {
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        homepage:
-            path:       /{_locale}
-            controller: App\Controller\MainController::homepage
-            defaults:   { _locale: en }
-            requirements:
-                _locale:  en|fr
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="homepage" path="/{_locale}">
-                <default key="_controller">App\Controller\MainController::homepage</default>
-                <default key="_locale">en</default>
-                <requirement key="_locale">en|fr</requirement>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('homepage', new Route('/{_locale}', [
-            '_controller' => 'App\Controller\MainController::homepage',
-            '_locale'     => 'en',
-        ], [
-            '_locale' => 'en|fr',
-        ]));
-
-        return $routes;
-
-For incoming requests, the ``{_locale}`` portion of the URL is matched against
-the regular expression ``(en|fr)``.
-
-=======  ========================
-Path     Parameters
-=======  ========================
-``/``    ``{_locale}`` = ``"en"``
-``/en``  ``{_locale}`` = ``"en"``
-``/fr``  ``{_locale}`` = ``"fr"``
-``/es``  *won't match this route*
-=======  ========================
-
-.. note::
-
-    You can enable UTF-8 route matching by setting the ``utf8`` option when
-    declaring or importing routes. This will make e.g. a ``.`` in requirements
-    match any UTF-8 characters instead of just a single byte.
-
-.. tip::
-
-    The route requirements can also include container parameters, as explained
-    in :doc:`this article </routing/service_container_parameters>`.
-    This comes in handy when the regular expression is very complex and used
-    repeatedly in your application.
-
-.. index::
-    single: Routing; Method requirement
-
-.. _routing-method-requirement:
-
-Adding HTTP Method Requirements
--------------------------------
-
-In addition to the URL, you can also match on the *method* of the incoming
-request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you create an API for
-your blog and you have 2 routes: One for displaying a post (on a GET or HEAD
-request) and one for updating a post (on a PUT request). This can be
-accomplished with the following route configuration:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/BlogApiController.php
-        namespace App\Controller;
-
-        // ...
-
-        class BlogApiController extends AbstractController
-        {
-            /**
-             * @Route("/api/posts/{id}", methods={"GET","HEAD"})
-             */
-            public function show($id)
-            {
-                // ... return a JSON response with the post
-            }
-
-            /**
-             * @Route("/api/posts/{id}", methods={"PUT"})
-             */
-            public function edit($id)
-            {
-                // ... edit a post
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        api_post_show:
-            path:       /api/posts/{id}
-            controller: App\Controller\BlogApiController::show
-            methods:    [GET, HEAD]
-
-        api_post_edit:
-            path:       /api/posts/{id}
-            controller: App\Controller\BlogApiController::edit
-            methods:    [PUT]
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="api_post_show" path="/api/posts/{id}" methods="GET|HEAD">
-                <default key="_controller">App\Controller\BlogApiController::show</default>
-            </route>
-
-            <route id="api_post_edit" path="/api/posts/{id}" methods="PUT">
-                <default key="_controller">App\Controller\BlogApiController::edit</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('api_post_show', new Route('/api/posts/{id}', [
-            '_controller' => 'App\Controller\BlogApiController::show',
-        ], [], [], '', [], ['GET', 'HEAD']));
-
-        $routes->add('api_post_edit', new Route('/api/posts/{id}', [
-            '_controller' => 'App\Controller\BlogApiController::edit',
-        ], [], [], '', [], ['PUT']));
-
-        return $routes;
-
-Despite the fact that these two routes have identical paths
-(``/api/posts/{id}``), the first route will match only GET or HEAD requests and
-the second route will match only PUT requests. This means that you can display
-and edit the post with the same URL, while using distinct controllers for the
-two actions.
-
-.. note::
-
-    If no ``methods`` are specified, the route will match on *all* methods.
-
-.. tip::
-
-    If you're using HTML forms and HTTP methods *other* than ``GET`` and ``POST``,
-    you'll need to include a ``_method`` parameter to *fake* the HTTP method. See
-    :doc:`/form/action_method` for more information.
-
-Adding a Host Requirement
--------------------------
-
-You can also match on the HTTP *host* of the incoming request. For more
-information, see :doc:`/routing/hostname_pattern` in the Routing
-component documentation.
-
-Adding Dynamic Requirements with Expressions
---------------------------------------------
-
-For really complex requirements, you can use dynamic expressions to match *any*
-information on the request. See :doc:`/routing/conditions`.
-
-.. _`PCRE Unicode property`: http://php.net/manual/en/regexp.reference.unicode.php
diff --git a/routing/routing_from_database.rst b/routing/routing_from_database.rst
index b39960ad79e..01281de39a8 100644
--- a/routing/routing_from_database.rst
+++ b/routing/routing_from_database.rst
@@ -24,7 +24,7 @@ When all routes are known during deploy time and the number is not too
 high, using a :doc:`custom route loader <custom_route_loader>` is the
 preferred way to add more routes. When working with just one type of
 objects, a slug parameter on the object and the ``@ParamConverter``
-annotation work fine (see FrameworkExtraBundle_) .
+annotation work fine (see `FrameworkExtraBundle`_) .
 
 The ``DynamicRouter`` is useful when you need ``Route`` objects with
 the full feature set of Symfony. Each route can define a specific
diff --git a/routing/scheme.rst b/routing/scheme.rst
deleted file mode 100644
index d2519e895a3..00000000000
--- a/routing/scheme.rst
+++ /dev/null
@@ -1,96 +0,0 @@
-.. index::
-   single: Routing; Scheme requirement
-
-How to Force Routes to Always Use HTTPS or HTTP
-===============================================
-
-Sometimes, you want to secure some routes and be sure that they are always
-accessed via the HTTPS protocol. The Routing component allows you to enforce
-the URI scheme via schemes:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        // src/Controller/MainController.php
-        namespace App\Controller;
-
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class MainController extends AbstractController
-        {
-            /**
-             * @Route("/secure", name="secure", schemes={"https"})
-             */
-            public function secure()
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        secure:
-            path:       /secure
-            controller: App\Controller\MainController::secure
-            schemes:    [https]
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="secure" path="/secure" schemes="https">
-                <default key="_controller">App\Controller\MainController::secure</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('secure', new Route('/secure', [
-            '_controller' => 'App\Controller\MainController::secure',
-        ], [], [], '', ['https']));
-
-        return $routes;
-
-The above configuration forces the ``secure`` route to always use HTTPS.
-
-When generating the ``secure`` URL, and if the current scheme is HTTP, Symfony
-will automatically generate an absolute URL with HTTPS as the scheme, even when
-using the ``path()`` function:
-
-.. code-block:: twig
-
-    {# If the current scheme is HTTPS #}
-    {{ path('secure') }}
-    {# generates a relative URL: /secure #}
-
-    {# If the current scheme is HTTP #}
-    {{ path('secure') }}
-    {# generates an absolute URL: https://example.com/secure #}
-
-The requirement is also enforced for incoming requests. If you try to access
-the ``/secure`` path with HTTP, you will automatically be redirected to the
-same URL, but with the HTTPS scheme.
-
-The above example uses ``https`` for the scheme, but you can also force a URL
-to always use ``http``.
-
-.. note::
-
-    The Security component provides another way to enforce HTTP or HTTPS via
-    the ``requires_channel`` setting. This alternative method is better suited
-    to secure an "area" of your website (all URLs under ``/admin``) or when
-    you want to secure URLs defined in a third party bundle (see
-    :doc:`/security/force_https` for more details).
diff --git a/routing/service_container_parameters.rst b/routing/service_container_parameters.rst
deleted file mode 100644
index 35e248232e7..00000000000
--- a/routing/service_container_parameters.rst
+++ /dev/null
@@ -1,140 +0,0 @@
-.. index::
-   single: Routing; Service Container Parameters
-
-How to Use Service Container Parameters in your Routes
-======================================================
-
-Sometimes you may find it useful to make some parts of your routes
-globally configurable. For instance, if you build an internationalized
-site, you'll probably start with one or two locales. Surely you'll
-add a requirement to your routes to prevent a user from matching a locale
-other than the locales you support.
-
-You *could* hardcode your ``_locale`` requirement in all your routes, but
-a better solution is to use a configurable service container parameter right
-inside your routing configuration:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        contact:
-            path:       /{_locale}/contact
-            controller: App\Controller\MainController::contact
-            requirements:
-                _locale: '%app.locales%'
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="contact" path="/{_locale}/contact">
-                <default key="_controller">App\Controller\MainController::contact</default>
-                <requirement key="_locale">%app.locales%</requirement>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('contact', new Route('/{_locale}/contact', [
-            '_controller' => 'App\Controller\MainController::contact',
-        ), [
-            '_locale' => '%app.locales%',
-        ]));
-
-        return $routes;
-
-You can now control and set the  ``app.locales`` parameter somewhere
-in your container:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            app.locales: en|es
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" charset="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="app.locales">en|es</parameter>
-            </parameters>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('app.locales', 'en|es');
-
-You can also use a parameter to define your route path (or part of your
-path):
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        some_route:
-            path:       /%app.route_prefix%/contact
-            controller: App\Controller\MainController::contact
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="some_route" path="/%app.route_prefix%/contact">
-                <default key="_controller">App\Controller\MainController::contact</default>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('some_route', new Route('/%app.route_prefix%/contact', [
-            '_controller' => 'App\Controller\MainController::contact',
-        ]));
-
-        return $routes;
-
-.. note::
-
-    Just like in normal service container configuration files, if you actually
-    need a ``%`` in your route, you can escape the percent sign by doubling
-    it, e.g. ``/score-50%%``, which would resolve to ``/score-50%``.
-
-    However, as the ``%`` characters included in any URL are automatically encoded,
-    the resulting URL of this example would be ``/score-50%25`` (``%25`` is the
-    result of encoding the ``%`` character).
-
-.. seealso::
-
-    For parameter handling within a Dependency Injection Class see
-    :doc:`/configuration/using_parameters_in_dic`.
diff --git a/routing/slash_in_parameter.rst b/routing/slash_in_parameter.rst
deleted file mode 100644
index c0a1cc99bec..00000000000
--- a/routing/slash_in_parameter.rst
+++ /dev/null
@@ -1,98 +0,0 @@
-.. index::
-   single: Routing; Allow / in route parameter
-
-How to Allow a "/" Character in a Route Parameter
-=================================================
-
-Sometimes, you need to compose URLs with parameters that can contain a slash
-``/``. For example, consider the ``/share/{token}`` route. If the ``token``
-value contains a ``/`` character this route won't match. This is because Symfony
-uses this character as separator between route parts.
-
-This article explains how you can modify a route definition so that placeholders
-can contain the ``/`` character too.
-
-Configure the Route
--------------------
-
-By default, the Symfony Routing component requires that the parameters match
-the following regular expression: ``[^/]+``. This means that all characters are
-allowed except ``/``.
-
-You must explicitly allow ``/`` to be part of your placeholder by specifying
-a more permissive regular expression for it:
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
-
-        use Symfony\Component\Routing\Annotation\Route;
-
-        class DefaultController
-        {
-            /**
-             * @Route("/share/{token}", name="share", requirements={"token"=".+"})
-             */
-            public function share($token)
-            {
-                // ...
-            }
-        }
-
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        share:
-            path:       /share/{token}
-            controller: App\Controller\DefaultController::share
-            requirements:
-                token: .+
-
-    .. code-block:: xml
-
-        <!-- config/routes.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <routes xmlns="http://symfony.com/schema/routing"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
-
-            <route id="share" path="/share/{token}">
-                <default key="_controller">App\Controller\DefaultController::share</default>
-                <requirement key="token">.+</requirement>
-            </route>
-        </routes>
-
-    .. code-block:: php
-
-        // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('share', new Route('/share/{token}', [
-            '_controller' => 'App\Controller\DefaultController::share',
-        ], [
-            'token' => '.+',
-        ]));
-
-        return $routes;
-
-That's it! Now, the ``{token}`` parameter can contain the ``/`` character.
-
-.. note::
-
-    If the route includes the special ``{_format}`` placeholder, you shouldn't
-    use the ``.+`` requirement for the parameters that allow slashes. For example,
-    if the pattern is ``/share/{token}.{_format}`` and ``{token}`` allows any
-    character, the ``/share/foo/bar.json`` URL will consider ``foo/bar.json``
-    as the token and the format will be empty. This can be solved replacing the
-    ``.+`` requirement by ``[^.]+`` to allow any character except dots.
-
-.. note::
-
-    If the route defines several placeholders and you apply this permissive
-    regular expression to all of them, the results won't be the expected. For
-    example, if the route definition is ``/share/{path}/{token}`` and both
-    ``path`` and ``token`` accept ``/``, then ``path`` will contain its contents
-    and the token, and ``token`` will be empty.
diff --git a/security.rst b/security.rst
index f871624fd9d..ad20d0df512 100644
--- a/security.rst
+++ b/security.rst
@@ -30,7 +30,7 @@ A few other important topics are discussed after.
 1) Installation
 ---------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the security feature before using it:
 
 .. code-block:: terminal
@@ -109,7 +109,7 @@ here: :doc:`User Providers </security/user_provider>`.
 2c) Encoding Passwords
 ----------------------
 
-Not all apps have "users" that need passwords. *If* your users have passwords,
+Not all applications have "users" that need passwords. *If* your users have passwords,
 you can control how those passwords are encoded in ``security.yaml``. The ``make:user``
 command will pre-configure this for you:
 
@@ -124,10 +124,9 @@ command will pre-configure this for you:
             encoders:
                 # use your user class name here
                 App\Entity\User:
-                    # bcrypt or argon2i are recommended
-                    # argon2i is more secure, but requires PHP 7.2 or the Sodium extension
-                    algorithm: bcrypt
-                    cost: 12
+                    # Use native password encoder
+                    # This value auto-selects the best possible hashing algorithm.
+                    algorithm: auto
 
     .. code-block:: xml
 
@@ -137,14 +136,14 @@ command will pre-configure this for you:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <encoder class="App\Entity\User"
                     algorithm="bcrypt"
-                    cost="12" />
+                    cost="12"/>
 
                 <!-- ... -->
             </config>
@@ -249,15 +248,15 @@ important section is ``firewalls``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="dev"
                     pattern="^/(_(profiler|wdt)|css|images|js)/"
-                    security="false" />
+                    security="false"/>
 
                 <firewall name="main">
-                    <anonymous />
+                    <anonymous/>
                 </firewall>
             </config>
         </srv:container>
@@ -408,8 +407,7 @@ Add Code to Deny Access
 There are **two** ways to deny access to something:
 
 #. :ref:`access_control in security.yaml <security-authorization-access-control>`
-   allows you to protect URL patterns (e.g. ``/admin/*``). This is easy,
-   but less flexible;
+   allows you to protect URL patterns (e.g. ``/admin/*``). Simpler, but less flexible;
 
 #. :ref:`in your controller (or other code) <security-securing-controller>`.
 
@@ -447,7 +445,7 @@ start with ``/admin``, you can:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -457,7 +455,7 @@ start with ``/admin``, you can:
                 </firewall>
 
                 <!-- require ROLE_ADMIN for /admin* -->
-                <rule path="^/admin" role="ROLE_ADMIN" />
+                <rule path="^/admin" role="ROLE_ADMIN"/>
             </config>
         </srv:container>
 
@@ -473,10 +471,10 @@ start with ``/admin``, you can:
                     // ...
                 ],
             ],
-           'access_control' => [
-               // require ROLE_ADMIN for /admin*
-               ['path' => '^/admin', 'role' => 'ROLE_ADMIN'],
-           ],
+            'access_control' => [
+                // require ROLE_ADMIN for /admin*
+                ['path' => '^/admin', 'role' => 'ROLE_ADMIN'],
+            ],
         ]);
 
 You can define as many URL patterns as you need - each is a regular expression.
@@ -506,13 +504,13 @@ the list and stops when it finds the first match:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
-                <rule path="^/admin/users" role="ROLE_SUPER_ADMIN" />
-                <rule path="^/admin" role="ROLE_ADMIN" />
+                <rule path="^/admin/users" role="ROLE_SUPER_ADMIN"/>
+                <rule path="^/admin" role="ROLE_ADMIN"/>
             </config>
         </srv:container>
 
@@ -529,8 +527,8 @@ the list and stops when it finds the first match:
         ]);
 
 Prepending the path with ``^`` means that only URLs *beginning* with the
-pattern are matched. For example, a path of simply ``/admin`` (without
-the ``^``) would match ``/admin/foo`` but would also match URLs like ``/foo/admin``.
+pattern are matched. For example, a path of ``/admin`` (without the ``^``)
+would match ``/admin/foo`` but would also match URLs like ``/foo/admin``.
 
 Each ``access_control`` can also match on IP address, hostname and HTTP methods.
 It can also be used to redirect a user to the ``https`` version of a URL pattern.
@@ -603,8 +601,8 @@ For more information, see the `FrameworkExtraBundle documentation`_.
 Access Control in Templates
 ...........................
 
-If you want to check if the current access inside a template, use
-the built-in ``is_granted()`` helper function:
+If you want to check if the current user has a certain role, you can use
+the built-in ``is_granted()`` helper function in any Twig template:
 
 .. code-block:: html+twig
 
@@ -620,7 +618,7 @@ See :doc:`/security/securing_services`.
 Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you *only* want to check if a user is simply logged in (you don't care about roles),
+If you *only* want to check if a user is logged in (you don't care about roles),
 you have two options. First, if you've given *every* user ``ROLE_USER``, you can
 just check for that role. Otherwise, you can use a special "attribute" in place
 of a role::
@@ -634,8 +632,8 @@ of a role::
         // ...
     }
 
-You can use ``IS_AUTHENTICATED_FULLY`` anywhere roles are used: like ``access_control``
-or in Twig.
+You can use ``IS_AUTHENTICATED_FULLY`` anywhere roles are used: like
+``access_control`` or in Twig.
 
 ``IS_AUTHENTICATED_FULLY`` isn't a role, but it kind of acts like one, and every
 user that has logged in will have this. Actually, there are 3 special attributes
@@ -766,14 +764,14 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="secured_area">
                     <!-- ... -->
-                    <logout path="app_logout" />
+                    <logout path="app_logout"/>
                 </firewall>
             </config>
         </srv:container>
@@ -796,12 +794,6 @@ Next, you'll need to create a route for this URL (but not a controller):
 
 .. configuration-block::
 
-    .. code-block:: yaml
-
-        # config/routes.yaml
-        app_logout:
-            path: /logout
-
     .. code-block:: php-annotations
 
         // src/Controller/SecurityController.php
@@ -813,7 +805,7 @@ Next, you'll need to create a route for this URL (but not a controller):
         class SecurityController extends AbstractController
         {
             /**
-             * @Route("/logout", name="app_logout")
+             * @Route("/logout", name="app_logout", methods={"GET"})
              */
             public function logout()
             {
@@ -822,6 +814,13 @@ Next, you'll need to create a route for this URL (but not a controller):
             }
         }
 
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        app_logout:
+            path: /logout
+            methods: GET
+
     .. code-block:: xml
 
         <!-- config/routes.xml -->
@@ -829,21 +828,21 @@ Next, you'll need to create a route for this URL (but not a controller):
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="app_logout" path="/logout" />
+            <route id="app_logout" path="/logout" methods="GET"/>
         </routes>
 
     ..  code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('app_logout', new Route('/logout'));
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('logout', '/logout')
+                ->methods(['GET'])
+            ;
+        };
 
 And that's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
 Symfony will un-authenticate the current user and redirect them.
@@ -882,7 +881,7 @@ rules by creating a role hierarchy:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -911,7 +910,8 @@ Users with the ``ROLE_ADMIN`` role will also have the
 ``ROLE_USER`` role. And users with ``ROLE_SUPER_ADMIN``, will automatically have
 ``ROLE_ADMIN``, ``ROLE_ALLOWED_TO_SWITCH`` and ``ROLE_USER`` (inherited from ``ROLE_ADMIN``).
 
-For role hierarchy to work, do not try to call ``$user->getRoles()`` manually::
+For role hierarchy to work, do not try to call ``$user->getRoles()`` manually.
+For example, in a controller extending from the :ref:`base controller <the-base-controller-class-services>`::
 
     // BAD - $user->getRoles() will not know about the role hierarchy
     $hasAccess = in_array('ROLE_ADMIN', $user->getRoles());
@@ -927,11 +927,6 @@ For role hierarchy to work, do not try to call ``$user->getRoles()`` manually::
     :doc:`security voter </security/voters>` that looks for the user roles
     in the database.
 
-Checking for Security Vulnerabilities in your Dependences
----------------------------------------------------------
-
-See :doc:`/security/security_checker`.
-
 Frequently Asked Questions
 --------------------------
 
@@ -962,8 +957,7 @@ Frequently Asked Questions
     To see if this is an issue, check your log file (``var/log/dev.log``) for
     the log message:
 
-    > Cannot refresh token because user has changed.
-
+**Cannot refresh token because user has changed**
     If you see this, there are two possible causes. First, there may be a problem
     loading your User from the session. See :ref:`user_session_refresh`. Second,
     if certain user information was changed in the database since the last page
@@ -1004,9 +998,8 @@ Authorization (Denying Access)
     security/access_denied_handler
     security/acl
     security/force_https
-    security/security_checker
 
-.. _`frameworkextrabundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
+.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle
 .. _`Symfony ACL bundle`: https://github.com/symfony/acl-bundle
 .. _`Symfony Security screencast series`: https://symfonycasts.com/screencast/symfony-security
diff --git a/security/access_control.rst b/security/access_control.rst
index cd2b1cc83e1..6ecbff460a6 100644
--- a/security/access_control.rst
+++ b/security/access_control.rst
@@ -26,6 +26,7 @@ options are used for matching:
 
 * ``path``
 * ``ip`` or ``ips`` (netmasks are also supported)
+* ``port``
 * ``host``
 * ``methods``
 
@@ -40,6 +41,7 @@ Take the following ``access_control`` entries as an example:
             # ...
             access_control:
                 - { path: ^/admin, roles: ROLE_USER_IP, ip: 127.0.0.1 }
+                - { path: ^/admin, roles: ROLE_USER_PORT, ip: 127.0.0.1, port: 8080 }
                 - { path: ^/admin, roles: ROLE_USER_HOST, host: symfony\.com$ }
                 - { path: ^/admin, roles: ROLE_USER_METHOD, methods: [POST, PUT] }
                 - { path: ^/admin, roles: ROLE_USER }
@@ -52,14 +54,15 @@ Take the following ``access_control`` entries as an example:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
-                <rule path="^/admin" role="ROLE_USER_IP" ip="127.0.0.1" />
-                <rule path="^/admin" role="ROLE_USER_HOST" host="symfony\.com$" />
-                <rule path="^/admin" role="ROLE_USER_METHOD" methods="POST, PUT" />
-                <rule path="^/admin" role="ROLE_USER" />
+                <rule path="^/admin" role="ROLE_USER_IP" ip="127.0.0.1"/>
+                <rule path="^/admin" role="ROLE_USER_PORT" ip="127.0.0.1" port="8080"/>
+                <rule path="^/admin" role="ROLE_USER_HOST" host="symfony\.com$"/>
+                <rule path="^/admin" role="ROLE_USER_METHOD" methods="POST, PUT"/>
+                <rule path="^/admin" role="ROLE_USER"/>
             </config>
         </srv:container>
 
@@ -74,6 +77,12 @@ Take the following ``access_control`` entries as an example:
                     'role' => 'ROLE_USER_IP',
                     'ip' => '127.0.0.1',
                 ],
+                [
+                    'path' => '^/admin',
+                    'role' => 'ROLE_USER_PORT',
+                    'ip' => '127.0.0.1',
+                    'port' => '8080',
+                ],
                 [
                     'path' => '^/admin',
                     'role' => 'ROLE_USER_HOST',
@@ -94,35 +103,37 @@ Take the following ``access_control`` entries as an example:
 For each incoming request, Symfony will decide which ``access_control``
 to use based on the URI, the client's IP address, the incoming host name,
 and the request method. Remember, the first rule that matches is used, and
-if ``ip``, ``host`` or ``method`` are not specified for an entry, that ``access_control``
-will match any ``ip``, ``host`` or ``method``:
-
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| URI             | IP          | HOST        | METHOD     | ``access_control``             | Why?                                                        |
-+=================+=============+=============+============+================================+=============================================================+
-| ``/admin/user`` | 127.0.0.1   | example.com | GET        | rule #1 (``ROLE_USER_IP``)     | The URI matches ``path`` and the IP matches ``ip``.         |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/admin/user`` | 127.0.0.1   | symfony.com | GET        | rule #1 (``ROLE_USER_IP``)     | The ``path`` and ``ip`` still match. This would also match  |
-|                 |             |             |            |                                | the ``ROLE_USER_HOST`` entry, but *only* the **first**      |
-|                 |             |             |            |                                | ``access_control`` match is used.                           |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/admin/user`` | 168.0.0.1   | symfony.com | GET        | rule #2 (``ROLE_USER_HOST``)   | The ``ip`` doesn't match the first rule, so the second      |
-|                 |             |             |            |                                | rule (which matches) is used.                               |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/admin/user`` | 168.0.0.1   | symfony.com | POST       | rule #2 (``ROLE_USER_HOST``)   | The second rule still matches. This would also match the    |
-|                 |             |             |            |                                | third rule (``ROLE_USER_METHOD``), but only the **first**   |
-|                 |             |             |            |                                | matched ``access_control`` is used.                         |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/admin/user`` | 168.0.0.1   | example.com | POST       | rule #3 (``ROLE_USER_METHOD``) | The ``ip`` and ``host`` don't match the first two entries,  |
-|                 |             |             |            |                                | but the third - ``ROLE_USER_METHOD`` - matches and is used. |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/admin/user`` | 168.0.0.1   | example.com | GET        | rule #4 (``ROLE_USER``)        | The ``ip``, ``host`` and ``method`` prevent the first       |
-|                 |             |             |            |                                | three entries from matching. But since the URI matches the  |
-|                 |             |             |            |                                | ``path`` pattern of the ``ROLE_USER`` entry, it is used.    |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/foo``        | 127.0.0.1   | symfony.com | POST       | matches no entries             | This doesn't match any ``access_control`` rules, since its  |
-|                 |             |             |            |                                | URI doesn't match any of the ``path`` values.               |
-+-----------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+if ``ip``, ``port``, ``host`` or ``method`` are not specified for an entry, that
+``access_control`` will match any ``ip``, ``port``, ``host`` or ``method``:
+
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| URI             | IP          | PORT        | HOST        | METHOD     | ``access_control``             | Why?                                                        |
++=================+=============+=============+=============+============+================================+=============================================================+
+| ``/admin/user`` | 127.0.0.1   | 80          | example.com | GET        | rule #1 (``ROLE_USER_IP``)     | The URI matches ``path`` and the IP matches ``ip``.         |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/admin/user`` | 127.0.0.1   | 80          | symfony.com | GET        | rule #1 (``ROLE_USER_IP``)     | The ``path`` and ``ip`` still match. This would also match  |
+|                 |             |             |             |            |                                | the ``ROLE_USER_HOST`` entry, but *only* the **first**      |
+|                 |             |             |             |            |                                | ``access_control`` match is used.                           |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/admin/user`` | 127.0.0.1   | 8080        | symfony.com | GET        | rule #2 (``ROLE_USER_PORT``)   | The ``path``, ``ip`` and ``port`` match.                    |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/admin/user`` | 168.0.0.1   | 80          | symfony.com | GET        | rule #3 (``ROLE_USER_HOST``)   | The ``ip`` doesn't match the first rule, so the second      |
+|                 |             |             |             |            |                                | rule (which matches) is used.                               |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/admin/user`` | 168.0.0.1   | 80          | symfony.com | POST       | rule #3 (``ROLE_USER_HOST``)   | The second rule still matches. This would also match the    |
+|                 |             |             |             |            |                                | third rule (``ROLE_USER_METHOD``), but only the **first**   |
+|                 |             |             |             |            |                                | matched ``access_control`` is used.                         |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/admin/user`` | 168.0.0.1   | 80          | example.com | POST       | rule #4 (``ROLE_USER_METHOD``) | The ``ip`` and ``host`` don't match the first two entries,  |
+|                 |             |             |             |            |                                | but the third - ``ROLE_USER_METHOD`` - matches and is used. |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/admin/user`` | 168.0.0.1   | 80          | example.com | GET        | rule #5 (``ROLE_USER``)        | The ``ip``, ``host`` and ``method`` prevent the first       |
+|                 |             |             |             |            |                                | three entries from matching. But since the URI matches the  |
+|                 |             |             |             |            |                                | ``path`` pattern of the ``ROLE_USER`` entry, it is used.    |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
+| ``/foo``        | 127.0.0.1   | 80          | symfony.com | POST       | matches no entries             | This doesn't match any ``access_control`` rules, since its  |
+|                 |             |             |             |            |                                | URI doesn't match any of the ``path`` values.               |
++-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
 
 .. _security-access-control-enforcement-options:
 
@@ -136,9 +147,7 @@ options:
 * ``roles`` If the user does not have the given role, then access is denied
   (internally, an :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
   is thrown). If this value is an array of multiple roles, the user must have
-  at least one of them (when using the default ``affirmative`` strategy in the
-  :ref:`Access Decision Manager <components-security-access-decision-manager>`)
-  or all of them when using the ``unanimous`` strategy;
+  at least one of them.
 
 * ``allow_if`` If the expression returns false, then access is denied;
 
@@ -193,7 +202,7 @@ pattern so that it is only accessible by requests from the local server itself:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -204,7 +213,7 @@ pattern so that it is only accessible by requests from the local server itself:
                     <ip>::1</ip>
                 </rule>
 
-                <rule path="^/internal" role="ROLE_NO_ACCESS" />
+                <rule path="^/internal" role="ROLE_NO_ACCESS"/>
             </config>
         </srv:container>
 
@@ -267,32 +276,37 @@ key:
             access_control:
                 -
                     path: ^/_internal/secure
-                    allow_if: "'127.0.0.1' == request.getClientIp() or has_role('ROLE_ADMIN')"
+                    allow_if: "'127.0.0.1' == request.getClientIp() or is_granted('ROLE_ADMIN')"
 
     .. code-block:: xml
 
-        <!-- app/config/security.xml -->
+        <!-- config/packages/security.xml -->
         <?xml version="1.0" encoding="UTF-8"?>
         <srv:container xmlns="http://symfony.com/schema/dic/security"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
+                <!-- ... -->
                 <rule path="^/_internal/secure"
-                    allow-if="'127.0.0.1' == request.getClientIp() or has_role('ROLE_ADMIN')" />
+                    allow-if="'127.0.0.1' == request.getClientIp() or is_granted('ROLE_ADMIN')"/>
             </config>
         </srv:container>
 
     .. code-block:: php
 
+        // config/packages/security.php
+        $container->loadFromExtension('security', [
+            // ...
             'access_control' => [
                 [
                     'path' => '^/_internal/secure',
-                    'allow_if' => '"127.0.0.1" == request.getClientIp() or has_role("ROLE_ADMIN")',
+                    'allow_if' => '"127.0.0.1" == request.getClientIp() or is_granted("ROLE_ADMIN")',
                 ],
             ],
+        ]);
 
 In this case, when the user tries to access any URL starting with ``/_internal/secure``,
 they will only be granted access if the IP address is ``127.0.0.1`` or if
@@ -311,9 +325,55 @@ For a list of the other functions and variables, see
     The ``allow_if`` expressions can also contain custom functions registered
     with :ref:`expression providers <components-expression-language-provider>`.
 
-    .. versionadded:: 4.1
-        The feature to use custom functions inside ``allow_if`` expressions was
-        introduced in Symfony 4.1.
+Restrict to a port
+------------------
+
+Add the ``port`` option to any ``access_control`` entries to require users to
+access those URLs via a specific port. This could be useful for example for
+``localhost:8080``.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+            access_control:
+                - { path: ^/cart/checkout, roles: IS_AUTHENTICATED_ANONYMOUSLY, port: 8080 }
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <rule path="^/cart/checkout"
+                    role="IS_AUTHENTICATED_ANONYMOUSLY"
+                    port="8080"
+                />
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        $container->loadFromExtension('security', [
+            // ...
+            'access_control' => [
+                [
+                    'path' => '^/cart/checkout',
+                    'role' => 'IS_AUTHENTICATED_ANONYMOUSLY',
+                    'port' => '8080',
+                ],
+            ],
+        ]);
 
 Forcing a Channel (http, https)
 -------------------------------
@@ -341,18 +401,22 @@ the user will be redirected to ``https``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
-            <rule path="^/cart/checkout"
-                role="IS_AUTHENTICATED_ANONYMOUSLY"
-                requires-channel="https"
-            />
+            <config>
+                <!-- ... -->
+                <rule path="^/cart/checkout"
+                    role="IS_AUTHENTICATED_ANONYMOUSLY"
+                    requires-channel="https"
+                />
+            </config>
         </srv:container>
 
     .. code-block:: php
 
         // config/packages/security.php
         $container->loadFromExtension('security', [
+            // ...
             'access_control' => [
                 [
                     'path' => '^/cart/checkout',
diff --git a/security/auth_providers.rst b/security/auth_providers.rst
index f307a320f51..f5ec3723c7b 100644
--- a/security/auth_providers.rst
+++ b/security/auth_providers.rst
@@ -57,13 +57,13 @@ To support HTTP Basic authentication, add the ``http_basic`` key to your firewal
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
-                    <http-basic realm="Secured Area" />
+                    <http-basic realm="Secured Area"/>
                 </firewall>
             </config>
         </srv:container>
@@ -123,14 +123,14 @@ Enable the x509 authentication for a particular firewall in the security configu
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <x509 provider="your_user_provider" />
+                    <x509 provider="your_user_provider"/>
                 </firewall>
             </config>
         </srv:container>
diff --git a/security/csrf.rst b/security/csrf.rst
index cb80169a2d4..620df0f887e 100644
--- a/security/csrf.rst
+++ b/security/csrf.rst
@@ -39,12 +39,12 @@ for more information):
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:csrf-protection enabled="true" />
+                <framework:csrf-protection enabled="true"/>
             </framework:config>
         </container>
 
@@ -108,22 +108,27 @@ this can be customized on a form-by-form basis::
         // ...
     }
 
+You can also customize the rendering of the CSRF form field creating a custom
+:doc:`form theme </form/form_themes>` and using ``csrf_token`` as the prefix of
+the field (e.g. define ``{% block csrf_token_widget %} ... {% endblock %}`` to
+customize the entire form field contents).
+
+.. versionadded:: 4.3
+
+    The ``csrf_token`` form field prefix was introduced in Symfony 4.3.
+
 CSRF Protection in Login Forms
 ------------------------------
 
 See :doc:`/security/form_login_setup` for a login form that is protected from
-CSRF attacks.
+CSRF attacks. You can also configure the
+:ref:`CSRF protection for the logout action <reference-security-logout-csrf>`.
 
 .. _csrf-protection-in-html-forms:
 
 Generating and Checking CSRF Tokens Manually
 --------------------------------------------
 
-.. versionadded:: 4.1
-
-    In Symfony versions prior to 4.1, CSRF support required installing the
-    Symfony Form component even if you didn't use it.
-
 Although Symfony Forms provide automatic CSRF protection by default, you may
 need to generate and check CSRF tokens manually for example when using regular
 HTML forms not managed by the Symfony Form component.
@@ -132,11 +137,11 @@ Consider a simple HTML form created to allow deleting items. First, use the
 :ref:`csrf_token() Twig function <reference-twig-function-csrf-token>` to
 generate a CSRF token in the template and store it as a hidden form field:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <form action="{{ url('admin_post_delete', { id: post.id }) }}" method="post">
         {# the argument of csrf_token() is an arbitrary string used to generate the token #}
-        <input type="hidden" name="token" value="{{ csrf_token('delete-item') }}" />
+        <input type="hidden" name="token" value="{{ csrf_token('delete-item') }}"/>
 
         <button type="submit">Delete item</button>
     </form>
diff --git a/security/custom_authentication_provider.rst b/security/custom_authentication_provider.rst
index 81902f7883f..1a0a78bf226 100644
--- a/security/custom_authentication_provider.rst
+++ b/security/custom_authentication_provider.rst
@@ -100,19 +100,19 @@ is responsible for fielding requests to the firewall and calling the authenticat
 provider. A listener must be an instance of
 :class:`Symfony\\Component\\Security\\Http\\Firewall\\ListenerInterface`.
 A security listener should handle the
-:class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent` event, and
+:class:`Symfony\\Component\\HttpKernel\\Event\\RequestEvent` event, and
 set an authenticated token in the token storage if successful::
 
     // src/Security/Firewall/WsseListener.php
     namespace App\Security\Firewall;
 
+    use App\Security\Authentication\Token\WsseUserToken;
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+    use Symfony\Component\HttpKernel\Event\RequestEvent;
     use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
     use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
     use Symfony\Component\Security\Http\Firewall\ListenerInterface;
-    use App\Security\Authentication\Token\WsseUserToken;
 
     class WsseListener implements ListenerInterface
     {
@@ -125,7 +125,7 @@ set an authenticated token in the token storage if successful::
             $this->authenticationManager = $authenticationManager;
         }
 
-        public function handle(GetResponseEvent $event)
+        public function handle(RequestEvent $event)
         {
             $request = $event->getRequest();
 
@@ -200,12 +200,13 @@ the ``PasswordDigest`` header value matches with the user's password::
     // src/Security/Authentication/Provider/WsseProvider.php
     namespace App\Security\Authentication\Provider;
 
+    use App\Security\Authentication\Token\WsseUserToken;
     use Psr\Cache\CacheItemPoolInterface;
     use Symfony\Component\Security\Core\Authentication\Provider\AuthenticationProviderInterface;
-    use Symfony\Component\Security\Core\User\UserProviderInterface;
-    use Symfony\Component\Security\Core\Exception\AuthenticationException;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
-    use App\Security\Authentication\Token\WsseUserToken;
+    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\NonceExpiredException;
+    use Symfony\Component\Security\Core\User\UserProviderInterface;
 
     class WsseProvider implements AuthenticationProviderInterface
     {
@@ -299,13 +300,13 @@ create a class which implements
     // src/DependencyInjection/Security/Factory/WsseFactory.php
     namespace App\DependencyInjection\Security\Factory;
 
+    use App\Security\Authentication\Provider\WsseProvider;
+    use App\Security\Firewall\WsseListener;
+    use Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\SecurityFactoryInterface;
+    use Symfony\Component\Config\Definition\Builder\NodeDefinition;
     use Symfony\Component\DependencyInjection\ChildDefinition;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Reference;
-    use Symfony\Component\Config\Definition\Builder\NodeDefinition;
-    use Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\SecurityFactoryInterface;
-    use App\Security\Authentication\Provider\WsseProvider;
-    use App\Security\Firewall\WsseListener;
 
     class WsseFactory implements SecurityFactoryInterface
     {
@@ -410,7 +411,7 @@ to service ids that may not exist yet: ``App\Security\Authentication\Provider\Ws
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Security\Authentication\Provider\WsseProvider"
@@ -423,7 +424,7 @@ to service ids that may not exist yet: ``App\Security\Authentication\Provider\Ws
                     public="false"
                 >
                     <argument type="service" id="security.token_storage"/>
-                    <argument type="service" id="security.authentication.manager" />
+                    <argument type="service" id="security.authentication.manager"/>
                 </service>
             </services>
         </container>
@@ -490,7 +491,7 @@ You are finished! You can now define parts of your app as under WSSE protection.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -546,10 +547,10 @@ the ``addConfiguration()`` method::
 
         public function addConfiguration(NodeDefinition $node)
         {
-          $node
-            ->children()
-                ->scalarNode('lifetime')->defaultValue(300)
-            ->end();
+            $node
+                ->children()
+                    ->scalarNode('lifetime')->defaultValue(300)
+                ->end();
         }
     }
 
@@ -606,13 +607,13 @@ set to any desirable value per firewall.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="wsse_secured" pattern="^/api/" stateless="true">
-                    <wsse lifetime="30" />
+                    <wsse lifetime="30"/>
                 </firewall>
             </config>
         </srv:container>
@@ -640,4 +641,3 @@ in the factory and consumed or passed to the other classes in the container.
 
 .. _`WSSE`: http://www.xml.com/pub/a/2003/12/17/dive.html
 .. _`nonce`: https://en.wikipedia.org/wiki/Cryptographic_nonce
-.. _`timing attacks`: https://en.wikipedia.org/wiki/Timing_attack
diff --git a/security/entity_provider.rst b/security/entity_provider.rst
deleted file mode 100644
index 8cd5c8cf679..00000000000
--- a/security/entity_provider.rst
+++ /dev/null
@@ -1,159 +0,0 @@
-.. index::
-   single: Security; User provider
-   single: Security; Entity provider
-
-How to Load Security Users from the Database (the Entity Provider)
-==================================================================
-
-Each User class in your app will usually need its own :doc:`user provider </security/user_provider>`.
-If you're loading users from the database, you can use the built-in ``entity`` provider:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/security.yaml
-            # ...
-
-            providers:
-                our_db_provider:
-                    entity:
-                        class: App\Entity\User
-                        # the property to query by - e.g. username, email, etc
-                        property: username
-                        # if you're using multiple entity managers
-                        # manager_name: customer
-
-            # ...
-
-    .. code-block:: xml
-
-        <!-- config/packages/security.xml -->
-        <?xml version="1.0" encoding="UTF-8"?>
-        <srv:container xmlns="http://symfony.com/schema/dic/security"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:srv="http://symfony.com/schema/dic/services"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <config>
-                <provider name="our_db_provider">
-                    <!-- if you're using multiple entity managers, add:
-                         manager-name="customer" -->
-                    <entity class="App\Entity\User" property="username" />
-                </provider>
-
-                <!-- ... -->
-            </config>
-        </srv:container>
-
-    .. code-block:: php
-
-        // config/packages/security.php
-        use App\Entity\User;
-
-        $container->loadFromExtension('security', [
-            'providers' => [
-                'our_db_provider' => [
-                    'entity' => [
-                        'class'    => User::class,
-                        'property' => 'username',
-                    ],
-                ],
-            ],
-
-            // ...
-        ]);
-
-The ``providers`` section creates a "user provider" called ``our_db_provider`` that
-knows to query from your ``App\Entity\User`` entity by the ``username`` property.
-The name ``our_db_provider`` isn't important: it's not used, unless you have multiple
-user providers and need to specify which user provider to use via the ``provider``
-key under your firewall.
-
-.. _authenticating-someone-with-a-custom-entity-provider:
-
-Using a Custom Query to Load the User
--------------------------------------
-
-The ``entity`` provider can only query from one *specific* field, specified by the
-``property`` config key. If you want a bit more control over this - e.g. you want
-to find a user by ``email`` *or* ``username``, you can do that by making your
-``UserRepository`` implement a special
-:class:`Symfony\\Bridge\\Doctrine\\Security\\User\\UserLoaderInterface`. This
-interface only requires one method: ``loadUserByUsername($username)``::
-
-    // src/Repository/UserRepository.php
-    namespace App\Repository;
-
-    use Symfony\Bridge\Doctrine\Security\User\UserLoaderInterface;
-    use Doctrine\ORM\EntityRepository;
-
-    class UserRepository extends EntityRepository implements UserLoaderInterface
-    {
-        public function loadUserByUsername($username)
-        {
-            return $this->createQueryBuilder('u')
-                ->where('u.username = :username OR u.email = :email')
-                ->setParameter('username', $username)
-                ->setParameter('email', $username)
-                ->getQuery()
-                ->getOneOrNullResult();
-        }
-    }
-
-To finish this, remove the ``property`` key from the user provider in
-``security.yaml``:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/security.yaml
-        security:
-            # ...
-
-            providers:
-                our_db_provider:
-                    entity:
-                        class: App\Entity\User
-
-    .. code-block:: xml
-
-        <!-- config/packages/security.xml -->
-        <?xml version="1.0" encoding="UTF-8"?>
-        <srv:container xmlns="http://symfony.com/schema/dic/security"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:srv="http://symfony.com/schema/dic/services"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <config>
-                <!-- ... -->
-
-                <provider name="our_db_provider">
-                    <entity class="App\Entity\User" />
-                </provider>
-            </config>
-        </srv:container>
-
-    .. code-block:: php
-
-        // config/packages/security.php
-        use App\Entity\User;
-
-        $container->loadFromExtension('security', [
-            // ...
-
-            'providers' => [
-                'our_db_provider' => [
-                    'entity' => [
-                        'class' => User::class,
-                    ],
-                ],
-            ],
-        ]);
-
-This tells Symfony to *not* query automatically for the User. Instead, when needed
-(e.g. because ``switch_user``, ``remember_me`` or some other security feature is
-activated), the ``loadUserByUsername()`` method on ``UserRepository`` will be called.
diff --git a/security/expressions.rst b/security/expressions.rst
index 91d51fa7271..069d9f8c917 100644
--- a/security/expressions.rst
+++ b/security/expressions.rst
@@ -43,7 +43,7 @@ Inside the expression, you have access to a number of variables:
     :ref:`role hierarchy <security-role-hierarchy>` but not including the
     ``IS_AUTHENTICATED_*`` attributes (see the functions below).
 ``object``
-     The object (if any) that's passed as the second argument to ``isGranted()``.
+    The object (if any) that's passed as the second argument to ``isGranted()``.
 ``token``
     The token object.
 ``trust_resolver``
@@ -56,14 +56,18 @@ Additionally, you have access to a number of functions inside the expression:
     Returns ``true`` if the user is authenticated via "remember-me" or authenticated
     "fully" - i.e. returns true if the user is "logged in".
 ``is_anonymous``
-    Equal to using ``IS_AUTHENTICATED_ANONYMOUSLY`` with the ``isGranted()`` function.
+    Returns ``true`` if the user is anonymous. That is, the firewall confirms that it
+    does not know this user's identity. This is different from ``IS_AUTHENTICATED_ANONYMOUSLY``,
+    which is granted to *all* users, including authenticated ones.
 ``is_remember_me``
     Similar, but not equal to ``IS_AUTHENTICATED_REMEMBERED``, see below.
 ``is_fully_authenticated``
     Similar, but not equal to ``IS_AUTHENTICATED_FULLY``, see below.
-``has_role``
-    Checks to see if the user has the given role - equivalent to an expression like
-    ``'ROLE_ADMIN' in roles``.
+``is_granted``
+    Checks if the user has the given permission. Optionally accepts a second argument
+    with the object where permission is checked on. It's equivalent to using
+    the :doc:`isGranted() method </security/securing_services>` from the authorization
+    checker service.
 
 .. sidebar:: ``is_remember_me`` is different than checking ``IS_AUTHENTICATED_REMEMBERED``
 
diff --git a/security/firewall_restriction.rst b/security/firewall_restriction.rst
index fd668e83a8a..0ce0c2e3ff5 100644
--- a/security/firewall_restriction.rst
+++ b/security/firewall_restriction.rst
@@ -4,20 +4,29 @@
 How to Restrict Firewalls to a Request
 ======================================
 
-When using the Security component, you can create firewalls that match certain request options.
-In most cases, matching against the URL is sufficient, but in special cases, you can further
-restrict the initialization of a firewall against other options of the request.
+When using the Security component, firewalls will decide whether they handle a
+request based on the result of a request matcher: the first firewall matching
+the request will handle it.
+
+The last firewall can be configured without any matcher to handle every incoming
+request.
+
+Restricting by Configuration
+----------------------------
+
+Most of the time you don't need to create matchers yourself as Symfony can do it
+for you based on the firewall configuration.
 
 .. note::
 
-    You can use any of these restrictions individually or mix them together to get
-    your desired firewall configuration.
+    You can use any of the following restrictions individually or mix them
+    together to get your desired firewall configuration.
 
-Restricting by Pattern
-----------------------
+Restricting by Path
+~~~~~~~~~~~~~~~~~~~
 
-This is the default restriction and restricts a firewall to only be initialized if the request URL
-matches the configured ``pattern``.
+This is the default restriction and restricts a firewall to only be initialized
+if the request path matches the configured ``pattern``.
 
 .. configuration-block::
 
@@ -40,7 +49,7 @@ matches the configured ``pattern``.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -65,12 +74,12 @@ matches the configured ``pattern``.
         ]);
 
 The ``pattern`` is a regular expression. In this example, the firewall will only be
-activated if the URL starts (due to the ``^`` regex character) with ``/admin``. If
-the URL does not match this pattern, the firewall will not be activated and subsequent
+activated if the path starts (due to the ``^`` regex character) with ``/admin``. If
+the path does not match this pattern, the firewall will not be activated and subsequent
 firewalls will have the opportunity to be matched for this request.
 
 Restricting by Host
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 If matching against the ``pattern`` only is not enough, the request can also be matched against
 ``host``. When the configuration option ``host`` is set, the firewall will be restricted to
@@ -97,7 +106,7 @@ only initialize if the host from the request matches against the configuration.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -129,7 +138,7 @@ and subsequent firewalls will have the opportunity to be matched for this
 request.
 
 Restricting by HTTP Methods
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The configuration option ``methods`` restricts the initialization of the firewall to
 the provided HTTP methods.
@@ -155,7 +164,7 @@ the provided HTTP methods.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -183,3 +192,54 @@ In this example, the firewall will only be activated if the HTTP method of the
 request is either ``GET`` or ``POST``. If the method is not in the array of the
 allowed methods, the firewall will not be activated and subsequent firewalls will again
 have the opportunity to be matched for this request.
+
+Restricting by Service
+----------------------
+
+If the above options don't fit your needs you can configure any service implementing
+:class:`Symfony\\Component\\HttpFoundation\\RequestMatcherInterface` as ``request_matcher``.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+
+        # ...
+        security:
+            firewalls:
+                secured_area:
+                    request_matcher: app.firewall.secured_area.request_matcher
+                    # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <firewall name="secured_area" request-matcher="app.firewall.secured_area.request_matcher">
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+
+        // ...
+        $container->loadFromExtension('security', [
+            'firewalls' => [
+                'secured_area' => [
+                    'request_matcher' => 'app.firewall.secured_area.request_matcher',
+                    // ...
+                ],
+            ],
+        ]);
diff --git a/security/force_https.rst b/security/force_https.rst
index eb1515763d7..6358f663942 100644
--- a/security/force_https.rst
+++ b/security/force_https.rst
@@ -36,12 +36,12 @@ access control:
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:srv="http://symfony.com/schema/dic/services"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <config>
                     <!-- ... -->
 
-                    <rule path="^/secure" role="ROLE_ADMIN" requires_channel="https" />
+                    <rule path="^/secure" role="ROLE_ADMIN" requires_channel="https"/>
                     <rule path="^/login"
                         role="IS_AUTHENTICATED_ANONYMOUSLY"
                         requires_channel="https"
@@ -85,8 +85,10 @@ like ``requires_channel: '%env(SECURE_SCHEME)%'``. In your ``.env`` file, set
 See :doc:`/security/access_control` for more details about ``access_control``
 in general.
 
-It is also possible to specify using HTTPS in the routing configuration,
-see :doc:`/routing/scheme` for more details.
+.. note::
+
+    An alternative way to enforce HTTP or HTTPS is to use
+    :ref:`the scheme option <routing-force-https>` of a route or group of routes.
 
 .. note::
 
diff --git a/security/form_login.rst b/security/form_login.rst
index f825d1f8cc7..2d2775b8f25 100644
--- a/security/form_login.rst
+++ b/security/form_login.rst
@@ -41,12 +41,12 @@ First, enable ``form_login`` under your firewall:
             xmlns:srv="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="main">
-                    <anonymous />
-                    <form-login login-path="login" check-path="login" />
+                    <anonymous/>
+                    <form-login login-path="login" check-path="login"/>
                 </firewall>
             </config>
         </srv:container>
@@ -74,7 +74,7 @@ First, enable ``form_login`` under your firewall:
 
 Now, when the security system initiates the authentication process, it will
 redirect the user to the login form ``/login``. Implementing this login form
-is your job. First, create a new ``SecurityController`` inside a bundle::
+is your job. First, create a new ``SecurityController``::
 
     // src/Controller/SecurityController.php
     namespace App\Controller;
@@ -100,7 +100,7 @@ configuration (``login``):
         class SecurityController extends AbstractController
         {
             /**
-             * @Route("/login", name="login")
+             * @Route("/login", name="login", methods={"GET", "POST"})
              */
             public function login()
             {
@@ -113,6 +113,7 @@ configuration (``login``):
         login:
             path:       /login
             controller: App\Controller\SecurityController::login
+            methods: GET|POST
 
     .. code-block:: xml
 
@@ -121,26 +122,23 @@ configuration (``login``):
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="login" path="/login">
-                <default key="_controller">App\Controller\SecurityController::login</default>
-            </route>
+            <route id="login" path="/login" controller="App\Controller\SecurityController::login" methods="GET|POST"/>
         </routes>
 
     ..  code-block:: php
 
         // config/routes.php
         use App\Controller\SecurityController;
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('login', new Route('/login', [
-            '_controller' => [SecurityController::class, 'login'],
-        ]));
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('login', '/login')
+                ->controller([SecurityController::class, 'login'])
+                ->methods(['GET', 'POST'])
+            ;
+        };
 
 Great! Next, add the logic to ``login()`` that displays the login form::
 
@@ -191,15 +189,15 @@ Finally, create the template:
 
     <form action="{{ path('login') }}" method="post">
         <label for="username">Username:</label>
-        <input type="text" id="username" name="_username" value="{{ last_username }}" />
+        <input type="text" id="username" name="_username" value="{{ last_username }}"/>
 
         <label for="password">Password:</label>
-        <input type="password" id="password" name="_password" />
+        <input type="password" id="password" name="_password"/>
 
         {#
             If you want to control the URL the user
             is redirected to on success (more details below)
-            <input type="hidden" name="_target_path" value="/account" />
+            <input type="hidden" name="_target_path" value="/account"/>
         #}
 
         <button type="submit">login</button>
@@ -281,14 +279,14 @@ security component:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="secured_area">
                     <!-- ... -->
-                    <form-login csrf-token-generator="security.csrf.token_manager" />
+                    <form-login csrf-token-generator="security.csrf.token_manager"/>
                 </firewall>
             </config>
         </srv:container>
@@ -363,7 +361,7 @@ After this, you have protected your login form against CSRF attacks.
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:srv="http://symfony.com/schema/dic/services"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <config>
                     <!-- ... -->
@@ -437,13 +435,13 @@ a relative/absolute URL or a Symfony route name:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
-                    <form-login default-target-path="after_login_route_name" />
+                    <form-login default-target-path="after_login_route_name"/>
                 </firewall>
             </config>
         </srv:container>
@@ -494,14 +492,14 @@ previously requested URL and always redirect to the default page:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <form-login always-use-default-target-path="true" />
+                    <form-login always-use-default-target-path="true"/>
                 </firewall>
             </config>
         </srv:container>
@@ -547,8 +545,8 @@ Defining the redirect URL via POST using a hidden form field:
     <form action="{{ path('login') }}" method="post">
         {# ... #}
 
-        <input type="hidden" name="_target_path" value="{{ path('account') }}" />
-        <input type="submit" name="login" />
+        <input type="hidden" name="_target_path" value="{{ path('account') }}"/>
+        <input type="submit" name="login"/>
     </form>
 
 Using the Referring URL
@@ -582,14 +580,14 @@ parameter is included in the request, you may use the value of the
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <form-login use-referer="true" />
+                    <form-login use-referer="true"/>
                 </firewall>
             </config>
         </srv:container>
@@ -648,14 +646,14 @@ option to define a new target via a relative/absolute URL or a Symfony route nam
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <form-login failure-path="login_failure_route_name" />
+                    <form-login failure-path="login_failure_route_name"/>
                 </firewall>
             </config>
         </srv:container>
@@ -689,8 +687,8 @@ This option can also be set via the ``_failure_path`` request parameter:
     <form action="{{ path('login') }}" method="post">
         {# ... #}
 
-        <input type="hidden" name="_failure_path" value="{{ path('forgot_password') }}" />
-        <input type="submit" name="login" />
+        <input type="hidden" name="_failure_path" value="{{ path('forgot_password') }}"/>
+        <input type="submit" name="login"/>
     </form>
 
 Customizing the Target and Failure Request Parameters
@@ -723,15 +721,15 @@ redirects can be customized using the  ``target_path_parameter`` and
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <form-login target-path-parameter="go_to" />
-                    <form-login failure-path-parameter="back_to" />
+                    <form-login target-path-parameter="go_to"/>
+                    <form-login failure-path-parameter="back_to"/>
                 </firewall>
             </config>
         </srv:container>
@@ -766,9 +764,9 @@ are now fully customized:
     <form action="{{ path('login') }}" method="post">
         {# ... #}
 
-        <input type="hidden" name="go_to" value="{{ path('dashboard') }}" />
-        <input type="hidden" name="back_to" value="{{ path('forgot_password') }}" />
-        <input type="submit" name="login" />
+        <input type="hidden" name="go_to" value="{{ path('dashboard') }}"/>
+        <input type="hidden" name="back_to" value="{{ path('forgot_password') }}"/>
+        <input type="submit" name="login"/>
     </form>
 
 .. _`Login CSRF attacks`: https://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests
diff --git a/security/form_login_setup.rst b/security/form_login_setup.rst
index a138a072419..3527c2a3fda 100644
--- a/security/form_login_setup.rst
+++ b/security/form_login_setup.rst
@@ -31,6 +31,9 @@ and your generated code may be slightly different:
 
     Choose a name for the controller class (e.g. SecurityController) [SecurityController]:
     > SecurityController
+    
+    Do you want to generate a '/logout' URL? (yes/no) [yes]:
+    > yes
 
      created: src/Security/LoginFormAuthenticator.php
      updated: config/packages/security.yaml
@@ -38,6 +41,7 @@ and your generated code may be slightly different:
      created: templates/security/login.html.twig
 
 .. versionadded:: 1.8
+
     Support for login form authentication was added to ``make:auth`` in MakerBundle 1.8.
 
 This generates the following: 1) a login route & controller, 2) a template that
@@ -73,10 +77,55 @@ class that processes the login submit and 4) updates the main security config fi
         }
     }
 
+Edit the ``security.yaml`` file in order to allow access for anyone to the
+``/login`` route:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            access_control:
+                - { path: ^/login$, roles: IS_AUTHENTICATED_ANONYMOUSLY }
+                # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" charset="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <rule path="^/login$" role="IS_AUTHENTICATED_ANONYMOUSLY"/>
+                <!-- ... -->
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        $container->loadFromExtension('security', [
+            // ...
+            'access_control' => [
+                [
+                    'path' => '^/login',
+                    'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY',
+                ],
+                // ...
+            ],
+        ]);
+
 **Step 2.** The template has very little to do with security: it just generates
 a traditional HTML form that submits to ``/login``:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {% extends 'base.html.twig' %}
 
@@ -122,11 +171,13 @@ a traditional HTML form that submits to ``/login``:
 
     use App\Entity\User;
     use Doctrine\ORM\EntityManagerInterface;
+
     use Symfony\Component\HttpFoundation\RedirectResponse;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\Routing\RouterInterface;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Exception\InvalidCsrfTokenException;
     use Symfony\Component\Security\Core\Security;
     use Symfony\Component\Security\Core\User\UserInterface;
@@ -237,14 +288,14 @@ a traditional HTML form that submits to ``/login``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
                 <firewall name="main">
                     <!-- ... -->
                     <guard>
-                        <authenticator class="App\Security\LoginFormAuthenticator" />
+                        <authenticator class="App\Security\LoginFormAuthenticator"/>
                     </guard>
                 </firewall>
             </config>
@@ -252,7 +303,7 @@ a traditional HTML form that submits to ``/login``:
 
     .. code-block:: php
 
-        // app/config/security.php
+        // config/packages/security.php
         use App\Security\LoginFormAuthenticator;
 
         $container->loadFromExtension('security', [
diff --git a/security/guard_authentication.rst b/security/guard_authentication.rst
index 4fd9a3840fc..205c52b286e 100644
--- a/security/guard_authentication.rst
+++ b/security/guard_authentication.rst
@@ -6,7 +6,7 @@ Custom Authentication System with Guard (API Token Example)
 
 Whether you need to build a traditional login form, an API token authentication system
 or you need to integrate with some proprietary single-sign-on system, the Guard
-component can make it easy... and fun!
+component will be the right choice!
 
 Guard authentication can be used to:
 
@@ -14,7 +14,7 @@ Guard authentication can be used to:
 * Create an API token authentication system (done on this page!)
 * `Social Authentication`_ (or use `HWIOAuthBundle`_ for a robust, but non-Guard solution)
 
-or anything else you dream up. In this example, we'll build an API token authentication
+or anything else. In this example, we'll build an API token authentication
 system so we can learn more about Guard in detail.
 
 Step 1) Prepare your User Class
@@ -66,14 +66,14 @@ This requires you to implement several methods::
 
     use App\Entity\User;
     use Doctrine\ORM\EntityManagerInterface;
-    use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\JsonResponse;
+    use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\Security\Core\User\UserInterface;
-    use Symfony\Component\Security\Guard\AbstractGuardAuthenticator;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\User\UserInterface;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
+    use Symfony\Component\Security\Guard\AbstractGuardAuthenticator;
 
     class TokenAuthenticator extends AbstractGuardAuthenticator
     {
@@ -207,7 +207,7 @@ Finally, configure your ``firewalls`` key in ``security.yaml`` to use this authe
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
             <config>
                 <!-- ... -->
 
@@ -215,7 +215,7 @@ Finally, configure your ``firewalls`` key in ``security.yaml`` to use this authe
                     pattern="^/"
                     anonymous="true"
                 >
-                    <logout />
+                    <logout/>
 
                     <guard>
                         <authenticator>App\Security\TokenAuthenticator</authenticator>
@@ -230,7 +230,7 @@ Finally, configure your ``firewalls`` key in ``security.yaml`` to use this authe
 
         // config/packages/security.php
 
-        // ..
+        // ...
         use App\Security\TokenAuthenticator;
 
         $container->loadFromExtension('security', [
@@ -252,7 +252,7 @@ Finally, configure your ``firewalls`` key in ``security.yaml`` to use this authe
 You did it! You now have a fully-working API token authentication system. If your
 homepage required ``ROLE_USER``, then you could test it under different conditions:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     # test with no token
     curl http://localhost:8000/
@@ -382,7 +382,7 @@ to cause a failure::
 In this case, since "ILuvAPIs" is a ridiculous API key, you could include an easter
 egg to return a custom message if someone tries this:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     curl -H "X-AUTH-TOKEN: ILuvAPIs" http://localhost:8000/
     # {"message":"ILuvAPIs is not a real API key: it's just a silly phrase"}
@@ -509,6 +509,5 @@ Frequently Asked Questions
     question) or use the ``User`` object from FOSUserBundle and create your own
     authenticator(s) (just like in this article).
 
-.. _`must be quoted with backticks`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words
 .. _`Social Authentication`: https://github.com/knpuniversity/oauth2-client-bundle#authenticating-with-guard
 .. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle
diff --git a/security/impersonating_user.rst b/security/impersonating_user.rst
index 7b3247118c6..a4f4e724e27 100644
--- a/security/impersonating_user.rst
+++ b/security/impersonating_user.rst
@@ -14,8 +14,8 @@ a user sees that you can't reproduce).
     (e.g. ``REMOTE_USER``) where the authentication information is expected to be
     sent on each request.
 
-Impersonating the user can be done by activating the ``switch_user``
-firewall listener:
+Impersonating the user can be done by activating the ``switch_user`` firewall
+listener:
 
 .. configuration-block::
 
@@ -38,14 +38,14 @@ firewall listener:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <switch-user />
+                    <switch-user/>
                 </firewall>
             </config>
         </srv:container>
@@ -98,11 +98,17 @@ to show a link to exit impersonation:
 Finding the Original User
 -------------------------
 
+.. versionadded:: 4.3
+
+    The ``SwitchUserToken`` class was introduced in Symfony 4.3.
+
 In some cases, you may need to get the object that represents the impersonator
-user rather than the impersonated user. Use the following snippet to iterate
-over the user's roles until you find one that is a ``SwitchUserRole`` object::
+user rather than the impersonated user. When a user is impersonated the token
+stored in the token storage will be a ``SwitchUserToken`` instance. Use the
+following snippet to obtain the original token which gives you access to
+the impersonator user::
 
-    use Symfony\Component\Security\Core\Role\SwitchUserRole;
+    use Symfony\Component\Security\Core\Authentication\Token\SwitchUserToken;
     use Symfony\Component\Security\Core\Security;
     // ...
 
@@ -119,14 +125,13 @@ over the user's roles until you find one that is a ``SwitchUserRole`` object::
         {
             // ...
 
-            if ($this->security->isGranted('ROLE_PREVIOUS_ADMIN')) {
-                foreach ($this->security->getToken()->getRoles() as $role) {
-                    if ($role instanceof SwitchUserRole) {
-                        $impersonatorUser = $role->getSource()->getUser();
-                        break;
-                    }
-                }
+            $token = $this->security->getToken();
+
+            if ($token instanceof SwitchUserToken) {
+                $impersonatorUser = $token->getOriginalToken()->getUser();
             }
+
+            // ...
         }
     }
 
@@ -159,13 +164,13 @@ also adjust the query parameter name via the ``parameter`` setting:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
             <config>
                 <!-- ... -->
 
                 <firewall name="main">
                     <!-- ... -->
-                    <switch-user role="ROLE_ADMIN" parameter="_want_to_be_this_user" />
+                    <switch-user role="ROLE_ADMIN" parameter="_want_to_be_this_user"/>
                 </firewall>
             </config>
         </srv:container>
@@ -190,29 +195,81 @@ also adjust the query parameter name via the ``parameter`` setting:
 Limiting User Switching
 -----------------------
 
-If you need more control over user switching, but don't require the complexity
-of a full ACL implementation, you can use a security voter. For example, you
-may want to allow employees to be able to impersonate a user with the
-``ROLE_CUSTOMER`` role without giving them the ability to impersonate a more
-elevated user such as an administrator.
+If you need more control over user switching, you can use a security voter. First,
+configure ``switch_user`` to check for some new, custom attribute. This can be
+anything, but *cannot* start with ``ROLE_`` (to enforce that only your voter will)
+be called:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            firewalls:
+                main:
+                    # ...
+                    switch_user: { role: CAN_SWITCH_USER }
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+            <config>
+                <!-- ... -->
+
+                <firewall name="main">
+                    <!-- ... -->
+                    <switch-user role="CAN_SWITCH_USER"/>
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
 
-.. versionadded:: 4.1
+        // config/packages/security.php
+        $container->loadFromExtension('security', [
+            // ...
 
-    The target user was added as the voter subject parameter in Symfony 4.1.
+            'firewalls' => [
+                'main'=> [
+                    // ...
+                    'switch_user' => [
+                        'role' => 'CAN_SWITCH_USER',
+                    ],
+                ],
+            ],
+        ]);
 
-Create the voter class::
+Then, create a voter class that responds to this role and includes whatever custom
+logic you want::
 
     namespace App\Security\Voter;
 
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Authorization\Voter\Voter;
+    use Symfony\Component\Security\Core\Security;
     use Symfony\Component\Security\Core\User\UserInterface;
 
     class SwitchToCustomerVoter extends Voter
     {
+        private $security;
+
+        public function __construct(Security $security)
+        {
+            $this->security = $security;
+        }
+
         protected function supports($attribute, $subject)
         {
-            return in_array($attribute, ['ROLE_ALLOWED_TO_SWITCH'])
+            return in_array($attribute, ['CAN_SWITCH_USER'])
                 && $subject instanceof UserInterface;
         }
 
@@ -224,34 +281,29 @@ Create the voter class::
                 return false;
             }
 
-            if (in_array('ROLE_CUSTOMER', $subject->getRoles())
-                && $this->hasSwitchToCustomerRole($token)) {
+            // you can still check for ROLE_ALLOWED_TO_SWITCH
+            if ($this->security->isGranted('ROLE_ALLOWED_TO_SWITCH')) {
                 return true;
             }
 
-            return false;
-        }
+            // check for any roles you want
+            if ($this->security->isGranted('ROLE_TECH_SUPPORT')) {
+                return true;
+            }
 
-        private function hasSwitchToCustomerRole(TokenInterface $token)
-        {
-            foreach ($token->getRoles() as $role) {
-                if ($role->getRole() === 'ROLE_SWITCH_TO_CUSTOMER') {
-                    return true;
-                }
+            /*
+             * or use some custom data from your User object
+            if ($user->isAllowedToSwitch()) {
+                return true;
             }
+            */
 
             return false;
         }
     }
 
-To enable the new voter in the app, register it as a service and
-:doc:`tag it </service_container/tags>` with the ``security.voter``
-tag. If you're using the
-:ref:`default services.yaml configuration <service-container-services-load-example>`,
-this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
-
-Now a user who has the ``ROLE_SWITCH_TO_CUSTOMER`` role can switch to a user who
-has the ``ROLE_CUSTOMER`` role, but not other users.
+That's it! When switching users, your voter now has full control over whether or
+not this is allowed. If your voter isn't called, see :ref:`declaring-the-voter-as-a-service`.
 
 Events
 ------
@@ -267,8 +319,8 @@ you switch users, add an event subscriber on this event::
     // src/EventListener/SwitchUserSubscriber.php
     namespace App\EventListener;
 
-    use Symfony\Component\Security\Http\Event\SwitchUserEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\Security\Http\Event\SwitchUserEvent;
     use Symfony\Component\Security\Http\SecurityEvents;
 
     class SwitchUserSubscriber implements EventSubscriberInterface
@@ -277,7 +329,7 @@ you switch users, add an event subscriber on this event::
         {
             $request = $event->getRequest();
 
-            if ($request->hasSession() && ($session = $request->getSession)) {
+            if ($request->hasSession() && ($session = $request->getSession())) {
                 $session->set(
                     '_locale',
                     // assuming your User has some getLocale() method
diff --git a/security/json_login_setup.rst b/security/json_login_setup.rst
index ed019c7b13f..4ca0b8809e6 100644
--- a/security/json_login_setup.rst
+++ b/security/json_login_setup.rst
@@ -29,12 +29,12 @@ First, enable the JSON login under your firewall:
             xmlns:srv="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="main">
-                    <anonymous />
-                    <json-login check-path="/login" />
+                    <anonymous/>
+                    <json-login check-path="/login"/>
                 </firewall>
             </config>
         </srv:container>
@@ -74,7 +74,7 @@ The next step is to configure a route in your app matching this path:
         class SecurityController extends AbstractController
         {
             /**
-             * @Route("/login", name="login")
+             * @Route("/login", name="login", methods={"POST"})
              */
             public function login(Request $request)
             {
@@ -93,6 +93,7 @@ The next step is to configure a route in your app matching this path:
         login:
             path:       /login
             controller: App\Controller\SecurityController::login
+            methods: POST
 
     .. code-block:: xml
 
@@ -101,25 +102,23 @@ The next step is to configure a route in your app matching this path:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="login" path="/login">
-                <default key="_controller">App\Controller\SecurityController::login</default>
-            </route>
+            <route id="login" path="/login" controller="App\Controller\SecurityController::login" methods="POST"/>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
+        use App\Controller\SecurityController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('login', new Route('/login', [
-            '_controller' => 'App\Controller\SecurityController::login',
-        ]));
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('login', '/login')
+                ->controller([SecurityController::class, 'login'])
+                ->methods(['POST'])
+            ;
+        };
 
 Now, when you make a ``POST`` request, with the header ``Content-Type: application/json``,
 to the ``/login`` URL with the following JSON document as the body, the security
@@ -178,14 +177,14 @@ The security configuration should be:
             xmlns:srv="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="main">
-                    <anonymous />
+                    <anonymous/>
                     <json-login check-path="login"
                                 username-path="security.credentials.login"
-                                password-path="security.credentials.password" />
+                                password-path="security.credentials.password"/>
                 </firewall>
             </config>
         </srv:container>
diff --git a/security/ldap.rst b/security/ldap.rst
index 44ecf13e535..2bb3eee95bd 100644
--- a/security/ldap.rst
+++ b/security/ldap.rst
@@ -37,7 +37,7 @@ This means that the following scenarios will work:
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the Ldap component before using it:
 
 .. code-block:: terminal
@@ -85,11 +85,11 @@ An LDAP client can be configured using the built-in
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Symfony\Component\Ldap\Ldap">
-                    <argument type="service" id="Symfony\Component\Ldap\Adapter\ExtLdap\Adapter" />
+                    <argument type="service" id="Symfony\Component\Ldap\Adapter\ExtLdap\Adapter"/>
                 </service>
                 <service id="Symfony\Component\Ldap\Adapter\ExtLdap\Adapter">
                     <argument type="collection">
@@ -108,11 +108,11 @@ An LDAP client can be configured using the built-in
     .. code-block:: php
 
         // config/services.php
-        use Symfony\Component\Ldap\Ldap;
         use Symfony\Component\Ldap\Adapter\ExtLdap\Adapter;
+        use Symfony\Component\Ldap\Ldap;
 
         $container->register(Ldap::class)
-            ->addArgument(new Reference(Adapter::class);
+            ->addArgument(new Reference(Adapter::class));
 
         $container
             ->register(Adapter::class)
@@ -158,7 +158,7 @@ use the ``ldap`` user provider.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <provider name="my_ldap">
@@ -256,19 +256,22 @@ and will not be considered as authenticated fully.
 uid_key
 .......
 
-**type**: ``string`` **default**: ``sAMAccountName``
+**type**: ``string`` **default**: ``null``
 
 This is the entry's key to use as its UID. Depends on your LDAP server
 implementation. Commonly used values are:
 
-* ``sAMAccountName``
+* ``sAMAccountName`` (default)
 * ``userPrincipalName``
 * ``uid``
 
+If you pass ``null`` as the value of this option, the default UID key is used
+``sAMAccountName``.
+
 filter
 ......
 
-**type**: ``string`` **default**: ``({uid_key}={username})``
+**type**: ``string`` **default**: ``null``
 
 This key lets you configure which LDAP query will be used. The ``{uid_key}``
 string will be replaced by the value of the ``uid_key`` configuration value
@@ -278,7 +281,10 @@ replaced by the username you are trying to load.
 For example, with a ``uid_key`` of ``uid``, and if you are trying to
 load the user ``fabpot``, the final string will be: ``(uid=fabpot)``.
 
-The username will be escaped, in order to prevent `LDAP injection`_.
+If you pass ``null`` as the value of this option, the default filter is used
+``({uid_key}={username})``.
+
+In order to prevent `LDAP injection`_, the username will be escaped.
 
 The syntax for the ``filter`` key is defined by `RFC4515`_.
 
@@ -324,12 +330,12 @@ providers with different ``base_dn``. The value of this option must be a valid
 search string (e.g. ``uid="{username}"``). The placeholder value will be
 replaced by the actual username.
 
-When this option is used, ``dn_string`` has to be updated accordingly. Following
-the previous example, if your users have the following two DN:
-``dc=companyA,dc=example,dc=com`` and ``dc=companyB,dc=example,dc=com``, then
-``dn_string`` should be ``dc=example,dc=com``. If the ``query_string`` option is
-``uid="{username}"``, then the authentication provider can authenticate users
-from both DN.
+When this option is used, ``query_string`` will search in the DN specified by
+``dn_string`` and the DN resulted of the ``query_string`` will be used to
+authenticate the user with their password. Following the previous example, if
+your users have the following two DN: ``dc=companyA,dc=example,dc=com`` and
+``dc=companyB,dc=example,dc=com``, then ``dn_string`` should be
+``dc=example,dc=com``.
 
 Bear in mind that usernames must be unique across both DN, as the authentication
 provider won't be able to select the correct user for the bind process if more
@@ -365,13 +371,13 @@ Configuration example for form login
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="main">
                     <form-login-ldap
                             service="Symfony\Component\Ldap\Ldap"
-                            dn-string="uid={username},dc=example,dc=com" />
+                            dn-string="uid={username},dc=example,dc=com"/>
                 </firewall>
             </config>
         </srv:container>
@@ -420,11 +426,11 @@ Configuration example for HTTP Basic
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="main" stateless="true">
-                    <http-basic-ldap service="Symfony\Component\Ldap\Ldap" dn-string="uid={username},dc=example,dc=com" />
+                    <http-basic-ldap service="Symfony\Component\Ldap\Ldap" dn-string="uid={username},dc=example,dc=com"/>
                 </firewall>
             </config>
         </srv:container>
@@ -475,14 +481,14 @@ Configuration example for form login and query_string
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <firewall name="main">
                     <form-login-ldap
                             service="Symfony\Component\Ldap\Ldap"
                             dn-string="dc=example,dc=com"
-                            query-string="(&amp;(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))" />
+                            query-string="(&amp;(uid={username})(memberOf=cn=users,ou=Services,dc=example,dc=com))"/>
                 </firewall>
             </config>
         </srv:container>
@@ -503,7 +509,7 @@ Configuration example for form login and query_string
                     ],
                 ],
             ]
-        ];
+        ]);
 
 .. _`LDAP PHP extension`: http://www.php.net/manual/en/intro.ldap.php
 .. _`RFC4515`: http://www.faqs.org/rfcs/rfc4515.html
diff --git a/security/multiple_guard_authenticators.rst b/security/multiple_guard_authenticators.rst
index 264a3516be4..b71d5186817 100644
--- a/security/multiple_guard_authenticators.rst
+++ b/security/multiple_guard_authenticators.rst
@@ -24,7 +24,7 @@ This is how your security configuration can look in action:
 
         # config/packages/security.yaml
         security:
-             # ...
+            # ...
             firewalls:
                 default:
                     anonymous: ~
@@ -42,12 +42,12 @@ This is how your security configuration can look in action:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
                 <firewall name="default">
-                    <anonymous />
+                    <anonymous/>
                     <guard entry-point="App\Security\LoginFormAuthenticator">
                         <authenticator>App\Security\LoginFormAuthenticator</authenticator>
                         <authenticator>App\Security\FacebookConnectAuthenticator</authenticator>
@@ -59,8 +59,8 @@ This is how your security configuration can look in action:
     .. code-block:: php
 
         // config/packages/security.php
-        use App\Security\LoginFormAuthenticator;
         use App\Security\FacebookConnectAuthenticator;
+        use App\Security\LoginFormAuthenticator;
 
         $container->loadFromExtension('security', [
             // ...
@@ -71,7 +71,7 @@ This is how your security configuration can look in action:
                         'entry_point' => '',
                         'authenticators' => [
                             LoginFormAuthenticator::class,
-                            FacebookConnectAuthenticator::class'
+                            FacebookConnectAuthenticator::class,
                         ],
                     ],
                 ],
@@ -120,7 +120,7 @@ the solution is to split the configuration into two separate firewalls:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -130,14 +130,14 @@ the solution is to split the configuration into two separate firewalls:
                     </guard>
                 </firewall>
                 <firewall name="default">
-                    <anonymous />
+                    <anonymous/>
                     <guard>
                         <authenticator>App\Security\LoginFormAuthenticator</authenticator>
                     </guard>
                 </firewall>
-                <rule path="^/login" role="IS_AUTHENTICATED_ANONYMOUSLY" />
-                <rule path="^/api" role="ROLE_API_USER" />
-                <rule path="^/" role="ROLE_USER" />
+                <rule path="^/login" role="IS_AUTHENTICATED_ANONYMOUSLY"/>
+                <rule path="^/api" role="ROLE_API_USER"/>
+                <rule path="^/" role="ROLE_USER"/>
             </config>
         </srv:container>
 
diff --git a/security/named_encoders.rst b/security/named_encoders.rst
index a2c1c823f02..462ade3a1da 100644
--- a/security/named_encoders.rst
+++ b/security/named_encoders.rst
@@ -27,7 +27,7 @@ to apply to all instances of a specific class:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd"
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
         >
             <config>
                 <!-- ... -->
@@ -81,14 +81,14 @@ be done with named encoders:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd"
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
         >
 
             <config>
                 <!-- ... -->
                 <encoder class="harsh"
                     algorithm="bcrypt"
-                    cost="15" />
+                    cost="15"/>
             </config>
         </srv:container>
 
@@ -109,7 +109,7 @@ be done with named encoders:
 
     If you are running PHP 7.2+ or have the `libsodium`_ extension installed,
     then the recommended hashing algorithm to use is
-    :ref:`Argon2i <reference-security-argon2i>`.
+    :ref:`Sodium <reference-security-sodium>`.
 
 This creates an encoder named ``harsh``. In order for a ``User`` instance
 to use it, the class must implement
@@ -120,8 +120,8 @@ the name of the encoder to use::
     // src/Acme/UserBundle/Entity/User.php
     namespace Acme\UserBundle\Entity;
 
-    use Symfony\Component\Security\Core\User\UserInterface;
     use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
+    use Symfony\Component\Security\Core\User\UserInterface;
 
     class User implements UserInterface, EncoderAwareInterface
     {
@@ -158,13 +158,13 @@ you must register a service for it in order to use it as a named encoder:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd"
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
         >
 
             <config>
                 <!-- ... -->
                 <encoder class="app_encoder"
-                    id="App\Security\Encoder\MyCustomPasswordEncoder" />
+                    id="App\Security\Encoder\MyCustomPasswordEncoder"/>
             </config>
         </srv:container>
 
diff --git a/security/remember_me.rst b/security/remember_me.rst
index bd37a56d587..f96bb7bbe9e 100644
--- a/security/remember_me.rst
+++ b/security/remember_me.rst
@@ -33,12 +33,12 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
     .. code-block:: xml
 
         <!-- config/packages/security.xml -->
-        <?xml version="1.0" encoding="utf-8" ?>
+        <?xml version="1.0" encoding="UTF-8" ?>
         <srv:container xmlns="http://symfony.com/schema/dic/security"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
@@ -50,7 +50,7 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
                     <remember-me
                         secret="%kernel.secret%"
                         lifetime="604800"
-                        path="/" />
+                        path="/"/>
                     <!-- by default, the feature is enabled by checking a checkbox
                          in the login form (see below), add always-remember-me="true"
                          to always enable it. -->
@@ -114,6 +114,10 @@ The ``remember_me`` firewall defines the following configuration options:
     through the HTTP protocol. This means that the cookie won't be accessible
     by scripting languages, such as JavaScript.
 
+``samesite`` (default value: ``null``)
+    If set to ``strict``, the cookie associated with this feature will not
+    be sent along with cross-site requests, even when following a regular link.
+
 ``remember_me_parameter`` (default value: ``_remember_me``)
     The name of the form field checked to decide if the "Remember Me" feature
     should be enabled or not. Keep reading this article to know how to enable
@@ -125,12 +129,8 @@ The ``remember_me`` firewall defines the following configuration options:
     end user.
 
 ``token_provider`` (default value: ``null``)
-    Defines the service id of a token provider to use. By default, tokens are
-    stored in a cookie. For example, you might want to store the token in a
-    database, to not have a (hashed) version of the password in a cookie. The
-    DoctrineBridge comes with a
-    ``Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider`` that
-    you can use.
+    Defines the service id of a token provider to use. If you want to store tokens
+    in the database, see :ref:`remember-me-token-in-database`.
 
 Forcing the User to Opt-Out of the Remember Me Feature
 ------------------------------------------------------
@@ -146,11 +146,10 @@ this:
 .. code-block:: html+twig
 
     {# templates/security/login.html.twig #}
-
     <form method="post">
         {# ... your form fields #}
 
-        <input type="checkbox" id="remember_me" name="_remember_me" checked />
+        <input type="checkbox" id="remember_me" name="_remember_me" checked/>
         <label for="remember_me">Keep me logged in</label>
 
         {# ... #}
@@ -168,8 +167,8 @@ to access protected resources as if the user had actually authenticated upon
 visiting the site.
 
 In some cases, however, you may want to force the user to actually re-authenticate
-before accessing certain resources. For example, you might allow "remember me"
-users to change their password. You can do this by leveraing a few special "roles"::
+before accessing certain resources. For example, you might not allow "remember me"
+users to change their password. You can do this by leveraging a few special "roles"::
 
     // src/Controller/AccountController.php
     // ...
@@ -192,3 +191,116 @@ users to change their password. You can do this by leveraing a few special "role
 
         // ...
     }
+
+.. _remember-me-token-in-database:
+
+Storing Remember Me Tokens in the Database
+------------------------------------------
+
+The token contents, including the hashed version of the user password, are
+stored by default in cookies. If you prefer to store them in a database, use the
+:class:`Symfony\\Bridge\\Doctrine\\Security\\RememberMe\\DoctrineTokenProvider`
+class provided by the Doctrine Bridge.
+
+First, you need to register ``DoctrineTokenProvider`` as a service:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            # ...
+
+            Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider: ~
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider"/>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider;
+
+        $container->register(DoctrineTokenProvider::class);
+
+Then you need to create a table with the following structure in your database
+so ``DoctrineTokenProvider`` can store the tokens:
+
+.. code-block:: sql
+
+    CREATE TABLE `rememberme_token` (
+        `series`   char(88)     UNIQUE PRIMARY KEY NOT NULL,
+        `value`    char(88)     NOT NULL,
+        `lastUsed` datetime     NOT NULL,
+        `class`    varchar(100) NOT NULL,
+        `username` varchar(200) NOT NULL
+    );
+
+Finally, set the ``token_provider`` option of the ``remember_me`` config to the
+service you just created:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            firewalls:
+                main:
+                    # ...
+                    remember_me:
+                        # ...
+                        token_provider: 'Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider'
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+
+                <firewall name="main">
+                    <!-- ... -->
+
+                    <remember-me
+                        token_provider="Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider"
+                        />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        $container->loadFromExtension('security', [
+            // ...
+
+            'firewalls' => [
+                'main' => [
+                    // ...
+                    'remember_me' => [
+                        // ...
+                        'token_provider' => 'Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider',
+                    ],
+                ],
+            ],
+        ]);
diff --git a/security/security_checker.rst b/security/security_checker.rst
deleted file mode 100644
index fc6ea1da618..00000000000
--- a/security/security_checker.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-.. index::
-    single: Security; Vulnerability Checker
-
-How to Check for Known Security Vulnerabilities in Your Dependencies
-====================================================================
-
-When using lots of dependencies in your Symfony projects, some of them may
-contain security vulnerabilities. That's why Symfony provides a command called
-``security:check`` that checks your ``composer.lock`` file to find any known
-security vulnerability in your installed dependencies.
-
-First, install the security checker in your project:
-
-.. code-block:: terminal
-
-    $ composer require sensiolabs/security-checker
-
-Then run this command:
-
-.. code-block:: terminal
-
-    $ php bin/console security:check
-
-A good security practice is to execute this command regularly to be able to
-update or replace compromised dependencies as soon as possible. Internally,
-this command uses the public `security advisories database`_ published by the
-FriendsOfPHP organization.
-
-.. tip::
-
-    The ``security:check`` command terminates with a non-zero exit code if
-    any of your dependencies is affected by a known security vulnerability.
-    This allows you to add it to your project build process and your continuous
-    integration workflows.
-
-.. tip::
-
-    The security checker is also available as an independent console application
-    and distributed as a PHAR file so you can use it in any PHP application.
-    Check out the `Security Checker repository`_ for more details.
-
-.. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
-.. _`Security Checker repository`: https://github.com/sensiolabs/security-checker
diff --git a/security/user_checkers.rst b/security/user_checkers.rst
index 222a72a6276..24d0e4051e1 100644
--- a/security/user_checkers.rst
+++ b/security/user_checkers.rst
@@ -16,9 +16,7 @@ User checkers are classes that must implement the
 defines two methods called ``checkPreAuth()`` and ``checkPostAuth()`` to
 perform checks before and after user authentication. If one or more conditions
 are not met, an exception should be thrown which extends the
-:class:`Symfony\\Component\\Security\\Core\\Exception\\AccountStatusException`.
-
-.. code-block:: php
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AccountStatusException`::
 
     namespace App\Security;
 
@@ -39,12 +37,7 @@ are not met, an exception should be thrown which extends the
 
             // user is deleted, show a generic Account Not Found message.
             if ($user->isDeleted()) {
-                throw new AccountDeletedException('...');
-
-                // or to customize the message shown
-                throw new CustomUserMessageAuthenticationException(
-                    'Your account was deleted. Sorry about that!'
-                );
+                throw new AccountDeletedException();
             }
         }
 
@@ -93,7 +86,7 @@ is the service id of your user checker:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:srv="http://symfony.com/schema/dic/services"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
                 <!-- ... -->
diff --git a/security/user_provider.rst b/security/user_provider.rst
index fd1f2103953..e4628a7ec31 100644
--- a/security/user_provider.rst
+++ b/security/user_provider.rst
@@ -1,8 +1,7 @@
-All about User Providers
-========================
+Security User Providers
+=======================
 
-Each User class in your app will usually need its own "user provider": a class
-that has two jobs:
+User providers are PHP classes related to Symfony Security that have two jobs:
 
 **Reload the User from the Session**
     At the beginning of each request (unless your firewall is ``stateless``), Symfony
@@ -12,26 +11,264 @@ that has two jobs:
     has "changed" and de-authenticates the user if they have (see :ref:`user_session_refresh`).
 
 **Load the User for some Feature**
-    Some features, like ``switch_user``, ``remember_me`` and many of the built-in
+    Some features, like :doc:`user impersonation </security/impersonating_user>`,
+    :doc:`Remember Me </security/remember_me>` and many of the built-in
     :doc:`authentication providers </security/auth_providers>`, use the user provider
     to load a User object via its "username" (or email, or whatever field you want).
 
 Symfony comes with several built-in user providers:
 
-.. toctree::
-    :hidden:
+* :ref:`Entity User Provider <security-entity-user-provider>` (loads users from
+  a database);
+* :ref:`LDAP User Provider <security-ldap-user-provider>` (loads users from a
+  LDAP server);
+* :ref:`Memory User Provider <security-memory-user-provider>` (loads users from
+  a configuration file);
+* :ref:`Chain User Provider <security-chain-user-provider>` (merges two or more
+  user providers into a new user provider).
+
+The built-in user providers cover all the needs for most applications, but you
+can also create your own :ref:`custom user provider <custom-user-provider>`.
+
+.. _security-entity-user-provider:
+
+Entity User Provider
+--------------------
+
+This is the most common user provider for traditional web applications. Users
+are stored in a database and the user provider uses :doc:`Doctrine </doctrine>`
+to retrieve them:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+            # ...
+
+            providers:
+                users:
+                    entity:
+                        # the class of the entity that represents users
+                        class: 'App\Entity\User'
+                        # the property to query by - e.g. username, email, etc
+                        property: 'username'
+                        # optional: if you're using multiple Doctrine entity
+                        # managers, this option defines which one to use
+                        # manager_name: 'customer'
+
+            # ...
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <provider name="users">
+                    <!-- 'class' is the entity that represents users and 'property'
+                         is the entity property to query by - e.g. username, email, etc -->
+                    <entity class="App\Entity\User" property="username"/>
+
+                    <!-- optional: if you're using multiple Doctrine entity
+                         managers, this option defines which one to use -->
+                    <!-- <entity class="App\Entity\User" property="username"
+                                 manager-name="customer"/> -->
+                </provider>
+
+                <!-- ... -->
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Entity\User;
+
+        $container->loadFromExtension('security', [
+            'providers' => [
+                'users' => [
+                    'entity' => [
+                        // the class of the entity that represents users
+                        'class'    => User::class,
+                        // the property to query by - e.g. username, email, etc
+                        'property' => 'username',
+                        // optional: if you're using multiple Doctrine entity
+                        // managers, this option defines which one to use
+                        // 'manager_name' => 'customer',
+                    ],
+                ],
+            ],
+
+            // ...
+        ]);
+
+The ``providers`` section creates a "user provider" called ``users`` that knows
+how to query from your ``App\Entity\User`` entity by the ``username`` property.
+You can choose any name for the user provider, but it's recommended to pick a
+descriptive name because this will be later used in the firewall configuration.
+
+.. _authenticating-someone-with-a-custom-entity-provider:
+
+Using a Custom Query to Load the User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``entity`` provider can only query from one *specific* field, specified by
+the ``property`` config key. If you want a bit more control over this - e.g. you
+want to find a user by ``email`` *or* ``username``, you can do that by making
+your ``UserRepository`` implement the
+:class:`Symfony\\Bridge\\Doctrine\\Security\\User\\UserLoaderInterface`. This
+interface only requires one method: ``loadUserByUsername($username)``::
+
+    // src/Repository/UserRepository.php
+    namespace App\Repository;
+
+    use Doctrine\ORM\EntityRepository;
+    use Symfony\Bridge\Doctrine\Security\User\UserLoaderInterface;
+
+    class UserRepository extends EntityRepository implements UserLoaderInterface
+    {
+        // ...
+
+        public function loadUserByUsername($usernameOrEmail)
+        {
+            return $this->createQueryBuilder('u')
+                ->where('u.username = :query OR u.email = :query')
+                ->setParameter('query', $usernameOrEmail)
+                ->getQuery()
+                ->getOneOrNullResult();
+        }
+    }
+
+To finish this, remove the ``property`` key from the user provider in
+``security.yaml``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            providers:
+                users:
+                    entity:
+                        class: App\Entity\User
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+
+                <provider name="users">
+                    <entity class="App\Entity\User"/>
+                </provider>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Entity\User;
+
+        $container->loadFromExtension('security', [
+            // ...
+
+            'providers' => [
+                'users' => [
+                    'entity' => [
+                        'class' => User::class,
+                    ],
+                ],
+            ],
+        ]);
+
+This tells Symfony to *not* query automatically for the User. Instead, when
+needed (e.g. because :doc:`user impersonation </security/impersonating_user>`,
+:doc:`Remember Me </security/remember_me>`, or some other security feature is
+activated), the ``loadUserByUsername()`` method on ``UserRepository`` will be called.
 
-    entity_provider
+.. _security-memory-user-provider:
 
-* :doc:`entity: (load users from the database) </security/entity_provider>`
-* :doc:`ldap </security/ldap>`
-* ``memory`` (users are hardcoded in config)
-* ``chain`` (try multiple user providers)
+Memory User Provider
+--------------------
 
-Or you can create a :ref:`custom user provider <custom-user-provider>`.
+It's not recommended to use this provider in real applications because of its
+limitations and how difficult it is to manage users. It may be useful in application
+prototypes and for limited applications that don't store users in databases.
 
-User providers are configured in ``config/packages/security.yaml`` under the
-``providers`` key, and each has different configuration options:
+This user provider stores all user information in a configuration file,
+including their passwords. That's why the first step is to configure how these
+users will encode their passwords:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+            encoders:
+                # this internal class is used by Symfony to represent in-memory users
+                Symfony\Component\Security\Core\User\User: 'bcrypt'
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+            <config>
+                <!-- ... -->
+
+                <!-- this internal class is used by Symfony to represent in-memory users -->
+                <encoder class="Symfony\Component\Security\Core\User\User"
+                    algorithm="bcrypt"
+                />
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+
+        // this internal class is used by Symfony to represent in-memory users
+        use Symfony\Component\Security\Core\User\User;
+
+        $container->loadFromExtension('security', [
+            // ...
+            'encoders' => [
+                User::class => [
+                    'algorithm' => 'bcrypt',
+                ],
+            ],
+        ]);
+
+Then, run this command to encode the plain text passwords of your users:
+
+.. code-block:: terminal
+
+    $ php bin/console security:encode-password
+
+Now you can configure all the user information in ``config/packages/security.yaml``:
 
 .. code-block:: yaml
 
@@ -39,37 +276,72 @@ User providers are configured in ``config/packages/security.yaml`` under the
     security:
         # ...
         providers:
-            # this becomes the internal name of the provider
-            # not usually important, but can be used to specify which
-            # provider you want for which firewall (advanced case) or
-            # for a specific authentication provider
-            some_provider_key:
-
-                # provider type - one of the above
+            backend_users:
                 memory:
-                    # custom options for that provider
                     users:
-                        user:  { password: '%env(USER_PASSWORD)%', roles: [ 'ROLE_USER' ] }
-                        admin: { password: '%env(ADMIN_PASSWORD)%', roles: [ 'ROLE_ADMIN' ] }
+                        john_admin: { password: '$2y$13$jxGxc ... IuqDju', roles: ['ROLE_ADMIN'] }
+                        jane_admin: { password: '$2y$13$PFi1I ... rGwXCZ', roles: ['ROLE_ADMIN', 'ROLE_SUPER_ADMIN'] }
+
+.. _security-ldap-user-provider:
+
+LDAP User Provider
+------------------
+
+This user provider requires installing certain dependencies and using some
+special authentication providers, so it's explained in a separate article:
+:doc:`/security/ldap`.
 
-            a_chain_provider:
+.. _security-chain-user-provider:
+
+Chain User Provider
+-------------------
+
+This user provider combines two or more of the other provider types (``entity``,
+``memory`` and ``ldap``) to create a new user provider. The order in which
+providers are configured is important because Symfony will look for users
+starting from the first provider and will keep looking for in the other
+providers until the user is found:
+
+.. code-block:: yaml
+
+    # config/packages/security.yaml
+    security:
+        # ...
+        providers:
+            backend_users:
+                memory:
+                    # ...
+
+            legacy_users:
+                entity:
+                    # ...
+
+            users:
+                entity:
+                    # ...
+
+            all_users:
                 chain:
-                    providers: [some_provider_key, another_provider_key]
+                    providers: ['legacy_users', 'users', 'backend']
 
 .. _custom-user-provider:
 
 Creating a Custom User Provider
 -------------------------------
 
-If you're loading users from a custom location (e.g. via an API or legacy database
-connection), you'll need to create a custom user provider class. First, make sure
-you've followed the :doc:`Security Guide </security>` to create your ``User`` class.
+Most applications don't need to create a custom provider. If you store users in
+a database, a LDAP server or a configuration file, Symfony supports that.
+However, if you're loading users from a custom location (e.g. via an API or
+legacy database connection), you'll need to create a custom user provider.
+
+First, make sure you've followed the :doc:`Security Guide </security>` to create
+your ``User`` class.
 
-If you used the ``make:user`` command to create your ``User`` class (and you answered
-the questions indicating that you need a custom user provider), that command will
-generate a nice skeleton to get you started::
+If you used the ``make:user`` command to create your ``User`` class (and you
+answered the questions indicating that you need a custom user provider), that
+command will generate a nice skeleton to get you started::
 
-    // .. src/Security/UserProvider.php
+    // src/Security/UserProvider.php
     namespace App\Security;
 
     use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
@@ -107,7 +379,7 @@ generate a nice skeleton to get you started::
          * called. Your job is to make sure the user's data is still fresh by,
          * for example, re-querying for fresh User data.
          *
-         * If your firewall is "stateless: false" (for a pure API), this
+         * If your firewall is "stateless: true" (for a pure API), this
          * method is not called.
          *
          * @return UserInterface
@@ -132,34 +404,32 @@ generate a nice skeleton to get you started::
         }
     }
 
-Most of the work is already done! Read the comments in the code and update the TODO
-sections to finish the user provider.
-
-When you're done, tell Symfony about the user provider by adding it in ``security.yaml``:
+Most of the work is already done! Read the comments in the code and update the
+TODO sections to finish the user provider. When you're done, tell Symfony about
+the user provider by adding it in ``security.yaml``:
 
 .. code-block:: yaml
 
     # config/packages/security.yaml
     security:
         providers:
-            # internal name - can be anything
+            # the name of your user provider can be anything
             your_custom_user_provider:
                 id: App\Security\UserProvider
 
-That's it! When you use any of the features that require a user provider, your
-provider will be used! If you have multiple firewalls and multiple providers,
-you can specify *which* provider to use by adding a ``provider`` key under your
-firewall and setting it to the internal name you gave to your user provider.
+Lastly, update the ``config/packages/security.yaml`` file to set the
+``provider`` key to ``your_custom_user_provider`` in all the firewalls which
+will use this custom user provider.
 
 .. _user_session_refresh:
 
 Understanding how Users are Refreshed from the Session
 ------------------------------------------------------
 
-At the end of every request (unless your firewall is ``stateless``), your ``User``
-object is serialized to the session. At the beginning of the next request, it's
-deserialized and then passed to your user provider to "refresh" it (e.g. Doctrine
-queries for a fresh user).
+At the end of every request (unless your firewall is ``stateless``), your
+``User`` object is serialized to the session. At the beginning of the next
+request, it's deserialized and then passed to your user provider to "refresh" it
+(e.g. Doctrine queries for a fresh user).
 
 Then, the two User objects (the original from the session and the refreshed User
 object) are "compared" to see if they are "equal". By default, the core
@@ -182,3 +452,58 @@ Or, if you need more control over the "compare users" process, make your User cl
 implement :class:`Symfony\\Component\\Security\\Core\\User\\EquatableInterface`.
 Then, your ``isEqualTo()`` method will be called when comparing users.
 
+Injecting a User Provider in your Services
+------------------------------------------
+
+Symfony defines several services related to user providers:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:container user.provider
+
+      Select one of the following services to display its information:
+      [0] security.user.provider.in_memory
+      [1] security.user.provider.in_memory.user
+      [2] security.user.provider.ldap
+      [3] security.user.provider.chain
+      ...
+
+Most of these services are abstract and cannot be injected in your services.
+Instead, you must inject the normal service that Symfony creates for each of
+your user providers. The names of these services follow this pattern:
+``security.user.provider.concrete.<your-provider-name>``.
+
+For example, if you are :doc:`building a form login </security/form_login_setup>`
+and want to inject in your ``LoginFormAuthenticator`` a user provider of type
+``memory`` and called  ``backend_users``, do the following::
+
+    // src/Security/LoginFormAuthenticator.php
+    namespace App\Security;
+
+    use Symfony\Component\Security\Core\User\InMemoryUserProvider;
+    use Symfony\Component\Security\Guard\Authenticator\AbstractFormLoginAuthenticator;
+
+    class LoginFormAuthenticator extends AbstractFormLoginAuthenticator
+    {
+        private $userProvider;
+
+        // change the 'InMemoryUserProvider' type-hint in the constructor if
+        // you are injecting a different type of user provider
+        public function __construct(InMemoryUserProvider $userProvider, /* ... */)
+        {
+            $this->userProvider = $userProvider;
+            // ...
+        }
+    }
+
+Then, inject the concrete service created by Symfony for the ``backend_users``
+user provider:
+
+.. code-block:: yaml
+
+    # config/services.yaml
+    services:
+        # ...
+
+        App\Security\LoginFormAuthenticator:
+            $userProvider: '@security.user.provider.concrete.backend_users'
diff --git a/security/voters.rst b/security/voters.rst
index 31a20ea3475..b0fd95411fc 100644
--- a/security/voters.rst
+++ b/security/voters.rst
@@ -296,11 +296,11 @@ security configuration:
             xmlns:srv="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd"
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
         >
 
             <config>
-                <access-decision-manager strategy="unanimous" allow-if-all-abstain="false"  />
+                <access-decision-manager strategy="unanimous" allow-if-all-abstain="false"/>
             </config>
         </srv:container>
 
diff --git a/serializer.rst b/serializer.rst
index 66a1f7fa782..85d5cf7ab6b 100644
--- a/serializer.rst
+++ b/serializer.rst
@@ -14,12 +14,12 @@ its philosophy and the normalizers and encoders terminology.
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the serializer before using it:
 
 .. code-block:: terminal
 
-    $ composer require symfony/serializer
+    $ composer require symfony/serializer-pack
 
 Using the Serializer Service
 ----------------------------
@@ -97,11 +97,11 @@ properties and setters (``setXxx()``) to change properties:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="get_set_method_normalizer" class="Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer" public="false">
-                    <tag name="serializer.normalizer" />
+                    <tag name="serializer.normalizer"/>
                 </service>
             </services>
         </container>
@@ -132,9 +132,13 @@ to your class and choose which groups to use when serializing::
 
     $json = $serializer->serialize(
         $someObject,
-        'json', ['groups' => ['group1']]
+        'json', ['groups' => 'group1']
     );
 
+.. tip::
+
+    The value of the ``groups`` key can be a single string, or an array of strings.
+
 In addition to the ``@Groups`` annotation, the Serializer component also
 supports YAML or XML files. These files are automatically loaded when being
 stored in one of the following locations:
@@ -153,7 +157,7 @@ Configuring the Metadata Cache
 
 The metadata for the serializer is automatically cached to enhance application
 performance. By default, the serializer uses the ``cache.system`` cache pool
-which is configured using the :ref:`cache.system <reference-cache-systen>`
+which is configured using the :ref:`cache.system <reference-cache-system>`
 option.
 
 Enabling a Name Converter
@@ -182,7 +186,7 @@ value:
         <!-- config/packages/framework.xml -->
         <framework:config>
             <!-- ... -->
-            <framework:serializer name-converter="serializer.name_converter.camel_case_to_snake_case" />
+            <framework:serializer name-converter="serializer.name_converter.camel_case_to_snake_case"/>
         </framework:config>
 
     .. code-block:: php
@@ -198,8 +202,19 @@ value:
 Going Further with the Serializer
 ---------------------------------
 
-`ApiPlatform`_ provides an API system supporting `JSON-LD`_ and `Hydra Core Vocabulary`_
-hypermedia formats. It is built on top of the Symfony Framework and its Serializer
+`API Platform`_ provides an API system supporting the following formats:
+
+* `JSON-LD`_ along with the `Hydra Core Vocabulary`_
+* `OpenAPI`_ v2 (formerly Swagger) and v3
+* `GraphQL`_
+* `JSON:API`_
+* `HAL`_
+* JSON
+* XML
+* YAML
+* CSV
+
+It is built on top of the Symfony Framework and its Serializer
 component. It provides custom normalizers and a custom encoder, custom metadata
 and a caching system.
 
@@ -213,8 +228,11 @@ take a look at how this bundle works.
     serializer/custom_encoders
     serializer/custom_normalizer
 
-.. _`APCu`: https://github.com/krakjoe/apcu
-.. _`ApiPlatform`: https://github.com/api-platform/core
+.. _`API Platform`: https://api-platform.com
 .. _`JSON-LD`: http://json-ld.org
 .. _`Hydra Core Vocabulary`: http://hydra-cg.com
+.. _`OpenAPI`: https://www.openapis.org
+.. _`GraphQL`: https://graphql.org
+.. _`JSON:API`: https://jsonapi.org
+.. _`HAL`: http://stateless.co/hal_specification.html
 .. _`Data URIs`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
diff --git a/serializer/custom_encoders.rst b/serializer/custom_encoders.rst
index f2ec339468b..5bb78def4e4 100644
--- a/serializer/custom_encoders.rst
+++ b/serializer/custom_encoders.rst
@@ -48,6 +48,14 @@ create your own encoder that uses the
         }
     }
 
+.. tip::
+
+    If you need access to ``$context`` in your ``supportsDecoding`` or
+    ``supportsEncoding`` method, make sure to implement
+    ``Symfony\Component\Serializer\Encoder\ContextAwareDecoderInterface``
+    or ``Symfony\Component\Serializer\Encoder\ContextAwareEncoderInterface`` accordingly.
+
+
 Registering it in your app
 --------------------------
 
@@ -61,5 +69,3 @@ that's done automatically!
     to register your class as a service and tag it with ``serializer.encoder``.
 
 Now you'll be able to serialize and deserialize YAML!
-
-.. _tracker: https://github.com/symfony/symfony/issues
diff --git a/serializer/custom_normalizer.rst b/serializer/custom_normalizer.rst
index ed149c26a57..9f2e50fdcf1 100644
--- a/serializer/custom_normalizer.rst
+++ b/serializer/custom_normalizer.rst
@@ -21,10 +21,10 @@ to customize the normalized data. To do that, leverage the ``ObjectNormalizer``:
 
     use App\Entity\Topic;
     use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
-    use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+    use Symfony\Component\Serializer\Normalizer\ContextAwareNormalizerInterface;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
 
-    class TopicNormalizer implements NormalizerInterface
+    class TopicNormalizer implements ContextAwareNormalizerInterface
     {
         private $router;
         private $normalizer;
@@ -47,7 +47,7 @@ to customize the normalized data. To do that, leverage the ``ObjectNormalizer``:
             return $data;
         }
 
-        public function supportsNormalization($data, $format = null)
+        public function supportsNormalization($data, $format = null, array $context = [])
         {
             return $data instanceof Topic;
         }
diff --git a/serializer/normalizers.rst b/serializer/normalizers.rst
index e38d29578ae..42e6481bbdc 100644
--- a/serializer/normalizers.rst
+++ b/serializer/normalizers.rst
@@ -12,8 +12,8 @@ denormalizing (array to object).
 
 Normalizers are enabled in the serializer passing them as its first argument::
 
-    use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+    use Symfony\Component\Serializer\Serializer;
 
     $normalizers = [new ObjectNormalizer()];
     $serializer = new Serializer($normalizers);
@@ -28,7 +28,7 @@ Symfony includes the following normalizers but you can also
   normalize PHP object using the :doc:`PropertyAccessor component </components/property_access>`;
 * :class:`Symfony\\Component\\Serializer\\Normalizer\\CustomNormalizer` to
   normalize PHP object using an object that implements
-  ``:class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizableInterface``;
+  :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizableInterface`;
 * :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` to
   normalize PHP object using the getter and setter methods of the object;
 * :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` to
diff --git a/service_container.rst b/service_container.rst
index 44e20000cd5..fc5405c1d7e 100644
--- a/service_container.rst
+++ b/service_container.rst
@@ -49,17 +49,21 @@ What other services are available? Find out by running:
 
     $ php bin/console debug:autowiring
 
-    # this is just a *small* sample of the output...
-    ==========================================================  ==================================
-    Class/Interface Type                                        Alias Service ID
-    ==========================================================  ==================================
-    Psr\Cache\CacheItemPoolInterface                            alias for "cache.app.recorder"
-    Psr\Log\LoggerInterface                                     alias for "monolog.logger"
-    Symfony\Component\EventDispatcher\EventDispatcherInterface  alias for "debug.event_dispatcher"
-    Symfony\Component\HttpFoundation\RequestStack               alias for "request_stack"
-    Symfony\Component\HttpFoundation\Session\SessionInterface   alias for "session"
-    Symfony\Component\Routing\RouterInterface                   alias for "router.default"
-    ==========================================================  ==================================
+      # this is just a *small* sample of the output...
+
+      Describes a logger instance.
+      Psr\Log\LoggerInterface (monolog.logger)
+
+      Request stack that controls the lifecycle of requests.
+      Symfony\Component\HttpFoundation\RequestStack (request_stack)
+
+      Interface for the session.
+      Symfony\Component\HttpFoundation\Session\SessionInterface (session)
+
+      RouterInterface is the interface that all Router classes must implement.
+      Symfony\Component\Routing\RouterInterface (router.default)
+
+      [...]
 
 When you use these type-hints in your controller methods or inside your
 :ref:`own services <service-container-creating-service>`, Symfony will automatically
@@ -154,7 +158,7 @@ each time you ask for it.
                 # this creates a service per class whose id is the fully-qualified class name
                 App\:
                     resource: '../src/*'
-                    exclude: '../src/{Entity,Migrations,Tests,Kernel.php}'
+                    exclude: '../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}'
 
                 # ...
 
@@ -165,13 +169,13 @@ each time you ask for it.
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <services>
                     <!-- Default configuration for services in *this* file -->
-                    <defaults autowire="true" autoconfigure="true" public="false" />
+                    <defaults autowire="true" autoconfigure="true" public="false"/>
 
-                    <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}" />
+                    <prototype namespace="App\" resource="../src/*" exclude="../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}"/>
                 </services>
             </container>
 
@@ -190,7 +194,7 @@ each time you ask for it.
             ;
 
             // $this is a reference to the current loader
-            $this->registerClasses($definition, 'App\\', '../src/*', '../src/{Entity,Migrations,Tests}');
+            $this->registerClasses($definition, 'App\\', '../src/*', '../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}');
 
     .. tip::
 
@@ -198,10 +202,6 @@ each time you ask for it.
         `glob pattern`_. The value of the ``exclude`` option can also be an
         array of glob patterns.
 
-        .. versionadded:: 4.2
-            The feature to pass arrays of glob patterns to the ``exclude``
-            option was introduced in Symfony 4.2.
-
     Thanks to this configuration, you can automatically use any classes from the
     ``src/`` directory as a service, without needing to manually configure
     it. Later, you'll learn more about this in :ref:`service-psr4-loader`.
@@ -261,18 +261,21 @@ type-hints by running:
 
     $ php bin/console debug:autowiring
 
-This command is your best friend.  This is a small subset of the output:
+      # this is just a *small* sample of the output...
+
+      Describes a logger instance.
+      Psr\Log\LoggerInterface (monolog.logger)
+
+      Request stack that controls the lifecycle of requests.
+      Symfony\Component\HttpFoundation\RequestStack (request_stack)
+
+      Interface for the session.
+      Symfony\Component\HttpFoundation\Session\SessionInterface (session)
 
-=============================================================== =====================================
-Class/Interface Type                                            Alias Service ID
-=============================================================== =====================================
-``Psr\Cache\CacheItemPoolInterface``                            alias for "cache.app.recorder"
-``Psr\Log\LoggerInterface``                                     alias for "monolog.logger"
-``Symfony\Component\EventDispatcher\EventDispatcherInterface``  alias for "debug.event_dispatcher"
-``Symfony\Component\HttpFoundation\RequestStack``               alias for "request_stack"
-``Symfony\Component\HttpFoundation\Session\SessionInterface``   alias for "session"
-``Symfony\Component\Routing\RouterInterface``                   alias for "router.default"
-=============================================================== =====================================
+      RouterInterface is the interface that all Router classes must implement.
+      Symfony\Component\Routing\RouterInterface (router.default)
+
+      [...]
 
 Handling Multiple Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -407,13 +410,13 @@ pass here. No problem! In your configuration, you can explicitly set this argume
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <!-- Same as before -->
-                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}" />
+                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}"/>
 
                 <!-- Explicitly configure the service -->
                 <service id="App\Updates\SiteUpdateManager">
@@ -457,23 +460,29 @@ Service Parameters
 ------------------
 
 In addition to holding service objects, the container also holds configuration,
-called ``parameters``. To create a parameter, add it under the ``parameters`` key
-and reference it with the ``%parameter_name%`` syntax:
+called **parameters**. The main article about Symfony configuration explains the
+:ref:`configuration parameters <configuration-parameters>` in detail and shows
+all their types (string, boolean, array, binary and PHP constant parameters).
+
+However, there is another type of parameter related to services. In YAML config,
+any string which starts with ``@`` is considered as the ID of a service, instead
+of a regular string. In XML config, use the ``type="service"`` type for the
+parameter and in PHP config use the ``Reference`` class:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # config/services.yaml
-        parameters:
-            admin_email: manager@example.com
-
         services:
-            # ...
+            App\Service\MessageGenerator:
+                # this is not a string, but a reference to a service called 'logger'
+                arguments: ['@logger']
 
-            App\Updates\SiteUpdateManager:
-                arguments:
-                    $adminEmail: '%admin_email%'
+                # if the value of a string parameter starts with '@', you need to escape
+                # it by adding another '@' so Symfony doesn't consider it a service
+                # (this will be parsed as the string '@securepassword')
+                mailer_password: '@@securepassword'
 
     .. code-block:: xml
 
@@ -482,17 +491,11 @@ and reference it with the ``%parameter_name%`` syntax:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="admin_email">manager@example.com</parameter>
-            </parameters>
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <!-- ... -->
-
-                <service id="App\Updates\SiteUpdateManager">
-                    <argument key="$adminEmail">%admin_email%</argument>
+                <service id="App\Service\MessageGenerator">
+                    <argument type="service" id="logger"/>
                 </service>
             </services>
         </container>
@@ -500,45 +503,38 @@ and reference it with the ``%parameter_name%`` syntax:
     .. code-block:: php
 
         // config/services.php
-        use App\Updates\SiteUpdateManager;
-        $container->setParameter('admin_email', 'manager@example.com');
-
-        $container->autowire(SiteUpdateManager::class)
-            // ...
-            ->setArgument('$adminEmail', '%admin_email%');
+        use App\Service\MessageGenerator;
+        use Symfony\Component\DependencyInjection\Reference;
 
-Actually, once you define a parameter, it can be referenced via the
-``%parameter_name%`` syntax in *any* other configuration file. Many parameters
-are defined in the ``config/services.yaml`` file.
+        $container->autowire(MessageGenerator::class)
+            ->setAutoconfigured(true)
+            ->setPublic(false)
+            ->setArgument(0, new Reference('logger'));
 
-You can then fetch the parameter in the service::
+Working with container parameters is straightforward using the container's
+accessor methods for parameters::
 
-    class SiteUpdateManager
-    {
-        // ...
+    // checks if a parameter is defined (parameter names are case-sensitive)
+    $container->hasParameter('mailer.transport');
 
-        private $adminEmail;
+    // gets value of a parameter
+    $container->getParameter('mailer.transport');
 
-        public function __construct($adminEmail)
-        {
-            $this->adminEmail = $adminEmail;
-        }
-    }
+    // adds a new parameter
+    $container->setParameter('mailer.transport', 'sendmail');
 
-You can also fetch parameters directly from the container::
-
-    public function new()
-    {
-        // ...
+.. caution::
 
-        // this ONLY works if you extend the base Controller
-        $adminEmail = $this->container->getParameter('admin_email');
+    The used ``.`` notation is a
+    :ref:`Symfony convention <service-naming-conventions>` to make parameters
+    easier to read. Parameters are flat key-value elements, they can't
+    be organized into a nested array
 
-        // or a shorter way!
-        // $adminEmail = $this->getParameter('admin_email');
-    }
+.. note::
 
-For more info about parameters, see :doc:`/service_container/parameters`.
+    You can only set a parameter before the container is compiled, not at run-time.
+    To learn more about compiling the container see
+    :doc:`/components/dependency_injection/compilation`.
 
 .. _services-wire-specific-service:
 
@@ -594,14 +590,14 @@ But, you can control this and pass in a different logger:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... same code as before -->
 
                 <!-- Explicitly configure the service -->
                 <service id="App\Service\MessageGenerator">
-                    <argument key="$logger" type="service" id="monolog.logger.request" />
+                    <argument key="$logger" type="service" id="monolog.logger.request"/>
                 </service>
             </services>
         </container>
@@ -655,6 +651,10 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
                     # service that's defined in this file
                     Psr\Log\LoggerInterface: '@monolog.logger.request'
 
+                    # optionally you can define both the name and type of the argument to match
+                    string $adminEmail: 'manager@example.com'
+                    Psr\Log\LoggerInterface $requestLogger: '@monolog.logger.request'
+
             # ...
 
     .. code-block:: xml
@@ -664,7 +664,7 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <defaults autowire="true" autoconfigure="true" public="false">
@@ -677,6 +677,13 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
                         type="service"
                         id="monolog.logger.request"
                     />
+
+                    <!-- optionally you can define both the name and type of the argument to match -->
+                    <bind key="string $adminEmail">manager@example.com</bind>
+                    <bind key="Psr\Log\LoggerInterface $requestLogger"
+                        type="service"
+                        id="monolog.logger.request"
+                    />
                 </defaults>
 
                 <!-- ... -->
@@ -687,8 +694,8 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
 
         // config/services.php
         use App\Controller\LuckyController;
-        use Symfony\Component\DependencyInjection\Reference;
         use Psr\Log\LoggerInterface;
+        use Symfony\Component\DependencyInjection\Reference;
 
         $container->register(LuckyController::class)
             ->setPublic(true)
@@ -696,52 +703,20 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type
                 '$adminEmail' => 'manager@example.com',
                 '$requestLogger' => new Reference('monolog.logger.request'),
                 LoggerInterface::class => new Reference('monolog.logger.request'),
+                // optionally you can define both the name and type of the argument to match
+                'string $adminEmail' => 'manager@example.com',
+                LoggerInterface::class.' $requestLogger' => new Reference('monolog.logger.request'),
             ])
         ;
 
 By putting the ``bind`` key under ``_defaults``, you can specify the value of *any*
 argument for *any* service defined in this file! You can bind arguments by name
-(e.g. ``$adminEmail``) or by type (e.g. ``Psr\Log\LoggerInterface``).
+(e.g. ``$adminEmail``), by type (e.g. ``Psr\Log\LoggerInterface``) or both
+(e.g. ``Psr\Log\LoggerInterface $requestLogger``).
 
 The ``bind`` config can also be applied to specific services or when loading many
 services at once (i.e. :ref:`service-psr4-loader`).
 
-Getting Container Parameters as a Service
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 4.1
-    The feature to get container parameters as a service was introduced in Symfony 4.1.
-
-If some service or controller needs lots of container parameters, there's an
-easier alternative to binding all of them with the ``services._defaults.bind``
-option. Type-hint any of its constructor arguments with the
-:class:`Symfony\\Component\\DependencyInjection\\ParameterBag\\ParameterBagInterface`
-or the new :class:`Symfony\\Component\\DependencyInjection\\ParameterBag\\ContainerBagInterface`
-and the service will get all container parameters in a
-:class:`Symfony\\Component\\DependencyInjection\\ParameterBag\\ParameterBag` object::
-
-    // src/Service/MessageGenerator.php
-    // ...
-
-    use Symfony\Component\DependencyInjection\ParameterBag\ParameterBagInterface;
-
-    class MessageGenerator
-    {
-        private $params;
-
-        public function __construct(ParameterBagInterface $params)
-        {
-            $this->params = $params;
-        }
-
-        public function someMethod()
-        {
-            // get any param from $this->params, which stores all container parameters
-            $sender = $this->params->get('mailer_sender');
-            // ...
-        }
-    }
-
 .. _services-autowire:
 
 The autowire Option
@@ -824,7 +799,7 @@ But, if you *do* need to make a service public, override the ``public`` setting:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... same code as before -->
@@ -863,12 +838,12 @@ key. For example, the default Symfony configuration contains this:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
-                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}" />
+                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}"/>
             </services>
         </container>
 
@@ -999,32 +974,32 @@ admin email. In this case, each needs to have a unique service id:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <service id="site_update_manager.superadmin" class="App\Updates\SiteUpdateManager" autowire="false">
-                    <argument type="service" id="App\Service\MessageGenerator" />
-                    <argument type="service" id="mailer" />
+                    <argument type="service" id="App\Service\MessageGenerator"/>
+                    <argument type="service" id="mailer"/>
                     <argument>superadmin@example.com</argument>
                 </service>
 
                 <service id="site_update_manager.normal_users" class="App\Updates\SiteUpdateManager" autowire="false">
-                    <argument type="service" id="App\Service\MessageGenerator" />
-                    <argument type="service" id="mailer" />
+                    <argument type="service" id="App\Service\MessageGenerator"/>
+                    <argument type="service" id="mailer"/>
                     <argument>contact@example.com</argument>
                 </service>
 
-                <service id="App\Updates\SiteUpdateManager" alias="site_update_manager.superadmin" />
+                <service id="App\Updates\SiteUpdateManager" alias="site_update_manager.superadmin"/>
             </services>
         </container>
 
     .. code-block:: php
 
         // config/services.php
-        use App\Updates\SiteUpdateManager;
         use App\Service\MessageGenerator;
+        use App\Updates\SiteUpdateManager;
         use Symfony\Component\DependencyInjection\Reference;
 
         $container->register('site_update_manager.superadmin', SiteUpdateManager::class)
@@ -1066,7 +1041,5 @@ Learn more
 
     /service_container/*
 
-.. _`service-oriented architecture`: https://en.wikipedia.org/wiki/Service-oriented_architecture
-.. _`Symfony Standard Edition (version 3.3) services.yaml`: https://github.com/symfony/symfony-standard/blob/3.3/app/config/services.yml
 .. _`glob pattern`: https://en.wikipedia.org/wiki/Glob_(programming)
 .. _`Symfony Fundamentals screencast series`: https://symfonycasts.com/screencast/symfony-fundamentals
diff --git a/service_container/3.3-di-changes.rst b/service_container/3.3-di-changes.rst
index 15778a4d8ac..7aed2e63980 100644
--- a/service_container/3.3-di-changes.rst
+++ b/service_container/3.3-di-changes.rst
@@ -66,15 +66,15 @@ what the file looks like in Symfony 4):
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <defaults autowire="true" autoconfigure="true" public="false" />
+                <defaults autowire="true" autoconfigure="true" public="false"/>
 
-                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}" />
+                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}"/>
 
                 <prototype namespace="App\Controller\" resource="../src/Controller">
-                    <tag name="controller.service_arguments" />
+                    <tag name="controller.service_arguments"/>
                 </prototype>
 
                 <!-- add more services, or override services that need manual wiring -->
@@ -117,12 +117,12 @@ thanks to the following config:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
-                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}" />
+                <prototype namespace="App\" resource="../src/*" exclude="../src/{Entity,Migrations,Tests}"/>
             </services>
         </container>
 
@@ -190,16 +190,16 @@ service as an argument to another with the following config:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="app.invoice_generator"
-                    class="App\Service\InvoiceGenerator" />
+                    class="App\Service\InvoiceGenerator"/>
 
                 <service id="app.invoice_mailer"
                     class="App\Service\InvoiceMailer">
 
-                    <argument type="service" id="app.invoice_generator" />
+                    <argument type="service" id="app.invoice_generator"/>
                 </service>
             </services>
         </container>
@@ -305,13 +305,13 @@ The third big change is that, in a new Symfony 3.3 project, your controllers are
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <prototype namespace="App\Controller\" resource="../src/Controller">
-                    <tag name="controller.service_arguments" />
+                    <tag name="controller.service_arguments"/>
                 </prototype>
             </services>
         </container>
@@ -373,12 +373,12 @@ create the class::
     // ...
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-    use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
+    use Symfony\Component\HttpKernel\Event\ResponseEvent;
     use Symfony\Component\HttpKernel\KernelEvents;
 
     class SetHeaderSusbcriber implements EventSubscriberInterface
     {
-        public function onKernelResponse(FilterResponseEvent $event)
+        public function onKernelResponse(ResponseEvent $event)
         {
             $event->getResponse()->headers->set('X-SYMFONY-3.3', 'Less config');
         }
@@ -403,8 +403,8 @@ In this case, you've created a class that implements ``EventSubscriberInterface`
 and registered it as a service. This is more than enough for the container to know
 that you want this to be used as an event subscriber: more configuration is not needed.
 And the tags system is its own, Symfony-specific mechanism. And you can
-always set ``autoconfigure`` to ``false`` in ``services.yaml``, or disable it for a specific
-service.
+always set ``autoconfigure`` to ``false`` in ``services.yaml``, or disable it
+for a specific service.
 
     Does this mean tags are dead? Does this work for all tags?
 
@@ -451,13 +451,13 @@ inherited from an abstract definition:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <instanceof id="App\Domain\LoaderInterface" public="true">
-                    <tag name="app.domain_loader" />
+                    <tag name="app.domain_loader"/>
                 </instanceof>
             </services>
         </container>
@@ -523,9 +523,9 @@ Start by adding a ``_defaults`` section with ``autowire`` and ``autoconfigure``.
 
         # ...
 
-This step does not yet change anything yet: you're already *explicitly* configuring all of your services.
-So, ``autowire`` does nothing. You're also already tagging your services, so
-``autoconfigure`` also doesn't change any existing services.
+You're already *explicitly* configuring all of your services. So, ``autowire``
+does nothing. You're also already tagging your services, so ``autoconfigure``
+also doesn't change any existing services.
 
 You have not added ``public: false`` yet. That will come in a minute.
 
@@ -565,7 +565,7 @@ Start by updating the service ids to class names:
     Services associated with global PHP classes (i.e. not using PHP namespaces)
     must maintain the ``class`` parameter. For example, when using the old Twig
     classes (e.g. ``Twig_Extensions_Extension_Intl`` instead of ``Twig\Extensions\IntlExtension``),
-    you can't redefine the service as ``Twig_Extensions_Extension_Intl: ~`` and
+    you can't redefine the service as ``Twig_Extensions_Extension_Intl: ~`` and
     you must keep the original ``class`` parameter.
 
 .. caution::
@@ -629,10 +629,10 @@ Now you're ready to default all services to be private:
     # ...
 
     services:
-         _defaults:
-             autowire: true
-             autoconfigure: true
-    +          public: false
+        _defaults:
+            autowire: true
+            autoconfigure: true
+    +       public: false
 
 Thanks to this, any services created in this file cannot be fetched directly from
 the container. But, since the old service id's are aliases in a separate file (``legacy_aliases.yaml``),
diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst
index 756ab691b68..c1e9da0e790 100644
--- a/service_container/alias_private.rst
+++ b/service_container/alias_private.rst
@@ -45,10 +45,10 @@ You can also control the ``public`` option on a service-by-service basis:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Service\Foo" public="false" />
+                <service id="App\Service\Foo" public="false"/>
             </services>
         </container>
 
@@ -111,12 +111,12 @@ services.
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Mail\PhpMailer" public="false" />
+                <service id="App\Mail\PhpMailer" public="false"/>
 
-                <service id="app.mailer" alias="App\Mail\PhpMailer" />
+                <service id="app.mailer" alias="App\Mail\PhpMailer"/>
             </services>
         </container>
 
@@ -146,6 +146,69 @@ This means that when using the container directly, you can access the
             # ...
             app.mailer: '@App\Mail\PhpMailer'
 
+Deprecating Service Aliases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you decide to deprecate the use of a service alias (because it is outdated
+or you decided not to maintain it anymore), you can deprecate its definition:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        app.mailer:
+            alias: '@App\Mail\PhpMailer'
+
+            # this will display a generic deprecation message...
+            deprecated: true
+
+            # ...but you can also define a custom deprecation message
+            deprecated: 'The "%alias_id%" alias is deprecated. Don\'t use it anymore.'
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.mailer" alias="App\Mail\PhpMailer">
+                    <!-- this will display a generic deprecation message... -->
+                    <deprecated/>
+
+                    <!-- ...but you can also define a custom deprecation message -->
+                    <deprecated>The "%alias_id%" service alias is deprecated. Don't use it anymore.</deprecated>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        $container
+            ->setAlias('app.mailer', 'App\Mail\PhpMailer')
+
+            // this will display a generic deprecation message...
+            ->setDeprecated(true)
+
+            // ...but you can also define a custom deprecation message
+            ->setDeprecated(
+                true,
+                'The "%alias_id%" service alias is deprecated. Don\'t use it anymore.'
+            )
+        ;
+
+Now, every time this service alias is used, a deprecation warning is triggered,
+advising you to stop or to change your uses of that alias.
+
+The message is actually a message template, which replaces occurrences of the
+``%alias_id%`` placeholder by the service alias id. You **must** have at least
+one occurrence of the ``%alias_id%`` placeholder in your template.
+
+.. versionadded:: 4.3
+
+    The ``deprecated`` option for service aliases was introduced in Symfony 4.3.
+
 Anonymous Services
 ------------------
 
@@ -178,12 +241,12 @@ The following example shows how to inject an anonymous service into another serv
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="foo" class="App\Foo">
                     <argument type="service">
-                        <service class="App\AnonymousBar" />
+                        <service class="App\AnonymousBar"/>
                     </argument>
                 </service>
             </services>
@@ -207,7 +270,7 @@ Using an anonymous service as a factory looks like this:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="foo" class="App\Foo">
@@ -230,7 +293,7 @@ or you decided not to maintain it anymore), you can deprecate its definition:
 
         # config/services.yaml
         App\Service\OldService:
-            deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.
+            deprecated: The "%service_id%" service is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0.
 
     .. code-block:: xml
 
@@ -238,11 +301,11 @@ or you decided not to maintain it anymore), you can deprecate its definition:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Service\OldService">
-                    <deprecated>The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.</deprecated>
+                    <deprecated>The "%service_id%" service is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0.</deprecated>
                 </service>
             </services>
         </container>
@@ -256,7 +319,7 @@ or you decided not to maintain it anymore), you can deprecate its definition:
             ->register(OldService::class)
             ->setDeprecated(
                 true,
-                'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.'
+                'The "%service_id%" service is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0.'
             )
         ;
 
diff --git a/service_container/autowiring.rst b/service_container/autowiring.rst
index f5ecb9635d2..0e1fad1aed1 100644
--- a/service_container/autowiring.rst
+++ b/service_container/autowiring.rst
@@ -89,15 +89,15 @@ both services:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <defaults autowire="true" autoconfigure="true" public="false" />
+                <defaults autowire="true" autoconfigure="true" public="false"/>
                 <!-- ... -->
 
-                <service id="App\Service\TwitterClient" autowire="true" />
+                <service id="App\Service\TwitterClient" autowire="true"/>
 
-                <service id="App\Util\Rot13Transformer" autowire="true" />
+                <service id="App\Util\Rot13Transformer" autowire="true"/>
             </services>
         </container>
 
@@ -165,7 +165,7 @@ Autowiring works by reading the ``Rot13Transformer`` *type-hint* in ``TwitterCli
 The autowiring system **looks for a service whose id exactly matches the type-hint**:
 so ``App\Util\Rot13Transformer``. In this case, that exists! When you configured
 the ``Rot13Transformer`` service, you used its fully-qualified class name as its
-id. Autowiring isn't magic: it simply looks for a service whose id matches the type-hint.
+id. Autowiring isn't magic: it looks for a service whose id matches the type-hint.
 If you :ref:`load services automatically <service-container-services-load-example>`,
 each service's id is its class name.
 
@@ -216,13 +216,13 @@ adding a service alias:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
-                <service id="app.rot13.transformer" class="App\Util\Rot13Transformer" autowire="true" />
-                <service id="App\Util\Rot13Transformer" alias="app.rot13.transformer" />
+                <service id="app.rot13.transformer" class="App\Util\Rot13Transformer" autowire="true"/>
+                <service id="App\Util\Rot13Transformer" alias="app.rot13.transformer"/>
             </services>
         </container>
 
@@ -254,8 +254,7 @@ Working with Interfaces
 -----------------------
 
 You might also find yourself type-hinting abstractions (e.g. interfaces) instead
-of concrete classes as it makes it easy to replace your dependencies with other
-objects.
+of concrete classes as it replaces your dependencies with other objects.
 
 To follow this best practice, suppose you decide to create a ``TransformerInterface``::
 
@@ -280,7 +279,7 @@ Now that you have an interface, you should use this as your type-hint::
     {
         public function __construct(TransformerInterface $transformer)
         {
-             // ...
+            // ...
         }
 
         // ...
@@ -312,13 +311,13 @@ To fix that, add an :ref:`alias <service-autowiring-alias>`:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
-                <service id="App\Util\Rot13Transformer" />
+                <service id="App\Util\Rot13Transformer"/>
 
-                <service id="App\Util\TransformerInterface" alias="App\Util\Rot13Transformer" />
+                <service id="App\Util\TransformerInterface" alias="App\Util\Rot13Transformer"/>
             </services>
         </container>
 
@@ -361,12 +360,42 @@ Suppose you create a second class - ``UppercaseTransformer`` that implements
 
 If you register this as a service, you now have *two* services that implement the
 ``App\Util\TransformerInterface`` type. Autowiring subsystem can not decide
-which one to use. Remember, autowiring isn't magic; it simply looks for a service
+which one to use. Remember, autowiring isn't magic; it looks for a service
 whose id matches the type-hint. So you need to choose one by creating an alias
 from the type to the correct service id (see :ref:`autowiring-interface-alias`).
+Additionally, you can define several named autowiring aliases if you want to use
+one implementation in some cases, and another implementation in some
+other cases.
+
+For instance, you may want to use by default the ``Rot13Transformer``
+implementation by default when the ``TransformerInterface`` interface is
+type hinted, but use the ``UppercaseTransformer`` implementation in some
+specific cases. To do so, you can create a normal alias from the
+``TransformerInterface`` interface to ``Rot13Transformer``, and then
+create a *named autowiring alias* from a special string containing the
+interface followed by a variable name matching the one you use when doing
+the injection::
+
+    namespace App\Service;
+
+    use App\Util\TransformerInterface;
+
+    class MastodonClient
+    {
+        private $transformer;
+
+        public function __construct(TransformerInterface $shoutyTransformer)
+        {
+            $this->transformer = $shoutyTransformer;
+        }
 
-If you want ``Rot13Transformer`` to be the service that's used for autowiring, create
-that alias:
+        public function toot($user, $key, $status)
+        {
+            $transformedStatus = $this->transformer->transform($status);
+
+            // ... connect to Mastodon and send the transformed status
+        }
+    }
 
 .. configuration-block::
 
@@ -379,16 +408,22 @@ that alias:
             App\Util\Rot13Transformer: ~
             App\Util\UppercaseTransformer: ~
 
-            # the ``App\Util\Rot13Transformer`` service will be injected when
-            # a ``App\Util\TransformerInterface`` type-hint is detected
+            # the ``App\Util\UppercaseTransformer`` service will be
+            # injected when an ``App\Util\TransformerInterface``
+            # type-hint for a ``$shoutyTransformer`` argument is detected.
+            App\Util\TransformerInterface $shoutyTransformer: '@App\Util\UppercaseTransformer'
+
+            # If the argument used for injection does not match, but the
+            # type-hint still matches, the ``App\Util\Rot13Transformer``
+            # service will be injected.
             App\Util\TransformerInterface: '@App\Util\Rot13Transformer'
 
             App\Service\TwitterClient:
                 # the Rot13Transformer will be passed as the $transformer argument
                 autowire: true
 
-                # If you wanted to choose the non-default service, wire it manually
-                # arguments:
+                # If you wanted to choose the non-default service and do not
+                # want to use a named autowiring alias, wire it manually:
                 #     $transformer: '@App\Util\UppercaseTransformer'
                 # ...
 
@@ -398,17 +433,20 @@ that alias:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
-                <service id="App\Util\Rot13Transformer" />
-                <service id="App\Util\UppercaseTransformer" />
+                <service id="App\Util\Rot13Transformer"/>
+                <service id="App\Util\UppercaseTransformer"/>
 
-                <service id="App\Util\TransformerInterface" alias="App\Util\Rot13Transformer" />
+                <service id="App\Util\TransformerInterface" alias="App\Util\Rot13Transformer"/>
+                <service
+                    id="App\Util\TransformerInterface $shoutyTransformer"
+                    alias="App\Util\UppercaseTransformer"/>
 
                 <service id="App\Service\TwitterClient" autowire="true">
-                    <!-- <argument key="$transformer" type="service" id="App\Util\UppercaseTransformer" /> -->
+                    <!-- <argument key="$transformer" type="service" id="App\Util\UppercaseTransformer"/> -->
                 </service>
             </services>
         </container>
@@ -416,24 +454,36 @@ that alias:
     .. code-block:: php
 
         // config/services.php
+        use App\Service\MastodonClient;
+        use App\Service\TwitterClient;
         use App\Util\Rot13Transformer;
-        use App\Util\UppercaseTransformer;
         use App\Util\TransformerInterface;
-        use App\Service\TwitterClient;
+        use App\Util\UppercaseTransformer;
 
         // ...
         $container->autowire(Rot13Transformer::class);
         $container->autowire(UppercaseTransformer::class);
         $container->setAlias(TransformerInterface::class, Rot13Transformer::class);
+        $container->setAlias(
+            TransformerInterface::class.' $shoutyTransformer',
+            UppercaseTransformer::class
+        );
         $container->autowire(TwitterClient::class)
             //->setArgument('$transformer', new Reference(UppercaseTransformer::class))
         ;
+        $container->autowire(MastodonClient::class);
 
 Thanks to the ``App\Util\TransformerInterface`` alias, any argument type-hinted
 with this interface will be passed the ``App\Util\Rot13Transformer`` service.
-But, you can also manually wire the *other* service by specifying the argument
+If the argument is named ``$shoutyTransformer``,
+``App\Util\UppercaseTransformer`` will be used instead.
+But, you can also manually wire any *other* service by specifying the argument
 under the arguments key.
 
+.. versionadded:: 4.2
+
+    Named autowiring aliases have been introduced in Symfony 4.2.
+
 Fixing Non-Autowireable Arguments
 ---------------------------------
 
@@ -499,6 +549,5 @@ Public and Reusable Bundles
 
 Public bundles should explicitly configure their services and not rely on autowiring.
 
-.. _Rapid Application Development: https://en.wikipedia.org/wiki/Rapid_application_development
 .. _ROT13: https://en.wikipedia.org/wiki/ROT13
 .. _service definition prototype: https://symfony.com/blog/new-in-symfony-3-3-psr-4-based-service-discovery
diff --git a/service_container/calls.rst b/service_container/calls.rst
index eeffdf585ff..a2dbcb7ea2d 100644
--- a/service_container/calls.rst
+++ b/service_container/calls.rst
@@ -51,13 +51,13 @@ To configure the container to call the ``setLogger`` method, use the ``calls`` k
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Service\MessageGenerator">
                     <!-- ... -->
                     <call method="setLogger">
-                        <argument type="service" id="logger" />
+                        <argument type="service" id="logger"/>
                     </call>
                 </service>
             </services>
diff --git a/service_container/compiler_passes.rst b/service_container/compiler_passes.rst
index b9f40d2818b..4d959e93dc6 100644
--- a/service_container/compiler_passes.rst
+++ b/service_container/compiler_passes.rst
@@ -68,16 +68,16 @@ and process the services inside the ``process()`` method::
 Working with Compiler Passes in Bundles
 ---------------------------------------
 
-`Bundles </bundles>`_ can define compiler passes in the ``build()`` method of
+:doc:`Bundles </bundles>` can define compiler passes in the ``build()`` method of
 the main bundle class (this is not needed when implementing the ``process()``
 method in the extension)::
 
     // src/MyBundle/MyBundle.php
     namespace App\MyBundle;
 
-    use Symfony\Component\HttpKernel\Bundle\Bundle;
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use App\DependencyInjection\Compiler\CustomPass;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\HttpKernel\Bundle\Bundle;
 
     class MyBundle extends Bundle
     {
diff --git a/service_container/configurators.rst b/service_container/configurators.rst
index b8b1a28f742..29b06bdea69 100644
--- a/service_container/configurators.rst
+++ b/service_container/configurators.rst
@@ -136,10 +136,10 @@ all the classes are already loaded as services. All you need to do is specify th
 
             # override the services to set the configurator
             App\Mail\NewsletterManager:
-                configurator: 'App\Mail\EmailConfigurator:configure'
+                configurator: ['@App\Mail\EmailConfigurator', 'configure']
 
             App\Mail\GreetingCardManager:
-                configurator: 'App\Mail\EmailConfigurator:configure'
+                configurator: ['@App\Mail\EmailConfigurator', 'configure']
 
     .. code-block:: xml
 
@@ -148,17 +148,17 @@ all the classes are already loaded as services. All you need to do is specify th
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <prototype namespace="App\" resource="../src/*" />
+                <prototype namespace="App\" resource="../src/*"/>
 
                 <service id="App\Mail\NewsletterManager">
-                    <configurator service="App\Mail\EmailConfigurator" method="configure" />
+                    <configurator service="App\Mail\EmailConfigurator" method="configure"/>
                 </service>
 
                 <service id="App\Mail\GreetingCardManager">
-                    <configurator service="App\Mail\EmailConfigurator" method="configure" />
+                    <configurator service="App\Mail\EmailConfigurator" method="configure"/>
                 </service>
             </services>
         </container>
@@ -184,16 +184,78 @@ all the classes are already loaded as services. All you need to do is specify th
         $container->getDefinition(GreetingCardManager::class)
             ->setConfigurator([new Reference(EmailConfigurator::class), 'configure']);
 
-The traditional configurator syntax in YAML files used an array to define
-the service id and the method name:
+.. _configurators-invokable:
 
-.. code-block:: yaml
+.. versionadded:: 4.3
 
-    app.newsletter_manager:
-        # new syntax
-        configurator: 'App\Mail\EmailConfigurator:configure'
-        # old syntax
-        configurator: ['@App\Mail\EmailConfigurator', configure]
+    Invokable configurators for services were introduced in Symfony 4.3.
+
+Services can be configured via invokable configurators (replacing the
+``configure()`` method with ``__invoke()``) by omitting the method name, just as
+routes can reference :ref:`invokable controllers <controller-service-invoke>`.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            # ...
+
+            # registers all classes as services, including App\Mail\EmailConfigurator
+            App\:
+                resource: '../src/*'
+                # ...
+
+            # override the services to set the configurator
+            App\Mail\NewsletterManager:
+                configurator: '@App\Mail\EmailConfigurator'
+
+            App\Mail\GreetingCardManager:
+                configurator: '@App\Mail\EmailConfigurator'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <prototype namespace="App\" resource="../src/*"/>
+
+                <service id="App\Mail\NewsletterManager">
+                    <configurator service="App\Mail\EmailConfigurator"/>
+                </service>
+
+                <service id="App\Mail\GreetingCardManager">
+                    <configurator service="App\Mail\EmailConfigurator"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\Mail\GreetingCardManager;
+        use App\Mail\NewsletterManager;
+        use Symfony\Component\DependencyInjection\Definition;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        // Same as before
+        $definition = new Definition();
+
+        $definition->setAutowired(true);
+
+        $this->registerClasses($definition, 'App\\', '../src/*');
+
+        $container->getDefinition(NewsletterManager::class)
+            ->setConfigurator(new Reference(EmailConfigurator::class));
+
+        $container->getDefinition(GreetingCardManager::class)
+            ->setConfigurator(new Reference(EmailConfigurator::class));
 
 That's it! When requesting the ``App\Mail\NewsletterManager`` or
 ``App\Mail\GreetingCardManager`` service, the created instance will first be
diff --git a/service_container/debug.rst b/service_container/debug.rst
index a477eddd67c..635bbdfa9ae 100644
--- a/service_container/debug.rst
+++ b/service_container/debug.rst
@@ -15,9 +15,6 @@ console. To show all services (public and private) and their PHP classes, run:
     # add this option to display "hidden services" too (those whose ID starts with a dot)
     $ php bin/console debug:container --show-hidden
 
-.. versionadded:: 4.1
-    Hidden services and the ``--show-hidden`` option were introduced in Symfony 4.1.
-
 To see a list of all of the available types that can be used for autowiring, run:
 
 .. code-block:: terminal
diff --git a/service_container/definitions.rst b/service_container/definitions.rst
index b57eb761c24..370f0dc7f25 100644
--- a/service_container/definitions.rst
+++ b/service_container/definitions.rst
@@ -56,8 +56,8 @@ Class
 The first optional argument of the ``Definition`` class is the fully qualified
 class name of the object returned when the service is fetched from the container::
 
-    use App\Config\UserConfigManager;
     use App\Config\CustomConfigManager;
+    use App\Config\UserConfigManager;
     use Symfony\Component\DependencyInjection\Definition;
 
     $definition = new Definition(UserConfigManager::class);
diff --git a/service_container/expression_language.rst b/service_container/expression_language.rst
index 4aa57599c34..ce41f0e184c 100644
--- a/service_container/expression_language.rst
+++ b/service_container/expression_language.rst
@@ -37,7 +37,7 @@ to another service: ``App\Mailer``. One way to do this is with an expression:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
@@ -90,7 +90,7 @@ via a ``container`` variable. Here's another example:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Mailer">
diff --git a/service_container/factories.rst b/service_container/factories.rst
index 39524ccc80c..2c926bab59c 100644
--- a/service_container/factories.rst
+++ b/service_container/factories.rst
@@ -41,7 +41,7 @@ configure the service container to use the
 
             App\Email\NewsletterManager:
                 # call the static method
-                factory: ['App\Email\NewsletterManagerStaticFactory', createNewsletterManager]
+                factory: ['App\Email\NewsletterManagerStaticFactory', 'createNewsletterManager']
 
     .. code-block:: xml
 
@@ -50,17 +50,17 @@ configure the service container to use the
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Email\NewsletterManager">
                     <!-- call the static method -->
-                    <factory class="App\Email\NewsletterManagerStaticFactory" method="createNewsletterManager" />
+                    <factory class="App\Email\NewsletterManagerStaticFactory" method="createNewsletterManager"/>
 
                     <!-- if the factory class is the same as the service class, you can omit
                          the 'class' attribute and define just the 'method' attribute:
 
-                         <factory method="createNewsletterManager" />
+                         <factory method="createNewsletterManager"/>
                     -->
                 </service>
             </services>
@@ -104,7 +104,7 @@ Configuration of the service container then looks like this:
 
             App\Email\NewsletterManager:
                 # call a method on the specified factory service
-                factory: 'App\Email\NewsletterManagerFactory:createNewsletterManager'
+                factory: ['@App\Email\NewsletterManagerFactory', 'createNewsletterManager']
 
     .. code-block:: xml
 
@@ -113,10 +113,10 @@ Configuration of the service container then looks like this:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Email\NewsletterManagerFactory" />
+                <service id="App\Email\NewsletterManagerFactory"/>
 
                 <service id="App\Email\NewsletterManager">
                     <!-- call a method on the specified factory service -->
@@ -132,6 +132,7 @@ Configuration of the service container then looks like this:
         // config/services.php
         use App\Email\NewsletterManager;
         use App\Email\NewsletterManagerFactory;
+        use Symfony\Component\DependencyInjection\Reference;
         // ...
 
         $container->register(NewsletterManagerFactory::class);
@@ -143,19 +144,72 @@ Configuration of the service container then looks like this:
                 'createNewsletterManager',
             ]);
 
-.. note::
+.. _factories-invokable:
+
+Suppose you now change your factory method to ``__invoke()`` so that your
+factory service can be used as a callback::
+
+    class InvokableNewsletterManagerFactory
+    {
+        public function __invoke()
+        {
+            $newsletterManager = new NewsletterManager();
+
+            // ...
 
-    The traditional configuration syntax in YAML files used an array to define
-    the factory service and the method name:
+            return $newsletterManager;
+        }
+    }
+
+.. versionadded:: 4.3
+
+    Invokable factories for services were introduced in Symfony 4.3.
+
+Services can be created and configured via invokable factories by omitting the
+method name, just as routes can reference
+:ref:`invokable controllers <controller-service-invoke>`.
+
+.. configuration-block::
 
     .. code-block:: yaml
 
         # config/services.yaml
-        App\Email\NewsletterManager:
-            # new syntax
-            factory: 'App\Email\NewsletterManagerFactory:createNewsletterManager'
-            # old syntax
-            factory: ['@App\Email\NewsletterManagerFactory', createNewsletterManager]
+        services:
+            # ...
+
+            App\Email\NewsletterManager:
+                class:   App\Email\NewsletterManager
+                factory: '@App\Email\NewsletterManagerFactory'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <!-- ... -->
+
+                <service id="App\Email\NewsletterManager"
+                         class="App\Email\NewsletterManager">
+                    <factory service="App\Email\NewsletterManagerFactory"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\Email\NewsletterManager;
+        use App\Email\NewsletterManagerFactory;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        // ...
+        $container->register(NewsletterManager::class, NewsletterManager::class)
+            ->setFactory(new Reference(NewsletterManagerFactory::class));
 
 .. _factories-passing-arguments-factory-method:
 
@@ -180,7 +234,7 @@ example takes the ``templating`` service as an argument:
             # ...
 
             App\Email\NewsletterManager:
-                factory:   'App\Email\NewsletterManagerFactory:createNewsletterManager'
+                factory:   ['@App\Email\NewsletterManagerFactory', createNewsletterManager]
                 arguments: ['@templating']
 
     .. code-block:: xml
@@ -190,7 +244,7 @@ example takes the ``templating`` service as an argument:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
diff --git a/service_container/import.rst b/service_container/import.rst
index cc622ca4f7b..eb096e1402a 100644
--- a/service_container/import.rst
+++ b/service_container/import.rst
@@ -52,7 +52,7 @@ decided to move some configuration to a new file:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <parameters>
                 <!-- ... some parameters -->
@@ -87,7 +87,7 @@ To import this file, use the ``imports`` key from a file that *is* loaded:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <imports>
                 <import resource="services/mailer.xml"/>
diff --git a/service_container/injection_types.rst b/service_container/injection_types.rst
index 6007f0c7f20..72faffd7a8b 100644
--- a/service_container/injection_types.rst
+++ b/service_container/injection_types.rst
@@ -55,7 +55,7 @@ service container configuration:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
@@ -124,7 +124,7 @@ that accepts the dependency::
     .. code-block:: yaml
 
         # config/services.yaml
-       services:
+        services:
             # ...
 
             app.newsletter_manager:
@@ -139,14 +139,14 @@ that accepts the dependency::
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <service id="app.newsletter_manager" class="App\Mail\NewsletterManager">
                     <call method="setMailer">
-                        <argument type="service" id="mailer" />
+                        <argument type="service" id="mailer"/>
                     </call>
                 </service>
             </services>
@@ -199,7 +199,7 @@ Another possibility is setting public fields of the class directly::
     .. code-block:: yaml
 
         # config/services.yaml
-       services:
+        services:
             # ...
 
             app.newsletter_manager:
@@ -214,13 +214,13 @@ Another possibility is setting public fields of the class directly::
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <service id="app.newsletter_manager" class="App\Mail\NewsletterManager">
-                    <property name="mailer" type="service" id="mailer" />
+                    <property name="mailer" type="service" id="mailer"/>
                 </service>
             </services>
         </container>
diff --git a/service_container/lazy_services.rst b/service_container/lazy_services.rst
index fc0c0709342..fa198777e3e 100644
--- a/service_container/lazy_services.rst
+++ b/service_container/lazy_services.rst
@@ -54,10 +54,10 @@ You can mark the service as ``lazy`` by manipulating its definition:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Twig\AppExtension" lazy="true" />
+                <service id="App\Twig\AppExtension" lazy="true"/>
             </services>
         </container>
 
@@ -76,8 +76,7 @@ same happens when calling ``Container::get()`` directly.
 The actual class will be instantiated as soon as you try to interact with the
 service (e.g. call one of its methods).
 
-To check if your proxy works you can check the interface of the
-received object::
+To check if your proxy works you can check the interface of the received object::
 
     dump(class_implements($service));
     // the output should include "ProxyManager\Proxy\LazyLoadingInterface"
diff --git a/service_container/optional_dependencies.rst b/service_container/optional_dependencies.rst
index f31a3ed1faa..fd3fa399ec8 100644
--- a/service_container/optional_dependencies.rst
+++ b/service_container/optional_dependencies.rst
@@ -20,13 +20,13 @@ if the service does not exist:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
 
                 <service id="App\Newsletter\NewsletterManager">
-                    <argument type="service" id="logger" on-invalid="null" />
+                    <argument type="service" id="logger" on-invalid="null"/>
                 </service>
             </services>
         </container>
@@ -35,8 +35,8 @@ if the service does not exist:
 
         // config/services.php
         use App\Newsletter\NewsletterManager;
-        use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\DependencyInjection\ContainerInterface;
+        use Symfony\Component\DependencyInjection\Reference;
 
         // ...
 
@@ -77,7 +77,7 @@ call if the service exists and remove the method call if it does not:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Newsletter\NewsletterManager">
@@ -92,8 +92,8 @@ call if the service exists and remove the method call if it does not:
 
         // config/services.php
         use App\Newsletter\NewsletterManager;
-        use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\DependencyInjection\ContainerInterface;
+        use Symfony\Component\DependencyInjection\Reference;
 
         $container
             ->register(NewsletterManager::class)
@@ -111,8 +111,8 @@ call if the service exists and remove the method call if it does not:
     them is missing, those elements are removed but the method call is still
     made with the remaining elements of the collection.
 
-In YAML, the special ``@?`` syntax tells the service container that the dependency
-is optional. The ``NewsletterManager`` must also be rewritten by
+In YAML, the special ``@?`` syntax tells the service container that the
+dependency is optional. The ``NewsletterManager`` must also be rewritten by
 adding a ``setLogger()`` method::
 
         public function setLogger(LoggerInterface $logger)
diff --git a/service_container/parameters.rst b/service_container/parameters.rst
deleted file mode 100644
index 9c9c1113d33..00000000000
--- a/service_container/parameters.rst
+++ /dev/null
@@ -1,355 +0,0 @@
-.. index::
-   single: DependencyInjection; Parameters
-
-Introduction to Parameters
-==========================
-
-You can define parameters in the service container which can then be used
-directly or as part of service definitions. This can help to separate out
-values that you will want to change more regularly.
-
-Parameters in Configuration Files
----------------------------------
-
-Use the ``parameters`` section of a config file to set parameters:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            mailer.transport: sendmail
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="mailer.transport">sendmail</parameter>
-            </parameters>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('mailer.transport', 'sendmail');
-
-You can refer to parameters elsewhere in any config file by surrounding them
-with percent (``%``) signs, e.g. ``%mailer.transport%``. One use for this is
-to inject the values into your services. This allows you to configure different
-versions of services between applications or multiple services based on the
-same class but configured differently within a single application. You could
-inject the choice of mail transport into the ``Mailer`` class directly. But
-declaring it as a parameter makes it easier to change rather than being tied up
-and hidden with the service definition:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            mailer.transport: sendmail
-
-        services:
-            App\Service\Mailer:
-                arguments: ['%mailer.transport%']
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="mailer.transport">sendmail</parameter>
-            </parameters>
-
-            <services>
-                <service id="App\Service\Mailer">
-                    <argument>%mailer.transport%</argument>
-                </service>
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        use App\Mailer;
-
-        $container->setParameter('mailer.transport', 'sendmail');
-
-        $container->register(Mailer::class)
-            ->addArgument('%mailer.transport%');
-
-.. caution::
-
-    The values between ``parameter`` tags in XML configuration files are
-    not trimmed.
-
-    This means that the following configuration sample will have the value
-    ``\n    sendmail\n``:
-
-    .. code-block:: xml
-
-        <parameter key="mailer.transport">
-            sendmail
-        </parameter>
-
-    In some cases (for constants or class names), this could throw errors.
-    In order to prevent this, you must always inline your parameters as
-    follow:
-
-    .. code-block:: xml
-
-        <parameter key="mailer.transport">sendmail</parameter>
-
-.. note::
-
-    If you use a string that starts with ``@`` or  has ``%`` anywhere in it, you
-    need to escape it by adding another ``@`` or ``%``:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/services.yaml
-            parameters:
-                # This will be parsed as string '@securepass'
-                mailer_password: '@@securepass'
-
-                # Parsed as http://symfony.com/?foo=%s&amp;bar=%d
-                url_pattern: 'http://symfony.com/?foo=%%s&amp;bar=%%d'
-
-        .. code-block:: xml
-
-            <!-- config/services.xml -->
-            <parameters>
-                <!-- the @ symbol does NOT need to be escaped in XML -->
-                <parameter key="mailer_password">@securepass</parameter>
-
-                <!-- But % does need to be escaped -->
-                <parameter key="url_pattern">http://symfony.com/?foo=%%s&amp;bar=%%d</parameter>
-            </parameters>
-
-        .. code-block:: php
-
-            // config/services.php
-            // the @ symbol does NOT need to be escaped in XML
-            $container->setParameter('mailer_password', '@securepass');
-
-            // But % does need to be escaped
-            $container->setParameter('url_pattern', 'http://symfony.com/?foo=%%s&amp;bar=%%d');
-
-Getting and Setting Container Parameters in PHP
------------------------------------------------
-
-Working with container parameters is straightforward using the container's
-accessor methods for parameters::
-
-    // checks if a parameter is defined (parameter names are case-sensitive)
-    $container->hasParameter('mailer.transport');
-
-    // gets value of a parameter
-    $container->getParameter('mailer.transport');
-
-    // adds a new parameter
-    $container->setParameter('mailer.transport', 'sendmail');
-
-.. caution::
-
-    The used ``.`` notation is a
-    :ref:`Symfony convention <service-naming-conventions>` to make parameters
-    easier to read. Parameters are flat key-value elements, they can't
-    be organized into a nested array
-
-.. note::
-
-    You can only set a parameter before the container is compiled: not at run-time.
-    To learn more about compiling the container see
-    :doc:`/components/dependency_injection/compilation`.
-
-.. _component-di-parameters-array:
-
-Array Parameters
-----------------
-
-Parameters do not need to be flat strings, they can also contain array values.
-For the XML format, you need to use the ``type="collection"`` attribute
-for all parameters that are arrays.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            my_mailer.gateways: [mail1, mail2, mail3]
-
-            my_multilang.language_fallback:
-                en:
-                    - en
-                    - fr
-                fr:
-                    - fr
-                    - en
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="my_mailer.gateways" type="collection">
-                    <parameter>mail1</parameter>
-                    <parameter>mail2</parameter>
-                    <parameter>mail3</parameter>
-                </parameter>
-
-                <parameter key="my_multilang.language_fallback" type="collection">
-                    <parameter key="en" type="collection">
-                        <parameter>en</parameter>
-                        <parameter>fr</parameter>
-                    </parameter>
-
-                    <parameter key="fr" type="collection">
-                        <parameter>fr</parameter>
-                        <parameter>en</parameter>
-                    </parameter>
-                </parameter>
-            </parameters>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('my_mailer.gateways', ['mail1', 'mail2', 'mail3']);
-        $container->setParameter('my_multilang.language_fallback', [
-            'en' => ['en', 'fr'],
-            'fr' => ['fr', 'en'],
-        ]);
-
-Environment Variables and Dynamic Values
-----------------------------------------
-
-See :doc:`/configuration/external_parameters`.
-
-.. _component-di-parameters-constants:
-
-Constants as Parameters
------------------------
-
-Setting PHP constants as parameters is also supported:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            global.constant.value: !php/const GLOBAL_CONSTANT
-            my_class.constant.value: !php/const My_Class::CONSTANT_NAME
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="global.constant.value" type="constant">GLOBAL_CONSTANT</parameter>
-                <parameter key="my_class.constant.value" type="constant">My_Class::CONSTANT_NAME</parameter>
-            </parameters>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('global.constant.value', GLOBAL_CONSTANT);
-        $container->setParameter('my_class.constant.value', My_Class::CONSTANT_NAME);
-
-Binary Values as Parameters
----------------------------
-
-.. versionadded:: 4.1
-    The support for binary values in container parameters was introduced in
-    Symfony 4.1
-
-If the value of a container parameter is a binary value, set it as a base64
-encoded value in YAML and XML configs and use the escape sequences in PHP:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/services.yaml
-        parameters:
-            some_parameter: !!binary VGhpcyBpcyBhIEJlbGwgY2hhciAH
-
-    .. code-block:: xml
-
-        <!-- config/services.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <parameters>
-                <parameter key="some_parameter" type="binary">VGhpcyBpcyBhIEJlbGwgY2hhciAH</parameter>
-            </parameters>
-        </container>
-
-    .. code-block:: php
-
-        // config/services.php
-        $container->setParameter('some_parameter', 'This is a Bell char \x07');
-
-PHP Keywords in XML
--------------------
-
-By default, ``true``, ``false`` and ``null`` in XML are converted to the
-PHP keywords (respectively ``true``, ``false`` and ``null``):
-
-.. code-block:: xml
-
-    <parameters>
-        <parameter key="mailer.send_all_in_once">false</parameter>
-    </parameters>
-
-    <!-- after parsing
-    $container->getParameter('mailer.send_all_in_once'); // returns false
-    -->
-
-To disable this behavior, use the ``string`` type:
-
-.. code-block:: xml
-
-    <parameters>
-        <parameter key="mailer.some_parameter" type="string">true</parameter>
-    </parameters>
-
-    <!-- after parsing
-    $container->getParameter('mailer.some_parameter'); // returns "true"
-    -->
-
-.. note::
-
-    This is not available for YAML and PHP, because they already have built-in
-    support for the PHP keywords.
diff --git a/service_container/parent_services.rst b/service_container/parent_services.rst
index 02357a6856d..9e6a3309444 100644
--- a/service_container/parent_services.rst
+++ b/service_container/parent_services.rst
@@ -90,14 +90,14 @@ duplicated service definitions:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Repository\BaseDoctrineRepository" abstract="true">
-                    <argument type="service" id="doctrine.orm.entity_manager" />
+                    <argument type="service" id="doctrine.orm.entity_manager"/>
 
                     <call method="setLogger">
-                        <argument type="service" id="logger" />
+                        <argument type="service" id="logger"/>
                     </call>
                 </service>
 
@@ -117,9 +117,9 @@ duplicated service definitions:
     .. code-block:: php
 
         // config/services.php
-        use App\Repository\DoctrineUserRepository;
-        use App\Repository\DoctrinePostRepository;
         use App\Repository\BaseDoctrineRepository;
+        use App\Repository\DoctrinePostRepository;
+        use App\Repository\DoctrineUserRepository;
         use Symfony\Component\DependencyInjection\ChildDefinition;
         use Symfony\Component\DependencyInjection\Reference;
 
@@ -165,8 +165,8 @@ Overriding Parent Dependencies
 ------------------------------
 
 There may be times where you want to override what service is injected for
-one child service only. You can override most settings by specifying it
-in the child class:
+one child service only. You can override most settings by specifying it in
+the child class:
 
 .. configuration-block::
 
@@ -200,7 +200,7 @@ in the child class:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <!-- ... -->
@@ -212,14 +212,14 @@ in the child class:
                 >
                     <!-- appends the '@app.username_checker' argument to the parent
                          argument list -->
-                    <argument type="service" id="app.username_checker" />
+                    <argument type="service" id="app.username_checker"/>
                 </service>
 
                 <service id="App\Repository\DoctrinePostRepository"
                     parent="App\Repository\BaseDoctrineRepository"
                 >
                     <!-- overrides the first argument (using the index attribute) -->
-                    <argument index="0" type="service" id="doctrine.custom_entity_manager" />
+                    <argument index="0" type="service" id="doctrine.custom_entity_manager"/>
                 </service>
 
                 <!-- ... -->
@@ -229,9 +229,9 @@ in the child class:
     .. code-block:: php
 
         // config/services.php
-        use App\Repository\DoctrineUserRepository;
-        use App\Repository\DoctrinePostRepository;
         use App\Repository\BaseDoctrineRepository;
+        use App\Repository\DoctrinePostRepository;
+        use App\Repository\DoctrineUserRepository;
         use Symfony\Component\DependencyInjection\ChildDefinition;
         use Symfony\Component\DependencyInjection\Reference;
         // ...
diff --git a/service_container/service_decoration.rst b/service_container/service_decoration.rst
index 4923cc9b451..0904f9cb500 100644
--- a/service_container/service_decoration.rst
+++ b/service_container/service_decoration.rst
@@ -25,14 +25,14 @@ When overriding an existing definition, the original service is lost:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
-            xsd:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Mailer" />
+                <service id="App\Mailer"/>
 
                 <!-- this replaces the old App\Mailer definition with the new
                      one, the old definition is lost -->
-                <service id="App\Mailer" class="App\NewMailer" />
+                <service id="App\Mailer" class="App\NewMailer"/>
             </services>
         </container>
 
@@ -73,10 +73,10 @@ but keeps a reference of the old one as ``App\DecoratingMailer.inner``:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
-            xsd:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Mailer" />
+                <service id="App\Mailer"/>
 
                 <service id="App\DecoratingMailer"
                     decorates="App\Mailer"
@@ -104,9 +104,6 @@ service replaces the ``App\Mailer`` service. If you're using the
 the decorated service is automatically injected when the constructor of the
 decorating service has one argument type-hinted with the decorated service class.
 
-.. versionadded:: 4.1
-    The autowiring of the decorated service was introduced in Symfony 4.1.
-
 If you are not using autowiring or the decorating service has more than one
 constructor argument type-hinted with the decorated service class, you must
 inject the decorated service explicitly (the ID of the decorated service is
@@ -131,15 +128,15 @@ automatically changed to ``decorating_service_id + '.inner'``):
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
-            xsd:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Mailer" />
+                <service id="App\Mailer"/>
 
                 <service id="App\DecoratingMailer"
                     decorates="App\Mailer"
                 >
-                    <argument type="service" id="App\DecoratingMailer.inner" />
+                    <argument type="service" id="App\DecoratingMailer.inner"/>
                 </service>
 
             </services>
@@ -189,7 +186,7 @@ automatically changed to ``decorating_service_id + '.inner'``):
             <?xml version="1.0" encoding="UTF-8" ?>
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
-                xsd:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+                xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <services>
                     <!-- ... -->
@@ -200,7 +197,7 @@ automatically changed to ``decorating_service_id + '.inner'``):
                         decoration-inner-name="App\DecoratingMailer.wooz"
                         public="false"
                     >
-                        <argument type="service" id="App\DecoratingMailer.wooz" />
+                        <argument type="service" id="App\DecoratingMailer.wooz"/>
                     </service>
 
                 </services>
@@ -251,17 +248,17 @@ the ``decoration_priority`` option. Its value is an integer that defaults to
 
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="Foo" />
+                <service id="Foo"/>
 
                 <service id="Bar" decorates="Foo" decoration-priority="5" public="false">
-                    <argument type="service" id="Bar.inner" />
+                    <argument type="service" id="Bar.inner"/>
                 </service>
 
                 <service id="Baz" decorates="Foo" decoration-priority="1" public="false">
-                    <argument type="service" id="Baz.inner" />
+                    <argument type="service" id="Baz.inner"/>
                 </service>
             </services>
         </container>
@@ -287,4 +284,4 @@ The generated code will be the following::
 
     $this->services[Foo::class] = new Baz(new Bar(new Foo()));
 
-.. _decorator pattern: https://en.wikipedia.org/wiki/Decorator_pattern
+.. _`Decorator pattern`: https://en.wikipedia.org/wiki/Decorator_pattern
diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst
index 0e57547e9a9..150f9bef638 100644
--- a/service_container/service_subscribers_locators.rst
+++ b/service_container/service_subscribers_locators.rst
@@ -74,7 +74,7 @@ a PSR-11 ``ContainerInterface``::
     use App\CommandHandler\BarHandler;
     use App\CommandHandler\FooHandler;
     use Psr\Container\ContainerInterface;
-    use Symfony\Component\DependencyInjection\ServiceSubscriberInterface;
+    use Symfony\Contracts\Service\ServiceSubscriberInterface;
 
     class CommandBus implements ServiceSubscriberInterface
     {
@@ -211,12 +211,12 @@ service type to a service.
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
 
                 <service id="App\CommandBus">
-                    <tag name="container.service_subscriber" key="logger" id="monolog.logger.event" />
+                    <tag name="container.service_subscriber" key="logger" id="monolog.logger.event"/>
                 </service>
 
             </services>
@@ -268,19 +268,19 @@ include as many services as needed in it.
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
 
                 <service id="app.command_handler_locator" class="Symfony\Component\DependencyInjection\ServiceLocator">
                     <argument type="collection">
-                        <argument key="App\FooCommand" type="service" id="app.command_handler.foo" />
-                        <argument key="App\BarCommand" type="service" id="app.command_handler.bar" />
+                        <argument key="App\FooCommand" type="service" id="app.command_handler.foo"/>
+                        <argument key="App\BarCommand" type="service" id="app.command_handler.bar"/>
                     </argument>
                     <!--
                         if you are not using the default service autoconfiguration,
                         add the following tag to the service definition:
-                        <tag name="container.service_locator" />
+                        <tag name="container.service_locator"/>
                     -->
                 </service>
 
@@ -290,8 +290,8 @@ include as many services as needed in it.
     .. code-block:: php
 
         // config/services.php
-        use Symfony\Component\DependencyInjection\ServiceLocator;
         use Symfony\Component\DependencyInjection\Reference;
+        use Symfony\Component\DependencyInjection\ServiceLocator;
 
         // ...
 
@@ -306,11 +306,6 @@ include as many services as needed in it.
             // ->addTag('container.service_locator')
         ;
 
-.. versionadded:: 4.1
-    The service locator autoconfiguration was introduced in Symfony 4.1. In
-    previous Symfony versions you always needed to add the
-    ``container.service_locator`` tag explicitly.
-
 .. note::
 
     The services defined in the service locator argument must include keys,
@@ -333,12 +328,12 @@ Now you can use the service locator by injecting it in any other service:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
 
                 <service id="App\CommandBus">
-                    <argument type="service" id="app.command_handler_locator" />
+                    <argument type="service" id="app.command_handler_locator"/>
                 </service>
 
             </services>
@@ -365,10 +360,10 @@ will share identical locators amongst all the services referencing them::
 
     public function process(ContainerBuilder $container)
     {
-        //...
+        // ...
 
         $locateableServices = [
-            //...
+            // ...
             'logger' => new Reference('logger'),
         ];
 
@@ -376,3 +371,94 @@ will share identical locators amongst all the services referencing them::
     }
 
 .. _`Command pattern`: https://en.wikipedia.org/wiki/Command_pattern
+
+Service Subscriber Trait
+------------------------
+
+The :class:`Symfony\\Contracts\\Service\\ServiceSubscriberTrait` provides an
+implementation for :class:`Symfony\\Contracts\\Service\\ServiceSubscriberInterface`
+that looks through all methods in your class that have no arguments and a return
+type. It provides a ``ServiceLocator`` for the services of those return types.
+The service id is ``__METHOD__``. This allows you to add dependencies to your
+services based on type-hinted helper methods::
+
+    // src/Service/MyService.php
+    namespace App\Service;
+
+    use Psr\Log\LoggerInterface;
+    use Symfony\Component\Routing\RouterInterface;
+    use Symfony\Contracts\Service\ServiceSubscriberInterface;
+    use Symfony\Contracts\Service\ServiceSubscriberTrait;
+
+    class MyService implements ServiceSubscriberInterface
+    {
+        use ServiceSubscriberTrait;
+
+        public function doSomething()
+        {
+            // $this->router() ...
+            // $this->logger() ...
+        }
+
+        private function router(): RouterInterface
+        {
+            return $this->container->get(__METHOD__);
+        }
+
+        private function logger(): LoggerInterface
+        {
+            return $this->container->get(__METHOD__);
+        }
+    }
+
+This  allows you to create helper traits like RouterAware, LoggerAware, etc...
+and compose your services with them::
+
+    // src/Service/LoggerAware.php
+    namespace App\Service;
+
+    use Psr\Log\LoggerInterface;
+
+    trait LoggerAware
+    {
+        private function logger(): LoggerInterface
+        {
+            return $this->container->get(__CLASS__.'::'.__FUNCTION__);
+        }
+    }
+
+    // src/Service/RouterAware.php
+    namespace App\Service;
+
+    use Symfony\Component\Routing\RouterInterface;
+
+    trait RouterAware
+    {
+        private function router(): RouterInterface
+        {
+            return $this->container->get(__CLASS__.'::'.__FUNCTION__);
+        }
+    }
+
+    // src/Service/MyService.php
+    namespace App\Service;
+
+    use Symfony\Contracts\Service\ServiceSubscriberInterface;
+    use Symfony\Contracts\Service\ServiceSubscriberTrait;
+
+    class MyService implements ServiceSubscriberInterface
+    {
+        use ServiceSubscriberTrait, LoggerAware, RouterAware;
+
+        public function doSomething()
+        {
+            // $this->router() ...
+            // $this->logger() ...
+        }
+    }
+
+.. caution::
+
+    When creating these helper traits, the service id cannot be ``__METHOD__``
+    as this will include the trait name, not the class name. Instead, use
+    ``__CLASS__.'::'.__FUNCTION__`` as the service id.
diff --git a/service_container/shared.rst b/service_container/shared.rst
index decb9d09cf2..00f0ddf0e43 100644
--- a/service_container/shared.rst
+++ b/service_container/shared.rst
@@ -26,7 +26,7 @@ in your service definition:
 
         <!-- config/services.xml -->
         <services>
-            <service id="App\SomeNonSharedService" shared="false" />
+            <service id="App\SomeNonSharedService" shared="false"/>
         </services>
 
     .. code-block:: php
diff --git a/service_container/synthetic_services.rst b/service_container/synthetic_services.rst
index 5ef7c04e36e..ad4cc9924ff 100644
--- a/service_container/synthetic_services.rst
+++ b/service_container/synthetic_services.rst
@@ -51,12 +51,12 @@ configuration:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
 
                 <!-- synthetic services don't specify a class -->
-                <service id="app.synthetic_service" synthetic="true" />
+                <service id="app.synthetic_service" synthetic="true"/>
 
             </services>
         </container>
diff --git a/service_container/tags.rst b/service_container/tags.rst
index 918b92d1a68..9a98cf17619 100644
--- a/service_container/tags.rst
+++ b/service_container/tags.rst
@@ -26,11 +26,11 @@ example:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Twig\AppExtension" public="false">
-                    <tag name="twig.extension" />
+                    <tag name="twig.extension"/>
                 </service>
             </services>
         </container>
@@ -82,13 +82,13 @@ If you want to apply tags automatically for your own services, use the
     .. code-block:: xml
 
         <!-- config/services.xml -->
-        <?xml version="1.0" encoding="utf-8"?>
-        <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+        <?xml version="1.0" encoding="UTF-8"?>
+        <container xmlns="http://symfony.com/schema/dic/services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
             <services>
                 <!-- this config only applies to the services created by this file -->
                 <instanceof id="App\Security\CustomInterface" autowire="true">
                     <!-- services whose classes are instances of CustomInterface will be tagged automatically -->
-                    <tag name="app.custom_tag" />
+                    <tag name="app.custom_tag"/>
                 </instanceof>
             </services>
         </container>
@@ -172,10 +172,10 @@ Then, define the chain as a service:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="App\Mail\TransportChain" />
+                <service id="App\Mail\TransportChain"/>
             </services>
         </container>
 
@@ -213,17 +213,17 @@ For example, you may add the following transports as services:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Swift_SmtpTransport">
                     <argument>%mailer_host%</argument>
 
-                    <tag name="app.mail_transport" />
+                    <tag name="app.mail_transport"/>
                 </service>
 
                 <service class="\Swift_SendmailTransport">
-                    <tag name="app.mail_transport" />
+                    <tag name="app.mail_transport"/>
                 </service>
             </services>
         </container>
@@ -253,10 +253,10 @@ container for any services with the ``app.mail_transport`` tag::
     // src/DependencyInjection/Compiler/MailTransportPass.php
     namespace App\DependencyInjection\Compiler;
 
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use App\Mail\TransportChain;
     use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Reference;
-    use App\Mail\TransportChain;
 
     class MailTransportPass implements CompilerPassInterface
     {
@@ -369,17 +369,17 @@ To answer this, change the service declaration:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="Swift_SmtpTransport">
                     <argument>%mailer_host%</argument>
 
-                    <tag name="app.mail_transport" alias="smtp" />
+                    <tag name="app.mail_transport" alias="smtp"/>
                 </service>
 
                 <service id="Swift_SendmailTransport">
-                    <tag name="app.mail_transport" alias="sendmail" />
+                    <tag name="app.mail_transport" alias="sendmail"/>
                 </service>
             </services>
         </container>
@@ -418,8 +418,8 @@ To answer this, change the service declaration:
 Notice that you've added a generic ``alias`` key to the tag. To actually
 use this, update the compiler::
 
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Reference;
 
     class TransportCompilerPass implements CompilerPassInterface
@@ -434,7 +434,7 @@ use this, update the compiler::
                 foreach ($tags as $attributes) {
                     $definition->addMethodCall('addTransport', [
                         new Reference($id),
-                        $attributes["alias"]
+                        $attributes['alias']
                     ]);
                 }
             }
@@ -479,20 +479,20 @@ first  constructor argument to the ``App\HandlerCollection`` service:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="App\Handler\One">
-                    <tag name="app.handler" />
+                    <tag name="app.handler"/>
                 </service>
 
                 <service id="App\Handler\Two">
-                    <tag name="app.handler" />
+                    <tag name="app.handler"/>
                 </service>
 
                 <service id="App\HandlerCollection">
                     <!-- inject all services tagged with app.handler as first argument -->
-                    <argument type="tagged" tag="app.handler" />
+                    <argument type="tagged" tag="app.handler"/>
                 </service>
             </services>
         </container>
@@ -513,9 +513,7 @@ first  constructor argument to the ``App\HandlerCollection`` service:
             ->addArgument(new TaggedIteratorArgument('app.handler'));
 
 After compilation the ``HandlerCollection`` service is able to iterate over your
-application handlers.
-
-.. code-block:: php
+application handlers::
 
     // src/HandlerCollection.php
     namespace App;
@@ -548,11 +546,11 @@ application handlers.
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <services>
                     <service id="App\Handler\One">
-                        <tag name="app.handler" priority="20" />
+                        <tag name="app.handler" priority="20"/>
                     </service>
                 </services>
             </container>
diff --git a/session.rst b/session.rst
index a046cc47896..53cf435eb15 100644
--- a/session.rst
+++ b/session.rst
@@ -1,10 +1,217 @@
 Sessions
 ========
 
-Symfony provides a nice session object that you can use to store information
-about the user between requests.
+Symfony provides a session object and several utilities that you can use to
+store information about the user between requests.
 
-To see how to use the session, read :ref:`session-intro`.
+Configuration
+-------------
+
+Sessions are provided by the `HttpFoundation component`_, which is included in
+all Symfony applications, no matter how you installed it. Before using the
+sessions, check their default configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            session:
+                # enables the support of sessions in the app
+                enabled: true
+                # ID of the service used for session storage.
+                # NULL =  means that PHP's default session mechanism is used
+                handler_id: null
+                # improves the security of the cookies used for sessions
+                cookie_secure: 'auto'
+                cookie_samesite: 'lax'
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <!--
+                    enabled: enables the support of sessions in the app
+                    handler-id: ID of the service used for session storage
+                                NULL means that PHP's default session mechanism is used
+                    cookie-secure and cookie-samesite: improves the security of the cookies used for sessions
+                -->
+                <framework:session enabled="true"
+                                   handler-id="null"
+                                   cookie-secure="auto"
+                                   cookie-samesite="lax"/>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        $container->loadFromExtension('framework', [
+            'session' => [
+                // enables the support of sessions in the app
+                'enabled' => true,
+                // ID of the service used for session storage
+                // NULL means that PHP's default session mechanism is used
+                'handler_id' => null,
+                // improves the security of the cookies used for sessions
+                'cookie_secure' => 'auto',
+                'cookie_samesite' => 'lax',
+            ],
+        ]);
+
+Setting the ``handler_id`` config option to ``null`` means that Symfony will
+use the native PHP session mechanism. The session metadata files will be stored
+outside of the Symfony application, in a directory controlled by PHP. Although
+this usually simplify things, some session expiration related options may not
+work as expected if other applications that write to the same directory have
+short max lifetime settings.
+
+If you prefer, you can use the ``session.handler.native_file`` service as
+``handler_id`` to let Symfony manage the sessions itself. Another useful option
+is ``save_path``, which defines the directory where Symfony will store the
+session metadata files:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            session:
+                # ...
+                handler_id: 'session.handler.native_file'
+                save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:session enabled="true"
+                                   handler-id="session.handler.native_file"
+                                   save-path="%kernel.project_dir%/var/sessions/%kernel.environment%"/>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        $container->loadFromExtension('framework', [
+            'session' => [
+                // ...
+                'handler_id' => 'session.handler.native_file',
+                'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%',
+            ],
+        ]);
+
+Check out the Symfony config reference to learn more about the other available
+:ref:`Session configuration options <config-framework-session>`. Also, if you
+prefer to store session metadata in a database instead of the filesystem,
+check out this article: :doc:`/doctrine/pdo_session_storage`.
+
+Basic Usage
+-----------
+
+Symfony provides a session service that is injected in your services and
+controllers if you type-hint an argument with
+:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface`::
+
+    use Symfony\Component\HttpFoundation\Session\SessionInterface;
+
+    class SomeService
+    {
+        private $session;
+
+        public function __construct(SessionInterface $session)
+        {
+            $this->session = $session;
+        }
+
+        public function someMethod()
+        {
+            // stores an attribute in the session for later reuse
+            $this->session->set('attribute-name', 'attribute-value');
+
+            // gets an attribute by name
+            $foo = $this->session->get('foo');
+
+            // the second argument is the value returned when the attribute doesn't exist
+            $filters = $this->session->get('filters', []);
+
+            // ...
+        }
+    }
+
+.. tip::
+
+    Every ``SessionInterface`` implementation is supported. If you have your
+    own implementation, type-hint this in the argument instead.
+
+Stored attributes remain in the session for the remainder of that user's session.
+By default, session attributes are key-value pairs managed with the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBag`
+class.
+
+If your application needs are complex, you may prefer to use
+:ref:`namespaced session attributes <namespaced-attributes>` which are managed with the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\NamespacedAttributeBag`
+class. Before using them, override the ``session`` service definition to replace
+the default ``AttributeBag`` by the ``NamespacedAttributeBag``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        session:
+            public: true
+            class: Symfony\Component\HttpFoundation\Session\Session
+            arguments: ['@session.storage', '@session.namespacedattributebag', '@session.flash_bag']
+
+        session.namespacedattributebag:
+            class: Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag
+
+.. _session-avoid-start:
+
+Avoid Starting Sessions for Anonymous Users
+-------------------------------------------
+
+Sessions are automatically started whenever you read, write or even check for
+the existence of data in the session. This may hurt your application performance
+because all users will receive a session cookie. In order to prevent that, you
+must *completely* avoid accessing the session.
+
+For example, if your templates include some code to display the
+:ref:`flash messages <flash-messages>`, sessions will start even if the user
+is not logged in and even if you haven't created any flash messages. To avoid
+this behavior, add a check before trying to access the flash messages:
+
+.. code-block:: html+twig
+
+    {# this check prevents starting a session when there are no flash messages #}
+    {% if app.request.hasPreviousSession %}
+        {% for message in app.flashes('notice') %}
+            <div class="flash-notice">
+                {{ message }}
+            </div>
+        {% endfor %}
+    {% endif %}
 
 More about Sessions
 -------------------
@@ -12,10 +219,9 @@ More about Sessions
 .. toctree::
     :maxdepth: 1
 
-    session/sessions_directory
-    session/avoid_session_start
+    /doctrine/pdo_session_storage
     session/locale_sticky_session
     session/php_bridge
     session/proxy_examples
 
-* :doc:`/doctrine/pdo_session_storage`
+.. _`HttpFoundation component`: https://symfony.com/components/HttpFoundation
diff --git a/session/avoid_session_start.rst b/session/avoid_session_start.rst
deleted file mode 100644
index e19498184cf..00000000000
--- a/session/avoid_session_start.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-.. index::
-    single: Sessions, cookies
-
-Avoid Starting Sessions for Anonymous Users
-===========================================
-
-Sessions are automatically started whenever you read, write or even check for the
-existence of data in the session. This means that if you need to avoid creating
-a session cookie for some users, it can be difficult: you must *completely* avoid
-accessing the session.
-
-For example, one common problem in this situation involves checking for flash
-messages, which are stored in the session. The following code would guarantee
-that a session is *always* started:
-
-.. code-block:: html+twig
-
-    {% for message in app.flashes('notice') %}
-        <div class="flash-notice">
-            {{ message }}
-        </div>
-    {% endfor %}
-
-Even if the user is not logged in and even if you haven't created any flash messages,
-just calling the ``get()`` (or even ``has()``) method of the ``flashBag`` will
-start a session. This may hurt your application performance because all users will
-receive a session cookie. To avoid this behavior, add a check before trying to
-access the flash messages:
-
-.. code-block:: html+twig
-
-    {% if app.request.hasPreviousSession %}
-        {% for message in app.flashes('notice') %}
-            <div class="flash-notice">
-                {{ message }}
-            </div>
-        {% endfor %}
-    {% endif %}
diff --git a/session/locale_sticky_session.rst b/session/locale_sticky_session.rst
index d4f08ffab25..f8caef23370 100644
--- a/session/locale_sticky_session.rst
+++ b/session/locale_sticky_session.rst
@@ -13,16 +13,16 @@ in the session, so that it's used on subsequent requests.
 Creating a LocaleSubscriber
 ---------------------------
 
-Create and a :ref:`new event subscriber <events-subscriber>`. Typically, ``_locale``
+Create a :ref:`new event subscriber <events-subscriber>`. Typically, ``_locale``
 is used as a routing parameter to signify the locale, though you can determine the
 correct locale however you want::
 
     // src/EventSubscriber/LocaleSubscriber.php
     namespace App\EventSubscriber;
 
-    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
-    use Symfony\Component\HttpKernel\KernelEvents;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpKernel\Event\RequestEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
 
     class LocaleSubscriber implements EventSubscriberInterface
     {
@@ -33,7 +33,7 @@ correct locale however you want::
             $this->defaultLocale = $defaultLocale;
         }
 
-        public function onKernelRequest(GetResponseEvent $event)
+        public function onKernelRequest(RequestEvent $event)
         {
             $request = $event->getRequest();
             if (!$request->hasPreviousSession()) {
@@ -63,7 +63,7 @@ you're done! Symfony will automatically know about the event subscriber and call
 the ``onKernelRequest`` method on each request.
 
 To see it working, either set the ``_locale`` key on the session manually (e.g.
-via some "Change Locale" route & controller), or create a route with a the :ref:`_locale default <translation-locale-url>`.
+via some "Change Locale" route & controller), or create a route with the :ref:`_locale default <translation-locale-url>`.
 
 .. sidebar:: Explicitly Configure the Subscriber
 
@@ -89,14 +89,14 @@ via some "Change Locale" route & controller), or create a route with a the :ref:
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd">
 
                 <services>
                     <service id="App\EventSubscriber\LocaleSubscriber">
                         <argument>%kernel.default_locale%</argument>
 
                         <!-- uncomment the next line if you are not using autoconfigure -->
-                        <!-- <tag name="kernel.event_subscriber" /> -->
+                        <!-- <tag name="kernel.event_subscriber"/> -->
                     </service>
                 </services>
             </container>
diff --git a/session/php_bridge.rst b/session/php_bridge.rst
index 86977db8d7b..42c8644e2a7 100644
--- a/session/php_bridge.rst
+++ b/session/php_bridge.rst
@@ -29,7 +29,7 @@ for the ``handler_id``:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <framework:config>
                 <framework:session storage-id="session.storage.php_bridge"
@@ -48,7 +48,7 @@ for the ``handler_id``:
             ],
         ]);
 
-Otherwise, if the problem is only that you cannot avoid the application
+Otherwise, if the problem is that you cannot avoid the application
 starting the session with ``session_start()``, you can still make use of
 a Symfony based session save handler by specifying the save handler as in
 the example below:
@@ -71,7 +71,7 @@ the example below:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <framework:config>
                 <framework:session storage-id="session.storage.php_bridge"
diff --git a/session/proxy_examples.rst b/session/proxy_examples.rst
index fbe7748520c..b11d1094147 100644
--- a/session/proxy_examples.rst
+++ b/session/proxy_examples.rst
@@ -35,10 +35,10 @@ Symfony to use your session handler instead of the default one:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <framework:config>
-                <framework:session handler-id="App\Session\CustomSessionHandler" />
+                <framework:session handler-id="App\Session\CustomSessionHandler"/>
             </framework:config>
         </container>
 
diff --git a/session/sessions_directory.rst b/session/sessions_directory.rst
deleted file mode 100644
index b1f6eb364b7..00000000000
--- a/session/sessions_directory.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-.. index::
-   single: Sessions, sessions directory
-
-Configuring the Directory where Session Files are Saved
-=======================================================
-
-By default, Symfony stores session metadata on the filesystem. If you want to control
-this path, update the ``framework.session.save_path`` configuration key:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/framework.yaml
-        framework:
-            session:
-                handler_id: session.handler.native_file
-                save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
-
-    .. code-block:: xml
-
-        <!-- config/packages/framework.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <framework:config>
-                <framework:session handler-id="session.handler.native_file" save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
-            </framework:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/framework.php
-        $container->loadFromExtension('framework', [
-            'session' => [
-                'handler_id' => 'session.handler.native_file',
-                'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%'
-            ],
-        ]);
-
-Storing Sessions Elsewhere (e.g. database)
-------------------------------------------
-
-You can store your session data anywhere by using the ``handler_id`` option.
-See :doc:`/components/http_foundation/session_configuration` for a discussion of
-session save handlers. There are also articles about storing sessions in a
-:doc:`relational database </doctrine/pdo_session_storage>`
-or a :doc:`NoSQL database </doctrine/mongodb_session_storage>`.
diff --git a/setup.rst b/setup.rst
index f67b9b66946..7ce997e49e0 100644
--- a/setup.rst
+++ b/setup.rst
@@ -10,94 +10,102 @@ Installing & Setting up the Symfony Framework
     Do you prefer video tutorials? Check out the `Stellar Development with Symfony`_
     screencast series.
 
-To create your new Symfony application, first make sure you're using PHP 7.1 or higher
-and have `Composer`_ installed. If you don't, start by :doc:`installing Composer globally </setup/composer>`
-on your system. If you want to use a virtual machine (VM), check out :doc:`Homestead </setup/homestead>`.
+.. _symfony-tech-requirements:
 
-Create your new project by running:
+Technical Requirements
+----------------------
 
-.. code-block:: terminal
+Before creating your first Symfony application you must:
 
-    $ composer create-project symfony/website-skeleton my-project
+* Install PHP 7.1 or higher and these PHP extensions (which are installed and
+  enabled by default in most PHP 7 installations): `Ctype`_, `iconv`_, `JSON`_,
+  `PCRE`_, `Session`_, `SimpleXML`_, and `Tokenizer`_;
+* `Install Composer`_, which is used to install PHP packages;
+* `Install Symfony`_, which creates in your computer a binary called ``symfony``
+  that provides all the tools you need to develop your application locally.
 
-This will create a new ``my-project`` directory, download some dependencies into
-it and even generate the basic directories and files you'll need to get started.
-In other words, your new app is ready!
+The ``symfony`` binary provides a tool to check if your computer meets these
+requirements. Open your console terminal and run this command:
 
-.. tip::
+.. code-block:: terminal
 
-    The ``website-skeleton`` is optimized for traditional web applications. If
-    you are building microservices, console applications or APIs, consider
-    using the much simpler ``skeleton`` project:
+    $ symfony check:requirements
 
-    .. code-block:: terminal
+.. _creating-symfony-applications:
 
-        $ composer create-project symfony/skeleton my-project
+Creating Symfony Applications
+-----------------------------
 
-        # optional: install the web server bundle (explained next)
-        $ cd my-project
-        $ composer require symfony/web-server-bundle --dev
+Open your console terminal and run any of these commands to create a new Symfony
+application:
 
-Running your Symfony Application
---------------------------------
+.. code-block:: terminal
 
-On production, you should use a web server like Nginx or Apache
-(see :doc:`configuring a web server to run Symfony </setup/web_server_configuration>`).
-But for development, it's convenient to use the :doc:`Symfony PHP web server <setup/built_in_web_server>`.
+    # run this if you are building a traditional web application
+    $ symfony new --full my_project_name
 
-Move into your new project and start the server:
+    # run this if you are building a microservice, console application or API
+    $ symfony new my_project_name
 
-.. code-block:: terminal
+The only difference between these two commands is the number of packages
+installed by default. The ``--full`` option installs all the packages that you
+usually need to build web applications, so the installation size will be bigger.
 
-    $ cd my-project
-    $ php bin/console server:run
+If you can't or don't want to `install Symfony`_ for any reason, run these
+commands to create the new Symfony application using Composer:
 
-Open your browser and navigate to ``http://localhost:8000/``. If everything is working,
-you'll see a welcome page. Later, when you are finished working, stop the server
-by pressing ``Ctrl+C`` from your terminal.
+.. code-block:: terminal
 
-.. tip::
+    # run this if you are building a traditional web application
+    $ composer create-project symfony/website-skeleton my_project_name
 
-    If you're having any problems running Symfony, your system may be missing
-    some technical requirements. Use the :doc:`Symfony Requirements Checker </reference/requirements>`
-    tool to make sure your system is set up.
+    # run this if you are building a microservice, console application or API
+    $ composer create-project symfony/skeleton my_project_name
 
-.. tip::
+No matter which command you run to create the Symfony application. All of them
+will create a new ``my_project_name/`` directory, download some dependencies
+into it and even generate the basic directories and files you'll need to get
+started. In other words, your new application is ready!
 
-    If you're using a VM, you may need to tell the server to bind to all IP addresses:
+.. note::
 
-    .. code-block:: terminal
+    The project's cache and logs directory (by default, ``<project>/var/cache/``
+    and ``<project>/var/log/``) must be writable by the web server. If you have
+    any issue, read how to :doc:`set up permissions for Symfony applications </setup/file_permissions>`.
 
-        $ php bin/console server:start 0.0.0.0:8000
+Running Symfony Applications
+----------------------------
 
-    You should **NEVER** listen to all interfaces on a computer that is
-    directly accessible from the Internet.
+On production, you should use a web server like Nginx or Apache (see
+:doc:`configuring a web server to run Symfony </setup/web_server_configuration>`).
+But for development, it's more convenient to use the
+:doc:`local web server </setup/symfony_server>` provided by Symfony.
 
-Storing your Project in git
----------------------------
+This local server provides support for HTTP/2, TLS/SSL, automatic generation of
+security certificates and many other features. It works with any PHP application,
+not only Symfony projects, so it's a very useful development tool.
 
-Storing your project in services like GitHub, GitLab and Bitbucket works like with
-any other code project! Init a new repository with ``Git`` and you are ready to push
-to your remote:
+Open your console terminal, move into your new project directory and start the
+local web server as follows:
 
 .. code-block:: terminal
 
-    $ git init
-    $ git add .
-    $ git commit -m "Initial commit"
+    $ cd my-project/
+    $ symfony server:start
 
-Your project already has a sensible ``.gitignore`` file. And as you install more
-packages, a system called :ref:`Flex <flex-quick-intro>` will add more lines to
-that file when needed.
+Open your browser and navigate to ``http://localhost:8000/``. If everything is
+working, you'll see a welcome page. Later, when you are finished working, stop
+the server by pressing ``Ctrl+C`` from your terminal.
 
 .. _install-existing-app:
 
 Setting up an Existing Symfony Project
 --------------------------------------
 
-If you're working on an existing Symfony application, you only need to get the
-project code and install the dependencies with Composer. Assuming your team uses Git,
-setup your project with the following commands:
+In addition to creating new Symfony projects, you will also work on projects
+already created by other developers. In that case, you only need to get the
+project code and install the dependencies with Composer. Assuming your team uses
+Git, setup your project with the following commands:
 
 .. code-block:: terminal
 
@@ -109,15 +117,111 @@ setup your project with the following commands:
     $ cd my-project/
     $ composer install
 
-You'll probably also need to customize your :ref:`.env <config-dot-env>` and do a
-few other project-specific tasks (e.g. creating database schema).
+You'll probably also need to customize your :ref:`.env file <config-dot-env>`
+and do a few other project-specific tasks (e.g. creating a database). When
+working on a existing Symfony application for the first time, it may be useful
+to run this command which displays information about the project:
+
+.. code-block:: terminal
+
+    $ php bin/console about
+
+.. _symfony-flex:
+
+Installing Packages
+-------------------
+
+A common practice when developing Symfony applications is to install packages
+(Symfony calls them :doc:`bundles </bundles>`) that provide ready-to-use
+features. Packages usually require some setup before using them (editing some
+file to enable the bundle, creating some file to add some initial config, etc.)
+
+Most of the time this setup can be automated and that's why Symfony includes
+`Symfony Flex`_, a tool to simplify the installation/removal of packages in
+Symfony applications. Technically speaking, Symfony Flex is a Composer plugin
+that is installed by default when creating a new Symfony application and which
+**automates the most common tasks of Symfony applications**.
+
+.. tip::
+
+    You can also :doc:`add Symfony Flex to an existing project </setup/flex>`.
+
+Symfony Flex modifies the behavior of the ``require``, ``update``, and
+``remove`` Composer commands to provide advanced features. Consider the
+following example:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ composer require logger
+
+If you execute that command in a Symfony application which doesn't use Flex,
+you'll see a Composer error explaining that ``logger`` is not a valid package
+name. However, if the application has Symfony Flex installed, that command
+installs and enables all the packages needed to use the official Symfony logger.
 
-Checking for Security Vulnerabilities
--------------------------------------
+This is possible because lots of Symfony packages/bundles define **"recipes"**,
+which are a set of automated instructions to install and enable packages into
+Symfony applications. Flex keeps tracks of the recipes it installed in a
+``symfony.lock`` file, which must be committed to your code repository.
 
-Symfony provides a utility called the "Security Checker" to check whether your
-project's dependencies contain any known security vulnerability. Check out
-the integration instructions for `the Security Checker`_ to set it up.
+Symfony Flex recipes are contributed by the community and they are stored in
+two public repositories:
+
+* `Main recipe repository`_, is a curated list of recipes for high quality and
+  maintained packages. Symfony Flex only looks in this repository by default.
+
+* `Contrib recipe repository`_, contains all the recipes created by the
+  community. All of them are guaranteed to work, but their associated packages
+  could be unmaintained. Symfony Flex will ask your permission before installing
+  any of these recipes.
+
+Read the `Symfony Recipes documentation`_ to learn everything about how to
+create recipes for your own packages.
+
+.. _security-checker:
+
+Checking Security Vulnerabilities
+---------------------------------
+
+The ``symfony`` binary created when you `install Symfony`_ provides a command to
+check whether your project's dependencies contain any known security
+vulnerability:
+
+.. code-block:: terminal
+
+    $ symfony check:security
+
+A good security practice is to execute this command regularly to be able to
+update or replace compromised dependencies as soon as possible. The security
+check is done locally by cloning the public `PHP security advisories database`_,
+so your ``composer.lock`` file is not sent on the network.
+
+.. tip::
+
+    The ``check:security`` command terminates with a non-zero exit code if
+    any of your dependencies is affected by a known security vulnerability.
+    This way you can add it to your project build process and your continuous
+    integration workflows to make them fail when there are vulnerabilities.
+
+Symfony LTS Versions
+--------------------
+
+According to the :doc:`Symfony release process </contributing/community/releases>`,
+"long-term support" (or LTS for short) versions are published every two years.
+Check out the `Symfony roadmap`_ to know which is the latest LTS version.
+
+By default, the command that creates new Symfony applications uses the latest
+stable version. If you want to use an LTS version, add the ``--version`` option:
+
+.. code-block:: terminal
+
+    # find the latest LTS version at https://symfony.com/roadmap
+    $ symfony new --version=3.4 my_project_name_name
+
+    # you can also base your project on development versions
+    $ symfony new --version=4.4.x-dev my_project_name
+    $ symfony new --version=dev-master my_project_name
 
 The Symfony Demo application
 ----------------------------
@@ -126,15 +230,19 @@ The Symfony Demo application
 recommended way to develop Symfony applications. It's a great learning tool for
 Symfony newcomers and its code contains tons of comments and helpful notes.
 
-To check out its code and install it locally, see `symfony/symfony-demo`_.
+Run this command to create a new project based on the Symfony Demo application:
+
+.. code-block:: terminal
+
+    $ symfony new --demo my_project_name
 
 Start Coding!
 -------------
 
 With setup behind you, it's time to :doc:`Create your first page in Symfony </page_creation>`.
 
-Go Deeper with Setup
---------------------
+Learn More
+----------
 
 .. toctree::
     :hidden:
@@ -146,13 +254,24 @@ Go Deeper with Setup
     :glob:
 
     setup/homestead
-    setup/built_in_web_server
     setup/web_server_configuration
-    setup/composer
     setup/*
 
 .. _`Stellar Development with Symfony`: http://symfonycasts.com/screencast/symfony
-.. _`Composer`: https://getcomposer.org/
-.. _`the Security Checker`: https://github.com/sensiolabs/security-checker#integration
-.. _`The Symfony Demo application`: https://github.com/symfony/demo
-.. _`symfony/symfony-demo`: https://github.com/symfony/demo
+.. _`Install Composer`: https://getcomposer.org/download/
+.. _`Install Symfony`: https://symfony.com/download
+.. _`install Symfony`: https://symfony.com/download
+.. _`The Symfony Demo Application`: https://github.com/symfony/demo
+.. _`Symfony Flex`: https://github.com/symfony/flex
+.. _`PHP security advisories database`: https://github.com/FriendsOfPHP/security-advisories
+.. _`Symfony roadmap`: https://symfony.com/roadmap
+.. _`Main recipe repository`: https://github.com/symfony/recipes
+.. _`Contrib recipe repository`: https://github.com/symfony/recipes-contrib
+.. _`Symfony Recipes documentation`: https://github.com/symfony/recipes/blob/master/README.rst
+.. _`iconv`: https://php.net/book.iconv
+.. _`JSON`: https://php.net/book.json
+.. _`Session`: https://php.net/book.session
+.. _`Ctype`: https://php.net/book.ctype
+.. _`Tokenizer`: https://php.net/book.tokenizer
+.. _`SimpleXML`: https://php.net/book.simplexml
+.. _`PCRE`: https://php.net/book.pcre
diff --git a/setup/built_in_web_server.rst b/setup/built_in_web_server.rst
index 7f87e0210f9..3f13a4c712c 100644
--- a/setup/built_in_web_server.rst
+++ b/setup/built_in_web_server.rst
@@ -4,11 +4,16 @@
 How to Use PHP's built-in Web Server
 ====================================
 
-Since PHP 5.4 the CLI SAPI comes with a `built-in web server`_. It can be used
-to run your PHP applications locally during development, for testing or for
-application demonstrations. This way, you don't have to bother configuring
-a full-featured web server such as
-:doc:`Apache or Nginx </setup/web_server_configuration>`.
+.. caution::
+
+    This article explains how to use the web server based on the WebServerBundle.
+    This is no longer recommended in new Symfony applications. Instead, use the
+    :doc:`Symfony Local Web Server </setup/symfony_server>`.
+
+The PHP CLI SAPI comes with a `built-in web server`_. It can be used to run your
+PHP applications locally during development, for testing or for application
+demonstrations. This way, you don't have to bother configuring a full-featured
+web server such as :doc:`Apache or Nginx </setup/web_server_configuration>`.
 
 .. caution::
 
@@ -27,7 +32,7 @@ Move into your project directory and run this command:
 .. code-block:: terminal
 
     $ cd your-project/
-    $ composer require symfony/web-server-bundle --dev
+    $ composer require --dev symfony/web-server-bundle
 
 Starting the Web Server
 -----------------------
@@ -109,8 +114,7 @@ you have to pass the correct location using the ``--docroot`` option:
 Stopping the Server
 -------------------
 
-When you are finished, you can stop the web server using the ``server:stop``
-command:
+When you finish your work, you can stop the web server with the following command:
 
 .. code-block:: terminal
 
diff --git a/setup/bundles.rst b/setup/bundles.rst
index a83916898c7..53104c6c9ba 100644
--- a/setup/bundles.rst
+++ b/setup/bundles.rst
@@ -142,7 +142,7 @@ following recommended configuration as the starting point of your own configurat
     matrix:
         include:
             - php: 5.3.3
-              env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=weak
+              env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=max[total]=999999
             - php: 5.6
               env: SYMFONY_VERSION='2.7.*'
             - php: 5.6
diff --git a/setup/composer.rst b/setup/composer.rst
deleted file mode 100644
index c50216b9520..00000000000
--- a/setup/composer.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. index::
-    double: Composer; Installation
-
-Installing Composer
-===================
-
-`Composer`_ is the package manager used by modern PHP applications. Use Composer
-to manage dependencies in your Symfony applications and to install Symfony
-Components in your PHP projects.
-
-Since this article was first published, Composer installation has improved a lot.
-Therefore, the original contents of this article have been removed and you are
-encouraged to `install Composer`_ as explained in the official Composer documentation.
-
-.. _`Composer`: https://getcomposer.org/
-.. _`install Composer`: https://getcomposer.org/download/
diff --git a/setup/file_permissions.rst b/setup/file_permissions.rst
index 55a5c49d22d..4c65ac8325e 100644
--- a/setup/file_permissions.rst
+++ b/setup/file_permissions.rst
@@ -9,7 +9,9 @@ was writable. But that is no longer true! In Symfony 4, everything works automat
 
 * In the ``prod`` environment (i.e. when ``APP_ENV`` is ``prod`` and ``APP_DEBUG``
   is ``0``), as long as you run ``php bin/console cache:warmup``, no cache files
-  will need to be written to disk at runtime.
+  will need to be written to disk at runtime. The only exception is when using
+  a filesystem-based cache, such as Doctrine's query result cache or Symfony's
+  cache with a filesystem provider configured.
 
 * In all environments, the log directory (``var/log/`` by default) must exist
   and be writable by your web server user and terminal user. One way this can
diff --git a/setup/flex.rst b/setup/flex.rst
index dc44186fd5c..87d40dd6c70 100644
--- a/setup/flex.rst
+++ b/setup/flex.rst
@@ -1,152 +1,32 @@
 .. index:: Flex
 
-Using Symfony Flex to Manage Symfony Applications
-=================================================
-
-`Symfony Flex`_ is the new way to install and manage Symfony applications. Flex
-is not a new Symfony version, but a tool that replaces and improves the
-`Symfony Installer`_ and the `Symfony Standard Edition`_.
-
-Symfony Flex **automates the most common tasks of Symfony applications**, like
-installing and removing bundles and other Composer dependencies. Symfony
-Flex works for Symfony 3.3 and higher. Starting from Symfony 4.0, Flex
-should be used by default, but it is still optional.
-
-How Does Flex Work
-------------------
-
-Symfony Flex is a Composer plugin that modifies the behavior of the
-``require``, ``update``, and ``remove`` commands. When installing or removing
-dependencies in a Flex-enabled application, Symfony can perform tasks before
-and after the execution of Composer tasks.
-
-Consider the following example:
-
-.. code-block:: terminal
-
-    $ cd my-project/
-    $ composer require mailer
-
-If you execute that command in a Symfony application which doesn't use Flex,
-you'll see a Composer error explaining that ``mailer`` is not a valid package
-name. However, if the application has Symfony Flex installed, that command ends
-up installing and enabling the SwiftmailerBundle, which is the best way to
-integrate Swiftmailer, the official mailer for Symfony applications.
-
-When Symfony Flex is installed in the application and you execute ``composer
-require``, the application makes a request to the Symfony Flex server before
-trying to install the package with Composer.
-
-* If there's no information about that package, the Flex server returns nothing and
-  the package installation follows the usual procedure based on Composer;
-
-* If there's special information about that package, Flex returns it in a file
-  called a "recipe" and the application uses it to decide which package to
-  install and which automated tasks to run after the installation.
-
-In the above example, Symfony Flex asks about the ``mailer`` package and the
-Symfony Flex server detects that ``mailer`` is in fact an alias for
-SwiftmailerBundle and returns the "recipe" for it.
-
-Flex keeps tracks of the recipes it installed in a ``symfony.lock`` file, which
-must be committed to your code repository.
-
-Symfony Flex Recipes
-~~~~~~~~~~~~~~~~~~~~
-
-Recipes are defined in a ``manifest.json`` file and can contain any number of
-other files and directories. For example, this is the ``manifest.json`` for
-SwiftmailerBundle:
-
-.. code-block:: javascript
-
-    {
-        "bundles": {
-            "Symfony\\Bundle\\SwiftmailerBundle\\SwiftmailerBundle": ["all"]
-        },
-        "copy-from-recipe": {
-            "config/": "%CONFIG_DIR%/"
-        },
-        "env": {
-            "MAILER_URL": "smtp://localhost:25?encryption=&auth_mode="
-        },
-        "aliases": ["mailer", "mail"]
-    }
-
-The ``aliases`` option allows Flex to install packages using short and easy to
-remember names (``composer require mailer`` vs
-``composer require symfony/swiftmailer-bundle``). The ``bundles`` option tells
-Flex in which environments this bundle should be enabled automatically (``all``
-in this case). The ``env`` option makes Flex add new environment variables to
-the application. Finally, the ``copy-from-recipe`` option allows the recipe to
-copy files and directories into your application.
-
-The instructions defined in this ``manifest.json`` file are also used by
-Symfony Flex when uninstalling dependencies (e.g. ``composer remove mailer``)
-to undo all changes. This means that Flex can remove the SwiftmailerBundle from
-the application, delete the ``MAILER_URL`` environment variable and any other
-file and directory created by this recipe.
-
-Symfony Flex recipes are contributed by the community and they are stored in
-two public repositories:
-
-* `Main recipe repository`_, is a curated list of recipes for high quality and
-  maintained packages. Symfony Flex only looks in this repository by default.
-
-* `Contrib recipe repository`_, contains all the recipes created by the
-  community. All of them are guaranteed to work, but their associated packages
-  could be unmaintained. Symfony Flex will ask your permission before installing
-  any of these recipes.
-
-Read the `Symfony Recipes documentation`_ to learn everything about how to
-create recipes for your own packages.
-
-Using Symfony Flex in New Applications
---------------------------------------
-
-Symfony has published a new "skeleton" project, which is a minimal Symfony
-project recommended to create new applications. This "skeleton" already
-includes Symfony Flex as a dependency. This means you can create a new Flex-enabled
-Symfony application by executing the following command:
-
-.. code-block:: terminal
-
-    $ composer create-project symfony/skeleton:4.1.* my-project
-
-.. note::
-
-    The use of the Symfony Installer to create new applications is no longer
-    recommended since Symfony 3.3. Use the Composer ``create-project`` command
-    instead.
-
-.. _upgrade-to-flex:
-
-Upgrading Existing Applications to Flex
----------------------------------------
+Upgrading Existing Applications to Symfony Flex
+===============================================
 
 Using Symfony Flex is optional, even in Symfony 4, where Flex is used by
 default. However, Flex is so convenient and improves your productivity so much
 that it's strongly recommended to upgrade your existing applications to it.
 
-The only caveat is that Symfony Flex requires that applications use the
-following directory structure, which is the same used by default in Symfony 4:
+Symfony Flex recommends that applications use the following directory structure,
+which is the same used by default in Symfony 4, but you can
+:ref:`customize some directories <flex-customize-paths>`:
 
 .. code-block:: text
 
     your-project/
     ├── assets/
     ├── bin/
-    │   └── console
+    │   └── console
     ├── config/
-    │   ├── bundles.php
-    │   ├── packages/
-    │   ├── routes.yaml
-    │   └── services.yaml
+    │   ├── bundles.php
+    │   ├── packages/
+    │   ├── routes.yaml
+    │   └── services.yaml
     ├── public/
-    │   └── index.php
+    │   └── index.php
     ├── src/
-    │   ├── ...
-    │   └── Kernel.php
+    │   ├── ...
+    │   └── Kernel.php
     ├── templates/
     ├── tests/
     ├── translations/
@@ -165,7 +45,7 @@ manual steps:
        $ composer require symfony/flex
 
 #. If the project's ``composer.json`` file contains ``symfony/symfony`` dependency,
-   it still depends on the Symfony Standard edition, which is no longer available
+   it still depends on the Symfony Standard Edition, which is no longer available
    in Symfony 4. First, remove this dependency:
 
    .. code-block:: terminal
@@ -239,7 +119,7 @@ manual steps:
 
 #. Move the original PHP source code from ``src/AppBundle/*``, except bundle
    specific files (like ``AppBundle.php`` and ``DependencyInjection/``), to
-   ``src/``. Remove ``src/AppBundle/``.
+   ``src/``.
 
    In addition to moving the files, update the ``autoload`` and ``autoload-dev``
    values of the ``composer.json`` file as `shown in this example`_ to use
@@ -257,6 +137,10 @@ manual steps:
 #. Move the source of the assets (e.g. the SCSS files) to ``assets/`` and use
    :doc:`Webpack Encore </frontend>` to manage and compile them.
 
+#. ``SYMFONY_DEBUG`` and ``SYMFONY_ENV`` environment variables were replaced by
+   ``APP_DEBUG`` and ``APP_ENV``. Copy their values to the new vars and then remove
+   the former ones.
+
 #. Create the new ``public/index.php`` front controller
    `copying Symfony's index.php source`_ and, if you made any customization in
    your ``web/app.php`` and ``web/app_dev.php`` files, copy those changes into
@@ -265,15 +149,50 @@ manual steps:
 #. Update the ``bin/console`` script `copying Symfony's bin/console source`_
    and changing anything according to your original console script.
 
+#. Remove ``src/AppBundle/``.
+
+#. Move the original source code from ``src/{App,...}Bundle/`` to ``src/`` and
+   update the namespaces of every PHP file to be ``App\...`` (advanced IDEs can do
+   this automatically).
+
 #. Remove the ``bin/symfony_requirements`` script and if you need a replacement
    for it, use the new `Symfony Requirements Checker`_.
 
-.. _`Symfony Flex`: https://github.com/symfony/flex
-.. _`Symfony Installer`: https://github.com/symfony/symfony-installer
-.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard
-.. _`Main recipe repository`: https://github.com/symfony/recipes
-.. _`Contrib recipe repository`: https://github.com/symfony/recipes-contrib
-.. _`Symfony Recipes documentation`: https://github.com/symfony/recipes/blob/master/README.rst
+#. Update the ``.gitignore`` file to replace the existing ``var/logs/`` entry
+   by ``var/log/``, which is the new name for the log directory.
+
+.. _flex-customize-paths:
+
+Customizing Flex Paths
+----------------------
+
+The Flex recipes make a few assumptions about your project's directory structure.
+Some of these assumptions can be customized by adding a key under the ``extra``
+section of your ``composer.json`` file. For example, to tell Flex to copy any
+PHP classes into ``src/App`` instead of ``src``:
+
+.. code-block:: json
+
+    {
+        "...": "...",
+
+        "extra": {
+            "src-dir": "src/App"
+        }
+    }
+
+The configurable paths are:
+
+* ``bin-dir``: defaults to ``bin/``
+* ``config-dir``: defaults to ``config/``
+* ``src-dir`` defaults to ``src/``
+* ``var-dir`` defaults to ``var/``
+* ``public-dir`` defaults to ``public/``
+
+If you customize these paths, some files copied from a recipe still may contain
+references to the original path. In other words: you may need to update some things
+manually after a recipe is installed.
+
 .. _`default services.yaml file`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/config/services.yaml
 .. _`shown in this example`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L24-L33
 .. _`shown in this example of the skeleton-project`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L44-L46
diff --git a/setup/homestead.rst b/setup/homestead.rst
index 747f6acf425..c68790800d3 100644
--- a/setup/homestead.rst
+++ b/setup/homestead.rst
@@ -4,8 +4,8 @@ Using Symfony with Homestead/Vagrant
 ====================================
 
 In order to develop a Symfony application, you might want to use a virtual
-development environment instead of the built-in server or WAMP/LAMP. Homestead_
-is an easy-to-use Vagrant_ box to get a virtual environment up and running
+development environment instead of the built-in server or WAMP/LAMP. `Homestead`_
+is an easy-to-use `Vagrant`_ box to get a virtual environment up and running
 quickly.
 
 .. tip::
@@ -72,8 +72,8 @@ developing your Symfony application!
     integration, automatic creation of MySQL databases and more, read the
     `Daily Usage`_ section of the Homestead documentation.
 
-.. _Homestead: https://laravel.com/docs/homestead
-.. _Vagrant: https://www.vagrantup.com/
-.. _the Homestead documentation: https://laravel.com/docs/homestead#installation-and-setup
-.. _Daily Usage: https://laravel.com/docs/homestead#daily-usage
-.. _this blog post: https://www.whitewashing.de/2013/08/19/speedup_symfony2_on_vagrant_boxes.html
+.. _`Homestead`: https://laravel.com/docs/homestead
+.. _`Vagrant`: https://www.vagrantup.com/
+.. _`the Homestead documentation`: https://laravel.com/docs/homestead#installation-and-setup
+.. _`Daily Usage`: https://laravel.com/docs/homestead#daily-usage
+.. _`this blog post`: https://www.whitewashing.de/2013/08/19/speedup_symfony2_on_vagrant_boxes.html
diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst
new file mode 100644
index 00000000000..a44ae3929d8
--- /dev/null
+++ b/setup/symfony_server.rst
@@ -0,0 +1,321 @@
+Symfony Local Web Server
+========================
+
+You can run Symfony applications with any web server (Apache, nginx, the
+internal PHP web server, etc.). However, Symfony provides its own web server to
+make you more productive while developing your applications.
+
+Although this server is not intended for production use, it supports HTTP/2,
+TLS/SSL, automatic generation of security certificates, local domains, and many
+other features that sooner or later you'll need when developing web projects.
+Moreover, the server is not tied to Symfony and you can also use it with any
+PHP application and even with HTML/SPA (single page applications).
+
+Installation
+------------
+
+The Symfony server is part of the ``symfony`` binary created when you
+`install Symfony`_ and has support for Linux, macOS and Windows.
+
+.. note::
+
+    If you want to report a bug or suggest a new feature, please create an issue
+    on `symfony/cli`_.
+
+Getting Started
+---------------
+
+The Symfony server is started once per project, so you may end up with several
+instances (each of them listening to a different port). This is the common
+workflow to serve a Symfony project:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ symfony server:start
+
+      [OK] Web server listening on http://127.0.0.1:....
+      ...
+
+    # Now, browse the given URL, or run this command:
+    $ symfony open:local
+
+Running the server this way makes it display the log messages in the console, so
+you won't be able to run other commands at the same time. If you prefer, you can
+run the Symfony server in the background:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+
+    # start the server in the background
+    $ symfony server:start -d
+
+    # continue working and running other commands...
+
+    # show the latest log messages
+    $ symfony server:log
+
+Enabling TLS
+------------
+
+Browsing the secure version of your applications locally is important to detect
+problems with mixed content early, and to run libraries that only run in HTTPS.
+Traditionally this has been painful and complicated to set up, but the Symfony
+server automates everything. First, run this command:
+
+.. code-block:: terminal
+
+    $ symfony server:ca:install
+
+This command creates a local certificate authority, registers it in your system
+trust store, registers it in Firefox (this is required only for that browser)
+and creates a default certificate for ``localhost`` and ``127.0.0.1``. In other
+words, it does everything for you.
+
+Before browsing your local application with HTTPS instead of HTTP, restart its
+server stopping and starting it again.
+
+Different PHP Settings Per Project
+----------------------------------
+
+Selecting a Different PHP Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have multiple PHP versions installed on your computer, you can tell
+Symfony which one to use creating a file called ``.php-version`` at the project
+root directory:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+
+    # use a specific PHP version
+    $ echo "7.2" > .php-version
+
+    # use any PHP 7.x version available
+    $ echo "7" > .php-version
+
+.. tip::
+
+    The Symfony server traverses the directory structure up to the root
+    directory, so you can create a ``.php-version`` file in some parent
+    directory to set the same PHP version for a group of projects under that
+    directory.
+
+Run the command below if you don't remember all the PHP versions installed on your
+computer:
+
+.. code-block:: terminal
+
+    $ symfony local:php:list
+
+      # You'll see all supported SAPIs (CGI, FastCGI, etc.) for each version.
+      # FastCGI (php-fpm) is used when possible; then CGI (which acts as a FastCGI
+      # server as well), and finally, the server falls back to plain CGI.
+
+Overriding PHP Config Options Per Project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can change the value of any PHP runtime config option per project by creating a
+file called ``php.ini`` at the project root directory. Add only the options you want
+to override:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+
+    # this project only overrides the default PHP timezone
+    $ cat php.ini
+    [Date]
+    date.timezone = Asia/Tokyo
+
+Running Commands with Different PHP Versions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When running different PHP versions it's useful to use the main ``symfony``
+command as a wrapper for the ``php`` command. This allows you to always select
+the most appropriate PHP version according to the project which is running the
+commands. It also loads the env vars automatically, which is important when
+running non-Symfony commands:
+
+.. code-block:: terminal
+
+    # runs the command with the default PHP version
+    $ php -r "..."
+
+    # runs the command with the PHP version selected by the project
+    # (or the default PHP version if the project didn't select one)
+    $ symfony php -r "..."
+
+If you are using this wrapper frequently, consider aliasing the ``php`` command
+to it:
+
+.. code-block:: terminal
+
+    $ cd ~/.symfony/bin
+    $ cp symfony php
+    # now you can run "php ..." and the "symfony" command will be executed instead
+
+    # other PHP commands can be wrapped too using this trick
+    $ cp symfony php-config
+    $ cp symfony pear
+    $ cp symfony pecl
+
+Local Domain Names
+------------------
+
+By default, projects are accessible at some random port of the ``127.0.0.1``
+local IP. However, sometimes it is preferable to associate a domain name to them:
+
+* It's more convenient when you work continuously on the same project because
+  port numbers can change but domains don't;
+* The behavior of some applications depend on their domains/subdomains;
+* To have stable endpoints, such as the local redirection URL for OAuth2.
+
+Setting up the Local Proxy
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Local domains are possible thanks to a local proxy provided by the Symfony
+server. First, start the proxy:
+
+.. code-block:: terminal
+
+    $ symfony proxy:start
+
+If this is the first time you run the proxy, you must follow these additional steps:
+
+* Open the **network configuration** of your operating system;
+* Find the **proxy settings** and select the **"Automatic Proxy Configuration"**;
+* Set the following URL as its value: ``http://127.0.0.1:7080/proxy.pac``
+
+Defining the Local Domain
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, Symfony proposes ``.wip`` (for *Work in Progress*) for the local
+domains. You can define a local domain for your project as follows:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ symfony proxy:domain:attach my-domain
+
+If you have installed the local proxy as explained in the previous section, you
+can now browse ``https://my-domain.wip`` to access your local project with the
+new custom domain.
+
+.. tip::
+
+    Browse the http://127.0.0.1:7080 URL to get the full list of local project
+    directories, their custom domains, and port numbers.
+
+When running console commands, add the ``HTTPS_PROXY`` env var to make custom
+domains work:
+
+.. code-block:: terminal
+
+    $ HTTPS_PROXY=http://127.0.0.1:7080 curl https://my-domain.wip
+
+.. tip::
+
+    If you prefer to use a different TLD, edit the ``~/.symfony/proxy.json``
+    file (where ``~`` means the path to your user directory) and change the
+    value of the ``tld`` option from ``wip`` to any other TLD.
+
+Long-Running Commands
+---------------------
+
+Long-running commands, such as the ones that compile front-end web assets, block
+the terminal and you can't run other commands at the same time. The Symfony
+server provides a ``run`` command to wrap them as follows:
+
+.. code-block:: terminal
+
+    # compile Webpack assets using Symfony Encore ... but do that in the
+    # background to not block the terminal
+    $ symfony run -d yarn encore dev --watch
+
+    # continue working and running other commands...
+
+    # from time to time, check the command logs if you want
+    $ symfony server:log
+
+    # and you can also check if the command is still running
+    $ symfony server:status
+    Web server listening on ...
+    Command "yarn ..." running with PID ...
+
+    # stop the web server (and all the associated commands) when you are finished
+    $ symfony server:stop
+
+Docker Integration
+------------------
+
+The local Symfony server provides full `Docker`_ integration for projects that
+use it. First, make sure to expose the container ports:
+
+.. code-block:: yaml
+
+    # docker-compose.override.yaml
+    services:
+        database:
+            ports:
+                - "3306"
+
+        redis:
+            ports:
+                - "6379"
+
+        # ...
+
+Then, check your service names and update them if needed (Symfony creates
+environment variables following the name of the services so they can be
+autoconfigured):
+
+.. code-block:: yaml
+
+    # docker-compose.yaml
+    services:
+        # DATABASE_URL
+        database: ...
+        # MONGODB_DATABASE, MONGODB_SERVER
+        mongodb: ...
+        # REDIS_URL
+        redis: ...
+        # ELASTISEARCH_HOST, ELASTICSEARCH_PORT
+        elasticsearch: ...
+        # RABBITMQ_DSN
+        rabbitmq: ...
+
+If your ``docker-compose.yaml`` file doesn't use the environment variable names
+expected by Symfony (e.g. you use ``MYSQL_URL`` instead of ``DATABASE_URL``)
+then you need to rename all occurrences of those environment variables in your
+Symfony application. A simpler alternative is to use the ``.env.local`` file to
+reassign the environment variables:
+
+.. code-block:: bash
+
+    # .env.local
+    DATABASE_URL=${MYSQL_URL}
+    # ...
+
+Now you can start the containers and all their services will be exposed. Browse
+any page of your application and check the "Symfony Server" section in the web
+debug toolbar. You'll see that "Docker Compose" is "Up".
+
+SymfonyCloud Integration
+------------------------
+
+The local Symfony server provides full, but optional, integration with
+`SymfonyCloud`_, a service optimized to run your Symfony applications on the
+cloud. It provides features such as creating environments, backups/snapshots,
+and even access to a copy of the production data from your local machine to help
+debug any issues.
+
+`Read SymfonyCloud technical docs`_.
+
+.. _`install Symfony`: https://symfony.com/download
+.. _`symfony/cli`: https://github.com/symfony/cli
+.. _`Docker`: https://en.wikipedia.org/wiki/Docker_(software)
+.. _`SymfonyCloud`: https://symfony.com/cloud/
+.. _`Read SymfonyCloud technical docs`: https://symfony.com/doc/master/cloud/intro.html
diff --git a/setup/unstable_versions.rst b/setup/unstable_versions.rst
index 4aa97b49dd3..be199a783d5 100644
--- a/setup/unstable_versions.rst
+++ b/setup/unstable_versions.rst
@@ -7,9 +7,10 @@ they are released as stable versions.
 Creating a New Project Based on an Unstable Symfony Version
 -----------------------------------------------------------
 
+
 Suppose that the Symfony 4.0 version hasn't been released yet and you want to create
-a new project to test its features. First, :doc:`install the Composer </setup/composer>`
-package manager. Then, open a command console, enter your project's directory and
+a new project to test its features. First, `install the Composer package manager`_.
+Then, open a command console, enter your project's directory and
 execute the following command:
 
 .. code-block:: terminal
@@ -72,3 +73,5 @@ Symfony version has deprecated some of its features.
         # ... after testing the new Symfony version
         $ git checkout master
         $ git branch -D testing_new_symfony
+
+.. _`install the Composer package manager`: https://getcomposer.org/download/
diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst
index fd746ffed2a..56b25062646 100644
--- a/setup/upgrade_major.rst
+++ b/setup/upgrade_major.rst
@@ -37,7 +37,7 @@ using these deprecated features in the last version before the major (e.g.
 
 To help you with this, deprecation notices are triggered whenever you end up
 using a deprecated feature. When visiting your application in the
-:doc:`dev environment </configuration/environments>`
+:ref:`dev environment <configuration-environments>`
 in your browser, these notices are shown in the web dev toolbar:
 
 .. image:: /_images/install/deprecations-in-profiler.png
@@ -83,7 +83,7 @@ Now, you can start fixing the notices:
 
     Remaining deprecation notices (6)
 
-    The "request" service is deprecated and will be removed in 3.0. Add a typehint for
+    The "request" service is deprecated and will be removed in 3.0. Add a type-hint for
     Symfony\Component\HttpFoundation\Request to your controller parameters to retrieve the
     request instead: 6x
         3x in PageAdminTest::testPageShow from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin
@@ -97,9 +97,9 @@ done!
 
     Sometimes, you can't fix all deprecations (e.g. something was deprecated
     in 3.4 and you still need to support 3.3). In these cases, you can still
-    use the bridge to fix as many deprecations as possible and then switch
-    to the weak test mode to make your tests pass again. You can do this by
-    using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
+    use the bridge to fix as many deprecations as possible and then allow
+    more of them to make your tests pass again. You can do this by using the
+    ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
 
     .. code-block:: xml
 
@@ -108,11 +108,15 @@ done!
             <!-- ... -->
 
             <php>
-                <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>
+                <env name="SYMFONY_DEPRECATIONS_HELPER" value="max[total]=999999"/>
             </php>
         </phpunit>
 
-    (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``).
+    You can also execute the command like:
+
+    .. code-block:: terminal
+
+        $ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 php ./bin/phpunit
 
 .. _upgrade-major-symfony-composer:
 
@@ -158,6 +162,4 @@ of.
 
 When upgrading to Symfony 4, you will probably also want to upgrade to the new
 Symfony 4 directory structure so that you can take advantage of Symfony Flex.
-This takes some work, but is optional. For details, see :ref:`upgrade-to-flex`.
-
-.. _`Symfony-Upgrade-Fixer`: https://github.com/umpirsky/Symfony-Upgrade-Fixer
+This takes some work, but is optional. For details, see :doc:`/setup/flex`.
diff --git a/setup/upgrade_minor.rst b/setup/upgrade_minor.rst
index ee3c90442a8..78999251f7b 100644
--- a/setup/upgrade_minor.rst
+++ b/setup/upgrade_minor.rst
@@ -21,9 +21,10 @@ There are two steps to upgrading a minor version:
 1) Update the Symfony Library via Composer
 ------------------------------------------
 
-Your ``composer.json`` file should already be configured to allow your Symfony
-packages to be upgraded to minor versions. But, if a package was not upgraded,
-check that the version constrains of your Symfony dependencies are like this:
+The ``composer.json`` file is configured to allow Symfony packages to be
+upgraded to patch versions. But, if you would like the packages to be upgraded
+to minor versions, check that the version constrains of the Symfony dependencies
+are like this:
 
 .. code-block:: json
 
@@ -42,6 +43,19 @@ check that the version constrains of your Symfony dependencies are like this:
         "...": "...",
     }
 
+At the bottom of your ``composer.json`` file, in the ``extra`` block you can
+find a data setting for the symfony version. Make sure to also upgrade
+this one. For instance, update it to ``4.3.*`` to upgrade to Symfony 4.3:
+
+.. code-block:: json
+
+    "extra": {
+        "symfony": {
+            "allow-contrib": false,
+            "require": "4.3.*"
+        }
+    }
+
 Next, use Composer to download new versions of the libraries:
 
 .. code-block:: terminal
diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst
index 7e80a5f533e..0f39552b398 100644
--- a/setup/web_server_configuration.rst
+++ b/setup/web_server_configuration.rst
@@ -5,10 +5,11 @@ Configuring a Web Server
 ========================
 
 The preferred way to develop your Symfony application is to use
-:doc:`PHP's internal web server </setup/built_in_web_server>`. However,
-when using an older PHP version or when running the application in the production
-environment, you'll need to use a fully-featured web server. This article
-describes several ways to use Symfony with Apache or Nginx.
+:doc:`Symfony Local Web Server </setup/symfony_server>`.
+
+However, when running the application in the production environment, you'll need
+to use a fully-featured web server. This article describes several ways to use
+Symfony with Apache or Nginx.
 
 When using Apache, you can configure PHP as an
 :ref:`Apache module <web-server-apache-mod-php>` or with FastCGI using
@@ -92,6 +93,8 @@ and increase web server performance:
         ServerAlias www.domain.tld
 
         DocumentRoot /var/www/project/public
+        DirectoryIndex /index.php
+
         <Directory /var/www/project/public>
             AllowOverride None
             Order Allow,Deny
@@ -177,10 +180,10 @@ listen on. Each pool can also be run under a different UID and GID:
 Using mod_proxy_fcgi with Apache 2.4
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass
-incoming requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket,
-enable ``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and
-use the ``SetHandler`` directive to pass requests for PHP files to PHP FPM:
+If you are running Apache 2.4, you can use ``mod_proxy_fcgi`` to pass incoming
+requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket, enable
+``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and use the
+``SetHandler`` directive to pass requests for PHP files to PHP FPM:
 
 .. code-block:: apache
 
@@ -288,7 +291,7 @@ The **minimum configuration** to get your application running under Nginx is:
         }
 
         location ~ ^/index\.php(/|$) {
-            fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;
+            fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
             fastcgi_split_path_info ^(.+\.php)(/.*)$;
             include fastcgi_params;
 
diff --git a/templating.rst b/templating.rst
index e89dc2d6692..72d7e66fa5c 100644
--- a/templating.rst
+++ b/templating.rst
@@ -23,7 +23,7 @@ code.
 Templates
 ---------
 
-A template is simply a text file that can generate any text-based format
+A template is a text file that can generate any text-based format
 (HTML, XML, CSV, LaTeX ...). The most familiar type of template is a *PHP*
 template - a text file parsed by PHP that contains a mix of text and PHP code:
 
@@ -98,7 +98,12 @@ it:
 
 Twig comes with a long list of `tags`_, `filters`_ and `functions`_ that are available
 by default. You can even add your own *custom* filters, functions (and more) via
-a :doc:`Twig Extension </templating/twig_extension>`.
+a :doc:`Twig Extension </templating/twig_extension>`. Run the following command
+to list them all:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:twig
 
 Twig code will look similar to PHP code, with subtle, nice differences. The following
 example uses a standard ``for`` tag and the ``cycle()`` function to print ten div tags,
@@ -108,7 +113,7 @@ with alternating ``odd``, ``even`` classes:
 
     {% for i in 1..10 %}
         <div class="{{ cycle(['even', 'odd'], i) }}">
-          <!-- some HTML here -->
+            <!-- some HTML here -->
         </div>
     {% endfor %}
 
@@ -119,7 +124,7 @@ Throughout this article, template examples will be shown in both Twig and PHP.
     Twig templates are meant to be simple and won't process PHP tags. This
     is by design: the Twig template system is meant to express presentation,
     not program logic. The more you use Twig, the more you'll appreciate
-    and benefit from this distinction. And of course, you'll be loved by
+    and benefit from this distinction. And you'll be loved by
     web designers everywhere.
 
     Twig can also do things that PHP can't, such as whitespace control,
@@ -381,10 +386,9 @@ the last part of the extension (e.g. ``.twig`` or ``.php``) specifies which
 of these two *engines* should be used. The first part of the extension,
 (e.g. ``.html``, ``.css``, etc) is the final format that the template will
 generate. Unlike the engine, which determines how Symfony parses the template,
-this is simply an organizational tactic used in case the same resource needs
-to be rendered as HTML (``index.html.twig``), XML (``index.xml.twig``),
-or any other format. For more information, read the :doc:`/templating/formats`
-section.
+this is an organizational tactic used in case the same resource needs to be
+rendered as HTML (``index.html.twig``), XML (``index.xml.twig``), or any other
+format. For more information, read the :doc:`/templating/formats` section.
 
 .. index::
    single: Templating; Tags and helpers
@@ -495,7 +499,7 @@ configuration:
         class WelcomeController extends AbstractController
         {
             /**
-             * @Route("/", name="welcome")
+             * @Route("/", name="welcome", methods={"GET"})
              */
             public function index()
             {
@@ -509,6 +513,7 @@ configuration:
         welcome:
             path:     /
             controller: App\Controller\WelcomeController::index
+            methods: GET
 
     .. code-block:: xml
 
@@ -517,25 +522,23 @@ configuration:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="welcome" path="/">
-                <default key="_controller">App\Controller\WelcomeController::index</default>
-            </route>
+            <route id="welcome" path="/" controller="App\Controller\WelcomeController::index" methods="GET"/>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\Route;
-        use Symfony\Component\Routing\RouteCollection;
+        use App\Controller\WelcomeController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('welcome', new Route('/', [
-            '_controller' => 'App\Controller\WelcomeController::index',
-        ]));
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('welcome', '/')
+                ->controller([WelcomeController::class, 'index'])
+                ->methods(['GET'])
+            ;
+        };
 
 To link to the page, use the ``path()`` Twig function and refer to the route:
 
@@ -558,7 +561,7 @@ route:
         class ArticleController extends AbstractController
         {
             /**
-             * @Route("/article/{slug}", name="article_show")
+             * @Route("/article/{slug}", name="article_show", methods={"GET"})
              */
             public function show($slug)
             {
@@ -572,6 +575,7 @@ route:
         article_show:
             path:       /article/{slug}
             controller: App\Controller\ArticleController::show
+            methods: GET
 
     .. code-block:: xml
 
@@ -580,25 +584,26 @@ route:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="article_show" path="/article/{slug}">
-                <default key="_controller">App\Controller\ArticleController::show</default>
-            </route>
+            <route id="article_show"
+                path="/article/{slug}"
+                controller="App\Controller\ArticleController::show"
+                methods="GET"/>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\Route;
-        use Symfony\Component\Routing\RouteCollection;
-
-        $routes = new RouteCollection();
-        $routes->add('article_show', new Route('/article/{slug}', [
-            '_controller' => 'App\Controller\ArticleController::show',
-        ]));
+        use App\Controller\ArticleController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('article_show', '/articles/{slug}')
+                ->controller([ArticleController::class, 'show'])
+                ->methods(['GET'])
+            ;
+        };
 
 In this case, you need to specify both the route name (``article_show``) and
 a value for the ``{slug}`` parameter. Using this route, revisit the
@@ -644,9 +649,9 @@ You can now use the ``asset()`` function:
 
 .. code-block:: html+twig
 
-    <img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
+    <img src="{{ asset('images/logo.png') }}" alt="Symfony!"/>
 
-    <link href="{{ asset('css/blog.css') }}" rel="stylesheet" />
+    <link href="{{ asset('css/blog.css') }}" rel="stylesheet"/>
 
 The ``asset()`` function's main purpose is to make your application more portable.
 If your application lives at the root of your host (e.g. ``http://example.com``),
@@ -666,9 +671,9 @@ being used and generating the correct paths accordingly.
 If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
 as follows:
 
-.. code-block:: html+jinja
+.. code-block:: html+twig
 
-    <img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
+    <img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!"/>
 
 .. index::
    single: Templating; Including stylesheets and JavaScripts
@@ -703,7 +708,7 @@ stylesheets and JavaScripts that you'll need throughout your site:
             {# ... #}
 
             {% block stylesheets %}
-                <link href="{{ asset('css/main.css') }}" rel="stylesheet" />
+                <link href="{{ asset('css/main.css') }}" rel="stylesheet"/>
             {% endblock %}
         </head>
         <body>
@@ -729,7 +734,7 @@ page. From inside that contact page's template, do the following:
     {% block stylesheets %}
         {{ parent() }}
 
-        <link href="{{ asset('css/contact.css') }}" rel="stylesheet" />
+        <link href="{{ asset('css/contact.css') }}" rel="stylesheet"/>
     {% endblock %}
 
     {# ... #}
@@ -742,12 +747,12 @@ template.
 
 You can also include assets located in your bundles' ``Resources/public/`` folder.
 You will need to run the ``php bin/console assets:install target [--symlink]``
-command, which copies (or symlinks) files into the correct location. (target
-is by default the "public/" directory of your application).
+command, which copies (or symlinks) files into the correct location. (By default,
+the target is the ``public/`` directory of your application.)
 
 .. code-block:: html+twig
 
-    <link href="{{ asset('bundles/acmedemo/css/contact.css') }}" rel="stylesheet" />
+    <link href="{{ asset('bundles/acmedemo/css/contact.css') }}" rel="stylesheet"/>
 
 The end result is a page that includes ``main.js`` and both the ``main.css`` and ``contact.css``
 stylesheets.
@@ -770,11 +775,11 @@ Suppose ``description`` equals ``I <3 this product``:
 
 .. code-block:: twig
 
-    <!-- output escaping is on automatically -->
-    {{ description }} <!-- I &lt;3 this product -->
+    {# output escaping is on automatically #}
+    {{ description }} {# I &lt;3 this product #}
 
-    <!-- disable output escaping with the raw filter -->
-    {{ description|raw }} <!-- I <3 this product -->
+    {# disable output escaping with the raw filter #}
+    {{ description|raw }} {# I <3 this product #}
 
 .. caution::
 
@@ -812,7 +817,4 @@ Learn more
 .. _`tags`: https://twig.symfony.com/doc/2.x/tags/index.html
 .. _`filters`: https://twig.symfony.com/doc/2.x/filters/index.html
 .. _`functions`: https://twig.symfony.com/doc/2.x/functions/index.html
-.. _`add your own extensions`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
 .. _`with_context`: https://twig.symfony.com/doc/2.x/functions/include.html
-.. _`include() function`: https://twig.symfony.com/doc/2.x/functions/include.html
-.. _`{% include %} tag`: https://twig.symfony.com/doc/2.x/tags/include.html
diff --git a/templating/PHP.rst b/templating/PHP.rst
index 6e89a46964b..52aa30694ec 100644
--- a/templating/PHP.rst
+++ b/templating/PHP.rst
@@ -4,6 +4,12 @@
 How to Use PHP instead of Twig for Templates
 ============================================
 
+.. deprecated:: 4.3
+
+    The integration of the Templating component in FrameworkBundle has been
+    deprecated since version 4.3 and will be removed in 5.0. PHP templates will
+    no longer be supported and you'll need to use Twig instead.
+
 Symfony defaults to Twig for its template engine, but you can still use
 plain PHP code if you want. Both templating engines are supported equally in
 Symfony. Symfony adds some nice features on top of PHP to make writing
@@ -17,6 +23,12 @@ templates with PHP more powerful.
 Rendering PHP Templates
 -----------------------
 
+.. deprecated:: 4.3
+
+    The integration of the Templating component in FrameworkBundle has been
+    deprecated since version 4.3 and will be removed in 5.0. PHP templates will
+    no longer be supported and you'll need to use Twig instead.
+
 If you want to use the PHP templating engine, first install the templating component:
 
 .. code-block:: terminal
@@ -43,15 +55,15 @@ Next, enable the php engine:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <!-- ... -->
                 <framework:templating>
-                    <framework:engine id="twig" />
-                    <framework:engine id="php" />
+                    <framework:engine id="twig"/>
+                    <framework:engine id="php"/>
                 </framework:templating>
             </framework:config>
         </container>
@@ -66,9 +78,9 @@ Next, enable the php engine:
             ],
         ]);
 
-You can now render a PHP template instead of a Twig one simply by using the
-``.php`` extension in the template name instead of ``.twig``. The controller
-below renders the ``index.html.php`` template::
+You can now render a PHP template instead of a Twig one by using the ``.php``
+extension in the template name instead of ``.twig``. The controller below
+renders the ``index.html.php`` template::
 
     // src/Controller/HelloController.php
 
@@ -149,7 +161,7 @@ another one:
     <!DOCTYPE html>
     <html>
         <head>
-            <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+            <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
             <title><?php $view['slots']->output('title', 'Hello Application') ?></title>
         </head>
         <body>
@@ -191,7 +203,7 @@ The base layout already has the code to output the title in the header:
 
     <!-- src/Resources/views/base.html.php -->
     <head>
-        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
         <title><?php $view['slots']->output('title', 'Hello Application') ?></title>
     </head>
 
@@ -309,9 +321,9 @@ Symfony provides the ``assets`` tag to deal with them:
 
 .. code-block:: html+php
 
-    <link href="<?= $view['assets']->getUrl('css/blog.css') ?>" rel="stylesheet" type="text/css" />
+    <link href="<?= $view['assets']->getUrl('css/blog.css') ?>" rel="stylesheet" type="text/css"/>
 
-    <img src="<?= $view['assets']->getUrl('images/logo.png') ?>" />
+    <img src="<?= $view['assets']->getUrl('images/logo.png') ?>"/>
 
 The ``assets`` helper's main purpose is to make your application more
 portable. Thanks to this helper, you can move the application root directory
@@ -423,9 +435,9 @@ form is rendered.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:templating>
@@ -448,9 +460,9 @@ form is rendered.
                         'App:Form',
                     ],
                 ],
-             ],
+            ],
 
-             // ...
+            // ...
         ]);
 
 By default, the PHP engine uses a *div* layout when rendering forms. Some people,
@@ -476,9 +488,9 @@ resource to use such a layout:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:templating>
@@ -502,7 +514,7 @@ resource to use such a layout:
                 ],
             ],
 
-             // ...
+            // ...
         ]);
 
 If you only want to make the change in one template, add the following line to
@@ -532,7 +544,7 @@ original template:
     <?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?>
     <?php if (!$compound) { $label_attr['for'] = $id; } ?>
     <?php if (!$label) { $label = $view['form']->humanize($name); } ?>
-    <label <?php foreach ($label_attr as $k => $v) { printf('%s="%s" ', $view->escape($k), $view->escape($v)); } ?>><?= $view->escape($view['translator']->trans($label, [], $translation_domain)) ?></label>
+    <label <?php foreach ($label_attr as $k => $v) { printf('%s="%s" ', $view->escape($k), $view->escape($v)); } ?>><?= $view->escape($view['translator']->trans($label, $label_translation_parameters, $translation_domain)) ?></label>
 
     <!-- customization -->
     <?php if ($required) : ?>
@@ -562,5 +574,3 @@ original template:
     <?php if (isset($help)) : ?>
         <span class="help"><?= $view->escape($help) ?></span>
     <?php endif ?>
-
-.. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view
diff --git a/templating/debug.rst b/templating/debug.rst
index d270151fade..1491b385d79 100644
--- a/templating/debug.rst
+++ b/templating/debug.rst
@@ -67,3 +67,17 @@ By design, the ``dump()`` function is only available in the ``dev`` and ``test``
 environments, to avoid leaking sensitive information in production. In fact,
 trying to use the ``dump()`` function in the ``prod`` environment will result in
 a PHP error.
+
+Execute this command to list all Twig functions, filters, globals, tests and
+registered namespaces and their paths:
+
+.. code-block:: terminal
+
+    # list general information
+    $ php bin/console debug:twig
+
+    # filter output by any keyword
+    $ php bin/console debug:twig --filter=date
+
+    # pass a template name to show the physical file which will be loaded
+    $ php bin/console debug:twig @Twig/Exception/error.html.twig
diff --git a/templating/escaping.rst b/templating/escaping.rst
index 67d7b887c1f..b976a2bbc24 100644
--- a/templating/escaping.rst
+++ b/templating/escaping.rst
@@ -10,7 +10,7 @@ is that dynamic content could break the HTML of the resulting page or allow
 a malicious user to perform a `Cross Site Scripting`_ (XSS) attack. Consider
 this classic example:
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     Hello {{ name }}
 
diff --git a/templating/formats.rst b/templating/formats.rst
index 70ba2f72aa2..b12f471a6ff 100644
--- a/templating/formats.rst
+++ b/templating/formats.rst
@@ -6,7 +6,7 @@ How to Work with Different Output Formats in Templates
 
 Templates are a generic way to render content in *any* format. While in
 most cases you'll use templates to render HTML content, a template can just
-as easily generate JavaScript, CSS, XML or any other format you can dream of.
+generate JavaScript, CSS, XML or any other format.
 
 For example, the same "resource" is often rendered in several formats.
 To render an article index page in XML, include the format in the
@@ -48,10 +48,10 @@ but can return any other format based on the format requested by the user.
 The request format is most often managed by the routing, where a route can
 be configured so that ``/about-us`` sets the request format to ``html`` while
 ``/about-us.xml`` sets the format to ``xml``. This can be achieved by using the
-special ``_format`` placeholder in your route definition::
+:ref:`special _format parameter <routing-format-parameter>` in your route definition::
 
     /**
-     * @Route("/{slug}.{_format}", defaults={"_format"="html"})
+     * @Route("/{slug}.{_format}", defaults={"_format"="html"}, requirements={"_format"="html|xml"}))
      */
     public function show(Request $request, $slug)
     {
@@ -67,10 +67,6 @@ format:
         View as XML
     </a>
 
-.. seealso::
-
-    For more information, see this :ref:`Advanced Routing Example <advanced-routing-example>`.
-
 .. tip::
 
     When building APIs, using file name extensions often isn't the best
diff --git a/templating/global_variables.rst b/templating/global_variables.rst
index 5bfaa5d8a86..13dc8c11106 100644
--- a/templating/global_variables.rst
+++ b/templating/global_variables.rst
@@ -25,9 +25,9 @@ This is possible inside your ``config/packages/twig.yaml`` file:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <!-- ... -->
@@ -39,10 +39,10 @@ This is possible inside your ``config/packages/twig.yaml`` file:
 
         // config/packages/twig.php
         $container->loadFromExtension('twig', [
-             // ...
-             'globals' => [
-                 'ga_tracking' => 'UA-xxxxx-x',
-             ],
+            // ...
+            'globals' => [
+                'ga_tracking' => 'UA-xxxxx-x',
+            ],
         ]);
 
 Now, the variable ``ga_tracking`` is available in all Twig templates:
@@ -82,9 +82,9 @@ system, which lets you isolate or reuse the value:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <twig:global key="ga_tracking">%ga_tracking%</twig:global>
@@ -95,9 +95,9 @@ system, which lets you isolate or reuse the value:
 
         // config/packages/twig.php
         $container->loadFromExtension('twig', [
-             'globals' => [
-                 'ga_tracking' => '%ga_tracking%',
-             ],
+            'globals' => [
+                'ga_tracking' => '%ga_tracking%',
+            ],
         ]);
 
 The same variable is available exactly as before.
@@ -137,9 +137,9 @@ This should feel familiar, as it's the same syntax you use in service configurat
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/twig
-                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
                 <!-- ... -->
@@ -151,8 +151,8 @@ This should feel familiar, as it's the same syntax you use in service configurat
 
         // config/packages/twig.php
         $container->loadFromExtension('twig', [
-             // ...
-             'globals' => [
-                 'user_management' => '@App\Service\UserManagement',
-             ],
+            // ...
+            'globals' => [
+                'user_management' => '@App\Service\UserManagement',
+            ],
         ]);
diff --git a/templating/hinclude.rst b/templating/hinclude.rst
index b9919b313b0..0f12fd23035 100644
--- a/templating/hinclude.rst
+++ b/templating/hinclude.rst
@@ -4,7 +4,7 @@
 How to Embed Asynchronous Content with hinclude.js
 ==================================================
 
-Controllers can be embedded asynchronously using the hinclude.js_ JavaScript library.
+Controllers can be embedded asynchronously using the `hinclude.js`_ JavaScript library.
 As the embedded content comes from another page (or controller for that matter),
 Symfony uses a version of the standard ``render()`` function to configure ``hinclude``
 tags:
@@ -40,12 +40,12 @@ tags:
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:framework="http://symfony.com/schema/dic/symfony"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
                 <!-- ... -->
                 <framework:config>
-                    <framework:fragment path="/_fragment" />
+                    <framework:fragment path="/_fragment"/>
                 </framework:config>
             </container>
 
@@ -67,7 +67,7 @@ in your application configuration:
         # config/packages/framework.yaml
         framework:
             # ...
-            templating:
+            fragments:
                 hinclude_default_template: hinclude.html.twig
 
     .. code-block:: xml
@@ -78,12 +78,12 @@ in your application configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <!-- ... -->
             <framework:config>
-                <framework:templating hinclude-default-template="hinclude.html.twig" />
+                <framework:fragments hinclude-default-template="hinclude.html.twig"/>
             </framework:config>
         </container>
 
@@ -92,13 +92,17 @@ in your application configuration:
         // config/packages/framework.php
         $container->loadFromExtension('framework', [
             // ...
-            'templating' => [
-                'hinclude_default_template' => [
-                    'hinclude.html.twig',
-                ],
+            'fragments' => [
+                'hinclude_default_template' => 'hinclude.html.twig',
             ],
         ]);
 
+.. versionadded:: 4.3
+
+    The ``framework.fragments.hinclude_default_template`` option was introduced
+    in Symfony 4.3. In previous Symfony versions it was called
+    ``framework.templating.hinclude_default_template``.
+
 You can define default templates per ``render()`` function (which will override
 any global default template that is defined):
 
diff --git a/templating/inheritance.rst b/templating/inheritance.rst
index 10c48a00424..3394a4de234 100644
--- a/templating/inheritance.rst
+++ b/templating/inheritance.rst
@@ -47,9 +47,8 @@ Notice that this template extends the section template (``blog/layout.html.twig`
 which in turn extends the base application layout (``base.html.twig``). This is
 the common three-level inheritance model.
 
-When building your application, you may choose to follow this method or simply
+When building your application, you may choose to follow this method or
 make each page template extend the base application template directly
 (e.g. ``{% extends 'base.html.twig' %}``). The three-template model is a
 best-practice method used by vendor bundles so that the base template for a
-bundle can be easily overridden to properly extend your application's base
-layout.
+bundle can be overridden to properly extend your application's base layout.
diff --git a/templating/namespaced_paths.rst b/templating/namespaced_paths.rst
index fe14f48b759..17b1ee2b429 100644
--- a/templating/namespaced_paths.rst
+++ b/templating/namespaced_paths.rst
@@ -46,7 +46,7 @@ First, register a namespace for this directory:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%">
                 <twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
@@ -71,6 +71,13 @@ in the ``vendor/acme/foo-bar/templates/`` directory, you can refer to it as:
 
     {{ include('@foo_bar/sidebar.twig') }}
 
+Execute this command to verify if your template name is correct and know which
+template file will be loaded:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:twig @foo_bar/sidebar.twig
+
 Multiple Paths per Namespace
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -100,7 +107,7 @@ specific template doesn't exist.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%">
                 <twig:path namespace="theme">%kernel.project_dir%/vendor/acme/themes/theme1</twig:path>
diff --git a/templating/render_without_controller.rst b/templating/render_without_controller.rst
index 16a1a4f4462..daca135674f 100644
--- a/templating/render_without_controller.rst
+++ b/templating/render_without_controller.rst
@@ -25,6 +25,7 @@ can do this without creating a controller:
             controller:   Symfony\Bundle\FrameworkBundle\Controller\TemplateController
             defaults:
                 template: static/privacy.html.twig
+            methods: GET
 
     .. code-block:: xml
 
@@ -32,10 +33,12 @@ can do this without creating a controller:
         <?xml version="1.0" encoding="UTF-8" ?>
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/routing https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="acme_privacy" path="/privacy">
-                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\TemplateController</default>
+            <route id="acme_privacy"
+                path="/privacy"
+                controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController"
+                methods="GET">
                 <default key="template">static/privacy.html.twig</default>
             </route>
         </routes>
@@ -43,19 +46,21 @@ can do this without creating a controller:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('acme_privacy', new Route('/privacy', [
-            '_controller' => 'Symfony\Bundle\FrameworkBundle\Controller\TemplateController',
-            'template'    => 'static/privacy.html.twig',
-        ]));
-
-        return $routes;
-
-The ``TemplateController`` will simply render whatever template you've passed as
-the ``template`` default value.
+        use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('acme_privacy', '/privacy')
+                ->controller(TemplateController::class)
+                ->methods(['GET'])
+                ->defaults([
+                    'template'  => 'static/privacy.html.twig',
+                ])
+            ;
+        };
+
+The ``TemplateController`` will render whatever template you've passed as the
+``template`` default value.
 
 You can also use this trick when rendering embedded controllers
 from within a template. But since the purpose of rendering a controller from
@@ -63,7 +68,7 @@ within a template is typically to prepare some data in a custom controller,
 this is probably only useful if you'd like to cache this page partial (see
 :ref:`templating-no-controller-caching`).
 
-.. code-block:: html+twig
+.. code-block:: twig
 
     {{ render(url('acme_privacy')) }}
 
@@ -88,6 +93,7 @@ exactly how your page is cached:
                 template:  'static/privacy.html.twig'
                 maxAge:    86400
                 sharedAge: 86400
+            methods: GET
 
     .. code-block:: xml
 
@@ -95,10 +101,12 @@ exactly how your page is cached:
         <?xml version="1.0" encoding="UTF-8" ?>
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/routing https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="acme_privacy" path="/privacy">
-                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\TemplateController</default>
+            <route id="acme_privacy"
+                path="/privacy"
+                controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController"
+                methods="GET">
                 <default key="template">static/privacy.html.twig</default>
                 <default key="maxAge">86400</default>
                 <default key="sharedAge">86400</default>
@@ -108,18 +116,20 @@ exactly how your page is cached:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $routes = new RouteCollection();
-        $routes->add('acme_privacy', new Route('/privacy', [
-            '_controller' => 'Symfony\Bundle\FrameworkBundle\Controller\TemplateController',
-            'template'    => 'static/privacy.html.twig',
-            'maxAge'      => 86400,
-            'sharedAge'   => 86400,
-        ]));
-
-        return $routes;
+        use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('acme_privacy', '/privacy')
+                ->controller(TemplateController::class)
+                ->methods(['GET'])
+                ->defaults([
+                    'template'  => 'static/privacy.html.twig',
+                    'maxAge'    => 86400,
+                    'sharedAge' => 86400,
+                ])
+            ;
+        };
 
 The ``maxAge`` and ``sharedAge`` values are used to modify the Response
 object created in the controller. For more information on caching, see
diff --git a/templating/twig_extension.rst b/templating/twig_extension.rst
index c3eb2cfd6c1..2b77d50de2f 100644
--- a/templating/twig_extension.rst
+++ b/templating/twig_extension.rst
@@ -94,8 +94,24 @@ Next, register your class as a service and tag it with ``twig.extension``. If yo
 using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
 you're done! Symfony will automatically know about your new service and add the tag.
 
+Optionally, execute this command to confirm that your new filter was
+successfully registered:
+
+.. code-block:: terminal
+
+    $ php bin/console debug:twig --filter=price
+
 You can now start using your filter in any Twig template.
 
+.. tip::
+
+    Run the following command to verify that the filters and functions created
+    by your extensions are successfully registered:
+
+    .. code-block:: terminal
+
+        $ php bin/console debug:twig
+
 .. _lazy-loaded-twig-extensions:
 
 Creating Lazy-Loaded Twig Extensions
@@ -117,7 +133,7 @@ be significant.
 
 That's why Twig allows to decouple the extension definition from its
 implementation. Following the same example as before, the first change would be
-to remove the ``priceFilter()`` method from the extension and update the PHP
+to remove the ``formatPrice()`` method from the extension and update the PHP
 callable defined in ``getFilters()``::
 
     // src/Twig/AppExtension.php
@@ -133,14 +149,14 @@ callable defined in ``getFilters()``::
         {
             return [
                 // the logic of this filter is now implemented in a different class
-                new TwigFilter('price', [AppRuntime::class, 'priceFilter']),
+                new TwigFilter('price', [AppRuntime::class, 'formatPrice']),
             ];
         }
     }
 
 Then, create the new ``AppRuntime`` class (it's not required but these classes
 are suffixed with ``Runtime`` by convention) and include the logic of the
-previous ``priceFilter()`` method::
+previous ``formatPrice()`` method::
 
     // src/Twig/AppRuntime.php
     namespace App\Twig;
@@ -155,7 +171,7 @@ previous ``priceFilter()`` method::
             // extensions, you'll need to inject services using this constructor
         }
 
-        public function priceFilter($number, $decimals = 0, $decPoint = '.', $thousandsSep = ',')
+        public function formatPrice($number, $decimals = 0, $decPoint = '.', $thousandsSep = ',')
         {
             $price = number_format($number, $decimals, $decPoint, $thousandsSep);
             $price = '$'.$price;
@@ -170,5 +186,4 @@ for this class and :doc:`tag your service </service_container/tags>` with ``twig
 
 .. _`official Twig extensions`: https://github.com/twigphp/Twig-extensions
 .. _`global variables`: https://twig.symfony.com/doc/2.x/advanced.html#id1
-.. _`functions`: https://twig.symfony.com/doc/2.x/advanced.html#id2
 .. _`Twig Extensions`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
diff --git a/testing.rst b/testing.rst
index ad256bc24e0..7a3c44836b6 100644
--- a/testing.rst
+++ b/testing.rst
@@ -33,7 +33,7 @@ command:
 
 .. note::
 
-    The ``./bin/phpunit`` command is created by :doc:`Symfony Flex </setup/flex>`
+    The ``./bin/phpunit`` command is created by :ref:`Symfony Flex <symfony-flex>`
     when installing the ``phpunit-bridge`` package. If the command is missing, you
     can remove the package (``composer remove symfony/phpunit-bridge``) and install
     it again. Another solution is to remove the project's ``symfony.lock`` file and
@@ -109,13 +109,13 @@ You can also limit a test run to a directory or a specific test file:
 .. code-block:: terminal
 
     # run all tests of the application
-    $ ./bin/phpunit
+    $ php bin/phpunit
 
     # run all tests in the Util/ directory
-    $ ./bin/phpunit tests/Util
+    $ php bin/phpunit tests/Util
 
     # run tests for the Calculator class
-    $ ./bin/phpunit tests/Util/CalculatorTest.php
+    $ php bin/phpunit tests/Util/CalculatorTest.php
 
 .. index::
    single: Tests; Functional tests
@@ -204,12 +204,29 @@ component, run:
     $ composer require --dev symfony/css-selector
 
 Now you can use CSS selectors with the crawler. To assert that the phrase
-"Hello World" is on the page at least once, you can use this assertion::
+"Hello World" is present in the page's main title, you can use this assertion::
 
-    $this->assertGreaterThan(
-        0,
-        $crawler->filter('html:contains("Hello World")')->count()
-    );
+    $this->assertSelectorTextContains('html h1.title', 'Hello World');
+
+This assertion will internally call ``$crawler->filter('html h1.title')``, which allows
+you to use CSS selectors to filter any HTML element in the page and check for
+its existence, attributes, text, etc.
+
+The ``assertSelectorTextContains`` method is not a native PHPUnit assertion and is
+available thanks to the ``WebTestCase`` class.
+
+.. versionadded:: 4.3
+
+    The ``WebTestCase`` assertions were introduced in Symfony 4.3
+
+.. seealso::
+
+    Using native PHPUnit methods, the same assertion would look like this::
+
+        $this->assertGreaterThan(
+            0,
+            $crawler->filter('html h1.title:contains("Hello World")')->count()
+        );
 
 The crawler can also be used to interact with the page. Click on a link by first
 selecting it with the crawler using either an XPath expression or a CSS selector,
@@ -242,7 +259,7 @@ some form values and submit the corresponding form::
     of form fields (e.g. ``select()`` and ``tick()``). For details, see the
     `Forms`_ section below.
 
-Now that you can easily navigate through an application, use assertions to test
+Now that you can navigate through an application, use assertions to test
 that it actually does what you expect it to. Use the Crawler to make assertions
 on the DOM::
 
@@ -412,22 +429,15 @@ returns a ``Crawler`` instance.
 Use the crawler to find DOM elements in the response. These elements can then
 be used to click on links and submit forms::
 
-    $link = $crawler->selectLink('Go elsewhere...')->link();
-    $crawler = $client->click($link);
+    $crawler = $client->clickLink('Go elsewhere...');
 
-    $form = $crawler->selectButton('validate')->form();
-    $crawler = $client->submit($form, ['name' => 'Fabien']);
+    $crawler = $client->submitForm('validate', ['name' => 'Fabien']);
 
-The ``click()`` and ``submit()`` methods both return a ``Crawler`` object.
+The ``clickLink()`` and ``submitForm()`` methods both return a ``Crawler`` object.
 These methods are the best way to browse your application as it takes care
 of a lot of things for you, like detecting the HTTP method from a form and
 giving you a nice API for uploading files.
 
-.. tip::
-
-    You will learn more about the ``Link`` and ``Form`` objects in the
-    :ref:`Crawler <testing-crawler>` section below.
-
 The ``request()`` method can also be used to simulate form submissions directly
 or perform more complex requests. Some useful examples::
 
@@ -470,7 +480,7 @@ or perform more complex requests. Some useful examples::
     );
 
 Last but not least, you can force each request to be executed in its own PHP
-process to avoid any side-effects when working with several clients in the same
+process to avoid any side effects when working with several clients in the same
 script::
 
     $client->insulate();
@@ -485,9 +495,6 @@ shortcut to make AJAX requests::
     // the required HTTP_X_REQUESTED_WITH header is added automatically
     $client->xmlHttpRequest('POST', '/submit', ['name' => 'Fabien']);
 
-.. versionadded:: 4.1
-    The ``xmlHttpRequest()`` method was introduced in Symfony 4.1.
-
 Browsing
 ~~~~~~~~
 
@@ -533,9 +540,6 @@ You can also get the objects related to the latest request::
 Accessing the Container
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.1
-    The ``self::$container`` property was introduced in Symfony 4.1.
-
 It's highly recommended that a functional test only tests the response. But
 under certain very rare circumstances, you might want to access some services
 to write assertions. Given that services are private by default, test classes
@@ -665,7 +669,7 @@ narrow down your node selection by chaining the method calls::
     $crawler
         ->filter('h1')
         ->reduce(function ($node, $i) {
-            if (!$node->getAttribute('class')) {
+            if (!$node->attr('class')) {
                 return false;
             }
         })
@@ -702,31 +706,39 @@ The Crawler can extract information from the nodes::
 Links
 ~~~~~
 
-To select links, you can use the traversing methods above or the convenient
-``selectLink()`` shortcut::
+Use the ``clickLink()`` method to click on the first link that contains the
+given text (or the first clickable image with that ``alt`` attribute)::
 
-    $crawler->selectLink('Click here');
+    $client = static::createClient();
+    $client->request('GET', '/post/hello-world');
 
-This selects all links that contain the given text, or clickable images for
-which the ``alt`` attribute contains the given text. Like the other filtering
-methods, this returns another ``Crawler`` object.
+    $client->clickLink('Click here');
 
-Once you've selected a link, you have access to a special ``Link`` object,
-which has helpful methods specific to links (such as ``getMethod()`` and
-``getUri()``). To click on the link, use the Client's ``click()`` method
-and pass it a ``Link`` object::
+If you need access to the :class:`Symfony\\Component\\DomCrawler\\Link` object
+that provides helpful methods specific to links (such as ``getMethod()`` and
+``getUri()``), use the ``selectLink()`` method instead::
 
-    $link = $crawler->selectLink('Click here')->link();
+    $client = static::createClient();
+    $crawler = $client->request('GET', '/post/hello-world');
 
+    $link = $crawler->selectLink('Click here')->link();
     $client->click($link);
 
 Forms
 ~~~~~
 
-Forms can be selected using their buttons, which can be selected with the
-``selectButton()`` method, just like links::
+Use the ``submitForm()`` method to submit the form that contains the given button::
 
-    $buttonCrawlerNode = $crawler->selectButton('submit');
+    $client = static::createClient();
+    $client->request('GET', '/post/hello-world');
+
+    $crawler = $client->submitForm('Add comment', [
+        'comment_form[content]' => '...',
+    ]);
+
+The first argument of ``submitForm()`` is the text content, ``id``, ``value`` or
+``name`` of any ``<button>`` or ``<input type="submit">`` included in the form.
+The second optional argument is used to override the default form field values.
 
 .. note::
 
@@ -734,33 +746,28 @@ Forms can be selected using their buttons, which can be selected with the
     buttons; if you use the traversing API, keep in mind that you must look for a
     button.
 
-The ``selectButton()`` method can select ``button`` tags and submit ``input``
-tags. It uses several parts of the buttons to find them:
+If you need access to the :class:`Symfony\\Component\\DomCrawler\\Form` object
+that provides helpful methods specific to forms (such as ``getUri()``,
+``getValues()`` and ``getFields()``) use the ``selectButton()`` method instead::
 
-* The ``value`` attribute value;
-* The ``id`` or ``alt`` attribute value for images;
-* The ``id`` or ``name`` attribute value for ``button`` tags.
+    $client = static::createClient();
+    $crawler = $client->request('GET', '/post/hello-world');
 
-Once you have a Crawler representing a button, call the ``form()`` method
-to get a ``Form`` instance for the form wrapping the button node::
+    $buttonCrawlerNode = $crawler->selectButton('submit');
 
+    // select the form that contains this button
     $form = $buttonCrawlerNode->form();
 
-When calling the ``form()`` method, you can also pass an array of field values
-that overrides the default ones::
-
+    // you can also pass an array of field values that overrides the default ones
     $form = $buttonCrawlerNode->form([
         'my_form[name]'    => 'Fabien',
         'my_form[subject]' => 'Symfony rocks!',
     ]);
 
-And if you want to simulate a specific HTTP method for the form, pass it as a
-second argument::
-
+    // you can pass a second argument to override the form HTTP method
     $form = $buttonCrawlerNode->form([], 'DELETE');
 
-The Client can submit ``Form`` instances::
-
+    // submit the Form object
     $client->submit($form);
 
 The field values can also be passed as a second argument of the ``submit()``
@@ -810,13 +817,11 @@ their type::
 
 .. tip::
 
-    The ``submit()`` method defines a third optional argument to add custom
-    HTTP headers when submitting the form::
+    The ``submit()`` and ``submitForm()`` methods define optional arguments to
+    add custom server parameters and HTTP headers when submitting the form::
 
         $client->submit($form, [], ['HTTP_ACCEPT_LANGUAGE' => 'es']);
-
-    .. versionadded:: 4.1
-        The feature to add custom HTTP headers was introduced in Symfony 4.1.
+        $client->submitForm($button, [], 'POST', ['HTTP_ACCEPT_LANGUAGE' => 'es']);
 
 Adding and Removing Forms to a Collection
 .........................................
@@ -896,12 +901,12 @@ configuration option:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/swiftmailer
-                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+                https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
             <!-- ... -->
-            <swiftmailer:config disable-delivery="true" />
+            <swiftmailer:config disable-delivery="true"/>
         </container>
 
     .. code-block:: php
diff --git a/testing/bootstrap.rst b/testing/bootstrap.rst
index dac44ecca07..cf1b63621a2 100644
--- a/testing/bootstrap.rst
+++ b/testing/bootstrap.rst
@@ -12,13 +12,13 @@ To do this, first add a file that executes your bootstrap work::
     if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) {
         // executes the "php bin/console cache:clear" command
         passthru(sprintf(
-            'php "%s/../bin/console" cache:clear --env=%s --no-warmup',
-            __DIR__,
-            $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV']
+            'APP_ENV=%s php "%s/../bin/console" cache:clear --no-warmup',
+            $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'],
+            __DIR__
         ));
     }
 
-    require __DIR__.'/../vendor/autoload.php';
+    require __DIR__.'/../config/bootstrap.php';
 
 Then, configure ``phpunit.xml.dist`` to execute this ``bootstrap.php`` file
 before running the tests:
@@ -44,7 +44,7 @@ cache to be cleared:
         <!-- ... -->
 
         <php>
-            <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test" />
+            <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test"/>
         </php>
     </phpunit>
 
diff --git a/testing/database.rst b/testing/database.rst
index 0078d04fa7b..ee48e55d8b1 100644
--- a/testing/database.rst
+++ b/testing/database.rst
@@ -67,7 +67,7 @@ Suppose the class you want to test looks like this::
     }
 
 Since the ``EntityManagerInterface`` gets injected into the class through the constructor,
-it's easy to pass a mock object within a test::
+you can pass a mock object within a test::
 
     // tests/Salary/SalaryCalculatorTest.php
     namespace App\Tests\Salary;
@@ -129,7 +129,7 @@ To do this, you can override the value of the ``DATABASE_URL`` env var in the
     <phpunit>
         <php>
             <!-- the value is the Doctrine connection string in DSN format -->
-            <env name="DATABASE_URL" value="mysql://USERNAME:PASSWORD@127.0.0.1/DB_NAME" />
+            <env name="DATABASE_URL" value="mysql://USERNAME:PASSWORD@127.0.0.1/DB_NAME"/>
         </php>
         <!-- ... -->
     </phpunit>
diff --git a/testing/doctrine.rst b/testing/doctrine.rst
index a565e7b7058..dacfaf7c006 100644
--- a/testing/doctrine.rst
+++ b/testing/doctrine.rst
@@ -8,8 +8,8 @@ Unit testing Doctrine repositories in a Symfony project is not recommended.
 When you're dealing with a repository, you're really dealing with something
 that's meant to be tested against a real database connection.
 
-Fortunately, you can easily test your queries against a real database, as
-described below.
+Fortunately, you can test your queries against a real database, as described
+below.
 
 Functional Testing
 ------------------
diff --git a/testing/functional_tests_assertions.rst b/testing/functional_tests_assertions.rst
new file mode 100644
index 00000000000..63482dd046b
--- /dev/null
+++ b/testing/functional_tests_assertions.rst
@@ -0,0 +1,83 @@
+.. index::
+   single: Tests; Assertions
+
+Functional Test specific Assertions
+===================================
+
+.. versionadded:: 4.3
+
+    The shortcut methods for assertions using ``WebTestCase`` were introduced
+    in Symfony 4.3.
+
+When doing functional tests, sometimes you need to make complex assertions in
+order to check whether the ``Request``, the ``Response`` or the ``Crawler``
+contain the expected information to make your test succeed.
+
+Here is an example with plain PHPUnit::
+
+    $this->assertGreaterThan(
+        0,
+        $crawler->filter('html:contains("Hello World")')->count()
+    );
+
+Now here is the example with the assertions specific to Symfony::
+
+    $this->assertSelectorTextContains('html', 'Hello World');
+
+.. note::
+
+    These assertions only work if a request has been made with the ``Client``
+    in a test case extending the ``WebTestCase`` class.
+
+Assertions Reference
+---------------------
+
+Response
+~~~~~~~~
+
+- ``assertResponseIsSuccessful()``
+- ``assertResponseStatusCodeSame()``
+- ``assertResponseRedirects()``
+- ``assertResponseHasHeader()``
+- ``assertResponseNotHasHeader()``
+- ``assertResponseHeaderSame()``
+- ``assertResponseHeaderNotSame()``
+- ``assertResponseHasCookie()``
+- ``assertResponseNotHasCookie()``
+- ``assertResponseCookieValueSame()``
+
+Request
+~~~~~~~
+
+- ``assertRequestAttributeValueSame()``
+- ``assertRouteSame()``
+
+Browser
+~~~~~~~
+
+- ``assertBrowserHasCookie()``
+- ``assertBrowserNotHasCookie()``
+- ``assertBrowserCookieValueSame()``
+
+Crawler
+~~~~~~~
+
+- ``assertSelectorExists()``
+- ``assertSelectorNotExists()``
+- ``assertSelectorTextContains()``
+- ``assertSelectorTextSame()``
+- ``assertSelectorTextNotContains()``
+- ``assertPageTitleSame()``
+- ``assertPageTitleContains()``
+- ``assertInputValueSame()``
+- ``assertInputValueNotSame()``
+
+Troubleshooting
+---------------
+
+These assertions will not work with `symfony/panther`_ as they use the
+``Request`` and ``Response`` objects from the ``HttpFoundation``
+component, and the ``KernelBrowser`` from the ``FrameworkBundle``.
+Panther only uses the ``BrowserKit`` component.
+
+.. _`symfony/panther`: https://github.com/symfony/panther
diff --git a/testing/http_authentication.rst b/testing/http_authentication.rst
index 671f4f96710..0fe6d4aea85 100644
--- a/testing/http_authentication.rst
+++ b/testing/http_authentication.rst
@@ -40,8 +40,8 @@ firewall, but only in the configuration file used by tests:
         <security:config>
             <!-- replace 'main' by the name of your own firewall -->
             <security:firewall name="main">
-              <security:http-basic />
-           </security:firewall>
+                <security:http-basic/>
+            </security:firewall>
         </security:config>
 
     .. code-block:: php
diff --git a/testing/insulating_clients.rst b/testing/insulating_clients.rst
index f49906d9b09..ad7820688b5 100644
--- a/testing/insulating_clients.rst
+++ b/testing/insulating_clients.rst
@@ -39,7 +39,7 @@ can insulate your clients::
     $this->assertRegExp('/Hello/', $sally->getResponse()->getContent());
 
 Insulated clients transparently execute their requests in a dedicated and
-clean PHP process, thus avoiding any side-effects.
+clean PHP process, thus avoiding any side effects.
 
 .. tip::
 
diff --git a/testing/profiling.rst b/testing/profiling.rst
index 28bb64458e7..bfe336442ec 100644
--- a/testing/profiling.rst
+++ b/testing/profiling.rst
@@ -34,13 +34,13 @@ tests significantly. That's why Symfony disables it by default:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <!-- ... -->
 
             <framework:config>
-                <framework:profiler enabled="true" collect="false" />
+                <framework:profiler enabled="true" collect="false"/>
             </framework:config>
         </container>
 
@@ -105,7 +105,7 @@ provided by the collectors obtained through the ``$client->getProfile()`` call::
 
 If a test fails because of profiling data (too many DB queries for instance),
 you might want to use the Web Profiler to analyze the request after the tests
-finish. It's easy to achieve if you embed the token in the error message::
+finish. It can be achieved by embedding the token in the error message::
 
     $this->assertLessThan(
         30,
diff --git a/translation.rst b/translation.rst
index c15b1c84e47..4b0bd36ae49 100644
--- a/translation.rst
+++ b/translation.rst
@@ -12,13 +12,11 @@ wrapping each with a function capable of translating the text (or "message")
 into the language of the user::
 
     // text will *always* print out in English
-    dump('Hello World');
-    die();
+    echo 'Hello World';
 
     // text can be translated into the end-user's language or
     // default to English
-    dump($translator->trans('Hello World'));
-    die();
+    echo $translator->trans('Hello World');
 
 .. note::
 
@@ -46,8 +44,6 @@ to learn even more. Overall, the process has several steps:
    for the request and optionally
    :doc:`on the user's entire session </session/locale_sticky_session>`.
 
-.. _translation-configuration:
-
 Installation
 ------------
 
@@ -57,6 +53,8 @@ First, run this command to install the translator before using it:
 
     $ composer require symfony/translation
 
+.. _translation-configuration:
+
 Configuration
 -------------
 
@@ -83,9 +81,9 @@ that will be used if Symfony can't find some translation:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config default-locale="en">
                 <framework:translator>
@@ -119,7 +117,7 @@ of text (called a *message*), use the
 for example, that you're translating a simple message from inside a controller::
 
     // ...
-    use Symfony\Component\Translation\TranslatorInterface;
+    use Symfony\Contracts\Translation\TranslatorInterface;
 
     public function index(TranslatorInterface $translator)
     {
@@ -163,7 +161,7 @@ different formats, XLIFF being the recommended format:
 
         // translations/messages.fr.php
         return [
-            'Symfony is great' => 'J\'aime Symfony',
+            'Symfony is great' => "J'aime Symfony",
         ];
 
 For information on where these files should be located, see
@@ -171,12 +169,13 @@ For information on where these files should be located, see
 
 Now, if the language of the user's locale is French (e.g. ``fr_FR`` or ``fr_BE``),
 the message will be translated into ``J'aime Symfony``. You can also translate
-the message inside your :ref:`templates <translation-tags>`.
+the message inside your :ref:`templates <translation-in-templates>`.
 
 The Translation Process
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-To actually translate the message, Symfony uses the following process:
+To actually translate the message, Symfony uses the following process when
+using the ``trans()`` method:
 
 * The ``locale`` of the current user, which is stored on the request is determined;
 
@@ -184,38 +183,27 @@ To actually translate the message, Symfony uses the following process:
   resources defined for the ``locale`` (e.g. ``fr_FR``). Messages from the
   :ref:`fallback locale <translation-fallback>` are also loaded and
   added to the catalog if they don't already exist. The end result is a large
-  "dictionary" of translations.
+  "dictionary" of translations. This catalog is cached in production to
+  minimize performance impact.
 
 * If the message is located in the catalog, the translation is returned. If
   not, the translator returns the original message.
 
-When using the ``trans()`` method, Symfony looks for the exact string inside
-the appropriate message catalog and returns it (if it exists).
+.. _message-placeholders:
+.. _pluralization:
 
-Message Placeholders
---------------------
+Message Format
+--------------
 
 Sometimes, a message containing a variable needs to be translated::
 
-    use Symfony\Component\Translation\TranslatorInterface;
-
-    public function index(TranslatorInterface $translator, $name)
-    {
-        $translated = $translator->trans('Hello '.$name);
-
-        // ...
-    }
+    // ...
+    $translated = $translator->trans('Hello '.$name);
 
-However, creating a translation for this string is impossible since the translator
-will try to look up the exact message, including the variable portions
+However, creating a translation for this string is impossible since the
+translator will try to look up the message including the variable portions
 (e.g. *"Hello Ryan"* or *"Hello Fabien"*).
 
-For details on how to handle this situation, see :ref:`component-translation-placeholders`
-in the components documentation. For how to do this in templates, see :ref:`translation-tags`.
-
-Pluralization
--------------
-
 Another complication is when you have translations that may or may not be
 plural, based on some variable:
 
@@ -224,122 +212,30 @@ plural, based on some variable:
     There is one apple.
     There are 5 apples.
 
-To handle this, use the :method:`Symfony\\Component\\Translation\\Translator::transChoice`
-method or the ``transchoice`` tag/filter in your :ref:`template <translation-tags>`.
+To manage these situations, Symfony follows the `ICU MessageFormat`_ syntax by
+using PHP's :phpclass:`MessageFormatter` class. Read more about this in
+:doc:`/translation/message_format`.
 
-For much more information, see :ref:`component-translation-pluralization`
-in the Translation component documentation.
+.. versionadded:: 4.2
+
+   Support for ICU MessageFormat was introduced in Symfony 4.2. Prior to this,
+   pluralization was managed by the
+   :method:`Symfony\\Component\\Translation\\Translator::transChoice` method.
+
+.. _translation-in-templates:
 
 Translations in Templates
 -------------------------
 
 Most of the time, translation occurs in templates. Symfony provides native
-support for both Twig and PHP templates.
-
-.. _translation-tags:
-
-Twig Templates
-~~~~~~~~~~~~~~
-
-Symfony provides specialized Twig tags (``trans`` and ``transchoice``) to
-help with message translation of *static blocks of text*:
-
-.. code-block:: twig
-
-    {% trans %}Hello %name%{% endtrans %}
-
-    {% transchoice count %}
-        {0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples
-    {% endtranschoice %}
-
-The ``transchoice`` tag automatically gets the ``%count%`` variable from
-the current context and passes it to the translator. This mechanism only
-works when you use a placeholder following the ``%var%`` pattern.
-
-.. caution::
-
-    The ``%var%`` notation of placeholders is required when translating in
-    Twig templates using the tag.
-
-.. tip::
-
-    If you need to use the percent character (``%``) in a string, escape it by
-    doubling it: ``{% trans %}Percent: %percent%%%{% endtrans %}``
-
-You can also specify the message domain and pass some additional variables:
-
-.. code-block:: twig
-
-    {% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
-
-    {% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
-
-    {% transchoice count with {'%name%': 'Fabien'} from 'app' %}
-        {0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
-    {% endtranschoice %}
-
-.. _translation-filters:
-
-The ``trans`` and ``transchoice`` filters can be used to translate *variable
-texts* and complex expressions:
+support for both Twig and PHP templates:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
-    {{ message|trans }}
+    <h1>{% trans %}Symfony is great!{% endtrans %}</h1>
 
-    {{ message|transchoice(5) }}
-
-    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
-
-    {{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
-
-.. tip::
-
-    Using the translation tags or filters have the same effect, but with
-    one subtle difference: automatic output escaping is only applied to
-    translations using a filter. In other words, if you need to be sure
-    that your translated message is *not* output escaped, you must apply
-    the ``raw`` filter after the translation filter:
-
-    .. code-block:: twig
-
-            {# text translated between tags is never escaped #}
-            {% trans %}
-                <h3>foo</h3>
-            {% endtrans %}
-
-            {% set message = '<h3>foo</h3>' %}
-
-            {# strings and variables translated via a filter are escaped by default #}
-            {{ message|trans|raw }}
-            {{ '<h3>bar</h3>'|trans|raw }}
-
-.. tip::
-
-    You can set the translation domain for an entire Twig template with a single tag:
-
-    .. code-block:: twig
-
-           {% trans_default_domain 'app' %}
-
-    Note that this only influences the current template, not any "included"
-    template (in order to avoid side effects).
-
-PHP Templates
-~~~~~~~~~~~~~
-
-The translator service is accessible in PHP templates through the
-``translator`` helper:
-
-.. code-block:: html+php
-
-    <?= $view['translator']->trans('Symfony is great') ?>
-
-    <?= $view['translator']->transChoice(
-        '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
-        10,
-        ['%count%' => 10]
-    ) ?>
+Read :doc:`/translation/templates` for more information about the Twig tags and
+filters for translation.
 
 Extracting Translation Contents and Updating Catalogs Automatically
 -------------------------------------------------------------------
@@ -351,23 +247,27 @@ with these tasks:
 
 .. code-block:: terminal
 
-    # updates the French translation file with the missing strings found in app/Resources/ templates
+    # updates the French translation file with the missing strings for that locale
     $ php bin/console translation:update --dump-messages --force fr
 
-    # updates the English translation file with the missing strings found in AppBundle
-    $ php bin/console translation:update --dump-messages --force en AppBundle
+The ``translation:update`` command looks for missing translations in:
+
+* Templates stored in the ``templates/`` directory (or any other directory
+  defined in the :ref:`twig.default_path <config-twig-default-path>` and
+  :ref:`twig.paths <config-twig-paths>` config options);
+* Any PHP file/class that injects or :doc:`autowires </service_container/autowiring>`
+  the ``translator`` service and makes calls to the ``trans()`` function.
+
+.. versionadded:: 4.3
+
+    The extraction of missing translation strings from PHP files was introduced
+    in Symfony 4.3.
 
 .. note::
 
     If you want to see the missing translation strings without actually updating
     the translation files, remove the ``--force`` option from the command above.
 
-.. tip::
-
-    If you need to extract translation strings from other sources, such as
-    controllers, forms and flash messages, consider using the more advanced
-    third-party `TranslationBundle`_.
-
 .. _translation-resource-locations:
 
 Translation Resource/File Names and Locations
@@ -375,11 +275,15 @@ Translation Resource/File Names and Locations
 
 Symfony looks for message files (i.e. translations) in the following default locations:
 
-* the ``translations/`` directory (at the root of the project);
+#. the ``translations/`` directory (at the root of the project);
+#. the ``src/Resources/<bundle name>/translations/`` directory;
+#. the ``Resources/translations/`` directory inside of any bundle.
 
-* the ``src/Resources/<bundle name>/translations/`` directory;
+.. deprecated:: 4.2
 
-* the ``Resources/translations/`` directory inside of any bundle.
+    Using the ``src/Resources/<bundle name>/translations/`` directory to store
+    translations was deprecated in Symfony 4.2. Use instead the directory
+    defined in the ``default_path`` option (which is ``translations/`` by default).
 
 The locations are listed here with the highest priority first. That is, you can
 override the translation messages of a bundle in any of the top two directories.
@@ -434,9 +338,9 @@ For more options, see :ref:`component-translator-message-catalogs`.
                 xmlns:framework="http://symfony.com/schema/dic/symfony"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
                     http://symfony.com/schema/dic/symfony
-                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
             >
 
                 <framework:config>
@@ -464,15 +368,18 @@ For more options, see :ref:`component-translator-message-catalogs`.
     :class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface` interface.
     See the :ref:`dic-tags-translation-loader` tag for more information.
 
-.. caution::
+.. versionadded:: 4.3
 
-    Each time you create a *new* translation resource (or install a bundle
-    that includes a translation resource), be sure to clear your cache so
-    that Symfony can discover the new translation resources:
+    Starting from Symfony 4.3, when you create a new translation file (or
+    install a bundle that includes translation files), you don't have to clear
+    the cache with the command ``php bin/console cache:clear`` as you had to do
+    in previous Symfony versions.
 
-    .. code-block:: terminal
+Handling the User's Locale
+--------------------------
 
-        $ php bin/console cache:clear
+Translating happens based on the user's locale. Read :doc:`/translation/locale`
+to learn more about how to handle it.
 
 .. _translation-fallback:
 
@@ -498,12 +405,6 @@ checks translation resources for several locales:
     add the missing translation to the log file. For details,
     see :ref:`reference-framework-translator-logging`.
 
-Handling the User's Locale
---------------------------
-
-Translating happens based on the user's locale. Read :doc:`/translation/locale`
-to learn more about how to handle it.
-
 Translating Database Content
 ----------------------------
 
@@ -525,10 +426,8 @@ Summary
 With the Symfony Translation component, creating an internationalized application
 no longer needs to be a painful process and boils down to these steps:
 
-* Abstract messages in your application by wrapping each in either the
-  :method:`Symfony\\Component\\Translation\\Translator::trans` or
-  :method:`Symfony\\Component\\Translation\\Translator::transChoice` methods
-  (learn about this in :doc:`/components/translation/usage`);
+* Abstract messages in your application by wrapping each in the
+  :method:`Symfony\\Component\\Translation\\Translator::trans` method;
 
 * Translate each message into multiple locales by creating translation message
   files. Symfony discovers and processes each file because its name follows
@@ -543,13 +442,15 @@ Learn more
 .. toctree::
     :maxdepth: 1
 
+    translation/message_format
+    translation/templates
     translation/locale
     translation/debug
     translation/lint
 
 .. _`i18n`: https://en.wikipedia.org/wiki/Internationalization_and_localization
+.. _`ICU MessageFormat`: http://userguide.icu-project.org/formatparse/messages
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`Translatable Extension`: http://atlantic18.github.io/DoctrineExtensions/doc/translatable.html
 .. _`Translatable Behavior`: https://github.com/KnpLabs/DoctrineBehaviors
-.. _`TranslationBundle`: https://github.com/php-translation/symfony-bundle
diff --git a/translation/debug.rst b/translation/debug.rst
index cec010c9901..8b2bdcd9a14 100644
--- a/translation/debug.rst
+++ b/translation/debug.rst
@@ -12,15 +12,11 @@ command helps you to find these missing or unused translation messages templates
 
 .. code-block:: twig
 
-    {# messages can be found when using the trans/transchoice filters and tags #}
+    {# messages can be found when using the trans filter and tag #}
     {% trans %}Symfony is great{% endtrans %}
 
     {{ 'Symfony is great'|trans }}
 
-    {{ 'Symfony is great'|transchoice(1) }}
-
-    {% transchoice 1 %}Symfony is great{% endtranschoice %}
-
 .. caution::
 
     The extractors can't find messages translated outside templates, like form
@@ -42,7 +38,7 @@ you've already setup some translations for the ``fr`` locale:
 
     .. code-block:: xml
 
-        <!-- translations/messages.fr.xliff -->
+        <!-- translations/messages.fr.xlf -->
         <?xml version="1.0"?>
         <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
             <file source-language="en" datatype="plaintext" original="file.ext">
@@ -73,7 +69,7 @@ and for the ``en`` locale:
 
     .. code-block:: xml
 
-        <!-- translations/messages.en.xliff -->
+        <!-- translations/messages.en.xlf -->
         <?xml version="1.0"?>
         <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
             <file source-language="en" datatype="plaintext" original="file.ext">
@@ -169,7 +165,7 @@ You can see that the translations of the message are identical in the ``fr``
 and ``en`` locales which means this message was probably copied from French
 to English and maybe you forgot to translate it.
 
-By default all domains are inspected, but it is possible to specify a single
+By default, all domains are inspected, but it is possible to specify a single
 domain:
 
 .. code-block:: terminal
diff --git a/translation/lint.rst b/translation/lint.rst
index ff0c0c1dff5..29cec3c5008 100644
--- a/translation/lint.rst
+++ b/translation/lint.rst
@@ -22,6 +22,10 @@ translation file using the ``lint:yaml`` and ``lint:xliff`` commands:
     $ php bin/console lint:yaml translations
     $ php bin/console lint:xliff translations
 
+    # lint multiple files or directories
+    $ php bin/console lint:yaml translations path/to/trans
+    $ php bin/console lint:xliff translations/messages.en.xlf translations/messages.es.xlf
+
 The linter results can be exported to JSON using the ``--format`` option:
 
 .. code-block:: terminal
diff --git a/translation/locale.rst b/translation/locale.rst
index 2632ebcf676..2dfd7c80b7c 100644
--- a/translation/locale.rst
+++ b/translation/locale.rst
@@ -18,7 +18,7 @@ To set the user's locale, you may want to create a custom event listener so
 that it's set before any other parts of the system (i.e. the translator) need
 it::
 
-        public function onKernelRequest(GetResponseEvent $event)
+        public function onKernelRequest(RequestEvent $event)
         {
             $request = $event->getRequest();
 
@@ -59,8 +59,8 @@ this violates a fundamental rule of the Web: that a particular URL returns
 the same resource regardless of the user. To further muddy the problem, which
 version of the content would be indexed by search engines?
 
-A better policy is to include the locale in the URL. This is fully-supported
-by the routing system using the special ``_locale`` parameter:
+A better policy is to include the locale in the URL using the
+:ref:`special _locale parameter <routing-locale-parameter>`:
 
 .. configuration-block::
 
@@ -80,10 +80,10 @@ by the routing system using the special ``_locale`` parameter:
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
-                http://symfony.com/schema/routing/routing-1.0.xsd">
+                https://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="contact" path="/{_locale}/contact">
-                <default key="_controller">App\Controller\ContactContorller::index</default>
+                controller="App\Controller\ContactController::index">
                 <requirement key="_locale">en|fr|de</requirement>
             </route>
         </routes>
@@ -91,22 +91,17 @@ by the routing system using the special ``_locale`` parameter:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
         use App\Controller\ContactController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        $routes = new RouteCollection();
-        $routes->add('contact', new Route(
-            '/{_locale}/contact',
-            [
-                '_controller' => [ContactController::class, 'index'],
-            ],
-            [
-                '_locale' => 'en|fr|de',
-            ]
-        ));
-
-        return $routes;
+        return function (RoutingConfigurator $routes) {
+            $routes->add('contact', '/{_locale}/contact')
+                ->controller([ContactController::class, 'index'])
+                ->requirements([
+                    '_locale' => 'en|fr|de',
+                ])
+            ;
+        };
 
 When using the special ``_locale`` parameter in a route, the matched locale
 is *automatically set on the Request* and can be retrieved via the
@@ -119,8 +114,8 @@ application.
 
 .. tip::
 
-    Read :doc:`/routing/service_container_parameters` to learn how to avoid
-    hardcoding the ``_locale`` requirement in all your routes.
+    Define the locale requirement as a :ref:`container parameter <configuration-parameters>`
+    to avoid hardcoding its value in all your routes.
 
 .. index::
     single: Translations; Fallback and default locale
@@ -150,11 +145,11 @@ the framework:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
+                https://symfony.com/schema/dic/services/services-1.0.xsd
                 http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
-            <framework:config default-locale="en" />
+            <framework:config default-locale="en"/>
         </container>
 
     .. code-block:: php
diff --git a/translation/message_format.rst b/translation/message_format.rst
new file mode 100644
index 00000000000..e0b6bea9dc8
--- /dev/null
+++ b/translation/message_format.rst
@@ -0,0 +1,443 @@
+.. index::
+    single: Translation; Message Format
+
+How to Translate Messages using the ICU MessageFormat
+=====================================================
+
+.. versionadded:: 4.2
+
+   Support for ICU MessageFormat was introduced in Symfony 4.2.
+
+Messages (i.e. strings) in applications are almost never completely static.
+They contain variables or other complex logic like pluralization. In order to
+handle this, the Translator component supports the `ICU MessageFormat`_ syntax.
+
+.. tip::
+
+    You can test out examples of the ICU MessageFormatter in this `online editor`_.
+
+Using the ICU Message Format
+----------------------------
+
+In order to use the ICU Message Format, the :ref:`message domain
+<using-message-domains>` has to be suffixed with ``+intl-icu``:
+
+======================  ===============================
+Normal file name        ICU Message Format filename
+======================  ===============================
+``messages.en.yaml``    ``messages+intl-icu.en.yaml``
+``messages.fr_FR.xlf``  ``messages+intl-icu.fr_FR.xlf``
+``admin.en.yaml``       ``admin+intl-icu.en.yaml``
+======================  ===============================
+
+All messages in this file will now be processed by the
+:phpclass:`MessageFormatter` during translation.
+
+.. _component-translation-placeholders:
+
+Message Placeholders
+--------------------
+
+The basic usage of the MessageFormat allows you to use placeholders (called
+*arguments* in ICU MessageFormat) in your messages:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # translations/messages+intl-icu.en.yaml
+        say_hello: 'Hello {name}!'
+
+    .. code-block:: xml
+
+        <!-- translations/messages+intl-icu.en.xlf -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="say_hello">
+                        <source>say_hello</source>
+                        <target>Hello {name}!</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // translations/messages+intl-icu.en.php
+        return [
+            'say_hello' => "Hello {name}!",
+        ];
+
+Everything within the curly braces (``{...}``) is processed by the formatter
+and replaced by its placeholder::
+
+    // prints "Hello Fabien!"
+    echo $translator->trans('say_hello', ['name' => 'Fabien']);
+
+    // prints "Hello Symfony!"
+    echo $translator->trans('say_hello', ['name' => 'Symfony']);
+
+Selecting Different Messages Based on a Condition
+-------------------------------------------------
+
+The curly brace syntax allows to "modify" the output of the variable. One of
+these functions is the ``select`` function. It acts like PHP's `switch statement`_
+and allows to use different strings based on the value of the variable. A
+typical usage of this is gender:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # translations/messages+intl-icu.en.yaml
+        invitation_title: >
+            {organizer_gender, select,
+                female {{organizer_name} has invited you for her party!}
+                male   {{organizer_name} has invited you for his party!}
+                other  {{organizer_name} have invited you for their party!}
+            }
+
+    .. code-block:: xml
+
+        <!-- translations/messages+intl-icu.en.xlf -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="invitation_title">
+                        <source>invitation_title</source>
+                        <target>{organizer_gender, select, female {{organizer_name} has invited you for her party!} male {{organizer_name} has invited you for his party!} other {{organizer_name} have invited you for their party!}}</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // translations/messages+intl-icu.en.php
+        return [
+            'invitation_title' => '{organizer_gender, select,
+                female {{organizer_name} has invited you for her party!}
+                male   {{organizer_name} has invited you for his party!}
+                other  {{organizer_name} have invited you for their party!}
+            }',
+        ];
+
+This might look very complex. The basic syntax for all functions is
+``{variable_name, function_name, function_statement}`` (where, as you see
+later, ``function_statement`` is optional for some functions). In this case,
+the function name is ``select`` and its statement contains the "cases" of this
+select. This function is applied over the ``organizer_gender`` variable::
+
+    // prints "Ryan has invited you for his party!"
+    echo $translator->trans('invitation_title', [
+        'organizer_name' => 'Ryan',
+        'organizer_gender' => 'male',
+    ]);
+
+    // prints "John & Jane have invited you for their party!"
+    echo $translator->trans('invitation_title', [
+        'organizer_name' => 'John & Jane',
+        'organizer_gender' => 'not_applicable',
+    ]);
+
+The ``{...}`` syntax alternates between "literal" and "code" mode. This allows
+you to use literal text in the select statements:
+
+#. The first ``{organizer_gender, select, ...}`` block starts the "code" mode,
+   which means ``organizer_gender`` is processed as a variable.
+#. The inner ``{... has invited you for her party!}`` block brings you back in
+   "literal" mode, meaning the text is not processed.
+#. Inside this block, ``{organizer_name}`` starts "code" mode again, allowing
+   ``organizer_name`` to be processed as variable.
+
+.. tip::
+
+    While it might seem more logical to only put ``her``, ``his`` or ``their``
+    in the switch statement, it is better to use "complex arguments" at the
+    outermost structure of the message. The strings are in this way better
+    readable for translators and, as you can see in the ``other`` case, other
+    parts of the sentence might be influenced by the variables.
+
+Pluralization
+-------------
+
+Another interesting function is ``plural``. It allows you to
+handle pluralization in your messages (e.g. ``There are 3 apples`` vs
+``There is one apple``). The function looks very similar to the ``select`` function:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # translations/messages+intl-icu.en.yaml
+        num_of_apples: >
+            {apples, plural,
+                =0    {There are no apples}
+                one   {There is one apple...}
+                other {There are # apples!}
+            }
+
+    .. code-block:: xml
+
+        <!-- translations/messages+intl-icu.en.xlf -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="num_of_apples">
+                        <source>num_of_apples</source>
+                        <target>{apples, plural, =0 {There are no apples} one {There is one apple...} other {There are # apples!}}</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // translations/messages+intl-icu.en.php
+        return [
+            'num_of_apples' => '{apples, plural,
+                =0    {There are no apples}
+                one   {There is one apple...}
+                other {There are # apples!}
+            }',
+        ];
+
+Pluralization rules are actually quite complex and differ for each language.
+For instance, Russian uses different plural forms for numbers ending with 1;
+numbers ending with 2, 3 or 4; numbers ending with 5, 6, 7, 8 or 9; and even
+some exceptions of this!
+
+In order to properly translate this, the possible cases in the ``plural``
+function are also different for each language. For instance, Russian has
+``one``, ``few``, ``many`` and ``other``, while English has only ``one`` and
+``other``. The full list of possible cases can be found in Unicode's
+`Language Plural Rules`_ document. By prefixing with ``=``, you can match exact
+values (like ``0`` in the above example).
+
+Usage of this string is the same as with variables and select::
+
+    // prints "There is one apple..."
+    echo $translator->trans('num_of_apples', ['apples' => 1]);
+
+    // prints "There are 23 apples!"
+    echo $translator->trans('num_of_apples', ['apples' => 23]);
+
+.. note::
+
+    You can also set an ``offset`` variable to determine whether the
+    pluralization should be offset (e.g. in sentences like ``You and # other people``
+    / ``You and # other person``).
+
+.. tip::
+
+    When combining the ``select`` and ``plural`` functions, try to still have
+    ``select`` as outermost function:
+
+    .. code-block:: text
+
+		{gender_of_host, select,
+            female {
+                {num_guests, plural, offset:1
+                =0    {{host} does not give a party.}
+                =1    {{host} invites {guest} to her party.}
+                =2    {{host} invites {guest} and one other person to her party.}
+                other {{host} invites {guest} and # other people to her party.}}
+            }
+            male {
+                {num_guests, plural, offset:1
+                =0    {{host} does not give a party.}
+                =1    {{host} invites {guest} to his party.}
+                =2    {{host} invites {guest} and one other person to his party.}
+                other {{host} invites {guest} and # other people to his party.}}
+            }
+            other {
+                {num_guests, plural, offset:1
+                =0    {{host} does not give a party.}
+                =1    {{host} invites {guest} to their party.}
+                =2    {{host} invites {guest} and one other person to their party.}
+                other {{host} invites {guest} and # other people to their party.}}
+            }
+        }
+
+Additional Placeholder Functions
+--------------------------------
+
+Besides these, the ICU MessageFormat comes with a couple other interesting functions.
+
+Ordinal
+~~~~~~~
+
+Similar to ``plural``, ``selectordinal`` allows you to use numbers as ordinal scale:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # translations/messages+intl-icu.en.yaml
+        finish_place: >
+            You finished {place, selectordinal,
+                one   {#st}
+                two   {#nd}
+                few   {#rd}
+                other {#th}
+            }!
+
+        # when only formatting the number as ordinal (like above), you can also
+        # use the `ordinal` function:
+        finish_place: You finished {place, ordinal}!
+
+    .. code-block:: xml
+
+        <!-- translations/messages+intl-icu.en.xlf -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="finish_place">
+                        <source>finish_place</source>
+                        <target>You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!</target>
+                    </trans-unit>
+
+                    <!-- when only formatting the number as ordinal (like
+                         above), you can also use the `ordinal` function: -->
+                    <trans-unit id="finish_place">
+                        <source>finish_place</source>
+                        <target>You finished {place, ordinal}!</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // translations/messages+intl-icu.en.php
+        return [
+            'finish_place' => 'You finished {place, selectordinal,
+                one {#st}
+                two {#nd}
+                few {#rd}
+                other {#th}
+            }!',
+
+            // when only formatting the number as ordinal (like above), you can
+            // also use the `ordinal` function:
+            'finish_place' => 'You finished {place, ordinal}!',
+        ];
+
+.. code-block:: php
+
+    // prints "You finished 1st!"
+    echo $translator->trans('finish_place', ['place' => 1]);
+
+    // prints "You finished 9th!"
+    echo $translator->trans('finish_place', ['place' => 9]);
+
+    // prints "You finished 23rd!"
+    echo $translator->trans('finish_place', ['place' => 23]);
+
+The possible cases for this are also shown in Unicode's `Language Plural Rules`_ document.
+
+Date and Time
+~~~~~~~~~~~~~
+
+The date and time function allows you to format dates in the target locale
+using the :phpclass:`IntlDateFormatter`:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # translations/messages+intl-icu.en.yaml
+        published_at: 'Published at {publication_date, date} - {publication_date, time, short}'
+
+    .. code-block:: xml
+
+        <!-- translations/messages+intl-icu.en.xlf -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="published_at">
+                        <source>published_at</source>
+                        <target>Published at {publication_date, date} - {publication_date, time, short}</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // translations/messages+intl-icu.en.php
+        return [
+            'published_at' => 'Published at {publication_date, date} - {publication_date, time, short}',
+        ];
+
+The "function statement" for the ``time`` and ``date`` functions can be one of
+``short``, ``medium``, ``long`` or ``full``, which correspond to the
+`constants defined by the IntlDateFormatter class`_::
+
+    // prints "Published at Jan 25, 2019 - 11:30 AM"
+    echo $translator->trans('published_at', ['publication_date' => new \DateTime('2019-01-25 11:30:00')]);
+
+Numbers
+~~~~~~~
+
+The ``number`` formatter allows you to format numbers using Intl's :phpclass:`NumberFormatter`:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # translations/messages+intl-icu.en.yaml
+        progress: '{progress, number, percent} of the work is done'
+        value_of_object: 'This artifact is worth {value, number, currency}'
+
+    .. code-block:: xml
+
+        <!-- translations/messages+intl-icu.en.xlf -->
+        <?xml version="1.0"?>
+        <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+            <file source-language="en" datatype="plaintext" original="file.ext">
+                <body>
+                    <trans-unit id="progress">
+                        <source>progress</source>
+                        <target>{progress, number, percent} of the work is done</target>
+                    </trans-unit>
+
+                    <trans-unit id="value_of_object">
+                        <source>value_of_object</source>
+                        <target>This artifact is worth {value, number, currency}</target>
+                    </trans-unit>
+                </body>
+            </file>
+        </xliff>
+
+    .. code-block:: php
+
+        // translations/messages+intl-icu.en.php
+        return [
+            'progress' => '{progress, number, percent} of the work is done',
+            'value_of_object' => 'This artifact is worth {value, number, currency}',
+        ];
+
+.. code-block:: php
+
+    // prints "82% of the work is done"
+    echo $translator->trans('progress', ['progress' => 0.82]);
+    // prints "100% of the work is done"
+    echo $translator->trans('progress', ['progress' => 1]);
+
+    // prints "This artifact is worth $9,988,776.65"
+    // if we would translate this to i.e. French, the value would be shown as
+    // "9 988 776,65 €"
+    echo $translator->trans('value_of_object', ['value' => 9988776.65]);
+
+.. _`online editor`: http://format-message.github.io/icu-message-format-for-translators/
+.. _`ICU MessageFormat`: http://userguide.icu-project.org/formatparse/messages
+.. _`switch statement`: https://php.net/control-structures.switch
+.. _`Language Plural Rules`: http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+.. _`constants defined by the IntlDateFormatter class`: https://php.net/manual/en/class.intldateformatter.php
diff --git a/translation/templates.rst b/translation/templates.rst
new file mode 100644
index 00000000000..903f1934d92
--- /dev/null
+++ b/translation/templates.rst
@@ -0,0 +1,123 @@
+Using Translation in Templates
+==============================
+
+Twig Templates
+--------------
+
+.. _translation-tags:
+
+Using Twig Tags
+~~~~~~~~~~~~~~~
+
+Symfony provides specialized Twig tags (``trans`` and ``transchoice``) to
+help with message translation of *static blocks of text*:
+
+.. code-block:: twig
+
+    {% trans %}Hello %name%{% endtrans %}
+
+    {% transchoice count %}
+        {0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples
+    {% endtranschoice %}
+
+The ``transchoice`` tag automatically gets the ``%count%`` variable from
+the current context and passes it to the translator. This mechanism only
+works when you use a placeholder following the ``%var%`` pattern.
+
+.. deprecated:: 4.2
+
+    The ``transchoice`` tag is deprecated since Symfony 4.2 and will be
+    removed in 5.0. Use the :doc:`ICU MessageFormat </translation/message_format>` with
+    the ``trans`` tag instead.
+
+.. caution::
+
+    The ``%var%`` notation of placeholders is required when translating in
+    Twig templates using the tag.
+
+.. tip::
+
+    If you need to use the percent character (``%``) in a string, escape it by
+    doubling it: ``{% trans %}Percent: %percent%%%{% endtrans %}``
+
+You can also specify the message domain and pass some additional variables:
+
+.. code-block:: twig
+
+    {% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
+
+    {% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
+
+    {% transchoice count with {'%name%': 'Fabien'} from 'app' %}
+        {0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
+    {% endtranschoice %}
+
+.. _translation-filters:
+
+Using Twig Filters
+~~~~~~~~~~~~~~~~~~
+
+The ``trans`` and ``transchoice`` filters can be used to translate *variable
+texts* and complex expressions:
+
+.. code-block:: twig
+
+    {{ message|trans }}
+
+    {{ message|transchoice(5) }}
+
+    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
+
+    {{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
+
+.. deprecated:: 4.2
+
+    The ``transchoice`` filter is deprecated since Symfony 4.2 and will be
+    removed in 5.0. Use the :doc:`ICU MessageFormat </translation/message_format>` with
+    the ``trans`` filter instead.
+
+.. tip::
+
+    Using the translation tags or filters have the same effect, but with
+    one subtle difference: automatic output escaping is only applied to
+    translations using a filter. In other words, if you need to be sure
+    that your translated message is *not* output escaped, you must apply
+    the ``raw`` filter after the translation filter:
+
+    .. code-block:: html+twig
+
+        {# text translated between tags is never escaped #}
+        {% trans %}
+            <h3>foo</h3>
+        {% endtrans %}
+
+        {% set message = '<h3>foo</h3>' %}
+
+        {# strings and variables translated via a filter are escaped by default #}
+        {{ message|trans|raw }}
+        {{ '<h3>bar</h3>'|trans|raw }}
+
+.. tip::
+
+    You can set the translation domain for an entire Twig template with a single tag:
+
+    .. code-block:: twig
+
+       {% trans_default_domain 'app' %}
+
+    Note that this only influences the current template, not any "included"
+    template (in order to avoid side effects).
+
+PHP Templates
+-------------
+
+The translator service is accessible in PHP templates through the
+``translator`` helper::
+
+    <?= $view['translator']->trans('Symfony is great') ?>
+
+    <?= $view['translator']->transChoice(
+        '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
+        10,
+        ['%count%' => 10]
+    ) ?>
diff --git a/validation.rst b/validation.rst
index f22788f680d..6b6d173c4e5 100644
--- a/validation.rst
+++ b/validation.rst
@@ -14,7 +14,7 @@ transparent. This component is based on the `JSR303 Bean Validation specificatio
 Installation
 ------------
 
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
 install the validator before using it:
 
 .. code-block:: terminal
@@ -82,11 +82,11 @@ following:
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="name">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -96,8 +96,8 @@ following:
         // src/Entity/Author.php
 
         // ...
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints\NotBlank;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -129,9 +129,9 @@ constraints. If validation fails, a non-empty list of errors
 returned. Take this simple example from inside a controller::
 
     // ...
+    use App\Entity\Author;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Validator\Validator\ValidatorInterface;
-    use App\Entity\Author;
 
     // ...
     public function author(ValidatorInterface $validator)
@@ -161,7 +161,7 @@ message:
 
 .. code-block:: text
 
-    App\Entity\Author.name:
+    Object(App\Entity\Author).name:
         This value should not be blank
 
 If you insert a value into the ``name`` property, the happy success message
@@ -172,7 +172,7 @@ will appear.
     Most of the time, you won't interact directly with the ``validator``
     service or need to worry about printing out the errors. Most of the time,
     you'll use validation indirectly when handling submitted form data. For
-    more information, see the :ref:`forms-form-validation`.
+    more information, see :ref:`how to validate Symfony forms <validating-forms>`.
 
 You could also pass the collection of errors into a template::
 
@@ -224,11 +224,11 @@ file:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:validation enabled="true" />
+                <framework:validation enabled="true"/>
             </framework:config>
         </container>
 
@@ -260,11 +260,11 @@ previous configuration by the following:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:validation enable-annotations="true" />
+                <framework:validation enable-annotations="true"/>
             </framework:config>
         </container>
 
@@ -358,7 +358,7 @@ literature genre mostly associated with the author, which can be set to either
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="genre">
@@ -380,8 +380,8 @@ literature genre mostly associated with the author, which can be set to either
         // src/Entity/Author.php
 
         // ...
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -442,7 +442,7 @@ options can be specified in this way.
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="genre">
@@ -461,8 +461,8 @@ options can be specified in this way.
         // src/Entity/Author.php
 
         // ...
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -498,7 +498,7 @@ of the form fields::
             ->add('myField', TextType::class, [
                 'required' => true,
                 'constraints' => [new Length(['min' => 3])]
-            ))
+            ])
         ;
     }
 
@@ -564,11 +564,11 @@ class to have at least 3 characters.
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="firstName">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                     <constraint name="Length">
                         <option name="min">3</option>
                     </constraint>
@@ -581,8 +581,8 @@ class to have at least 3 characters.
         // src/Entity/Author.php
 
         // ...
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
@@ -650,7 +650,7 @@ this method must return ``true``:
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <getter property="passwordSafe">
@@ -666,8 +666,8 @@ this method must return ``true``:
         // src/Entity/Author.php
 
         // ...
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst
index fbb4af48295..0c0bc2960cf 100644
--- a/validation/custom_constraint.rst
+++ b/validation/custom_constraint.rst
@@ -60,6 +60,7 @@ The validator class is also simple, and only has one required method ``validate(
     use Symfony\Component\Validator\Constraint;
     use Symfony\Component\Validator\ConstraintValidator;
     use Symfony\Component\Validator\Exception\UnexpectedTypeException;
+    use Symfony\Component\Validator\Exception\UnexpectedValueException;
 
     class ContainsAlphanumericValidator extends ConstraintValidator
     {
@@ -68,7 +69,7 @@ The validator class is also simple, and only has one required method ``validate(
             if (!$constraint instanceof ContainsAlphanumeric) {
                 throw new UnexpectedTypeException($constraint, ContainsAlphanumeric::class);
             }
-            
+
             // custom constraints should ignore null and empty values to allow
             // other constraints (NotBlank, NotNull, etc.) take care of that
             if (null === $value || '' === $value) {
@@ -76,7 +77,11 @@ The validator class is also simple, and only has one required method ``validate(
             }
 
             if (!is_string($value)) {
-                throw new UnexpectedTypeException($value, 'string');
+                // throw this exception if your validator cannot handle the passed type so that it can be marked as invalid
+                throw new UnexpectedValueException($value, 'string');
+
+                // separate multiple types using pipes
+                // throw new UnexpectedValueException($value, 'string|int');
             }
 
             if (!preg_match('/^[a-zA-Z0-9]+$/', $value, $matches)) {
@@ -97,15 +102,15 @@ The ``addViolation()`` method call finally adds the violation to the context.
 Using the new Validator
 -----------------------
 
-Using custom validators looks the same as using the ones provided by Symfony itself:
+You can use custom validators just as the ones provided by Symfony itself:
 
 .. configuration-block::
 
     .. code-block:: php-annotations
 
         // src/Entity/AcmeEntity.php
-        use Symfony\Component\Validator\Constraints as Assert;
         use App\Validator\Constraints as AcmeAssert;
+        use Symfony\Component\Validator\Constraints as Assert;
 
         class AcmeEntity
         {
@@ -135,12 +140,12 @@ Using custom validators looks the same as using the ones provided by Symfony its
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\AcmeEntity">
                 <property name="name">
-                    <constraint name="NotBlank" />
-                    <constraint name="App\Validator\Constraints\ContainsAlphanumeric" />
+                    <constraint name="NotBlank"/>
+                    <constraint name="App\Validator\Constraints\ContainsAlphanumeric"/>
                 </property>
             </class>
         </constraint-mapping>
@@ -148,9 +153,9 @@ Using custom validators looks the same as using the ones provided by Symfony its
     .. code-block:: php
 
         // src/Entity/AcmeEntity.php
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
-        use Symfony\Component\Validator\Constraints\NotBlank;
         use App\Validator\Constraints\ContainsAlphanumeric;
+        use Symfony\Component\Validator\Constraints\NotBlank;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class AcmeEntity
         {
@@ -178,15 +183,15 @@ with the necessary ``validator.constraint_validator``. This means you can
 Class Constraint Validator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Beside validating a class property, a constraint can have a class scope by
-providing a target in its ``Constraint`` class::
+Besides validating a single property, a constraint can have an entire class
+as its scope. You only need to add this to the ``Constraint`` class::
 
     public function getTargets()
     {
         return self::CLASS_CONSTRAINT;
     }
 
-With this, the validator ``validate()`` method gets an object as its first argument::
+With this, the validator's ``validate()`` method gets an object as its first argument::
 
     class ProtocolClassValidator extends ConstraintValidator
     {
@@ -206,7 +211,7 @@ With this, the validator ``validate()`` method gets an object as its first argum
     associated to. Use any :doc:`valid PropertyAccess syntax </components/property_access>`
     to define that property.
 
-Note that a class constraint validator is applied to the class itself, and
+A class constraint validator is applied to the class itself, and
 not to the property:
 
 .. configuration-block::
@@ -214,7 +219,7 @@ not to the property:
     .. code-block:: php-annotations
 
         /**
-         * @AcmeAssert\ContainsAlphanumeric
+         * @AcmeAssert\ProtocolClass
          */
         class AcmeEntity
         {
@@ -226,11 +231,11 @@ not to the property:
         # config/validator/validation.yaml
         App\Entity\AcmeEntity:
             constraints:
-                - App\Validator\Constraints\ContainsAlphanumeric: ~
+                - App\Validator\Constraints\ProtocolClass: ~
 
     .. code-block:: xml
 
         <!-- config/validator/validation.xml -->
         <class name="App\Entity\AcmeEntity">
-            <constraint name="App\Validator\Constraints\ContainsAlphanumeric" />
+            <constraint name="App\Validator\Constraints\ProtocolClass"/>
         </class>
diff --git a/validation/groups.rst b/validation/groups.rst
index 8195fd104fa..a16b041159e 100644
--- a/validation/groups.rst
+++ b/validation/groups.rst
@@ -64,7 +64,7 @@ user registers and when a user updates their contact information later:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="
                 http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd
             ">
 
             <class name="App\Entity\User">
@@ -103,8 +103,8 @@ user registers and when a user updates their contact information later:
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
@@ -132,7 +132,8 @@ With this configuration, there are three validation groups:
 
 ``Default``
     Contains the constraints in the current class and all referenced classes
-    that belong to no other group.
+    that belong to no other group. In this example, it only contains the
+    ``city`` field.
 
 ``User``
     Equivalent to all constraints of the ``User`` object in the ``Default``
@@ -140,7 +141,9 @@ With this configuration, there are three validation groups:
     and ``Default`` is explained in :doc:`/validation/sequence_provider`.
 
 ``registration``
-    Contains the constraints on the ``email`` and ``password`` fields only.
+    This is a custom validation group, so it only contains the constraints
+    explicitly associated to it. In this example, only the ``email`` and
+    ``password`` fields.
 
 Constraints in the ``Default`` group of a class are the constraints that have
 either no explicit group configured or that are configured to a group equal to
@@ -179,6 +182,6 @@ as the third argument to the ``validate()`` method::
 If no groups are specified, all constraints that belong to the group ``Default``
 will be applied.
 
-In a full stack Symfony project, you'll usually work with validation indirectly through the form
-library. For information on how to use validation groups inside forms, see
-:doc:`/form/validation_groups`.
+In a full stack Symfony project, you'll usually work with validation indirectly
+through the form library. For information on how to use validation groups inside
+forms, see :doc:`/form/validation_groups`.
diff --git a/validation/raw_values.rst b/validation/raw_values.rst
index 9602b82a0c0..34f8b7ac09e 100644
--- a/validation/raw_values.rst
+++ b/validation/raw_values.rst
@@ -6,8 +6,7 @@ How to Validate Raw Values (Scalar Values and Arrays)
 
 Usually you will be validating entire objects. But sometimes, you just want
 to validate a simple value - like to verify that a string is a valid email
-address. To achieve this, you can instantiate the validator directly. From inside a
-controller, it looks like this::
+address. From inside a controller, it looks like this::
 
     // ...
     use Symfony\Component\Validator\Constraints as Assert;
@@ -46,8 +45,8 @@ section.
 
 Validation of arrays is possible using the ``Collection`` constraint::
 
-    use Symfony\Component\Validator\Validation;
     use Symfony\Component\Validator\Constraints as Assert;
+    use Symfony\Component\Validator\Validation;
 
     $validator = Validation::createValidator();
 
diff --git a/validation/sequence_provider.rst b/validation/sequence_provider.rst
index 84b9751c2ba..98a9389212f 100644
--- a/validation/sequence_provider.rst
+++ b/validation/sequence_provider.rst
@@ -71,15 +71,15 @@ username and the password are different only if all other validation passes
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="username">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
 
                 <property name="password">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
 
                 <getter property="passwordSafe">
@@ -103,8 +103,8 @@ username and the password are different only if all other validation passes
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
@@ -140,6 +140,13 @@ that group are valid, the second group, ``Strict``, will be validated.
     sequence, which will contain the ``Default`` group which references the
     same group sequence, ...).
 
+.. caution::
+
+    Calling ``validate()`` with a group in the sequence (``Strict`` in previous
+    example) will cause a validation **only** with that group and not with all
+    the groups in the sequence. This is because sequence is now referred to
+    ``Default`` group validation.
+
 You can also define a group sequence in the ``validation_groups`` form option::
 
     use Symfony\Component\Form\AbstractType;
@@ -212,11 +219,11 @@ entity and a new constraint group called ``Premium``:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="name">
-                    <constraint name="NotBlank" />
+                    <constraint name="NotBlank"/>
                 </property>
 
                 <property name="creditCard">
@@ -322,10 +329,10 @@ provides a sequence of groups to be validated:
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
-                <group-sequence-provider />
+                <group-sequence-provider/>
                 <!-- ... -->
             </class>
         </constraint-mapping>
diff --git a/validation/severity.rst b/validation/severity.rst
index 23b2aeea1d7..23b81145ee9 100644
--- a/validation/severity.rst
+++ b/validation/severity.rst
@@ -74,7 +74,7 @@ Use the ``payload`` option to configure the error level for each constraint:
         <?xml version="1.0" encoding="UTF-8" ?>
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\User">
                 <property name="username">
@@ -106,8 +106,8 @@ Use the ``payload`` option to configure the error level for each constraint:
         // src/Entity/User.php
         namespace App\Entity;
 
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class User
         {
@@ -142,7 +142,7 @@ method. Each constraint exposes the attached payload as a public property::
 For example, you can leverage this to customize the ``form_errors`` block
 so that the severity is added as an additional HTML class:
 
-.. code-block:: html+jinja
+.. code-block:: html+twig
 
     {%- block form_errors -%}
         {%- if errors|length > 0 -%}
diff --git a/validation/translations.rst b/validation/translations.rst
index cef1179aeb7..5aa4703e722 100644
--- a/validation/translations.rst
+++ b/validation/translations.rst
@@ -4,8 +4,8 @@
 How to Translate Validation Constraint Messages
 ===============================================
 
-If you're using validation constraints with the Form component, then translating
-the error messages is done in the translation resource for the
+If you're using validation constraints with the Form component, you can translate
+the error messages by creating a translation resource for the
 ``validators`` :ref:`domain <using-message-domains>`.
 
 To start, suppose you've created a plain-old-PHP object that you need to
@@ -53,7 +53,7 @@ property is not empty, add the following:
         <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
-                http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+                https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Author">
                 <property name="name">
@@ -69,8 +69,8 @@ property is not empty, add the following:
         // src/Entity/Author.php
 
         // ...
-        use Symfony\Component\Validator\Mapping\ClassMetadata;
         use Symfony\Component\Validator\Constraints\NotBlank;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
 
         class Author
         {
diff --git a/web_link.rst b/web_link.rst
index 793ff2ab2e4..c4766a2e498 100644
--- a/web_link.rst
+++ b/web_link.rst
@@ -1,3 +1,6 @@
+.. index::
+   single: Web Link
+
 Asset Preloading and Resource Hints with HTTP/2 and WebLink
 ===========================================================
 
@@ -24,9 +27,8 @@ Preloading Assets
 
 Imagine that your application includes a web page like this:
 
-.. code-block:: twig
+.. code-block:: html
 
-    {# templates/homepage.html.twig #}
     <!DOCTYPE html>
     <html>
     <head>
@@ -36,7 +38,7 @@ Imagine that your application includes a web page like this:
     </head>
     <body>
         <main role="main" class="container">
-            {# ... some content here ... #}
+            <!-- ... -->
         </main>
     </body>
     </html>
@@ -50,60 +52,66 @@ To do that, first install the WebLink component:
 
 .. code-block:: terminal
 
-    $ composer req web-link
+    $ composer require symfony/web-link
 
 Now, update the template to use the ``preload()`` Twig function provided by
-WebLink:
+WebLink. The `"as" attribute`_ is mandatory because browsers need it to apply
+correct prioritization and the content security policy:
 
-.. code:: twig
+.. code-block:: html+twig
 
     <head>
-       {# ... #}
-        <link rel="stylesheet" href="{{ preload('/app.css') }}">
+        <!-- ... -->
+        <link rel="stylesheet" href="{{ preload('/app.css', { as: 'style' }) }}">
     </head>
 
 If you reload the page, the perceived performance will improve because the
 server responded with both the HTML page and the CSS file when the browser only
 requested the HTML page.
 
+.. note::
+
+    You can preload an asset by wrapping it with the ``preload()`` function:
+
+    .. code-block:: html+twig
+
+        <head>
+            <!-- ... -->
+            <link rel="stylesheet" href="{{ preload(asset('build/app.css')) }}">
+        </head>
+
 Additionally, according to `the Priority Hints specification`_, you can signal
 the priority of the resource to download using the ``importance`` attribute:
 
-.. code:: twig
+.. code-block:: html+twig
 
     <head>
-       {# ... #}
-        <link rel="stylesheet" href="{{ preload('/app.css', { importance: 'low' }) }}">
+        <!-- ... -->
+        <link rel="stylesheet" href="{{ preload('/app.css', { as: 'style', importance: 'low' }) }}">
     </head>
 
-.. tip::
-
-    Google Chrome provides an interface to debug HTTP/2 connections. Browse
-    ``chrome://net-internals/#http2`` to see all the details.
-
 How does it work?
 ~~~~~~~~~~~~~~~~~
 
 The WebLink component manages the ``Link`` HTTP headers added to the response.
 When using the ``preload()`` function in the previous example, the following
-header was added to the response: ``Link </app.css>; rel="preload"``
-
+header was added to the response: ``Link </app.css>; rel="preload"; as="style"``
 According to `the Preload specification`_, when an HTTP/2 server detects that
 the original (HTTP 1.x) response contains this HTTP header, it will
 automatically trigger a push for the related file in the same HTTP/2 connection.
 
 Popular proxy services and CDNs including `Cloudflare`_, `Fastly`_ and `Akamai`_
 also leverage this feature. It means that you can push resources to clients and
-improve performance of your apps in production right now.
+improve performance of your applications in production right now.
 
 If you want to prevent the push but let the browser preload the resource by
 issuing an early separate HTTP request, use the ``nopush`` option:
 
-.. code:: twig
+.. code-block:: html+twig
 
     <head>
-       {# ... #}
-        <link rel="stylesheet" href="{{ preload('/app.css', { nopush: true }) }}">
+        <!-- ... -->
+        <link rel="stylesheet" href="{{ preload('/app.css', { as: 'style', nopush: true }) }}">
     </head>
 
 Resource Hints
@@ -132,12 +140,12 @@ The component also supports sending HTTP links not related to performance and
 any link implementing the `PSR-13`_ standard. For instance, any
 `link defined in the HTML specification`_:
 
-.. code:: twig
+.. code-block:: html+twig
 
     <head>
-       {# ... #}
+        <!-- ... -->
         <link rel="alternate" href="{{ link('/index.jsonld', 'alternate') }}">
-        <link rel="stylesheet" href="{{ preload('/app.css', {nopush: true}) }}">
+        <link rel="stylesheet" href="{{ preload('/app.css', { as: 'style', nopush: true }) }}">
     </head>
 
 The previous snippet will result in this HTTP header being sent to the client:
@@ -150,15 +158,19 @@ You can also add links to the HTTP response directly from controllers and servic
 
     use Fig\Link\GenericLinkProvider;
     use Fig\Link\Link;
-    use Symfony\Component\HttpFoundation\Request;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Request;
 
     class BlogController extends AbstractController
     {
         public function index(Request $request)
         {
+            // using the addLink() shortcut provided by AbstractController
+            $this->addLink($request, new Link('preload', '/app.css'));
+
+            // alternative if you don't want to use the addLink() shortcut
             $linkProvider = $request->attributes->get('_links', new GenericLinkProvider());
-            $request->attributes->set('_links', $linkProvider->withLink(new Link('preload', '/app.css')));
+            $request->attributes->set('_links', $linkProvider->withLink(new Link('preload', '/app.css', ['as' : 'style'])));
 
             return $this->render('...');
         }
@@ -172,12 +184,11 @@ You can also add links to the HTTP response directly from controllers and servic
 .. _`HTTP/2 Server Push`: https://tools.ietf.org/html/rfc7540#section-8.2
 .. _`Resource Hints`: https://www.w3.org/TR/resource-hints/
 .. _`Docker installer and runtime for Symfony`: https://github.com/dunglas/symfony-docker
-.. _`preload`: https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content
+.. _`"as" attribute`: https://w3c.github.io/preload/#as-attribute
 .. _`the Priority Hints specification`: https://wicg.github.io/priority-hints/
 .. _`the Preload specification`: https://www.w3.org/TR/preload/#server-push-(http/2)
 .. _`Cloudflare`: https://blog.cloudflare.com/announcing-support-for-http-2-server-push-2/
 .. _`Fastly`: https://docs.fastly.com/guides/performance-tuning/http2-server-push
 .. _`Akamai`: https://blogs.akamai.com/2017/03/http2-server-push-the-what-how-and-why.html
-.. _`this great article`: https://www.shimmercat.com/en/blog/articles/whats-push/
 .. _`link defined in the HTML specification`: https://html.spec.whatwg.org/dev/links.html#linkTypes
-.. _`PSR-13`: http://www.php-fig.org/psr/psr-13/
+.. _`PSR-13`: https://www.php-fig.org/psr/psr-13/
diff --git a/workflow.rst b/workflow.rst
index b25e62b8379..6b36d4df338 100644
--- a/workflow.rst
+++ b/workflow.rst
@@ -1,45 +1,733 @@
 Workflow
 ========
 
-A workflow is a model of a process in your application. It may be the process
-of how a blog post goes from draft, review and publish. Another example is when
-a user submits a series of different forms to complete a task. Such processes are
-best kept away from your models and should be defined in configuration.
+Using the Workflow component inside a Symfony application requires to know first
+some basic theory and concepts about workflows and state machines.
+:doc:`Read this article </workflow/introduction>` for a quick overview.
 
-A **definition** of a workflow consist of places and actions to get from one
-place to another. The actions are called **transitions**. A workflow does also
-need to know each object's position in the workflow. That **marking store** writes
-to a property of the object to remember the current place.
+Installation
+------------
+
+In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to
+install the workflow feature before using it:
+
+.. code-block:: terminal
+
+    $ composer require symfony/workflow
+
+Configuration
+-------------
+
+To see all configuration options, if you are using the component inside a
+Symfony project run this command:
+
+.. code-block:: terminal
+
+    $ php bin/console config:dump-reference framework workflows
+
+Creating a Workflow
+-------------------
+
+A workflow is a process or a lifecycle that your objects go through. Each
+step or stage in the process is called a *place*. You do also define *transitions*
+to that describes the action to get from one place to another.
+
+.. image:: /_images/components/workflow/states_transitions.png
+
+A set of places and transitions creates a **definition**. A workflow needs
+a ``Definition`` and a way to write the states to the objects (i.e. an
+instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`.)
+
+Consider the following example for a blog post. A post can have these places:
+``draft``, ``reviewed``, ``rejected``, ``published``. You can define the workflow
+like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/framework.yaml
+        framework:
+            workflows:
+                blog_publishing:
+                    type: 'workflow' # or 'state_machine'
+                    audit_trail:
+                        enabled: true
+                    marking_store:
+                        type: 'method'
+                        property:
+                            - 'currentPlace'
+                    supports:
+                        - App\Entity\BlogPost
+                    initial_marking: draft
+                    places:
+                        - draft
+                        - reviewed
+                        - rejected
+                        - published
+                    transitions:
+                        to_review:
+                            from: draft
+                            to:   reviewed
+                        publish:
+                            from: reviewed
+                            to:   published
+                        reject:
+                            from: reviewed
+                            to:   rejected
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+
+            <framework:config>
+                <framework:workflow name="blog_publishing" type="workflow">
+                    <framework:audit-trail enabled="true"/>
+                    <framework:marking-store type="single_state">
+                        <framework:argument>currentPlace</framework:argument>
+                    </framework:marking-store>
+                    <framework:support>App\Entity\BlogPost</framework:support>
+                    <framework:initial-marking>draft</framework:initial-marking>
+                    <framework:place>draft</framework:place>
+                    <framework:place>reviewed</framework:place>
+                    <framework:place>rejected</framework:place>
+                    <framework:place>published</framework:place>
+                    <framework:transition name="to_review">
+                        <framework:from>draft</framework:from>
+                        <framework:to>reviewed</framework:to>
+                    </framework:transition>
+                    <framework:transition name="publish">
+                        <framework:from>reviewed</framework:from>
+                        <framework:to>published</framework:to>
+                    </framework:transition>
+                    <framework:transition name="reject">
+                        <framework:from>reviewed</framework:from>
+                        <framework:to>rejected</framework:to>
+                    </framework:transition>
+                </framework:workflow>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', [
+            // ...
+            'workflows' => [
+                'blog_publishing' => [
+                    'type' => 'workflow', // or 'state_machine'
+                    'audit_trail' => [
+                        'enabled' => true
+                    ],
+                    'marking_store' => [
+                        'type' => 'method'
+                        'property' => ['currentPlace']
+                    ],
+                    'supports' => ['App\Entity\BlogPost'],
+                    'initial_marking' => 'draft',
+                    'places' => [
+                        'draft',
+                        'reviewed',
+                        'rejected',
+                        'published',
+                    ],
+                    'transitions' => [
+                        'to_review' => [
+                            'from' => 'draft',
+                            'to' => 'reviewed',
+                        ],
+                        'publish' => [
+                            'from' => 'reviewed',
+                            'to' => 'published',
+                        ],
+                        'reject' => [
+                            'from' => 'reviewed',
+                            'to' => 'rejected',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+
+.. tip::
+
+    If you are creating your first workflows, consider using the ``workflow:dump``
+    command to :doc:`debug the workflow contents </workflow/dumping-workflows>`.
+
+As configured, the following property is used by the marking store::
+
+    class BlogPost
+    {
+        // This property is used by the marking store
+        public $currentPlace;
+        public $title;
+        public $content;
+    }
+
+.. tip::
+
+    Setting the ``audit_trail.enabled`` option to ``true`` makes the application
+    generate detailed log messages for the workflow activity.
+
+With this workflow named ``blog_publishing``, you can get help to decide
+what actions are allowed on a blog post::
+
+    use App\Entity\BlogPost;
+    use Symfony\Component\Workflow\Exception\LogicException;
+
+    $post = new BlogPost();
+
+    $workflow = $this->container->get('workflow.blog_publishing');
+    $workflow->can($post, 'publish'); // False
+    $workflow->can($post, 'to_review'); // True
+
+    // Update the currentState on the post
+    try {
+        $workflow->apply($post, 'to_review');
+    } catch (LogicException $exception) {
+        // ...
+    }
+
+    // See all the available transitions for the post in the current state
+    $transitions = $workflow->getEnabledTransitions($post);
+
+Using Events
+------------
+
+To make your workflows more flexible, you can construct the ``Workflow``
+object with an ``EventDispatcher``. You can now create event listeners to
+block transitions (i.e. depending on the data in the blog post) and do
+additional actions when a workflow operation happened (e.g. sending
+announcements).
+
+Each step has three events that are fired in order:
+
+* An event for every workflow;
+* An event for the workflow concerned;
+* An event for the workflow concerned with the specific transition or place name.
+
+When a state transition is initiated, the events are dispatched in the following
+order:
+
+``workflow.guard``
+    Validate whether the transition is blocked or not (see
+    :ref:`guard events <workflow-usage-guard-events>` and
+    :ref:`blocking transitions <workflow-blocking-transitions>`).
+
+    The three events being dispatched are:
+
+    * ``workflow.guard``
+    * ``workflow.[workflow name].guard``
+    * ``workflow.[workflow name].guard.[transition name]``
+
+``workflow.leave``
+    The subject is about to leave a place.
+
+    The three events being dispatched are:
+
+    * ``workflow.leave``
+    * ``workflow.[workflow name].leave``
+    * ``workflow.[workflow name].leave.[place name]``
+
+``workflow.transition``
+    The subject is going through this transition.
+
+    The three events being dispatched are:
+
+    * ``workflow.transition``
+    * ``workflow.[workflow name].transition``
+    * ``workflow.[workflow name].transition.[transition name]``
+
+``workflow.enter``
+    The subject is about to enter a new place. This event is triggered just
+    before the subject places are updated, which means that the marking of the
+    subject is not yet updated with the new places.
+
+    The three events being dispatched are:
+
+    * ``workflow.enter``
+    * ``workflow.[workflow name].enter``
+    * ``workflow.[workflow name].enter.[place name]``
+
+``workflow.entered``
+    The subject has entered in the places and the marking is updated (making it a good
+    place to flush data in Doctrine).
+
+    The three events being dispatched are:
+
+    * ``workflow.entered``
+    * ``workflow.[workflow name].entered``
+    * ``workflow.[workflow name].entered.[place name]``
+
+``workflow.completed``
+    The object has completed this transition.
+
+    The three events being dispatched are:
+
+    * ``workflow.completed``
+    * ``workflow.[workflow name].completed``
+    * ``workflow.[workflow name].completed.[transition name]``
+
+
+``workflow.announce``
+    Triggered for each transition that now is accessible for the subject.
+
+    The three events being dispatched are:
+
+    * ``workflow.announce``
+    * ``workflow.[workflow name].announce``
+    * ``workflow.[workflow name].announce.[transition name]``
 
 .. note::
 
-    The terminology above is commonly used when discussing workflows and
-    `Petri nets`_
+    The leaving and entering events are triggered even for transitions that stay
+    in same place.
+
+Here is an example of how to enable logging for every time a "blog_publishing"
+workflow leaves a place::
+
+    use Psr\Log\LoggerInterface;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\Workflow\Event\Event;
+
+    class WorkflowLogger implements EventSubscriberInterface
+    {
+        private $logger;
+
+        public function __construct(LoggerInterface $logger)
+        {
+            $this->logger = $logger;
+        }
+
+        public function onLeave(Event $event)
+        {
+            $this->logger->alert(sprintf(
+                'Blog post (id: "%s") performed transition "%s" from "%s" to "%s"',
+                $event->getSubject()->getId(),
+                $event->getTransition()->getName(),
+                implode(', ', array_keys($event->getMarking()->getPlaces())),
+                implode(', ', $event->getTransition()->getTos())
+            ));
+        }
+
+        public static function getSubscribedEvents()
+        {
+            return [
+                'workflow.blog_publishing.leave' => 'onLeave',
+            ];
+        }
+    }
+
+.. _workflow-usage-guard-events:
 
-The Workflow component does also support state machines. A state machine is a subset
-of a workflow and its purpose is to hold a state of your model. Read more about the
-differences and specific features of state machine in :doc:`/workflow/state-machines`.
+Guard Events
+~~~~~~~~~~~~
 
-Examples
---------
+There are a special kind of events called "Guard events". Their event listeners
+are invoked every time a call to ``Workflow::can``, ``Workflow::apply`` or
+``Workflow::getEnabledTransitions`` is executed. With the guard events you may
+add custom logic to decide which transitions should be blocked or not. Here is a
+list of the guard event names.
 
-The simplest workflow looks like this. It contains two places and one transition.
+* ``workflow.guard``
+* ``workflow.[workflow name].guard``
+* ``workflow.[workflow name].guard.[transition name]``
 
-.. image:: /_images/components/workflow/simple.png
+This example stops any blog post being transitioned to "reviewed" if it is
+missing a title::
 
-Workflows could be more complicated when they describe a real business case. The
-workflow below describes the process to fill in a job application.
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\Workflow\Event\GuardEvent;
 
-.. image:: /_images/components/workflow/job_application.png
+    class BlogPostReviewListener implements EventSubscriberInterface
+    {
+        public function guardReview(GuardEvent $event)
+        {
+            /** @var App\Entity\BlogPost $post */
+            $post = $event->getSubject();
+            $title = $post->title;
 
-When you fill in a job application in this example there are 4 to 7 steps depending
-on the what job you are applying for. Some jobs require personality tests, logic tests
-and/or formal requirements to be answered by the user. Some jobs don't. The
-``GuardEvent`` is used to decide what next steps are allowed for a specific application.
+            if (empty($title)) {
+                // Block the transition "to_review" if the post has no title
+                $event->setBlocked(true);
+            }
+        }
 
-By defining a workflow like this, there is an overview how the process looks like. The process
-logic is not mixed with the controllers, models or view. The order of the steps can be changed
-by changing the configuration only.
+        public static function getSubscribedEvents()
+        {
+            return [
+                'workflow.blog_publishing.guard.to_review' => ['guardReview'],
+            ];
+        }
+    }
+
+Event Methods
+~~~~~~~~~~~~~
+
+Each workflow event is an instance of :class:`Symfony\\Component\\Workflow\\Event\\Event`.
+This means that each event has access to the following information:
+
+:method:`Symfony\\Component\\Workflow\\Event\\Event::getMarking`
+    Returns the :class:`Symfony\\Component\\Workflow\\Marking` of the workflow.
+
+:method:`Symfony\\Component\\Workflow\\Event\\Event::getSubject`
+    Returns the object that dispatches the event.
+
+:method:`Symfony\\Component\\Workflow\\Event\\Event::getTransition`
+    Returns the :class:`Symfony\\Component\\Workflow\\Transition` that dispatches the event.
+
+:method:`Symfony\\Component\\Workflow\\Event\\Event::getWorkflowName`
+    Returns a string with the name of the workflow that triggered the event.
+
+:method:`Symfony\\Component\\Workflow\\Event\\Event::getMetadata`
+    Returns a metadata.
+
+For Guard Events, there is an extended class :class:`Symfony\\Component\\Workflow\\Event\\GuardEvent`.
+This class has two more methods:
+
+:method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::isBlocked`
+    Returns if transition is blocked.
+
+:method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::setBlocked`
+    Sets the blocked value.
+
+:method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::getTransitionBlockerList`
+    Returns the event :class:`Symfony\\Component\\Workflow\\TransitionBlockerList`.
+    See :ref:`blocking transitions <workflow-blocking-transitions>`.
+
+:method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::addTransitionBlocker`
+    Add a :class:`Symfony\\Component\\Workflow\\TransitionBlocker` instance.
+
+.. _workflow-blocking-transitions:
+
+Blocking Transitions
+--------------------
+
+The execution of the workflow can be controlled by executing custom logic to
+decide if the current transition is blocked or allowed before applying it. This
+feature is provided by "guards", which can be used in two ways.
+
+First, you can listen to :ref:`the guard events <workflow-usage-guard-events>`.
+Alternatively, you can define a ``guard`` configuration option for the
+transition. The value of this option is any valid expression created with the
+:doc:`ExpressionLanguage component </components/expression_language>`:
+
+.. code-block:: yaml
+
+    # config/packages/workflow.yaml
+    framework:
+        workflows:
+            blog_publishing:
+                # previous configuration
+                transitions:
+                    to_review:
+                        # the transition is allowed only if the current user has the ROLE_REVIEWER role.
+                        guard: "is_granted('ROLE_REVIEWER')"
+                        from: draft
+                        to:   reviewed
+                    publish:
+                        # or "is_anonymous", "is_remember_me", "is_fully_authenticated", "is_granted", "is_valid"
+                        guard: "is_authenticated"
+                        from: reviewed
+                        to:   published
+                    reject:
+                        # or any valid expression language with "subject" referring to the supported object
+                        guard: "has_role('ROLE_ADMIN') and subject.isRejectable()"
+                        from: reviewed
+                        to:   rejected
+
+You can also use transition blockers to block and return a user-friendly error
+message when you stop a transition from happening.
+In the example we get this message from the
+:class:`Symfony\\Component\\Workflow\\Event\\Event`'s metadata, giving you a
+central place to manage the text.
+
+This example has been simplified; in production you may prefer to use the
+:doc:`Translation </components/translation>` component to manage messages in one
+place::
+
+    namespace App\Listener\Workflow\Task;
+
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\Workflow\Event\GuardEvent;
+    use Symfony\Component\Workflow\TransitionBlocker;
+
+    class BlogPostPublishListener implements EventSubscriberInterface
+    {
+        public function guardPublish(GuardEvent $event)
+        {
+            $eventTransition = $event->getTransition();
+            $hourLimit = $event->getMetadata('hour_limit', $eventTransition);
+
+            if (date('H') <= $hourLimit) {
+                return;
+            }
+
+            // Block the transition "publish" if it is more than 8 PM
+            // with the message for end user
+            $explanation = $event->getMetadata('explanation', $eventTransition);
+            $event->addTransitionBlocker(new TransitionBlocker($explanation , 0));
+        }
+
+        public static function getSubscribedEvents()
+        {
+            return [
+                'workflow.blog_publishing.guard.publish' => ['guardPublish'],
+            ];
+        }
+    }
+
+.. versionadded:: 4.1
+
+    The transition blockers were introduced in Symfony 4.1.
+
+Usage in Twig
+-------------
+
+Symfony defines several Twig functions to manage workflows and reduce the need
+of domain logic in your templates:
+
+``workflow_can()``
+    Returns ``true`` if the given object can make the given transition.
+
+``workflow_transitions()``
+    Returns an array with all the transitions enabled for the given object.
+
+``workflow_marked_places()``
+    Returns an array with the place names of the given marking.
+
+``workflow_has_marked_place()``
+    Returns ``true`` if the marking of the given object has the given state.
+
+The following example shows these functions in action:
+
+.. code-block:: html+twig
+
+    <h3>Actions on Blog Post</h3>
+    {% if workflow_can(post, 'publish') %}
+        <a href="...">Publish</a>
+    {% endif %}
+    {% if workflow_can(post, 'to_review') %}
+        <a href="...">Submit to review</a>
+    {% endif %}
+    {% if workflow_can(post, 'reject') %}
+        <a href="...">Reject</a>
+    {% endif %}
+
+    {# Or loop through the enabled transitions #}
+    {% for transition in workflow_transitions(post) %}
+        <a href="...">{{ transition.name }}</a>
+    {% else %}
+        No actions available.
+    {% endfor %}
+
+    {# Check if the object is in some specific place #}
+    {% if workflow_has_marked_place(post, 'reviewed') %}
+        <p>This post is ready for review.</p>
+    {% endif %}
+
+    {# Check if some place has been marked on the object #}
+    {% if 'reviewed' in workflow_marked_places(post) %}
+        <span class="label">Reviewed</span>
+    {% endif %}
+
+Storing Metadata
+----------------
+
+.. versionadded:: 4.1
+
+    The feature to store metadata in workflows was introduced in Symfony 4.1.
+
+In case you need it, you can store arbitrary metadata in workflows, their
+places, and their transitions using the ``metadata`` option. This metadata can
+be as simple as the title of the workflow or as complex as your own application
+requires:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/workflow.yaml
+        framework:
+            workflows:
+                blog_publishing:
+                    metadata:
+                        title: 'Blog Publishing Workflow'
+                    # ...
+                    places:
+                        draft:
+                            metadata:
+                                max_num_of_words: 500
+                        # ...
+                    transitions:
+                        to_review:
+                            from: draft
+                            to:   review
+                            metadata:
+                                priority: 0.5
+                        publish:
+                            from: reviewed
+                            to:   published
+                            metadata:
+                                hour_limit: 20
+                                explanation: 'You can not publish after 8 PM.'
+
+    .. code-block:: xml
+
+        <!-- config/packages/workflow.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+            <framework:config>
+                <framework:workflow name="blog_publishing">
+                    <framework:metadata>
+                        <framework:title>Blog Publishing Workflow</framework:title>
+                    </framework:metadata>
+                    <!-- ... -->
+                    <framework:place name="draft">
+                        <framework:metadata>
+                            <framework:max-num-of-words>500</framework:max-num-of-words>
+                        </framework:metadata>
+                    </framework:place>
+                    <!-- ... -->
+                    <framework:transition name="to_review">
+                        <framework:from>draft</framework:from>
+                        <framework:to>review</framework:to>
+                        <framework:metadata>
+                            <framework:priority>0.5</framework:priority>
+                        </framework:metadata>
+                    </framework:transition>
+                    <framework:transition name="publish">
+                        <framework:from>reviewed</framework:from>
+                        <framework:to>published</framework:to>
+                        <framework:metadata>
+                            <framework:hour_limit>20</framework:hour_limit>
+                            <framework:explanation>You can not publish after 8 PM.</framework:explanation>
+                        </framework:metadata>
+                    </framework:transition>
+                </framework:workflow>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/workflow.php
+        $container->loadFromExtension('framework', [
+            // ...
+            'workflows' => [
+                'blog_publishing' => [
+                    'metadata' => [
+                        'title' => 'Blog Publishing Workflow',
+                    ],
+                    // ...
+                    'places' => [
+                        'draft' => [
+                            'metadata' => [
+                                'max_num_of_words' => 500,
+                            ],
+                        ],
+                        // ...
+                    ],
+                    'transitions' => [
+                        'to_review' => [
+                            'from' => 'draft',
+                            'to' => 'review',
+                            'metadata' => [
+                                'priority' => 0.5,
+                            ],
+                        ],
+                        'publish' => [
+                            'from' => 'reviewed',
+                            'to' => 'published',
+                            'metadata' => [
+                                'hour_limit' => 20,
+                                'explanation' => 'You can not publish after 8 PM.',
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+
+Then you can access this metadata in your controller as follows::
+
+    use App\Entity\BlogPost;
+    use Symfony\Component\Workflow\Registry;
+
+    public function myController(Registry $registry, BlogPost $post)
+    {
+        $workflow = $registry->get($post);
+
+        $title = $workflow
+            ->getMetadataStore()
+            ->getWorkflowMetadata()['title'] ?? 'Default title'
+        ;
+
+        // or
+        $aTransition = $workflow->getDefinition()->getTransitions()[0];
+        $transitionTitle = $workflow
+            ->getMetadataStore()
+            ->getTransitionMetadata($aTransition)['priority'] ?? 0
+        ;
+    }
+
+There is a shortcut that works with every metadata level::
+
+    $title = $workflow->getMetadataStore()->getMetadata('title');
+    $priority = $workflow->getMetadataStore()->getMetadata('priority');
+
+In a :ref:`flash message <flash-messages>` in your controller::
+
+    // $transition = ...; (an instance of Transition)
+
+    // $workflow is a Workflow instance retrieved from the Registry (see above)
+    $title = $workflow->getMetadataStore()->getMetadata('title', $transition);
+    $this->addFlash('info', "You have successfully applied the transition with title: '$title'");
+
+Metadata can also be accessed in a Listener, from the :class:`Symfony\\Component\\Workflow\\Event\\Event` object.
+
+In Twig templates, metadata is available via the ``workflow_metadata()`` function:
+
+.. code-block:: html+twig
+
+    <h2>Metadata of Blog Post</h2>
+    <p>
+        <strong>Workflow</strong>:<br>
+        <code>{{ workflow_metadata(blog_post, 'title') }}</code>
+    </p>
+    <p>
+        <strong>Current place(s)</strong>
+        <ul>
+            {% for place in workflow_marked_places(blog_post) %}
+                <li>
+                    {{ place }}:
+                    <code>{{ workflow_metadata(blog_post, 'max_num_of_words', place) ?: 'Unlimited'}}</code>
+                </li>
+            {% endfor %}
+        </ul>
+    </p>
+    <p>
+        <strong>Enabled transition(s)</strong>
+        <ul>
+            {% for transition in workflow_transitions(blog_post) %}
+                <li>
+                    {{ transition.name }}:
+                    <code>{{ workflow_metadata(blog_post, 'priority', transition) ?: '0' }}</code>
+                </li>
+            {% endfor %}
+        </ul>
+    </p>
 
 Learn more
 ----------
@@ -47,8 +735,5 @@ Learn more
 .. toctree::
    :maxdepth: 1
 
-   workflow/usage
-   workflow/state-machines
+   workflow/introduction
    workflow/dumping-workflows
-
-.. _Petri nets: https://en.wikipedia.org/wiki/Petri_net
diff --git a/workflow/dumping-workflows.rst b/workflow/dumping-workflows.rst
index b8709f722ee..2499dd35225 100644
--- a/workflow/dumping-workflows.rst
+++ b/workflow/dumping-workflows.rst
@@ -4,60 +4,295 @@
 How to Dump Workflows
 =====================
 
-To help you debug your workflows, you can dump a representation of your workflow
-or state machine with the use of a ``DumperInterface``. Symfony provides 2
-different dumpers both based on Dot.
+To help you debug your workflows, you can generate a visual representation of
+them as SVG or PNG images. First, install any of these free and open source
+applications needed to generate the images:
 
-Use the ``GraphvizDumper`` or ``StateMachineGraphvizDumper`` to create DOT
-files, or use ``PlantUmlDumper`` for PlantUML files. Both types can be converted
-to PNG or SVG images.
+* `Graphviz`_, provides the ``dot`` command;
+* `PlantUML`_, provides the ``plantuml.jar`` file (which requires Java).
 
-Images of the workflow defined above:
+If you are defining the workflow inside a Symfony application, run this command
+to dump it as an image:
 
-.. code-block:: php
+.. code-block:: terminal
 
-    // dump-graph-dot.php
-    $dumper = new GraphvizDumper();
-    echo $dumper->dump($definition);
+    # using Graphviz's 'dot' and SVG images
+    $ php bin/console workflow:dump workflow-name | dot -Tsvg -o graph.svg
+
+    # using Graphviz's 'dot' and PNG images
+    $ php bin/console workflow:dump workflow-name | dot -Tpng -o graph.png
+
+    # using PlantUML's 'plantuml.jar'
+    $ php bin/console workflow:dump workflow_name --dump-format=puml | java -jar plantuml.jar -p  > graph.png
+
+    # highlight 'place1' and 'place2' in the dumped workflow
+    $ php bin/console workflow:dump workflow-name place1 place2 | dot -Tsvg -o graph.svg
 
-.. code-block:: php
+The DOT image will look like this:
+
+.. image:: /_images/components/workflow/blogpost.png
+
+The PlantUML image will look like this:
+
+.. image:: /_images/components/workflow/blogpost_puml.png
 
-    // dump-graph-puml.php
-    $dumper = new PlantUmlDumper();
+If you are creating workflows outside of a Symfony application, use the
+``GraphvizDumper`` or ``StateMachineGraphvizDumper`` class to create the DOT
+files and ``PlantUmlDumper`` to create the PlantUML files::
+
+    // Add this code to a PHP script; for example: dump-graph.php
+    $dumper = new GraphvizDumper();
     echo $dumper->dump($definition);
 
+    # if you prefer PlantUML, use this code:
+    # $dumper = new PlantUmlDumper();
+    # echo $dumper->dump($definition);
+
 .. code-block:: terminal
 
-    $ php dump-graph-dot.php | dot -Tpng -o dot_graph.png
-    $ php dump-graph-puml.php | java -jar plantuml.jar -p  > puml_graph.png
+    # replace 'dump-graph.php' by the name of your PHP script
+    $ php dump-graph.php | dot -Tsvg -o graph.svg
+    $ php dump-graph.php | java -jar plantuml.jar -p  > graph.png
 
-    # run this command if you prefer SVG images:
-    # $ php dump-graph-dot.php | dot -Tsvg -o dot_graph.svg
+Styling
+-------
 
-The DOT result will look like this:
+You can use ``metadata`` with the following keys to style the workflow:
 
-.. image:: /_images/components/workflow/blogpost.png
+* for places:
+  * ``bg_color``: a color;
+  * ``description``: a string that describes the state.
+* for transitions:
+  * ``label``: a string that replaces the name of the transition;
+  * ``color``: a color;
+  * ``arrow_color``: a color.
 
-The PUML result:
+Strings can include ``\n`` characters to display the contents in multiple lines.
+Colors can be defined as:
 
-.. image:: /_images/components/workflow/blogpost_puml.png
+* a color name from `PlantUML's color list`_;
+* an hexadecimal color (both ``#AABBCC`` and ``#ABC`` formats are supported).
 
-Inside a Symfony application, you can dump the files with those commands using
-``workflow:dump`` command:
+Below is the configuration for the pull request state machine with styling added.
 
-.. code-block:: terminal
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/workflow.yaml
+        framework:
+            workflows:
+                pull_request:
+                    type: 'state_machine'
+                    supports:
+                        - App\Entity\PullRequest
+                    initial_place: start
+                    places:
+                        start: ~
+                        coding: ~
+                        test: ~
+                        review:
+                            metadata:
+                                description: Human review
+                        merged: ~
+                        closed:
+                            metadata:
+                                bg_color: DeepSkyBlue
+                    transitions:
+                        submit:
+                            from: start
+                            to: test
+                        update:
+                            from: [coding, test, review]
+                            to: test
+                            metadata:
+                                arrow_color: Turquoise
+                        wait_for_review:
+                            from: test
+                            to: review
+                            metadata:
+                                color: Orange
+                        request_change:
+                            from: review
+                            to: coding
+                        accept:
+                            from: review
+                            to: merged
+                            metadata:
+                                label: Accept PR
+                        reject:
+                            from: review
+                            to: closed
+                        reopen:
+                            from: closed
+                            to: review
+
+    .. code-block:: xml
+
+        <!-- config/packages/workflow.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+
+            <framework:config>
+                <framework:workflow name="pull_request" type="state_machine">
+                    <framework:marking-store type="single_state"/>
+
+                    <framework:support>App\Entity\PullRequest</framework:support>
+
+                    <framework:place>start</framework:place>
+                    <framework:place>coding</framework:place>
+                    <framework:place>test</framework:place>
+                    <framework:place name="review">
+                        <framework:metadata>
+                            <framework:description>Human review</framework:description>
+                        </framework:metadata>
+                    </framework:place>
+                    <framework:place>merged</framework:place>
+                    <framework:place name="closed">
+                        <framework:metadata>
+                            <framework:bg_color>DeepSkyBlue</framework:bg_color>
+                        </framework:metadata>
+                    </framework:place>
+                    </framework:place>
+
+                    <framework:transition name="submit">
+                        <framework:from>start</framework:from>
+
+                        <framework:to>test</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="update">
+                        <framework:from>coding</framework:from>
+                        <framework:from>test</framework:from>
+                        <framework:from>review</framework:from>
+
+                        <framework:to>test</framework:to>
+
+                        <framework:metadata>
+                            <framework:arrow_color>Turquoise</framework:arrow_color>
+                        </framework:metadata>
+                    </framework:transition>
+
+                    <framework:transition name="wait_for_review">
+                        <framework:from>test</framework:from>
+
+                        <framework:to>review</framework:to>
+
+                        <framework:metadata>
+                            <framework:color>Orange</framework:color>
+                        </framework:metadata>
+                    </framework:transition>
+
+                    <framework:transition name="request_change">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>coding</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="accept">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>merged</framework:to>
+
+                        <framework:metadata>
+                            <framework:label>Accept PR</framework:label>
+                        </framework:metadata>
+                    </framework:transition>
+
+                    <framework:transition name="reject">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>closed</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="reopen">
+                        <framework:from>closed</framework:from>
+
+                        <framework:to>review</framework:to>
+                    </framework:transition>
+
+                </framework:workflow>
 
-    $ php bin/console workflow:dump name | dot -Tsvg -o graph.svg
-    $ php bin/console workflow:dump name --dump-format=puml | java -jar plantuml.jar -p  > workflow.png
+            </framework:config>
+        </container>
 
-.. note::
+    .. code-block:: php
 
-    The ``dot`` command is part of Graphviz. You can download it and read
-    more about it on `Graphviz.org`_.
+        // config/packages/workflow.php
+        $container->loadFromExtension('framework', [
+            // ...
+            'workflows' => [
+                'pull_request' => [
+                    'type' => 'state_machine',
+                    'supports' => ['App\Entity\PullRequest'],
+                    'places' => [
+                        'start',
+                        'coding',
+                        'test',
+                        'review' => [
+                          'metadata' => [
+                              'description' => 'Human review',
+                          ],
+                        ],
+                        'merged',
+                        'closed' => [
+                          'metadata' => [
+                              'bg_color' => 'DeepSkyBlue',
+                          ],
+                        ],
+                    ],
+                    'transitions' => [
+                        'submit'=> [
+                            'from' => 'start',
+                            'to' => 'test',
+                        ],
+                        'update'=> [
+                            'from' => ['coding', 'test', 'review'],
+                            'to' => 'test',
+                            'metadata' => [
+                                'arrow_color' => 'Turquoise',
+                            ],
+                        ],
+                        'wait_for_review'=> [
+                            'from' => 'test',
+                            'to' => 'review',
+                            'metadata' => [
+                                'color' => 'Orange',
+                            ],
+                        ],
+                        'request_change'=> [
+                            'from' => 'review',
+                            'to' => 'coding',
+                        ],
+                        'accept'=> [
+                            'from' => 'review',
+                            'to' => 'merged',
+                            'metadata' => [
+                                'label' => 'Accept PR',
+                            ],
+                        ],
+                        'reject'=> [
+                            'from' => 'review',
+                            'to' => 'closed',
+                        ],
+                        'reopen'=> [
+                            'from' => 'start',
+                            'to' => 'review',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
 
-    The ``plantuml.jar`` command is part of PlantUML. You can download it and
-    read more about it on `PlantUML.com`_.
+The PlantUML image will look like this:
 
+.. image:: /_images/components/workflow/pull_request_puml_styled.png
 
-.. _Graphviz.org: http://www.graphviz.org
-.. _PlantUML.com: http://plantuml.com/
+.. _`Graphviz`: http://www.graphviz.org
+.. _`PlantUML`: http://plantuml.com/
+.. _`PlantUML's color list`: http://plantuml.com/en/color
diff --git a/workflow/introduction.rst b/workflow/introduction.rst
new file mode 100644
index 00000000000..385ec8e8cd1
--- /dev/null
+++ b/workflow/introduction.rst
@@ -0,0 +1,294 @@
+Workflows and State Machines
+============================
+
+Workflows
+---------
+
+A workflow is a model of a process in your application. It may be the process of
+how a blog post goes from draft to review and publish. Another example is when a
+user submits a series of different forms to complete a task. Such processes are
+best kept away from your models and should be defined in configuration.
+
+A **definition** of a workflow consists of places and actions to get from one
+place to another. The actions are called **transitions**. A workflow does also
+need to know each object's position in the workflow. That **marking store**
+writes to a property of the object to remember the current place.
+
+.. note::
+
+    The terminology above is commonly used when discussing workflows and
+    `Petri nets`_
+
+Examples
+~~~~~~~~
+
+The simplest workflow looks like this. It contains two places and one transition.
+
+.. image:: /_images/components/workflow/simple.png
+
+Workflows could be more complicated when they describe a real business case. The
+workflow below describes the process to fill in a job application.
+
+.. image:: /_images/components/workflow/job_application.png
+
+When you fill in a job application in this example there are 4 to 7 steps
+depending on the job you are applying for. Some jobs require personality
+tests, logic tests and/or formal requirements to be answered by the user. Some
+jobs don't. The ``GuardEvent`` is used to decide what next steps are allowed for
+a specific application.
+
+By defining a workflow like this, there is an overview how the process looks
+like. The process logic is not mixed with the controllers, models or view. The
+order of the steps can be changed by changing the configuration only.
+
+State Machines
+--------------
+
+A state machine is a subset of a workflow and its purpose is to hold a state of
+your model. The most important differences between them are:
+
+* Workflows can be in more than one place at the same time, whereas state
+  machines can't;
+* Workflows usually don't have cyclic paths in the definition graph, but it's
+  common for state machines;
+* In order to apply a transition, workflows require that the object is in all
+  the previous places of the transition, whereas state machines only require
+  that the object is at least in one of those places.
+
+Example
+~~~~~~~
+
+A pull request starts in an initial "start" state, then a state "test" for e.g. running
+tests on continuous integration stack. When this is finished, the pull request is in the "review"
+state, where contributors can require changes, reject or accept the
+pull request. At any time, you can also "update" the pull request, which
+will result in another continuous integration run.
+
+.. image:: /_images/components/workflow/pull_request.png
+
+Below is the configuration for the pull request state machine.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/workflow.yaml
+        framework:
+            workflows:
+                pull_request:
+                    type: 'state_machine'
+                    supports:
+                        - App\Entity\PullRequest
+                    initial_marking: start
+                    places:
+                        - start
+                        - coding
+                        - test
+                        - review
+                        - merged
+                        - closed
+                    transitions:
+                        submit:
+                            from: start
+                            to: test
+                        update:
+                            from: [coding, test, review]
+                            to: test
+                        wait_for_review:
+                            from: test
+                            to: review
+                        request_change:
+                            from: review
+                            to: coding
+                        accept:
+                            from: review
+                            to: merged
+                        reject:
+                            from: review
+                            to: closed
+                        reopen:
+                            from: closed
+                            to: review
+
+    .. code-block:: xml
+
+        <!-- config/packages/workflow.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+
+            <framework:config>
+                <framework:workflow name="pull_request" type="state_machine">
+                    <framework:marking-store type="single_state"/>
+
+                    <framework:support>App\Entity\PullRequest</framework:support>
+
+                    <framework:place>start</framework:place>
+                    <framework:place>coding</framework:place>
+                    <framework:place>test</framework:place>
+                    <framework:place>review</framework:place>
+                    <framework:place>merged</framework:place>
+                    <framework:place>closed</framework:place>
+
+                    <framework:transition name="submit">
+                        <framework:from>start</framework:from>
+
+                        <framework:to>test</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="update">
+                        <framework:from>coding</framework:from>
+                        <framework:from>test</framework:from>
+                        <framework:from>review</framework:from>
+
+                        <framework:to>test</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="wait_for_review">
+                        <framework:from>test</framework:from>
+
+                        <framework:to>review</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="request_change">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>coding</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="accept">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>merged</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="reject">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>closed</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="reopen">
+                        <framework:from>closed</framework:from>
+
+                        <framework:to>review</framework:to>
+                    </framework:transition>
+
+                </framework:workflow>
+
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/workflow.php
+        $container->loadFromExtension('framework', [
+            // ...
+            'workflows' => [
+                'pull_request' => [
+                    'type' => 'state_machine',
+                    'supports' => ['App\Entity\PullRequest'],
+                    'places' => [
+                        'start',
+                        'coding',
+                        'test',
+                        'review',
+                        'merged',
+                        'closed',
+                    ],
+                    'transitions' => [
+                        'submit'=> [
+                            'from' => 'start',
+                            'to' => 'test',
+                        ],
+                        'update'=> [
+                            'from' => ['coding', 'test', 'review'],
+                            'to' => 'test',
+                        ],
+                        'wait_for_review'=> [
+                            'from' => 'test',
+                            'to' => 'review',
+                        ],
+                        'request_change'=> [
+                            'from' => 'review',
+                            'to' => 'coding',
+                        ],
+                        'accept'=> [
+                            'from' => 'review',
+                            'to' => 'merged',
+                        ],
+                        'reject'=> [
+                            'from' => 'review',
+                            'to' => 'closed',
+                        ],
+                        'reopen'=> [
+                            'from' => 'start',
+                            'to' => 'review',
+                        ],
+                    ],
+                ],
+            ],
+        ]);
+
+In a Symfony application using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+you can get this state machine by injecting the Workflow registry service::
+
+    // ...
+    use App\Entity\PullRequest;
+    use Symfony\Component\Workflow\Registry;
+
+    class SomeService
+    {
+        private $workflows;
+
+        public function __construct(Registry $workflows)
+        {
+            $this->workflows = $workflows;
+        }
+
+        public function someMethod(PullRequest $pullRequest)
+        {
+            $stateMachine = $this->workflows->get($pullRequest, 'pull_request');
+            $stateMachine->apply($pullRequest, 'wait_for_review');
+            // ...
+        }
+
+        // ...
+    }
+
+Symfony automatically creates a service for each workflow (:class:`Symfony\\Component\\Workflow\\Workflow`)
+or state machine (:class:`Symfony\\Component\\Workflow\\StateMachine`) you
+have defined in your configuration. This means that you can use ``workflow.pull_request``
+or ``state_machine.pull_request`` respectively in your service definitions
+to access the proper service::
+
+    // ...
+    use App\Entity\PullRequest;
+    use Symfony\Component\Workflow\StateMachine;
+
+    class SomeService
+    {
+        private $stateMachine;
+
+        public function __construct(StateMachine $stateMachine)
+        {
+            $this->stateMachine = $stateMachine;
+        }
+
+        public function someMethod(PullRequest $pullRequest)
+        {
+            $this->stateMachine->apply($pullRequest, 'wait_for_review', [
+                'log_comment' => 'My logging comment for the wait for review transition.',
+            ]);
+            // ...
+        }
+
+        // ...
+    }
+
+.. _`Petri nets`: https://en.wikipedia.org/wiki/Petri_net
diff --git a/workflow/state-machines.rst b/workflow/state-machines.rst
deleted file mode 100644
index 7dd0b651f93..00000000000
--- a/workflow/state-machines.rst
+++ /dev/null
@@ -1,218 +0,0 @@
-.. index::
-    single: Workflow; Workflows as State Machines
-
-Workflows as State Machines
-===========================
-
-The workflow component is modelled after a *Workflow net* which is a subclass
-of a `Petri net`_. By adding further restrictions you can get a state machine.
-The most important one being that a state machine cannot be in more than
-one place simultaneously. It is also worth noting that a workflow does not
-commonly have cyclic path in the definition graph, but it is common for a state
-machine.
-
-Example of a State Machine
---------------------------
-
-A pull request starts in an initial "start" state, a state for e.g. running
-tests on Travis. When this is finished, the pull request is in the "review"
-state, where contributors can require changes, reject or accept the
-pull request. At any time, you can also "update" the pull request, which
-will result in another Travis run.
-
-.. image:: /_images/components/workflow/pull_request.png
-
-Below is the configuration for the pull request state machine.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/workflow.yaml
-        framework:
-            workflows:
-                pull_request:
-                    type: 'state_machine'
-                    supports:
-                        - App\Entity\PullRequest
-                    initial_place: start
-                    places:
-                        - start
-                        - coding
-                        - travis
-                        - review
-                        - merged
-                        - closed
-                    transitions:
-                        submit:
-                            from: start
-                            to: travis
-                        update:
-                            from: [coding, travis, review]
-                            to: travis
-                        wait_for_review:
-                            from: travis
-                            to: review
-                        request_change:
-                            from: review
-                            to: coding
-                        accept:
-                            from: review
-                            to: merged
-                        reject:
-                            from: review
-                            to: closed
-                        reopen:
-                            from: closed
-                            to: review
-
-    .. code-block:: xml
-
-        <!-- config/packages/workflow.xml -->
-        <?xml version="1.0" encoding="utf-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
-        >
-
-            <framework:config>
-                <framework:workflow name="pull_request" type="state_machine">
-                    <framework:marking-store type="single_state"/>
-
-                    <framework:support>App\Entity\PullRequest</framework:support>
-
-                    <framework:place>start</framework:place>
-                    <framework:place>coding</framework:place>
-                    <framework:place>travis</framework:place>
-                    <framework:place>review</framework:place>
-                    <framework:place>merged</framework:place>
-                    <framework:place>closed</framework:place>
-
-                    <framework:transition name="submit">
-                        <framework:from>start</framework:from>
-
-                        <framework:to>travis</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="update">
-                        <framework:from>coding</framework:from>
-                        <framework:from>travis</framework:from>
-                        <framework:from>review</framework:from>
-
-                        <framework:to>travis</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="wait_for_review">
-                        <framework:from>travis</framework:from>
-
-                        <framework:to>review</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="request_change">
-                        <framework:from>review</framework:from>
-
-                        <framework:to>coding</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="accept">
-                        <framework:from>review</framework:from>
-
-                        <framework:to>merged</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="reject">
-                        <framework:from>review</framework:from>
-
-                        <framework:to>closed</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="reopen">
-                        <framework:from>closed</framework:from>
-
-                        <framework:to>review</framework:to>
-                    </framework:transition>
-
-                </framework:workflow>
-
-            </framework:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/workflow.php
-        $container->loadFromExtension('framework', [
-            // ...
-            'workflows' => [
-                'pull_request' => [
-                  'type' => 'state_machine',
-                  'supports' => ['App\Entity\PullRequest'],
-                  'places' => [
-                    'start',
-                    'coding',
-                    'travis',
-                    'review',
-                    'merged',
-                    'closed',
-                  ],
-                  'transitions' => [
-                    'submit'=> [
-                      'from' => 'start',
-                      'to' => 'travis',
-                    ],
-                    'update'=> [
-                      'from' => ['coding','travis','review'],
-                      'to' => 'travis',
-                    ],
-                    'wait_for_review'=> [
-                      'from' => 'travis',
-                      'to' => 'review',
-                    ],
-                    'request_change'=> [
-                      'from' => 'review',
-                      'to' => 'coding',
-                    ],
-                    'accept'=> [
-                      'from' => 'review',
-                      'to' => 'merged',
-                    ],
-                    'reject'=> [
-                      'from' => 'review',
-                      'to' => 'closed',
-                    ],
-                    'reopen'=> [
-                      'from' => 'start',
-                      'to' => 'review',
-                    ],
-                  ],
-                ],
-            ],
-        ]);
-
-In a Symfony application using the
-:ref:`default services.yaml configuration <service-container-services-load-example>`,
-you can get this state machine by injecting the Workflow registry service::
-
-    // ...
-    use Symfony\Component\Workflow\Registry;
-
-    class SomeService
-    {
-        private $workflows;
-
-        public function __construct(Registry $workflows)
-        {
-            $this->workflows = $workflows;
-        }
-
-        public function someMethod($subject)
-        {
-            $stateMachine = $this->workflows->get($subject, 'pull_request');
-            // ...
-        }
-
-        // ...
-    }
-
-.. _Petri net: https://en.wikipedia.org/wiki/Petri_net
diff --git a/workflow/usage.rst b/workflow/usage.rst
deleted file mode 100644
index 44451510ba1..00000000000
--- a/workflow/usage.rst
+++ /dev/null
@@ -1,477 +0,0 @@
-.. index::
-    single: Workflow; Usage
-
-How to Create and Use Workflows
-===============================
-
-Installation
-------------
-
-In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
-install the workflow feature before using it:
-
-.. code-block:: terminal
-
-    $ composer require symfony/workflow
-
-Creating a Workflow
--------------------
-
-A workflow is a process or a lifecycle that your objects go through. Each
-step or stage in the process is called a *place*. You do also define *transitions*
-to that describes the action to get from one place to another.
-
-.. image:: /_images/components/workflow/states_transitions.png
-
-A set of places and transitions creates a **definition**. A workflow needs
-a ``Definition`` and a way to write the states to the objects (i.e. an
-instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`.)
-
-Consider the following example for a blog post that can have these places:
-``draft``, ``review``, ``rejected``, ``published``. You can define the workflow
-like this:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/workflow.yaml
-        framework:
-            workflows:
-                blog_publishing:
-                    type: 'workflow' # or 'state_machine'
-                    audit_trail:
-                        enabled: true
-                    marking_store:
-                        type: 'multiple_state' # or 'single_state'
-                        arguments:
-                            - 'currentPlace'
-                    supports:
-                        - App\Entity\BlogPost
-                    initial_place: draft
-                    places:
-                        - draft
-                        - review
-                        - rejected
-                        - published
-                    transitions:
-                        to_review:
-                            from: draft
-                            to:   review
-                        publish:
-                            from: review
-                            to:   published
-                        reject:
-                            from: review
-                            to:   rejected
-
-    .. code-block:: xml
-
-        <!-- config/packages/workflow.xml -->
-        <?xml version="1.0" encoding="utf-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
-        >
-
-            <framework:config>
-                <framework:workflow name="blog_publishing" type="workflow">
-                    <framework:audit-trail enabled="true" />
-
-                    <framework:marking-store type="single_state">
-                      <framework:argument>currentPlace</framework:argument>
-                    </framework:marking-store>
-
-                    <framework:support>App\Entity\BlogPost</framework:support>
-
-                    <framework:place>draft</framework:place>
-                    <framework:place>review</framework:place>
-                    <framework:place>rejected</framework:place>
-                    <framework:place>published</framework:place>
-
-                    <framework:transition name="to_review">
-                        <framework:from>draft</framework:from>
-
-                        <framework:to>review</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="publish">
-                        <framework:from>review</framework:from>
-
-                        <framework:to>published</framework:to>
-                    </framework:transition>
-
-                    <framework:transition name="reject">
-                        <framework:from>review</framework:from>
-
-                        <framework:to>rejected</framework:to>
-                    </framework:transition>
-
-                </framework:workflow>
-
-            </framework:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/workflow.php
-
-        $container->loadFromExtension('framework', [
-            // ...
-            'workflows' => [
-                'blog_publishing' => [
-                    'type' => 'workflow', // or 'state_machine'
-                    'audit_trail' => [
-                        'enabled' => true
-                    ],
-                    'marking_store' => [
-                        'type' => 'multiple_state', // or 'single_state'
-                        'arguments' => ['currentPlace'],
-                    ),
-                    'supports' => ['App\Entity\BlogPost'],
-                    'places' => [
-                        'draft',
-                        'review',
-                        'rejected',
-                        'published',
-                    ],
-                    'transitions' => [
-                        'to_review' => [
-                            'from' => 'draft',
-                            'to' => 'review',
-                        ],
-                        'publish' => [
-                            'from' => 'review',
-                            'to' => 'published',
-                        ],
-                        'reject' => [
-                            'from' => 'review',
-                            'to' => 'rejected',
-                        ],
-                    ],
-                ],
-            ],
-        ]);
-
-.. code-block:: php
-
-    class BlogPost
-    {
-        // This property is used by the marking store
-        public $currentPlace;
-        public $title;
-        public $content;
-    }
-
-.. note::
-
-    The marking store type could be "multiple_state" or "single_state".
-    A single state marking store does not support a model being on multiple places
-    at the same time.
-
-.. tip::
-
-    The ``type`` (default value ``single_state``) and ``arguments`` (default
-    value ``marking``) attributes of the ``marking_store`` option are optional.
-    If omitted, their default values will be used.
-
-.. tip::
-
-    Setting the ``audit_trail.enabled`` option to ``true`` makes the application
-    generate detailed log messages for the workflow activity.
-
-Using a Workflow
-----------------
-
-Once the ``blog_publishing`` workflow has been created, you can now use it to
-decide what actions are allowed on a blog post. For example, inside a controller
-of an application using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-you can get the workflow by injecting the Workflow registry service::
-
-    // ...
-    use Symfony\Component\Workflow\Registry;
-    use App\Entity\BlogPost;
-    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-    use Symfony\Component\Workflow\Exception\TransitionException;
-
-    class BlogController extends AbstractController
-    {
-        public function edit(Registry $workflows)
-        {
-            $post = new BlogPost();
-            $workflow = $workflows->get($post);
-
-            // if there are multiple workflows for the same class,
-            // pass the workflow name as the second argument
-            // $workflow = $workflows->get($post, 'blog_publishing');
-
-            // you can also get all workflows associated with an object, which is useful
-            // for example to show the status of all those workflows in a backend
-            $postWorkflows = $workflows->all($post);
-
-            $workflow->can($post, 'publish'); // False
-            $workflow->can($post, 'to_review'); // True
-
-            // Update the currentState on the post
-            try {
-                $workflow->apply($post, 'to_review');
-            } catch (TransitionException $exception) {
-                // ... if the transition is not allowed
-            }
-
-            // See all the available transitions for the post in the current state
-            $transitions = $workflow->getEnabledTransitions($post);
-        }
-    }
-
-.. versionadded:: 4.1
-    The :class:`Symfony\\Component\\Workflow\\Exception\\TransitionException`
-    class was introduced in Symfony 4.1.
-
-.. versionadded:: 4.1
-    The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
-    introduced in Symfony 4.1.
-
-Using Events
-------------
-
-To make your workflows more flexible, you can construct the ``Workflow``
-object with an ``EventDispatcher``. You can now create event listeners to
-block transitions (i.e. depending on the data in the blog post) and do
-additional actions when a workflow operation happened (e.g. sending
-announcements).
-
-Each step has three events that are fired in order:
-
-* An event for every workflow;
-* An event for the workflow concerned;
-* An event for the workflow concerned with the specific transition or place name.
-
-When a state transition is initiated, the events are dispatched in the following
-order:
-
-``workflow.guard``
-    Validate whether the transition is allowed at all (:ref:`see below <workflow-usage-guard-events>`).
-
-    The three events being dispatched are:
-
-    * ``workflow.guard``
-    * ``workflow.[workflow name].guard``
-    * ``workflow.[workflow name].guard.[transition name]``
-
-``workflow.leave``
-    The subject is about to leave a place.
-
-    The three events being dispatched are:
-
-    * ``workflow.leave``
-    * ``workflow.[workflow name].leave``
-    * ``workflow.[workflow name].leave.[place name]``
-
-``workflow.transition``
-    The subject is going through this transition.
-
-    The three events being dispatched are:
-
-    * ``workflow.transition``
-    * ``workflow.[workflow name].transition``
-    * ``workflow.[workflow name].transition.[transition name]``
-
-``workflow.enter``
-    The subject is about to enter a new place. This event is triggered just
-    before the subject places are updated, which means that the marking of the
-    subject is not yet updated with the new places.
-
-    The three events being dispatched are:
-
-    * ``workflow.enter``
-    * ``workflow.[workflow name].enter``
-    * ``workflow.[workflow name].enter.[place name]``
-
-``workflow.entered``
-    The subject has entered in the places and the marking is updated (making it a good
-    place to flush data in Doctrine).
-
-    The three events being dispatched are:
-
-    * ``workflow.entered``
-    * ``workflow.[workflow name].entered``
-    * ``workflow.[workflow name].entered.[place name]``
-
-``workflow.completed``
-    The object has completed this transition.
-
-    The three events being dispatched are:
-
-    * ``workflow.completed``
-    * ``workflow.[workflow name].completed``
-    * ``workflow.[workflow name].completed.[transition name]``
-
-
-``workflow.announce``
-    Triggered for each transition that now is accessible for the subject.
-
-    The three events being dispatched are:
-
-    * ``workflow.announce``
-    * ``workflow.[workflow name].announce``
-    * ``workflow.[workflow name].announce.[transition name]``
-
-.. note::
-
-    The leaving and entering events are triggered even for transitions that stay
-    in same place.
-
-Here is an example of how to enable logging for every time the ``blog_publishing``
-workflow leaves a place::
-
-    use Psr\Log\LoggerInterface;
-    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-    use Symfony\Component\Workflow\Event\Event;
-
-    class WorkflowLogger implements EventSubscriberInterface
-    {
-        public function __construct(LoggerInterface $logger)
-        {
-            $this->logger = $logger;
-        }
-
-        public function onLeave(Event $event)
-        {
-            $this->logger->alert(sprintf(
-                'Blog post (id: "%s") performed transaction "%s" from "%s" to "%s"',
-                $event->getSubject()->getId(),
-                $event->getTransition()->getName(),
-                implode(', ', array_keys($event->getMarking()->getPlaces())),
-                implode(', ', $event->getTransition()->getTos())
-            ));
-        }
-
-        public static function getSubscribedEvents()
-        {
-            return [
-                'workflow.blog_publishing.leave' => 'onLeave',
-            ];
-        }
-    }
-
-.. _workflow-usage-guard-events:
-
-Guard Events
-~~~~~~~~~~~~
-
-There are a special kind of events called "Guard events". Their event listeners
-are invoked every time a call to ``Workflow::can``, ``Workflow::apply`` or
-``Workflow::getEnabledTransitions`` is executed. With the guard events you may
-add custom logic to decide what transitions that are valid or not. Here is a list
-of the guard event names.
-
-* ``workflow.guard``
-* ``workflow.[workflow name].guard``
-* ``workflow.[workflow name].guard.[transition name]``
-
-See example to make sure no blog post without title is moved to "review"::
-
-    use Symfony\Component\Workflow\Event\GuardEvent;
-    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-
-    class BlogPostReviewListener implements EventSubscriberInterface
-    {
-        public function guardReview(GuardEvent $event)
-        {
-            /** @var \App\Entity\BlogPost $post */
-            $post = $event->getSubject();
-            $title = $post->title;
-
-            if (empty($title)) {
-                // Posts with no title should not be allowed
-                $event->setBlocked(true);
-            }
-        }
-
-        public static function getSubscribedEvents()
-        {
-            return [
-                'workflow.blogpost.guard.to_review' => ['guardReview'],
-            ];
-        }
-    }
-
-Event Methods
-~~~~~~~~~~~~~
-
-Each workflow event is an instance of :class:`Symfony\\Component\\Workflow\\Event\\Event`.
-This means that each event has access to the following information:
-
-:method:`Symfony\\Component\\Workflow\\Event\\Event::getMarking`
-    Returns the :class:`Symfony\\Component\\Workflow\\Marking` of the workflow.
-
-:method:`Symfony\\Component\\Workflow\\Event\\Event::getSubject`
-    Returns the object that dispatches the event.
-
-:method:`Symfony\\Component\\Workflow\\Event\\Event::getTransition`
-    Returns the :class:`Symfony\\Component\\Workflow\\Transition` that dispatches the event.
-
-:method:`Symfony\\Component\\Workflow\\Event\\Event::getWorkflowName`
-    Returns a string with the name of the workflow that triggered the event.
-
-For Guard Events, there is an extended class :class:`Symfony\\Component\\Workflow\\Event\\GuardEvent`.
-This class has two more methods:
-
-:method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::isBlocked`
-    Returns if transition is blocked.
-
-:method:`Symfony\\Component\\Workflow\\Event\\GuardEvent::setBlocked`
-    Sets the blocked value.
-
-Usage in Twig
--------------
-
-Symfony defines several Twig functions to manage workflows and reduce the need
-of domain logic in your templates:
-
-``workflow_can()``
-    Returns ``true`` if the given object can make the given transition.
-
-``workflow_transitions()``
-    Returns an array with all the transitions enabled for the given object.
-
-``workflow_marked_places()``
-    Returns an array with the place names of the given marking.
-
-``workflow_has_marked_place()``
-    Returns ``true`` if the marking of the given object has the given state.
-
-The following example shows these functions in action:
-
-.. code-block:: twig
-
-    <h3>Actions</h3>
-    {% if workflow_can(post, 'publish') %}
-        <a href="...">Publish article</a>
-    {% endif %}
-    {% if workflow_can(post, 'to_review') %}
-        <a href="...">Submit to review</a>
-    {% endif %}
-    {% if workflow_can(post, 'reject') %}
-        <a href="...">Reject article</a>
-    {% endif %}
-
-    {# Or loop through the enabled transitions #}
-    {% for transition in workflow_transitions(post) %}
-        <a href="...">{{ transition.name }}</a>
-    {% else %}
-        No actions available.
-    {% endfor %}
-
-    {# Check if the object is in some specific place #}
-    {% if workflow_has_marked_place(post, 'review') %}
-        <p>This post is ready for review.</p>
-    {% endif %}
-
-    {# Check if some place has been marked on the object #}
-    {% if 'waiting_some_approval' in workflow_marked_places(post) %}
-        <span class="label">PENDING</span>
-    {% endif %}