Merge branch '5.0'

* 5.0:
  [#12835] add use statement
  Update custom-transport.rst
  Update injection_types.rst
  Document PasswordAuthenticatedInterface
  Update Valid.rst
  remove old versionadded directive
  Update guard_authentication.rst
  Update password_migration.rst

Author: xabbuh

messenger/custom-transport.rst

@@ -12,12 +12,13 @@ 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\Serialization\SerializerInterface;
     use Symfony\Component\Messenger\Transport\TransportFactoryInterface;
     use Symfony\Component\Messenger\Transport\TransportInterface;
 
     class YourTransportFactory implements TransportFactoryInterface
     {
-        public function createTransport(string $dsn, array $options): TransportInterface
+        public function createTransport(string $dsn, array $options, SerializerInterface $serializer): TransportInterface
         {
             return new YourTransport(/* ... */);
         }

performance.rst

@@ -39,11 +39,6 @@ features, such as the APCu Cache adapter.
 Dump the Service Container into a Single File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 4.4
-
-    The ``container.dumper.inline_factories`` parameter was introduced in
-    Symfony 4.4.
-
 Symfony compiles the :doc:`service container </service_container>` into multiple
 small files by default. Set this parameter to ``true`` to compile the entire
 container into a single file, which could improve performance when using

reference/constraints/Valid.rst

@@ -155,7 +155,7 @@ stores an ``Address`` instance in the ``$address`` property::
             {
                 $metadata->addPropertyConstraint('street', new Assert\NotBlank());
                 $metadata->addPropertyConstraint('zipCode', new Assert\NotBlank());
-                $metadata->addPropertyConstraint('zipCode', new Assert\Length(["max" => 5]));
+                $metadata->addPropertyConstraint('zipCode', new Assert\Length(['max' => 5]));
             }
         }
 
@@ -170,7 +170,7 @@ stores an ``Address`` instance in the ``$address`` property::
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('firstName', new Assert\NotBlank());
-                $metadata->addPropertyConstraint('firstName', new Assert\Length(["min" => 4]));
+                $metadata->addPropertyConstraint('firstName', new Assert\Length(['min' => 4]));
                 $metadata->addPropertyConstraint('lastName', new Assert\NotBlank());
             }
         }

security/guard_authentication.rst

@@ -241,7 +241,7 @@ Finally, configure your ``firewalls`` key in ``security.yaml`` to use this authe
                     'logout'         => true,
                     'guard'          => [
                         'authenticators'  => [
-                            TokenAuthenticator::class
+                            TokenAuthenticator::class,
                         ],
                     ],
                     // ...
@@ -300,7 +300,7 @@ Each authenticator needs the following methods:
     (or throw an :ref:`AuthenticationException <guard-customize-error>`),
     authentication will fail.
 
-**onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey)**
+**onAuthenticationSuccess(Request $request, TokenInterface $token, string $providerKey)**
     This is called after successful authentication and your job is to either
     return a :class:`Symfony\\Component\\HttpFoundation\\Response` object
     that will be sent to the client or ``null`` to continue the request
@@ -321,7 +321,7 @@ Each authenticator needs the following methods:
     the user authenticate (e.g. a 401 response that says "token is missing!").
 
 **supportsRememberMe()**
-    If you want to support "remember me" functionality, return true from this method.
+    If you want to support "remember me" functionality, return ``true`` from this method.
     You will still need to activate ``remember_me`` under your firewall for it to work.
     Since this is a stateless API, you do not want to support "remember me"
     functionality in this example.
@@ -330,7 +330,7 @@ Each authenticator needs the following methods:
     If you are implementing the :class:`Symfony\\Component\\Security\\Guard\\AuthenticatorInterface`
     instead of extending the :class:`Symfony\\Component\\Security\\Guard\\AbstractGuardAuthenticator`
     class, you have to implement this method. It will be called
-    after a successful authentication to create and return the token
+    after a successful authentication to create and return the token (a class implementing :class:`Symfony\\Component\\Security\\Guard\\Token\\GuardTokenInterface`)
     for the user, who was supplied as the first argument.
 
 The picture below shows how Symfony calls Guard Authenticator methods:

security/password_migration.rst

@@ -115,14 +115,41 @@ Upgrade the Password
 
 Upon successful login, the Security system checks whether a better algorithm
 is available to hash the user's password. If it is, it'll hash the correct
-password using the new hash. You can enable this behavior by implementing how
-this newly hashed password should be stored:
+password using the new hash. If you use a Guard authenticator, you first need to
+`provide the original password to the Security system <Provide the Password when using Guards>`_.
+
+You can enable the upgrade behavior by implementing how this newly hashed
+password should be stored:
 
 * `When using Doctrine's entity user provider <Upgrade the Password when using Doctrine>`_
 * `When using a custom user provider <Upgrade the Password when using a custom User Provider>`_
 
 After this, you're done and passwords are always hashed as secure as possible!
 
+Provide the Password when using Guard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you're using a custom :doc:`guard authenticator </security/guard_authentication>`,
+you need to implement :class:`Symfony\\Component\\Security\\Guard\\PasswordAuthenticatedInterface`.
+This interface defines a ``getPassword()`` method that returns the password
+for this login request. This password is used in the migration process::
+
+    // src/Security/CustomAuthenticator.php
+    namespace App\Security;
+
+    use Symfony\Component\Security\Guard\PasswordAuthenticatedInterface;
+    // ...
+
+    class CustomAuthenticator extends AbstractGuardAuthenticator implements PasswordAuthenticatedInterface
+    {
+        // ...
+
+        public function getPassword($credentials): ?string
+        {
+            return $credentials['password'];
+        }
+    }
+
 Upgrade the Password when using Doctrine
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -184,7 +211,7 @@ Trigger Password Migration From a Custom Encoder
 If you're using a custom password encoder, you can trigger the password
 migration by returning ``true`` in the ``needsRehash()`` method::
 
-    // src/Security/UserProvider.php
+    // src/Security/CustomPasswordEncoder.php
     namespace App\Security;
 
     // ...

service_container/injection_types.rst

@@ -349,7 +349,7 @@ Another possibility is setting public fields of the class directly::
         return function(ContainerConfigurator $configurator) {
             $services = $configurator->services();
 
-            $services->set('app.newsletter_manager, NewsletterManager::class)
+            $services->set('app.newsletter_manager', NewsletterManager::class)
                 ->property('mailer', ref('mailer'));
         };