this implementation is not enough. We also need to rehash if any other encoder than the best one was actually validating it.

I don't understand why. To me, only the best encoder should be used. Can you elaborate?

would this encoder return true in this method if the hash was not generated by this encoder but by one of the extra encoders ? Or would it fail entirely or return false ?
There is 2 reasons to rehash a password:

• the best encoder was already used, but it now has a stronger hashing and wants to rehash the password
• a weaker encoder was used. In this case, we want to rehash, but this code expects the best encoder to detect that case when passing it the hash generated by the other encoder (and so potentially in a different format).

would this encoder return true in this method if the hash was not generated by this encoder but by one of the extra encoders

Yes, absolutely! There cannot be any other return value in this situation. The encoder must return true only if it supports the hash of course - that's what implementations do also.

would this encoder return true in this method if the hash was not generated by this encoder but by one of the extra encoders ? Or would it fail entirely or return false ?
There is 2 reasons to rehash a password:

• the best encoder was already used, but it now has a stronger hashing and wants to rehash the password
• a weaker encoder was used. In this case, we want to rehash, but this code expects the best encoder to detect that case when passing it the hash generated by the other encoder (and so potentially in a different format).

A silent failure seems odd here. Maybe log something in debug that the user will not be saved because the repository doesn't support it? At least that way when people are trying to figure out why the feature doesn't appear to be working there is something in the logs to tell them why.

A hard failure would be even more odd: you don't want your users not being able to log in when password upgrades cannot happen. They must be opportunistic to me. Logging why not!

I agree a hard failure would be incorrect here.

I'm not sure anymore about the logger: it would be noisy for ppl that just don't want to implement password upgrades for some reason.
Better document this: if you need pwd upgrade, you must implement the interface.

This gives this method two responsibilies: checking the password and upgrading it if needed. Maybe this should be done at some higher -orchistration- level?

You mean the checkAuthentication method? I've no better idea, can you elaborate?

Yes, the checkAuthentication method.
So instead of doing this inside the checkAuthentication do this in the code that calls checkAuthentication, so move it one level up to decouple the behaviours:

if ($provider->checkAuthentication(...)) {
    $provider->upgradePassword(...);
}

I'll have a look but I think what misses in your example is the encoder: the "if" must involve it before calling upgrade. Yet the encoder is internal detail of the provider.

encoder is internal detail of the provider

I confirm - and so is the cleartext password btw. Same for guard.
Deadend to me.

Seems to me it could be moved to \Symfony\Component\Security\Core\Authentication\Provider\UserAuthenticationProvider. That way it's part of the template method so all AuthenticationProviders can benefit from it, instead of being part of a particular implementation.

public function authenticate(TokenInterface $token)
{

    // ...

    try {
        $this->userChecker->checkPreAuth($user);
        $this->checkAuthentication($user, $token);
        if ($this instanceof PasswordUpgradingAuthenticationProvider) {
            // optional: if ($this->needsPasswordRehash($user, $token)) {
            $this->upgradeUserPassword($user, $token);
            // optional: }
        }
        $this->userChecker->checkPostAuth($user);
    } catch (BadCredentialsException $e) {
        if ($this->hideUserNotFoundExceptions) {
            throw new BadCredentialsException('Bad credentials.', 0, $e);
        }
        throw $e;
    }

and then \Symfony\Component\Security\Core\Authentication\Provider\DaoAuthenticationProvider would implement PasswordUpgradingAuthenticationProvider:

class DaoAuthenticationProvider extends UserAuthenticationProvider implements PasswordUpgradingAuthenticationProvider
{

   // ...

   public function upgradeUserPassword(UserInterface $user, UsernamePasswordToken $token): void
   {
      if ($this->userProvider instanceof PasswordUpgraderInterface && method_exists($encoder, 'needsRehash') && $encoder->needsRehash($user->getPassword())) {
          $this->userProvider->upgradePassword($user, $encoder->encodePassword($token->getCredentials(), $user->getSalt()));
      }
   }
}

optional: if ($this->needsPasswordRehash($user, $token)) {

yes but no :) this is not optional: this is part of the critical lifecycle of password migrations.
Not all auth providers have a concept of encoders. Only those should know and care about migrations. Said another way, your initial issue was SRP for the method, this proposal is moving the issue somewhere else. Let's say there is no SRP issue in the first place and everything is fine: checkAuthentication is the correct place to wire opportunistic password upgrades to me.

My issue was with CQS, not SRP. My issue with SRP was in the naming of the ChainPasswordEncoder.

My issue here is still CQS, and I think it would be solved by my proposal.

Sorry it wouldn't, see my objections about encoders. See also the guard interface.
Opportunistic password upgrades don't align to CQS here to me.

But please submit a PR on my fork if I'm missing the point :)

Instead of (or: in addition to) this warning, why not put a check in the constructor that throws an exception when the PlaintextPasswordEncoder is passed?

I wouldn't do this: technically one might have a reason to do so, we shouldn't close the door.

fwiw, I use plaintextpasswordencoder in my unit test harness.