UniqueEntity

编辑此页

验证 Doctrine 实体中的特定字段（或多个字段）是否唯一。这通常用于例如阻止新用户使用系统中已存在的电子邮件地址进行注册。

另请参阅

如果您想验证集合中的所有元素都是唯一的，请使用 Unique 约束。

注意

为了使用此约束，您应该使用 Composer 安装 symfony/doctrine-bridge。

适用于 类
类 UniqueEntity
验证器 UniqueEntityValidator

基本用法

假设您有一个 User 实体，其中包含一个 email 字段。您可以使用 UniqueEntity 约束来保证 email 字段在用户表的所有行中保持唯一

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// src/Entity/User.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

// DON'T forget the following use statement!!!
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;

use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[UniqueEntity('email')]
class User
{
    #[ORM\Column(name: 'email', type: 'string', length: 255, unique: true)]
    #[Assert\Email]
    protected string $email;
}

警告

此约束不提供任何针对 竞态条件 的保护。当外部进程在此验证通过后且此实体实际持久化到数据库之前持久化另一个实体时，可能会发生竞态条件。

警告

此约束无法处理在尚未作为实体持久化的项目集合中找到的重复项。您需要创建自己的验证器来处理这种情况。

选项

em

类型: string 默认值: null

用于进行查询以确定唯一性的实体管理器名称。如果留空，将为此类确定正确的实体管理器。因此，可能不需要使用此选项。

entityClass

类型: string 默认值: null

默认情况下，用于确保唯一性的查询使用当前类实例的存储库。但是，在某些情况下，例如使用 Doctrine 继承映射时，您需要在不同的存储库中执行查询。使用此选项定义与您要使用的存储库关联的 Doctrine 实体的完全限定类名 (FQCN)。

errorPath

类型: string 默认值: fields 中第一个字段的名称

如果实体违反了约束，则错误消息将绑定到 fields 中的第一个字段。如果存在多个字段，您可能希望将错误消息映射到另一个字段。

考虑以下示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// src/Entity/Service.php
namespace App\Entity;

use App\Entity\Host;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;

#[ORM\Entity]
#[UniqueEntity(
    fields: ['host', 'port'],
    message: 'This port is already in use on that host.',
    errorPath: 'port',
)]
class Service
{
    #[ORM\ManyToOne(targetEntity: Host::class)]
    public Host $host;

    #[ORM\Column(type: 'integer')]
    public int $port;
}

现在，使用此配置，消息将绑定到 port 字段。

fields

类型: array | string [默认选项]

此必需选项是此实体应唯一的字段（或字段列表）。例如，如果您在单个 UniqueEntity 约束中同时指定了 email 和 name 字段，那么它将强制执行组合值是唯一的（例如，两个用户可以具有相同的电子邮件，只要他们没有相同的名称）。

如果您需要要求两个字段分别唯一（例如，唯一的 email 和唯一的 username），您可以使用两个 UniqueEntity 条目，每个条目都包含一个字段。

groups

类型: array | string 默认值: null

它定义了此约束的验证组。阅读更多关于 验证组 的信息。

ignoreNull

类型: boolean array 默认值: true

如果此选项设置为 true，则约束将允许多个实体对字段具有 null 值而不会验证失败。如果设置为 false，则只允许一个 null 值 - 如果第二个实体也具有 null 值，则验证将失败。

除了忽略所有唯一字段的 null 值之外，您还可以使用此选项指定一个或多个字段，仅忽略它们的 null 值

1
2
3
4
5
6
7
8
9
10
11
12
13
// src/Entity/User.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[UniqueEntity(fields: ['email', 'phoneNumber'], ignoreNull: 'phoneNumber')]
class User
{
    // ...
}

警告

如果您在数据库中唯一索引的一部分字段上 ignoreNull，您可能会在应用程序尝试持久化 UniqueEntity 约束认为有效的实体时看到插入错误。

message

类型: string 默认值: This value is already used.

当此约束失败时显示的消息。默认情况下，此消息映射到导致违规的第一个字段。当在约束中使用多个字段时，可以通过 errorPath 属性指定映射。

消息可以包含 {{ value }} 占位符，以显示无效实体的字符串表示形式。如果实体未定义 __toString() 方法，则将使用以下通用值："Object of class __CLASS__ identified by <comma separated IDs>"

您可以在此消息中使用以下参数

参数 描述
{{ value }} 当前（无效）值
{{ label }} 对应的表单字段标签

payload

类型: mixed 默认值: null

此选项可用于将任意特定于域的数据附加到约束。Validator 组件不使用配置的有效负载，但其处理完全取决于您。

例如，您可能想要使用 多个错误级别，以便根据错误严重性在前端以不同方式呈现失败的约束。

repositoryMethod

类型: string 默认值: findBy

用于确定唯一性的存储库方法的名称。如果留空，将使用 findBy()。该方法接收一个 fieldName => value 关联数组作为参数（其中 fieldName 是在 fields 选项中配置的每个字段）。该方法应返回一个 可计数 PHP 变量。

本作品，包括代码示例，均根据 Creative Commons BY-SA 3.0 许可获得许可。
目录
    版本