docs(SecurityBundle): register alias for argument for password hasher

Author: vinceAmstoutz

security.rst

@@ -461,8 +461,8 @@ You can also manually hash a password by running:
 
     $ php bin/console security:hash-password
 
-Read more about all available hashers and password migration in
-:doc:`security/passwords`.
+Read more about all available hashers (including specific hashers) and password
+migration in :doc:`security/passwords`.
 
 .. _firewalls-authentication:
 .. _a-authentication-firewalls:

security/passwords.rst

@@ -226,6 +226,61 @@ After configuring the correct algorithm, you can use the
             throw new \Exception('Bad credentials, cannot delete this user.');
         }
 
+Injecting a Specific Password Hasher
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In some cases, you might define a password hasher in your configuration that is
+not linked to a user entity but is instead identified by a unique key.
+For example, you might have a separate hasher for things like password recovery
+codes.
+
+With the following configuration:
+
+.. code-block:: yaml
+
+    # config/packages/security.yaml
+    security:
+        password_hashers:
+            recovery_code: 'auto'
+
+        firewalls:
+            main:
+                # ...
+
+It is possible to inject the recovery_code password hasher into any service.
+To do this, you can't rely on standard autowiring, as Symfony wouldn't know
+which specific hasher to provide.
+
+Instead, you can use the ``#[Target]`` attribute to request the hasher by its
+configuration key::
+
+    // src/Controller/HomepageController.php
+    namespace App\Controller;
+
+    use Symfony\Component\DependencyInjection\Attribute\Target;
+    use Symfony\Component\PasswordHasher\PasswordHasherInterface;
+
+    class HomepageController extends AbstractController
+    {
+        public function __construct(
+            #[Target('recovery_code')]
+            private readonly PasswordHasherInterface $passwordHasher,
+        ) {
+        }
+
+        #[Route('/')]
+        public function index(): Response
+        {
+            $plaintextToken = 'some-secret-token';
+
+            // Note: use hash(), not hashPassword(), as we are not using a UserInterface object
+            $hashedToken = $this->passwordHasher->hash($plaintextToken);
+        }
+    }
+
+When injecting a specific hasher by its name, you should type-hint the generic
+:class:`Symfony\\Component\\PasswordHasher\\PasswordHasherInterface`.
+
 Reset Password
 --------------