Merge branch '4.4' into 5.0

* 4.4:
  Update http_authentication.rst
  Update routing.rst
  Update routing.rst
  Update mailer.rst
  Update messenger.rst
  Reference method
  Update form.rst
  Use valid versionj in maintainer guide. refs #13175
  [DependencyInjection] Fixed public service use case
  fixup
  tweak #13099
  Use valid version in maintainer guide
  Mention region parameter for Mailgun mailer too
  Update service_subscribers_locators.rst

Author: OskarStark

_build/maintainer_guide.rst

@@ -134,9 +134,9 @@ original contributor.
     $ cd symfony-docs/
 
     # make sure that your local branch is updated
-    $ git checkout 3.4
+    $ git checkout 4.4
     $ git fetch upstream
-    $ git merge upstream/3.4
+    $ git merge upstream/4.4
 
     # merge any PR passing its GitHub number as argument
     $ gh merge 11159
@@ -153,20 +153,20 @@ 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
+    # e.g. this PR was sent against 'master', but it's merged in '4.4'
+    $ gh merge 11160 -s 4.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
+    $ gh merge 11160 -s 4.4
 
       ...
 
       Unable to rebase the patch for <comment>pull/11183</comment>
-      The command "'git' 'rebase' '--onto' '3.4' '4.2' 'pull/11160'" failed.
+      The command "'git' 'rebase' '--onto' '4.4' '5.0' 'pull/11160'" failed.
       Exit Code: 128(Invalid exit argument)
 
       [...]
@@ -183,7 +183,7 @@ usually simple to fix:
 
     # 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
+    $ gh merge 11160 -s 4.4
 
       The previous run had some conflicts. Do you want to resume the merge? (Y/n)
 
@@ -195,29 +195,29 @@ 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``:
+``4.4`` and the maintained branches are ``4.4``, ``5.0`` and ``master``:
 
 .. code-block:: terminal
 
     $ git fetch upstream
 
-    $ git checkout 3.4
-    $ git merge upstream/3.4
+    $ git checkout 4.4
+    $ git merge upstream/4.4
 
     $ gh merge 11159
     $ git push origin
     $ git push upstream
 
-    $ git checkout 4.2
-    $ git merge upstream/4.2
-    $ git merge --log 3.4
+    $ git checkout 5.0
+    $ git merge upstream/5.0
+    $ git merge --log 4.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 merge --log 5.0
     $ git push origin
     $ git push upstream
 
@@ -247,26 +247,26 @@ When updating your local branches before merging:
 .. code-block:: terminal
 
     $ git fetch upstream
-    $ git checkout 3.4
-    $ git merge upstream/3.4
+    $ git checkout 4.4
+    $ git merge upstream/4.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
+    $ git checkout 4.4
+    $ git merge upstream/5.0
 
 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
+    $ git branch -D 4.4
+    $ git checkout 4.4 upstream/4.4
 
 If you did push the wrong branch merge, ask for help in the documentation
 mergers chat and we'll help solve the problem.
@@ -278,9 +278,9 @@ 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
+    $ git checkout 5.0
+    $ git merge upstream/5.0
+    $ git merge --log 4.4
 
       Auto-merging security/entity_provider.rst
       Auto-merging logging/monolog_console.rst
@@ -314,13 +314,13 @@ 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
+    $ git checkout 5.0
+    $ git merge upstream/5.0
+    $ git merge --log 4.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.
+      modified in 4.4. Version 4.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

components/form.rst

@@ -535,7 +535,7 @@ Changing a Form's Method and Action
 By default, a form is submitted to the same URI that rendered the form with
 an HTTP POST request. This behavior can be changed using the :ref:`form-option-action`
 and :ref:`form-option-method` options (the ``method`` option is also used
-by ``handleRequest()`` to determine whether a form has been submitted):
+by :method:`Symfony\\Component\\Form\\Form::handleRequest` to determine whether a form has been submitted):
 
 .. configuration-block::
 
