Merge branch '5.4' into 6.0

* 5.4:
  Restore a reference to a section
  Correct spelling & grammar in 4.4 components/
  Correct spelling & grammar in 4.4. contributing/
  Correct spelling & grammar in 4.4 reference/
  Correct spelling & grammar in 4.4 messenger.rst
  Correct spelling & grammar in 4.4. frontend.rst
  Correct spelling & grammar in 4.4 forms.rst
  Correct spelling & grammar in 4.4 event_dispatcher.rst
  Correct spelling & grammar in 4.4 email.rst
  Correct spelling & grammar in 4.4 CODE_OF_CONDUCT.md
  Correct spelling & grammar in 4.4 cache.rst
  Correct spelling & grammar in 4.4 best-practices.rst
  Correct spelling & grammar in 4.4 security.rst

Author: javiereguiluz

CODE_OF_CONDUCT.md

@@ -52,7 +52,7 @@ 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
+representing a project or community include using an official project email
 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.

best_practices.rst

@@ -269,7 +269,7 @@ Templates
 Use Snake Case for Template Names and Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use lowercased snake_case for template names, directories and variables (e.g.
+Use lowercase snake_case for template names, directories and variables (e.g.
 ``user_profile`` instead of ``userProfile`` and ``product/edit_form.html.twig``
 instead of ``Product/EditForm.html.twig``).
 
@@ -387,7 +387,7 @@ Use Webpack Encore to Process Web Assets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Web assets are things like CSS, JavaScript and image files that make the
-frontend of your site look and work great. `Webpack`_ is the leading JavaScript
+frontend of your site looks and works great. `Webpack`_ is the leading JavaScript
 module bundler that compiles, transforms and packages assets for usage in a browser.
 
 :doc:`Webpack Encore </frontend>` is a JavaScript library that gets rid of most
@@ -439,7 +439,9 @@ Add this test while creating your application because it requires little effort
 and checks that none of your pages returns an error. Later, you'll add more
 specific tests for each page.
 
-Hardcode URLs in a Functional Test
+.. _hardcode-urls-in-a-functional-test:
+
+Hard-code URLs in a Functional Test
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In Symfony applications, it's recommended to :ref:`generate URLs <routing-generating-urls>`

cache.rst

@@ -45,7 +45,7 @@ of:
     An adapter is a *template* that you use to create pools.
 **Provider**
     A provider is a service that some adapters use to connect to the storage.
-    Redis and Memcached are example of such adapters. If a DSN is used as the
+    Redis and Memcached are examples 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

components/asset.rst

@@ -8,7 +8,7 @@ The Asset Component
     The Asset component manages URL generation and versioning of web assets such
     as CSS stylesheets, JavaScript files and image files.
 
-In the past, it was common for web applications to hardcode URLs of web assets.
+In the past, it was common for web applications to hard-code the URLs of web assets.
 For example:
 
 .. code-block:: html
@@ -387,7 +387,7 @@ they all have different base paths::
     $packages = new Packages($defaultPackage, $namedPackages);
 
 The ``Packages`` class allows to define a default package, which will be applied
-to assets that don't define the name of package to use. In addition, this
+to assets that don't define the name of the package to use. In addition, this
 application defines a package named ``img`` to serve images from an external
 domain and a ``doc`` package to avoid repeating long paths when linking to a
 document inside a template::

components/http_kernel.rst

@@ -249,7 +249,7 @@ on the request's information.
 
     The Symfony Framework uses the built-in
     :class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolver`
-    class (actually, it uses a sub-class with some extra functionality
+    class (actually, it uses a subclass with some extra functionality
     mentioned below). This class leverages the information that was placed
     on the ``Request`` object's ``attributes`` property during the ``RouterListener``.
 
@@ -358,7 +358,7 @@ of arguments that should be passed when executing that callable.
 5) Calling the Controller
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The next step ``HttpKernel::handle()`` does is executing the controller.
+The next step of ``HttpKernel::handle()`` is executing the controller.
 
 The job of the controller is to build the response for the given resource.
 This could be an HTML page, a JSON string or anything else. Unlike every
@@ -590,7 +590,7 @@ on creating and attaching event listeners, see :doc:`/components/event_dispatche
 
 The name of each of the "kernel" events is defined as a constant on the
 :class:`Symfony\\Component\\HttpKernel\\KernelEvents` class. Additionally, each
-event listener is passed a single argument, which is some sub-class of :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`.
+event listener is passed a single argument, which is some subclass of :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`.
 This object contains information about the current state of the system and
 each event has their own event object:
 
@@ -667,7 +667,7 @@ Sub Requests
 ------------
 
 In addition to the "main" request that's sent into ``HttpKernel::handle()``,
-you can also send so-called "sub request". A sub request looks and acts like
+you can also send a so-called "sub request". A sub request looks and acts like
 any other request, but typically serves to render just one small portion of
 a page instead of a full page. You'll most commonly make sub-requests from
 your controller (or perhaps from inside a template, that's being rendered by
@@ -696,9 +696,9 @@ argument as follows::
 This creates another full request-response cycle where this new ``Request`` is
 transformed into a ``Response``. The only difference internally is that some
 listeners (e.g. security) may only act upon the main request. Each listener
-is passed some sub-class of :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`,
+is passed some subclass of :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`,
 whose :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::isMainRequest`
-can be used to check if the current request is a "main" or "sub" request.
+method can be used to check if the current request is a "main" or "sub" request.
 
 For example, a listener that only needs to act on the main request may
 look like this::

components/lock.rst

@@ -46,7 +46,7 @@ method will try to acquire the lock::
 
     if ($lock->acquire()) {
         // The resource "pdf-invoice-generation" is locked.
-        // You can compute and generate invoice safely here.
+        // You can compute and generate the invoice safely here.
 
         $lock->release();
     }
@@ -65,7 +65,7 @@ method can be safely called repeatedly, even if the lock is already acquired.
 .. tip::
 
     If you don't release the lock explicitly, it will be released automatically
-    on instance destruction. In some cases, it can be useful to lock a resource
+    upon instance destruction. In some cases, it can be useful to lock a resource
     across several requests. To disable the automatic release behavior, set the
     third argument of the ``createLock()`` method to ``false``.
 
@@ -74,7 +74,7 @@ Serializing Locks
 
 The ``Key`` contains the state of the ``Lock`` and can be serialized. This
 allows the user to begin a long job in a process by acquiring the lock, and
-continue the job in an other process using the same lock::
+continue the job in another process using the same lock::
 
     use Symfony\Component\Lock\Key;
     use Symfony\Component\Lock\Lock;
@@ -205,7 +205,7 @@ as seconds) and ``isExpired()`` (which returns a boolean).
 Automatically Releasing The Lock
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Lock are automatically released when their Lock objects are destructed. This is
+Locks are automatically released when their Lock objects are destructed. This is
 an implementation detail that will be important when sharing Locks between
 processes. In the example below, ``pcntl_fork()`` creates two processes and the
 Lock will be released automatically as soon as one process finishes::
@@ -670,11 +670,11 @@ FlockStore
 ~~~~~~~~~~
 
 By using the file system, this ``Store`` is reliable as long as concurrent
-processes use the same physical directory to stores locks.
+processes use the same physical directory to store locks.
 
 Processes must run on the same machine, virtual machine or container.
-Be careful when updating a Kubernetes or Swarm service because for a short
-period of time, there can be two running containers in parallel.
+Be careful when updating a Kubernetes or Swarm service because, for a short
+period of time, there can be two containers running in parallel.
 
 The absolute path to the directory must remain the same. Be careful of symlinks
 that could change at anytime: Capistrano and blue/green deployment often use
@@ -686,7 +686,7 @@ Some file systems (such as some types of NFS) do not support locking.
 .. caution::
 
     All concurrent processes must use the same physical file system by running
-    on the same machine and using the same absolute path to locks directory.
+    on the same machine and using the same absolute path to the lock directory.
 
     By definition, usage of ``FlockStore`` in an HTTP context is incompatible
     with multiple front servers, unless to ensure that the same resource will
@@ -708,7 +708,7 @@ MemcachedStore
 
 The way Memcached works is to store items in memory. That means that by using
 the :ref:`MemcachedStore <lock-store-memcached>` the locks are not persisted
-and may disappear by mistake at anytime.
+and may disappear by mistake at any time.
 
 If the Memcached service or the machine hosting it restarts, every lock would
 be lost without notifying the running processes.
@@ -785,7 +785,7 @@ 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.
+    synchronously propagated to every node, or always use the same node.
 
 .. caution::
 
@@ -820,7 +820,7 @@ RedisStore
 
 The way Redis works is to store items in memory. That means that by using
 the :ref:`RedisStore <lock-store-redis>` the locks are not persisted
-and may disappear by mistake at anytime.
+and may disappear by mistake at any time.
 
 If the Redis service or the machine hosting it restarts, every locks would
 be lost without notifying the running processes.
@@ -847,7 +847,7 @@ removed by mistake.
 CombinedStore
 ~~~~~~~~~~~~~
 
-Combined stores allow to store locks across several backends. It's a common
+Combined stores allow the storage of locks across several backends. It's a common
 mistake to think that the lock mechanism will be more reliable. This is wrong.
 The ``CombinedStore`` will be, at best, as reliable as the least reliable of
 all managed stores. As soon as one managed store returns erroneous information,

components/mime.rst

@@ -34,7 +34,7 @@ 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.
+  to have absolute control over every single part of the email message.
 
 Usage
 -----
@@ -56,7 +56,7 @@ methods to compose the entire email message::
         ->html('<h1>Lorem ipsum</h1> <p>...</p>')
     ;
 
-This only purpose of this component is to create the email messages. Use the
+The only purpose of this component is to create the email messages. Use the
 :doc:`Mailer component </mailer>` to actually send them.
 
 Twig Integration

components/options_resolver.rst

@@ -451,8 +451,8 @@ 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`.
+To normalize a new allowed value in subclasses that are being normalized
+in parent classes, use :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addNormalizer` method.
 This way, the ``$value`` argument will receive the previously normalized
 value, otherwise you can prepend the new normalizer by passing ``true`` as
 third argument.
@@ -465,7 +465,7 @@ encryption chosen by the user of the ``Mailer`` class. More precisely, you want
 to set the port to ``465`` if SSL is used and to ``25`` otherwise.
 
 You can implement this feature by passing a closure as the default value of
-the ``port`` option. The closure receives the options as argument. Based on
+the ``port`` option. The closure receives the options as arguments. Based on
 these options, you can return the desired default value::
 
     use Symfony\Component\OptionsResolver\Options;
@@ -497,7 +497,7 @@ these options, you can return the desired default value::
 .. note::
 
     The closure is only executed if the ``port`` option isn't set by the user
-    or overwritten in a sub-class.
+    or overwritten in a subclass.
 
 A previously set default value can be accessed by adding a second argument to
 the closure::

components/process.rst

@@ -116,7 +116,7 @@ You can configure the options passed to the ``other_options`` argument of
 Using Features From the OS Shell
 --------------------------------
 
-Using array of arguments is the recommended way to define commands. This
+Using an 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 while they run)::
 
@@ -327,7 +327,7 @@ provides the :class:`Symfony\\Component\\Process\\InputStream` class::
     echo $process->getOutput();
 
 The :method:`Symfony\\Component\\Process\\InputStream::write` method accepts scalars,
-stream resources or ``Traversable`` objects as argument. As shown in the above example,
+stream resources or ``Traversable`` objects as arguments. As shown in the above example,
 you need to explicitly call the :method:`Symfony\\Component\\Process\\InputStream::close`
 method when you are done writing to the standard input of the subprocess.
 

components/property_access.rst

@@ -399,7 +399,7 @@ properties through *adder* and *remover* methods::
 The PropertyAccess component checks for methods called ``add<SingularOfThePropertyName>()``
 and ``remove<SingularOfThePropertyName>()``. Both methods must be defined.
 For instance, in the previous example, the component looks for the ``addChild()``
-and ``removeChild()`` methods to access to the ``children`` property.
+and ``removeChild()`` methods to access the ``children`` property.
 `The String component`_ inflector is used to find the singular of a property name.
 
 If available, *adder* and *remover* methods have priority over a *setter* method.

components/property_info.rst

@@ -208,7 +208,7 @@ strings::
         Example Result
         --------------
         string(79):
-            These is the subsequent paragraph in the DocComment.
+            This is the subsequent paragraph in the DocComment.
             It can span multiple lines.
     */
 

components/serializer.rst

@@ -603,7 +603,7 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`::
 
     You can also implement
     :class:`Symfony\\Component\\Serializer\\NameConverter\\AdvancedNameConverterInterface`
-    to access to the current class name, format and context.
+    to access the current class name, format and context.
 
 .. _using-camelized-method-names-for-underscored-attributes:
 

components/var_exporter.rst

@@ -118,7 +118,7 @@ any other methods::
 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.
+    // Creates an SplObjectHash where $info1 is associated with $object1, etc.
     $theObject = Instantiator::instantiate(SplObjectStorage::class, [
         "\0" => [$object1, $info1, $object2, $info2...],
     ]);

contributing/code/bc.rst

@@ -10,7 +10,7 @@ may introduce new features, but must do so without breaking the existing API of
 that release branch (5.x in the previous example).
 
 We also provide deprecation message triggered in the code base to help you with
-the migration process across major release.
+the migration process across major releases.
 
 .. caution::
 

contributing/code/core_team.rst

@@ -171,7 +171,7 @@ The **Project Leader** is also the release manager for every Symfony version.
 Symfony Core Rules and Protocol Amendments
 ------------------------------------------
 
-The rules described in this document may be amended at anytime at the
+The rules described in this document may be amended at any time at the
 discretion of the **Project Leader**.
 
 .. [1] Minor changes comprise typos, DocBlock fixes, code standards

contributing/code/maintenance.rst

@@ -74,7 +74,7 @@ are never accepted in a patch version:
 .. note::
 
     This policy is designed to enable a continuous upgrade path that allows one
-    to move forward with newest Symfony versions in the safest way. One should
+    to move forward with the newest Symfony versions in the safest way. One should
     be able to move PHP versions, OS or Symfony versions almost independently.
     That's the reason why supporting the latest PHP versions or OS features is
     considered as bug fixes.

contributing/code/stack_trace.rst

@@ -56,7 +56,7 @@ things for you beforehand, like routing or access control.
 Symfony being both a framework and library of components, it calls your
 code and then your code might call it. This means you will always have
 at least 2 parts, very often 3 in your stack traces when using Symfony:
-a part that starts in one of the entrypoints of the framework
+a part that starts in one of the entry points of the framework
 (``bin/console`` or ``public/index.php`` in most cases), and ends when
 reaching your code, most times in a command or in a controller found under
 ``src``. Then, either the exception is thrown in your code or in
@@ -75,7 +75,7 @@ Next, you can have a look at what packages are involved. Files under
 library and ``acme/router`` the Composer package. If you plan on
 reporting the bug, make sure to report it to the library throwing the
 exception. ``composer home acme/router`` should lead you to the right
-place for that. As Symfony is a monorepository, use ``composer home
+place for that. As Symfony is a mono-repository, use ``composer home
 symfony/symfony`` when reporting a bug for any component.
 
 Getting Stack Traces with Symfony
@@ -92,7 +92,7 @@ from your development environment through a web browser:
 
 1. Are there several exceptions? If yes, the most interesting one is
    often exception 1/n which, is shown *last* in the example below (it
-   is the one marked as exception [1/2]).
+   is the one marked as an exception [1/2]).
 2. Under the "Stack Traces" tab, you will find exceptions in plain
    text, so that you can easily share them in e.g. bug reports. Make
    sure to **remove any sensitive information** before doing so.
@@ -109,7 +109,7 @@ Since stack traces may contain sensitive data, they should not be
 exposed in production. Getting a stack trace from your production
 environment, although more involving, is still possible with solutions
 that include but are not limited to sending them to an email address
-with monolog.
+with Monolog.
 
 Stack Traces in the CLI
 ~~~~~~~~~~~~~~~~~~~~~~~

contributing/code/standards.rst

@@ -78,7 +78,7 @@ short example containing most features described below::
         }
 
         /**
-         * Transforms the input given as first argument.
+         * Transforms the input given as the first argument.
          *
          * @param bool|string $dummy   Some argument description
          * @param array       $options An options collection to be used within the transformation

contributing/code_of_conduct/code_of_conduct.rst

@@ -53,7 +53,7 @@ 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
+representing a project or community include using an official project email
 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.