深入理解与定制 Symfony 5.3 认证失败消息

# config/packages/security.yaml

security:
    # ...
    hide_user_not_found: false # 根据需求设置为 true 或 false
    firewalls:
        # ...

<?php

namespace App\Security;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Core\Exception\BadCredentialsException;
use Symfony\Component\Security\Http\Authenticator\AbstractLoginFormAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\CsrfTokenBadge;
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;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class LoginFormAuthenticator extends AbstractLoginFormAuthenticator
{
    private UrlGeneratorInterface $urlGenerator;

    public function __construct(UrlGeneratorInterface $urlGenerator)
    {
        $this->urlGenerator = $urlGenerator;
    }

    protected function getLoginUrl(Request $request): string
    {
        return $this->urlGenerator->generate('app_login');
    }

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

        // 假设这里进行一些初步的凭据验证
        if (empty($email) || empty($password)) {
            // 抛出自定义错误，例如：用户未输入完整信息
            throw new CustomUserMessageAuthenticationException('请输入完整的邮箱和密码。');
        }

        // ... 其他验证逻辑

        return new Passport(
            new UserBadge($email),
            new PasswordCredentials($password),
            [
                new CsrfTokenBadge('authenticate', $csrfToken),
            ]
        );
    }

    // onAuthenticationFailure 方法保持其默认行为，它将接收上面抛出的异常
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): Response
    {
        // 默认实现会将异常存储到会话中，无需在此处再次抛出
        if ($request->hasSession()) {
            $request->getSession()->set(\Symfony\Component\Security\Core\Security::AUTHENTICATION_ERROR, $exception);
        }

        $url = $this->getLoginUrl($request);
        return new RedirectResponse($url);
    }

    // ... 其他方法如 onAuthenticationSuccess
}

<?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\User\UserProviderInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Symfony\Component\Security\Core\Exception\UsernameNotFoundException; // 旧版本使用

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

    /**
     * Used to upgrade (rehash) the user's password automatically over time.
     */
    public function upgradePassword(UserInterface $user, string $newHashedPassword): void
    {
        if (!$user instanceof User) {
            throw new UnsupportedUserException(sprintf('Instances of "%s" are not supported.', \get_class($user)));
        }

        $user->setPassword($newHashedPassword);
        $this->getEntityManager()->persist($user);
        $this->getEntityManager()->flush();
    }

    /**
     * Loads the user for the given user identifier (e.g. username or email).
     *
     * @throws CustomUserMessageAuthenticationException If the user is not found.
     */
    public function loadUserByIdentifier(string $identifier): UserInterface
    {
        $user = $this->findOneBy(['email' => $identifier]);

        if (!$user) {
            // 如果 hide_user_not_found 为 true，此异常可能被 BadCredentialsException 覆盖
            // 如果希望显示此消息，可以考虑 CustomUserMessageAccountStatusException 或禁用 hide_user_not_found
            throw new CustomUserMessageAuthenticationException('该邮箱未注册。');
        }

        return $user;
    }

    // 如果你的 Symfony 版本仍然使用 loadUserByUsername，请确保它调用 loadUserByIdentifier
    public function loadUserByUsername(string $username): UserInterface
    {
        return $this->loadUserByIdentifier($username);
    }
}

<?php

namespace App\Security;

use App\Entity\User; // 假设你的用户实体是 App\Entity\User
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserCheckerInterface;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAccountStatusException;
use Symfony\Component\Security\Core\Exception\AccountExpiredException;
use Symfony\Component\Security\Core\Exception\DisabledException;
use Symfony\Component\Security\Core\Exception\LockedException;
use Symfony\Component\Security\Core\Exception\CredentialsExpiredException;

class UserChecker implements UserCheckerInterface
{
    /**
     * Checks the user account before authentication.
     *
     * @throws CustomUserMessageAccountStatusException
     */
    public function checkPreAuth(UserInterface $user): void
    {
        if (!$user instanceof User) {
            return;
        }

        // 示例：检查用户是否被禁用
        if (!$user->isActive()) { // 假设 User 实体有一个 isActive() 方法
            throw new DisabledException('您的账户已被禁用，请联系管理员。');
            // 或者使用 CustomUserMessageAccountStatusException
            // throw new CustomUserMessageAccountStatusException('您的账户已被禁用，请联系管理员。');
        }

        // 示例：检查账户是否过期
        // if ($user->isAccountExpired()) {
        //     throw new AccountExpiredException('您的账户已过期，请重新激活。');
        // }
    }

    /**
     * Checks the user account after authentication.
     *
     * @throws CustomUserMessageAccountStatusException
     */
    public function checkPostAuth(UserInterface $user): void
    {
        if (!$user instanceof User) {
            return;
        }

        // 示例：检查密码是否过期
        // if ($user->isPasswordExpired()) {
        //     throw new CredentialsExpiredException('您的密码已过期，请重置。');
        // }

        // 示例：检查账户是否锁定
        // if ($user->isLocked()) {
        //     throw new LockedException('您的账户已被锁定，请稍后再试。');
        // }
    }
}

# config/packages/security.yaml

security:
    # ...
    providers:
        app_user_provider:
            entity:
                class: App\Entity\User
                property: email
    firewalls:
        main:
            lazy: true
            provider: app_user_provider
            form_login:
                login_path: app_login
                check_path: app_login
                # ...
            # 注册你的用户检查器
            user_checker: App\Security\UserChecker
    # ...

{# ... 其他 HTML 代码 ... #}

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

    {# ... 登录表单字段 ... #}

    <button class="btn btn-lg btn-primary" type="submit">
        登录
    </button>
</form>
{% endblock %}