@@ -651,15 +651,15 @@ This defines a common form "workflow", which contains 3 different possibilities:
 1) On the initial GET request (i.e. when the user "surfs" to your page),
    build your form and render it;
 
-If the request is a POST, process the submitted data (via ``handleRequest()``).
+If the request is a POST, process the submitted data (via :method:`Symfony\\Component\\Form\\Form::handleRequest`).
 Then:
 
 2) if the form is invalid, re-render the form (which will now contain errors);
 3) if the form is valid, perform some action and redirect.
 
 Luckily, you don't need to decide whether or not a form has been submitted.
-Pass the current request to the ``handleRequest()`` method. Then, the Form
-component will do all the necessary work for you.
+Just pass the current request to the :method:`Symfony\\Component\\Form\\Form::handleRequest`
+method. Then, the Form component will do all the necessary work for you.
 
 .. _component-form-intro-validation:
 

mailer.rst

@@ -74,7 +74,7 @@ The *only* part you need to change is to replace ``KEY`` in the ``MAILER_DSN`` (
 Each provider has different environment variables that the Mailer uses to
 configure the *actual* protocol, address and authentication for delivery. Some
 also have options that can be configured with query parameters at the end of the
-``MAILER_DSN`` - like ``?region=`` for Amazon SES. Some providers support
+``MAILER_DSN`` - like ``?region=`` for Amazon SES or Mailgun. Some providers support
 sending via ``http``, ``api`` or ``smtp``. Symfony chooses the best available
 transport, but you can force to use one:
 
@@ -562,7 +562,7 @@ encrypt a signed message and/or to sign an encrypted message.
 Before signing/encrypting messages, make sure to have:
 
 * The `OpenSSL PHP extension`_ properly installed and configured;
-* A valid S/MIME security certificate.
+* A valid `S/MIME`_ security certificate.
 
 Signing Messages
 ~~~~~~~~~~~~~~~~

messenger.rst

@@ -17,7 +17,7 @@ install messenger:
 
 .. code-block:: terminal
 
-    $ composer require messenger
+    $ composer require symfony/messenger
 
 Creating a Message & Handler
 ----------------------------
@@ -321,6 +321,9 @@ If you need to pass a Doctrine entity in a message, it's better to pass the enti
 primary key (or whatever relevant information the handler actually needs, like ``email``,
 etc) instead of the object::
 
+    // src/Message/NewUserWelcomeEmail.php
+    namespace App\Message;
+    
     class NewUserWelcomeEmail
     {
         private $userId;

routing.rst

@@ -34,10 +34,14 @@ following configuration file:
 
 .. code-block:: yaml
 
-    # config/routes.yaml
+    # config/routes/annotations.yaml
     controllers:
-        resource: '../src/Controller/'
-        type:     annotation
+        resource: '../../src/Controller/'
+        type: annotation
+        
+    kernel:
+        resource: ../../src/Kernel.php
+        type: annotation
 
 This configuration tells Symfony to look for routes defined as annotations in
 any PHP class stored in the ``src/Controller/`` directory.
@@ -1946,6 +1950,9 @@ This information can be configured per command too::
     // src/Command/SomeCommand.php
     namespace App\Command;
 
+    use Symfony\Component\Console\Command\Command;
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
     use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
     use Symfony\Component\Routing\RouterInterface;
     // ...

service_container.rst

@@ -807,20 +807,35 @@ Public Versus Private Services
 From Symfony 4.0, every service defined is private by default.
 
 What does this mean? When a service **is** public, you can access it directly
-from the container object, which is accessible from any controller that extends
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`::
+from the container object, which can also be injected thanks to autowiring.
+This is mostly useful when you want to fetch services lazily::
 
-    use App\Service\MessageGenerator;
+    namespace App\Generator;
 
-    // ...
-    public function new()
+    use Psr\Container\ContainerInterface;
+
+    class MessageGenerator
     {
-        // there IS a public "logger" service in the container
-        $logger = $this->container->get('logger');
+        private $container;
 
-        // this will NOT work: MessageGenerator is a private service
-        $generator = $this->container->get(MessageGenerator::class);
-    }
+        public function __construct(ContainerInterface $container)
+        {
+            $this->container = $container;
+        }
+
+        public function generate(string $message, string $template = null, array $context = []): string
+        {
+            if ($template && $this->container->has('twig')) {
+                // there IS a public "twig" service in the container
+                $twig = $this->container->get('twig');
+
+                return $twig->render($template, $context + ['message' => $message]);
+            }
+
+            // if no template is passed, the "twig" service will not be loaded
+
+            // ...
+        }
 
 As a best practice, you should only create *private* services, which will happen
 automatically. And also, you should *not* use the ``$container->get()`` method to
@@ -837,7 +852,7 @@ But, if you *do* need to make a service public, override the ``public`` setting:
             # ... same code as before
 
             # explicitly configure the service
-            App\Service\MessageGenerator:
+            Acme\PublicService:
                 public: true
 
     .. code-block:: xml
@@ -853,7 +868,7 @@ But, if you *do* need to make a service public, override the ``public`` setting:
                 <!-- ... same code as before -->
 
                 <!-- Explicitly configure the service -->
-                <service id="App\Service\MessageGenerator" public="true"></service>
+                <service id="Acme\PublicService" public="true"></service>
             </services>
         </container>
 
@@ -862,17 +877,22 @@ But, if you *do* need to make a service public, override the ``public`` setting:
         // config/services.php
         namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
-        use App\Service\MessageGenerator;
+        use Acme\PublicService;
 
         return function(ContainerConfigurator $configurator) {
             // ... same as code before
 
             // explicitly configure the service
-            $services->set(MessageGenerator::class)
+            $services->set(PublicService::class)
                 ->public()
             ;
         };
 
+.. note::
+
+    Instead of injecting the container you should consider using a
+    :ref:`service locator <service-locators>` instead.
+
 .. _service-psr4-loader:
 
 Importing Many Services at once with resource

service_container/service_subscribers_locators.rst

@@ -1,6 +1,8 @@
 .. index::
     single: DependencyInjection; Service Subscribers
 
+.. _service-locators:
+
 Service Subscribers & Locators
 ==============================
 
@@ -515,7 +517,7 @@ attribute to the locator service defining the name of this custom method:
             # ...
 
             App\HandlerCollection:
-                arguments: [!tagged_locator { tag: 'app.handler', default_index_method: 'myOwnMethodName' }]
+                arguments: [!tagged_locator { tag: 'app.handler', index_by: 'key', default_index_method: 'myOwnMethodName' }]
 
     .. code-block:: xml
 
@@ -531,7 +533,7 @@ attribute to the locator service defining the name of this custom method:
                 <!-- ... -->
 
                 <service id="App\HandlerCollection">
-                    <argument type="tagged_locator" tag="app.handler" default-index-method="myOwnMethodName"/>
+                    <argument type="tagged_locator" tag="app.handler" index-by="key" default-index-method="myOwnMethodName"/>
                 </service>
             </services>
         </container>
@@ -544,10 +546,16 @@ attribute to the locator service defining the name of this custom method:
         return function(ContainerConfigurator $configurator) {
             $configurator->services()
                 ->set(App\HandlerCollection::class)
-                    ->args([tagged_locator('app.handler', null, 'myOwnMethodName')])
+                    ->args([tagged_locator('app.handler', 'key', 'myOwnMethodName')])
             ;
         };
 
+.. note::
+
+    Since code should not be responsible for defining how the locators are
+    going to be used, a configuration key (``key`` in the example above) must
+    be set so the custom method may be called as a fallback.
+
 Service Subscriber Trait
 ------------------------
 

testing/http_authentication.rst

@@ -111,7 +111,7 @@ needs::
 
         private function logIn()
         {
-            $session = $this->client->getContainer()->get('session');
+            $session = self::$container->get('session');
 
             $firewallName = 'secure_area';
             // if you don't define multiple connected firewalls, the context defaults to the firewall name