minor symfony#60009 Improve documentation of PasswordUpgraderInterface (stof)

This PR was squashed before being merged into the 7.3 branch.

Discussion
----------

Improve documentation of PasswordUpgraderInterface

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | no
| Deprecations? | no
| Issues        | n/a
| License       | MIT

Implementations of PasswordUpgraderInterface can be called with a user instance that they don't support and are expected to handle it gracefully.
Handling it gracefully can be done either by being silent or by throwing an UnsupportedUserException.

This is a follow-up of symfony#51283 to document that throwing UnsupportedUserException is actually fine for implementations as the way to handle unsupported users, as shown by the implementation of the ChainUserProvider: https://github.com/symfony/symfony/blob/07e020abdd1ab820ca3c2ead8dfda75ea6e84eae/src/Symfony/Component/Security/Core/User/ChainUserProvider.php#L107-L113

Commits
-------

0784f98 Improve documentation of PasswordUpgraderInterface

Author: nicolas-grekas

src/Symfony/Component/Security/Core/User/PasswordUpgraderInterface.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Security\Core\User;
 
+use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
+
 /**
  * @author Nicolas Grekas <[email protected]>
  */
@@ -22,6 +24,8 @@ interface PasswordUpgraderInterface
      * This method should persist the new password in the user storage and update the $user object accordingly.
      * Because you don't want your users not being able to log in, this method should be opportunistic:
      * it's fine if it does nothing or if it fails without throwing any exception.
+     *
+     * @throws UnsupportedUserException if the implementation does not support that user
      */
     public function upgradePassword(PasswordAuthenticatedUserInterface $user, string $newHashedPassword): void;
 }