在 Symfony 5.3 中定制用户认证失败提示

// Symfony\Component\Security\Http\Authentication\AuthenticatorManager.php

try {
    // 获取认证器返回的 Passport
    $passport = $authenticator->authenticate($request);
    // ...
} catch (AuthenticationException $e) {
    // 认证失败！
    $response = $this->handleAuthenticationFailure($e, $request, $authenticator, $passport);
    // ...
}

private function handleAuthenticationFailure(AuthenticationException $authenticationException, Request $request, AuthenticatorInterface $authenticator, ?PassportInterface $passport): ?Response
{
    // ...
    // 如果 hide_user_not_found 为 true 且异常不是 CustomUserMessageAccountStatusException，
    // 则会将 UsernameNotFoundException 或 AccountStatusException 替换为 BadCredentialsException。
    if ($this->hideUserNotFoundExceptions && ($authenticationException instanceof UsernameNotFoundException || ($authenticationException instanceof AccountStatusException && !$authenticationException instanceof CustomUserMessageAccountStatusException))) {
        $authenticationException = new BadCredentialsException('Bad credentials.', 0, $authenticationException);
    }

    $response = $authenticator->onAuthenticationFailure($request, $authenticationException);
    // ...
}

# config/packages/security.yaml

security:
    # ...
    hide_user_not_found: false

    firewalls:
        # ...

// src/Security/MyLoginFormAuthenticator.php

namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractLoginFormAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;

class MyLoginFormAuthenticator extends AbstractLoginFormAuthenticator
{
    // ... 其他方法

    public function authenticate(Request $request): Passport
    {
        $email = $request->request->get('email', '');
        $password = $request->request->get('password', '');

        // 示例：如果邮箱格式不正确，可以抛出自定义异常
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new CustomUserMessageAuthenticationException('请输入有效的邮箱地址。');
        }

        // 实际的用户加载和密码验证逻辑
        // UserBadge 会尝试通过 UserProvider 加载用户
        return new Passport(
            new UserBadge($email),
            new PasswordCredentials($password)
        );
    }

    // ... onAuthenticationSuccess, getLoginUrl 等方法
}

// src/Repository/UserRepository.php

namespace App\Repository;

use App\Entity\User;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;

/**
 * @extends ServiceEntityRepository<User>
 *
 * @implements PasswordUpgraderInterface<User>
 */
class UserRepository extends ServiceEntityRepository implements UserProviderInterface, PasswordUpgraderInterface
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, User::class);
    }

    public function loadUserByIdentifier(string $identifier): UserInterface
    {
        $user = $this->findOneBy(['email' => $identifier]);

        if (!$user) {
            // 用户不存在时抛出自定义消息
            throw new CustomUserMessageAuthenticationException('该邮箱未注册，请检查或注册新账号。');
        }

        return $user;
    }

    // ... 其他方法
}

// src/Security/UserChecker.php

namespace App\Security;

use App\Entity\User;
use Symfony\Component\Security\Core\Exception\AccountExpiredException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Core\User\UserCheckerInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class UserChecker implements UserCheckerInterface
{
    public function checkPreAuth(UserInterface $user): void
    {
        if (!$user instanceof User) {
            return;
        }

        // 示例：如果用户未激活
        if (!$user->isActivated()) {
            throw new CustomUserMessageAuthenticationException('您的账户尚未激活，请检查您的邮箱进行激活。');
        }

        // 示例：如果账户已锁定
        if ($user->isLocked()) {
            throw new CustomUserMessageAuthenticationException('您的账户已被锁定，请联系管理员。');
        }
    }

    public function checkPostAuth(UserInterface $user): void
    {
        if (!$user instanceof User) {
            return;
        }

        // 示例：如果密码已过期
        if ($user->isPasswordExpired()) {
            throw new CustomUserMessageAuthenticationException('您的密码已过期，请重置密码。');
        }
    }
}

# config/packages/security.yaml

security:
    # ...
    firewalls:
        main:
            # ...
            user_checker: App\Security\UserChecker
            # ...

{# templates/security/login.html.twig #}

{% block body %}
<form method="post">
    {% if error %}
        {# error.messageKey 将是 CustomUserMessageAuthenticationException 中传入的消息 #}
        <div class="alert alert-danger">{{ error.messageKey|trans(error.messageData, 'security') }}</div>
    {% endif %}

    {# ... 其他登录表单字段 #}
</form>
{% endblock %}