DoctrineExtensions 注解使用指南：从基础到高级实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00459/article/details/148549476

DoctrineExtensions 注解使用指南：从基础到高级实践

DoctrineExtensions Doctrine2 behavioral extensions, Translatable, Sluggable, Tree-NestedSet, Timestampable, Loggable, Sortable 项目地址: https://gitcode.com/gh_mirrors/do/DoctrineExtensions

前言：注解与属性的演进

在开始深入探讨 DoctrineExtensions 的注解系统之前，需要特别说明一个重要变化：注解(Annotations)支持已被标记为废弃，并将在 4.0 版本中移除。对于使用 PHP 8 及更高版本的开发者，建议迁移到属性(Attributes)系统。不过考虑到当前仍有许多项目在使用注解系统，本文仍将全面介绍注解的使用方法。

核心扩展注解详解

1. 可追溯操作扩展 (Blameable)

Blameable 扩展用于自动记录操作用户信息，非常适合需要审计追踪的系统。

核心注解：

@Gedmo\Mapping\Annotation\Blameable

关键配置项：

on：触发时机（create/update/change）
field：监听字段变化（仅change模式）
value：字段值匹配条件（仅change模式）

最佳实践示例：

/**
 * 记录内容修改者（仅当title或body变更时更新）
 * @ORM\Column(type="string", nullable=true)
 * @Gedmo\Blameable(on="change", field={"title", "body"})
 */
public ?string $contentChangedBy = null;

2. IP追踪扩展 (IpTraceable)

与Blameable类似，但记录的是IP地址而非用户信息。

特殊注意事项：

字段类型必须为字符串
支持IPv4和IPv6地址记录
生产环境需要确保能获取真实客户端IP

3. 日志记录扩展 (Loggable)

提供完善的实体变更历史记录功能。

架构组成：

@Gedmo\Loggable 类注解标记可日志化实体
@Gedmo\Versioned 属性注解标记需记录字段

高级特性：

支持自定义日志存储实体
提供版本回滚功能
不支持集合类型的版本控制

4. 引用完整性扩展 (Reference Integrity)

MongoDB专属特性：

nullify：置空引用
pull：移除引用
restrict：阻止删除操作

典型应用场景：确保文章删除时，相关评论得到正确处理。

5. 跨数据库引用扩展 (References)

实现不同数据库系统间的关联关系。

三种引用类型：

@ReferenceOne：一对一跨库引用
@ReferenceMany：一对多跨库引用
@ReferenceManyEmbed：嵌入式多引用

配置要点：

必须明确指定type（entity/document）
需要处理标识符映射
支持双向关联配置

6. 智能Slug生成 (Sluggable)

自动生成URL友好的标识符。

进阶配置：

@Gedmo\Slug(
    fields={"title"},
    style="lower",
    separator="_",
    handlers={
        @Gedmo\SlugHandler(
            class="Gedmo\Sluggable\Handler\TreeSlugHandler",
            options={
                @Gedmo\SlugHandlerOption(name="parentRelationField", value="category")
            }
        )
    }
)

处理程序体系：