Merge branch '4.4' into 5.0

* 4.4:
  [#12835] add use statement
  Update custom-transport.rst
  Update injection_types.rst
  Document PasswordAuthenticatedInterface
  Update Valid.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(/* ... */);
         }

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/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'));
         };