Doctrine Annotations 自定义注解开发指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00979/article/details/148465461

Doctrine Annotations 自定义注解开发指南

annotations Annotations Docblock Parser 项目地址: https://gitcode.com/gh_mirrors/an/annotations

什么是自定义注解

在 Doctrine Annotations 项目中，自定义注解是指开发者根据业务需求创建的特定注解类。这些注解可以像内置注解一样被使用，为代码添加元数据信息。注解在PHP中通过特殊的DocBlock注释实现，为类、方法、属性等元素提供附加信息。

创建基本注解类

要创建自定义注解，首先需要定义一个类并添加@Annotation标记：

namespace MyCompany\Annotations;

/** @Annotation */
class CustomAnnotation
{
    // 注解类实现
}

这个简单的结构就定义了一个可用的注解。注解类可以包含属性和方法，就像普通PHP类一样。

注解值的注入方式

Doctrine Annotations 提供了两种主要方式来注入注解值：

1. 通过构造函数注入

namespace MyCompany\Annotations;

/** @Annotation */
class ConstructorInjection
{
    private $value;

    public function __construct(array $values)
    {
        $this->value = $values['value'];
    }
}

当注解类定义了构造函数时，Doctrine会将所有注解参数作为关联数组传递给构造函数。

2. 通过公共属性直接注入

namespace MyCompany\Annotations;

/** @Annotation */
class PropertyInjection
{
    public $value;
}

如果没有定义构造函数，Doctrine会尝试直接将注解参数赋值给同名的公共属性。

命名参数构造函数（高级特性）

从1.11版本开始，Doctrine Annotations支持命名参数构造函数，这与PHP 8的属性特性兼容：

namespace MyCompany\Annotations;

/**
 * @Annotation
 * @NamedArgumentConstructor
 */
class NamedArguments
{
    public function __construct(private string $param1, private int $param2 = 0) {}
}

使用方式：

/** @NamedArguments(param1="value", param2=123) */
// 或简写形式（第一个参数）
/** @NamedArguments("value") */

注解目标限制

使用@Target可以限制注解的使用位置：

/**
 * @Annotation
 * @Target({"CLASS", "METHOD"})
 */
class RestrictedAnnotation
{
    // 只能用于类和方法的注解
}

可用目标包括：

CLASS - 类级别
PROPERTY - 属性级别
METHOD - 方法级别
FUNCTION - 函数级别
ALL - 所有位置
ANNOTATION - 其他注解内部

类型验证

Doctrine提供了多种方式来验证注解参数的类型：

1. 使用`@var`注解

/** @Annotation */
class TypedAnnotation
{
    /** @var string */
    public $stringParam;
    
    /** @var int */
    public $intParam;
}

2. 使用`@Attributes`和`@Attribute`

/**
 * @Annotation
 * @Attributes({
 *   @Attribute("name", type="string"),
 *   @Attribute("age", type="integer")
 * })
 */
class StrictTypedAnnotation
{
    // 实现
}

必填参数

使用@Required标记可以指定必须提供的参数：

/**
 * @Annotation
 */
class RequiredAnnotation
{
    /** @Required */
    public $mustHave;
}

如果使用注解时未提供必填参数，将抛出AnnotationException。

枚举值限制

使用@Enum可以限制参数只能取特定值：

/**
 * @Annotation
 */
class EnumAnnotation
{
    /**
     * @Enum({"A", "B", "C"})
     */
    public $value;
}

使用常量

注解参数中可以使用常量和类常量：

/** 
 * @SomeAnnotation(PHP_EOL)
 * @AnotherAnnotation(MyClass::CONSTANT)
 */
class Example
{
    // 类实现
}

注意：修改常量后需要清除注解缓存才能生效。

注解使用示例

定义注解后，可以这样使用：

namespace MyApp\Entity;

use MyCompany\Annotations\CustomAnnotation;

/**
 * @CustomAnnotation(param1="value", param2=123)
 */
class User
{
    // 类实现
}

读取注解

通过反射API可以读取注解信息：

$reflectionClass = new ReflectionClass('MyApp\Entity\User');
$annotations = $reader->getClassAnnotations($reflectionClass);

foreach ($annotations as $annotation) {
    if ($annotation instanceof CustomAnnotation) {
        echo $annotation->param1; // 输出"value"
    }
}