在 Symfony + ApiPlatform 项目中，对用户执行 PUT 更新操作时若未区分明文密码与已哈希密码，会导致 password 字段被二次哈希，引发登录失败。正确做法是引入 plainPassword 属性并仅在创建或显式修改密码时进行哈希。

在 symfony + apiplatform 项目中，对用户执行 put 更新操作时若未区分明文密码与已哈希密码，会导致 `password` 字段被二次哈希，引发登录失败。正确做法是引入 `plainpassword` 属性并仅在创建或显式修改密码时进行哈希。

问题根源分析

ApiPlatform 默认会对所有标记了 Groups 的字段（包括 password）在反序列化时写入实体。当用户发起 PUT /users/{id} 请求但未提供 password 字段时，若实体的 $password 属性仍保留数据库中已哈希的原始值（如 argon2id$...），而 UserDataPersister::persist() 又无条件调用 $userPasswordEncoder->hashPassword($data, $data->getPassword())，就会将已哈希的密文再次哈希——结果是一个非法、不可验证的密码字符串，导致后续登录失败。

关键误区在于：$password 字段应始终只存储哈希值，绝不参与输入；而密码输入行为必须通过独立的、非持久化的 plainPassword 属性承载。

正确实现方案

1. 在 User 实体中添加 plainPassword 属性

// src/Entity/User.php

use Symfony\Component\Serializer\Annotation\SerializedName;
use Symfony\Component\Validator\Constraints as Assert;

// ... 其他 use 声明

#[ORM\Entity(repositoryClass: UserRepository::class)]
#[ORM\Table(name: '`user`')]
#[ApiResource(
    // ... 保持原有配置
    denormalizationContext: ['groups' => ['user:input']],
    // 注意：确保 POST 创建时启用额外校验组
    collectionOperations: [
        'post' => ['validation_groups' => ['Default', 'postValidation']],
        // ... 其他操作
    ],
)]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    // ... 其他属性（id, email, roles 等）

    #[ORM\Column(type: 'string')]
    private $password;

    /**
     * 仅用于接收前端传入的明文密码（不映射到数据库）
     * @var string|null
     */
    #[Groups(['user:input'])]
    #[SerializedName('password')] // 确保 JSON 中的 "password" 映射至此属性
    #[Assert\NotBlank(normalizer: 'trim', groups: ['postValidation'])]
    #[Assert\Regex(
        pattern: '/^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/',
        message: 'Le mot de passe doit contenir au moins 8 caractères, une lettre et un chiffre.',
        groups: ['postValidation']
    )]
    private $plainPassword;

    // ... 其他属性

    public function getPlainPassword(): ?string
    {
        return $this->plainPassword;
    }

    public function setPlainPassword(?string $plainPassword): self
    {
        $this->plainPassword = $plainPassword;
        return $this;
    }

    // 注意：移除或注释掉原 setPassword() 中对空值的隐式处理逻辑
    // 因为 setPassword() 现在只用于设置哈希值（由 DataPersister 调用）
}

✅ 关键点：

• plainPassword 加入 user:input 组，使其可被 API 接收；
• 使用 @SerializedName("password") 保证 JSON 字段名与前端一致；
• 通过 validation_groups 将密码强度校验隔离至创建场景（postValidation），避免更新时强制校验；
• plainPassword 不映射到数据库（无 @ORM\Column），纯属传输层契约。

2. 更新 UserDataPersister 逻辑

// src/DataPersister/UserDataPersister.php

namespace App\DataPersister;

use ApiPlatform\Core\DataPersister\DataPersisterInterface;
use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

class UserDataPersister implements DataPersisterInterface
{
    public function __construct(
        private EntityManagerInterface $entityManager,
        private UserPasswordHasherInterface $passwordHasher
    ) {}

    public function supports($data): bool
    {
        return $data instanceof User;
    }

    public function persist($data): void
    {
        // ✅ 仅当明确提交了新密码时才重新哈希
        if (null !== $plainPassword = $data->getPlainPassword()) {
            $data->setPassword($this->passwordHasher->hashPassword($data, $plainPassword));
            $data->eraseCredentials(); // 清理敏感临时数据
        }

        $this->entityManager->persist($data);
        $this->entityManager->flush();
    }

    public function remove($data): void
    {
        $this->entityManager->remove($data);
        $this->entityManager->flush();
    }
}

⚠️ 注意事项：

Webnovel Serial Pipeline

构建并发布在 Quartz 平台上的韩语网络小说连载（草稿→封面→webp→章节 md→lint→发布），使用 Nano Banana Pro + ffmpeg。

下载

• 不再检查 $data->getPassword()（它始终是哈希值）；
• eraseCredentials() 必须在哈希后调用，防止 plainPassword 残留内存；
• 若使用 UserPasswordHasherInterface（Symfony 5.3+ 推荐），确保服务注入正确（旧版 UserPasswordEncoderInterface 已废弃）。

3. （可选）优化更新操作的序列化组

为彻底避免 password 字段在 PUT 响应中暴露哈希值，建议在 itemOperations 中为 update_user 指定最小化输出组：

"update_user" => [
    "method" => "PUT",
    "path" => "/users/{id}/update",
    "controller" => UpdateUser::class,
    "normalization_context" => ["groups" => ["user_update"]], // 不包含 password
    "denormalization_context" => ["groups" => ["user:input"]], // 包含 plainPassword
],

并在 User 类中为 password 移除 user_update 组：

#[Groups(['user:output'])] // ❌ 移除 'user_update'
private $password;

总结

• 核心原则：password 是只读哈希存储字段，plainPassword 是单向输入凭证；
• 安全实践：永远不在 denormalizationContext 中让 password 参与反序列化；
• 验证分层：密码复杂度校验应绑定 postValidation 组，而非全局 Default；
• 兼容性：此方案完全兼容 ApiPlatform 2.6+ 和 Symfony 5.4+/6.x 的密码哈希器体系。

遵循以上改造后，用户更新资料（如邮箱、姓名）将不再触发密码重哈希，而仅当显式提交 password 字段时才安全更新凭证，彻底解决登录失效问题。