PHP8之属性注解(Attributes)

距离PHP 8发布已经过了好几个月了，本文将针对一个非常重要的功能特性进行讲解。它就是万众期待的注解(Attributes)也叫做属性。在没有Attributes之前我们也可以通过注释来实现它的一些功能，也有很多的注释解析库如: Doctrine Annotations, phpdocumentor/reflection-docblock等。PHP 8之后我们得到了原生的支持。

什么是Attributes

Attributes是为PHP类，函数，闭包，类属性，类方法，常量甚至在匿名类上添加的元数据。 PHP DocBlock注释可能是最熟悉的示例。

/**
 * @param string $message
 */
function foo(string $message) {}

这些注释在某种程度上由@param“注释”构成。这些注释块不会被执行，但是PHP提供了一个称为"Reflection API"的API，可以方便地读取这些注释。就像刚刚说得那几种注释库都是通过这个API来解析数据。

这种注释的方法有点缺陷，因为它很容易打错字，直到将这些注释从代码中的其他地方读出来您才会注意到。PHP 8中添加的新方法是Attributes。属性提供了一种更为实用的方法来声明和获取这些信息。

在没有Attributes之前，比如Drupal，Symfony和Doctrine之类的框架使用注释的方式来组织为某些类提供辅助信息。最典型的就是注释路由:

class AboutPage extends AbstractController {
    /**
     * @Route("/about")
     */
    public function page() {}
}

带有DocBlock注释，此注释提供了关于AboutPage类的有用信息。在框架中，可以将其转换为路由表中的一条路由，以将“/about”路径路由到AboutPage::page方法。

PHP 8中的Attributes更优于注释，它为注释带来了一种结构化且经过引擎验证的方法。

class AboutPage extends AbstractController {
    #[Route('/about')]
    public function page() {}
}

属性不是以XML架构或JSON架构的形式编写单独的定义，而是提供一种轻松且可管理的方式来组织此元数据。

其他语言的Attributes

许多语言具有与PHP属性类似的功能特性。

Java可能是最受欢迎的Java，它的Annotations语法类似于@Route(name="/about")。
Rust的Attributes语法类似于＃[route(name="/about")]，与PHP的实现完全相同。
Python注释称为装饰器，并遵循类似的语法：@route("/about")。

PHP现有的注释形式被广泛使用，但是PHP 8中的属性使用＃[]大括号语法。社区对此和用户进行了辩论，并将其从最初的<< Attr >>实现更改为@@ Attr，再更改为最终的#[Attr]语法。

属性与注释

属性和注释提供相同的功能。 “注释”已在PHP库和框架中广泛使用，因此名称Attributes有助于最大程度地减少与注释的混淆。使用属性我们不必去解析注释，使用最新的PhpStorm IDE也支持了Attributes功能。

以前的尝试

以前有两次尝试将此功能引入PHP。第一个大约在8年前，提出了一个名为“注释”的提案。 2016年，Dmitry Stogov提出了第一个Attributes RFC。这些尝试都没有取得丰硕的成果。实际上，第一个Attribute RFC提出了与PHP 8相同的语法，但是第二个RFC简化了PHP 8，Benjamin Eberlei做出了巨大的工作来解决次要细节并与之进行健康的讨论。社区同意其语法和功能。

属性语法和功能

属性语法只是用＃[]来完成约定。

#[Attribute]

选择此语法时，官方进行了很好的讨论，建议的一些替代模式是：

@@ Attribute
[[Attribute]]
@: Attribute

从最初的<<Attr>>语法后来被RFC更改为@@，随后又是另一个RFC更改为"＃[]"，这也带来了某种形式的向后兼容性。

设计目标

PHP 8属性提供了对信息的便捷访问。语法和实现的目的是使语法非常熟悉用户已经熟悉的内容：

属性可以解析为类名。
属性可以命名空间。
可以使用use语句导入属性类名称。
属性可以具有零个或多个参数。
一个声明可以有多个属性。
可以从Reflection API中检索属性实例。

本文的其余部分将通过详尽的示例来说明所有这些功能。

使用命名空间并将它们与类名称相关联，可以更轻松地重用和组织属性。可以扩展它们或实现接口，在轮询属性时，Reflection API会提供方便的过滤器功能。

属性可以解析为类名

尽管不是必需的，PHP 8提供了将属性名称解析为类名称的功能。您可以使用use语句来清理代码。将遵循类名称解析的标准规则。将属性名称与类名称匹配是可选的。如果属性未映射到类名，则允许重复该属性，并且不允许从Reflection API实例化该属性。

属性可以具有参数

每个属性可以具有零个或多个参数。如果尝试获取属性的实例化对象，则将它们传递给Attribute类构造函数。参数可以是简单的标量类型，数组，甚至可以是简单的表达式，例如数学表达式，PHP常数，类常数（包括魔术常数）。任何可以用作类常量的表达式都可以用作Attribute参数。

允许多个属性

接收属性的每个类目可以具有零个或多个属性，每个属性都在其自己的[]括号内，或用逗号分隔。每个属性都可以由空格（换行或空格）分隔。请注意，如果一个属性映射到一个类名，则不允许该属性多次被赋予属性。可以将该属性显式声明为可重复，以允许此操作。

#[Attr]
#[FooAttr]
function foo(){}

#[Attr, FooAttr]
function bar(){}

DocBlock之前和之后的注释

属性可以出现在DocBlock注释之前和之后。对于代码样式，没有标准的建议，但是肯定会在以后的PSR代码样式建议中消除这一建议。我比较喜欢注释之后。

属性示例

可以将属性添加到各种声明中。

函数

#[Attr('foo')]
function example(){}

类

#[Attr('foo')]
class Example {}

函数方法参数

function example(#[Attr('foo')] string $foo) {}

类属性

class Foo {
    #[Attr('foo')]
    private string $foo;
}

类常量

class Foo {
    #[Attr('foo')]
    private const FOO = 'foo';
}

闭包

$fn = #[Attr('foo')] fn() => 1 > 2;

$fn = #[Attr('foo')] function() {
    return 1 > 2;
}

匿名类

$instance = new #[Attr('foo')] class {};

使用DocBlocks

可以在DocBlock注释之前和/或之后放置属性：

#[AttributeBefore('foo')]
#[AttributeBefore2('foo')]
#[AttrCommas('foo'), AttrCommas('foo')]
/**
 * Foo
 */
#[AttributeAfter('foo')]
function example() {}

完整的例子

#[FooAttribute]
function foo_func(#[FooParamAttrib('Foo1')] $foo) {}

#[FooAttribute('hello')]
#[BarClassAttrib(42)]
class Foo {
    #[ConstAttr]
    #[FooAttribute(null)]
    private const FOO_CONST = 28;
    private const BAR_CONST = 28;

    #[PropAttr(Foo::BAR_CONST, 'string')]
    private string $foo;

    #[SomeoneElse\FooMethodAttrib]
    public function getFoo(#[FooClassAttrib(28)] $a): string{}
}

// Declare Attributes

/*
 * Attributes are declared with `#[Attribute]`.
 */

#[Attribute]
class FooAttribute {
    public function __construct(?string $param1 = null) {}
}

#[Attribute]
class ClassAttrib {
    public function __construct(int $index) {}
}

声明属性

属性本身可以声明为类。仅当获取属性时才对此进行验证，而在解析代码时不立即进行验证。 PHP是标准的PHP类，使用＃[Attribute]属性声明。

#[Attribute]
class FooAttribute{

}

默认情况下，可以在任何接受属性的类目上使用声明的属性。这包括类，类方法，闭包，函数，参数和类属性。

声明属性时，可以声明必须使用该属性的目标。

#[Attribute(Attribute::TARGET_CLASS)]
class Foo {}

当该属性带有其支持的目标时，PHP不允许将该属性用于任何其他目标。它接受位掩码以允许该属性出现在一个或多个目标中。

#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class Foo {}

它允许以下目标：

Attribute::TARGET_ALL
Attribute::TARGET_FUNCTION
Attribute::TARGET_METHOD
Attribute::TARGET_PROPERTY
Attribute::TARGET_CLASS_CONSTANT
Attribute::TARGET_PARAMETER
Attribute::TARGET_METHOD

TARGET_ALL是所有其他目标.

属性类声明为final

Attribute类被声明为final，这阻止了它的扩展。

可重复属性

默认情况下，不允许在同一目标上多次使用同一属性。该属性必须明确允许它：

#[Attribute(Attribute::IS_REPEATABLE)]
class MyRepeatableAttribute{}

属性类简介

#[Attribute(Attribute::TARGET_CLASS)]
final class Attribute {
    public int $flags;
    /**
     * Marks that attribute declaration is allowed only in classes.
     */
    const TARGET_CLASS = 1;

    /**
     * Marks that attribute declaration is allowed only in functions.
     */
    const TARGET_FUNCTION = 1 << 1;

    /**
     * Marks that attribute declaration is allowed only in class methods.
     */
    const TARGET_METHOD = 1 << 2;

    /**
     * Marks that attribute declaration is allowed only in class properties.
     */
    const TARGET_PROPERTY = 1 << 3;

    /**
     * Marks that attribute declaration is allowed only in class constants.
     */
    const TARGET_CLASS_CONSTANT = 1 << 4;

    /**
     * Marks that attribute declaration is allowed only in function or method parameters.
     */
    const TARGET_PARAMETER = 1 << 5;

    /**
     * Marks that attribute declaration is allowed anywhere.
     */
    const TARGET_ALL = (1 << 6) - 1;

    /**
     * Notes that an attribute declaration in the same place is
     * allowed multiple times.
     */
    const IS_REPEATABLE = 1 << 10;

    /**
     * @param int $flags A value in the form of a bitmask indicating the places
     * where attributes can be defined.
     */
    public function __construct(int $flags = self::TARGET_ALL)
    {
    }
}

反射API

使用反射API检索属性。当PHP引擎解析包含属性的代码时，它们会存储在内部结构中以备将来使用。包含Opcache支持。除非请求Attribute的实例，否则它不会执行任何代码或调用属性的构造函数（请参见下面的示例）。
使用Reflection API，可以以包含属性名称（已解析类名）及其可选参数的字符串的形式检索属性。 Reflection API还可以实例化Attribute类的实例，其中解析了类名，自动加载了该类名，并将可选参数传递给了类构造函数。未能实例化该类将抛出\ Error异常，可以在调用方级别捕获该异常。

getAttributes

$reflector = new \ReflectionClass(Foo::class);
$reflector->getAttributes();

所有Reflection类都有一个新方法getAttributes方法，该方法返回ReflectionAttribute对象的数组。此新方法的摘要类似于以下内容：

/**
 *  @param string $name Name of the class to filter the return list
 *  @param int $flags Flags to pass for the filtering process.
 *  @return array ReflectionAttribute[]
 */
public function getAttributes(?string $name = null, int $flags = 0): array {}

ReflectionAttribute

final class ReflectionAttribute {
    /**
     * @return string The name of the attribute, with class names resolved.
     */
    public function getName(): string {}

    /**
     * @return array Arguments passed to the attribute when it is declared.
     */
    public function getArguments(): array {}

    /**
     * @return object An instantiated class object of the name, with arguments passed to the constructor.
     */
    public function newInstance(): object {}
}

属性过滤

getAttributes可选地接受一个类名字符串，该字符串可用于通过某个属性名来过滤属性的返回数组。

$attrs = $reflector->getAttributes(FooAttribute::class);

$attrs数组现在仅是ReflectionAttribute对象或FooAttribute属性名称。第二个可选参数接受整数以进一步微调返回数组。

$attrs = $reflector->getAttributes(BaseAttribute::class, \ReflectionAttribute::IS_INSTANCEOF);

目前，仅\ReflectionAttribute::IS_INSTANCEOF可用。如果传递了\ReflectionAttribute::IS_INSTANCEOF，则返回数组将包含具有相同类名或扩展或实现所提供名称的类的Attribute（即所有满足instanceOf $name的类）。

属性对象实例

ReflectionAttribute::newInstance方法返回Attribute类的实例，并将任何参数传递给Attribute对象类的构造函数。

完整的反射示例

#[exampleAttribute('Hello world', 42)]
class Foo {}

#[Attribute]
class ExampleAttribute {
    private string $message;
    private int $answer;
    public function __construct(string $message, int $answer) {
        $this->message = $message;
        $this->answer = $answer;
    }
}

$reflector = new \ReflectionClass(Foo::class);
$attrs = $reflector->getAttributes();

foreach ($attrs as $attribute) {
    $attribute->getName(); // "My\Attributes\ExampleAttribute"
    $attribute->getArguments(); // ["Hello world", 42]
    $attribute->newInstance();
        // object(ExampleAttribute)#1 (2) {
        //  ["message":"Foo":private]=> string(11) "Hello World"        
        //  ["answer":"Foo":private]=> int(42) 
        // }
}

实际用例

Attributes功能非常强大，因为它们可以直接与类名关联，并且类名解析是内置的，静态分析器和IDE可以轻松添加对Attributes的支持。像PHPStorm这样的IDE已经支持Attributes，它甚至还提供了一些自己的内置属性，例如#[Deprecated]。

从注释迁移到属性

当您的项目有能力使用PHP 8作为最低版本时，可以将具有Doctrine风格的注释升级为一流的PHP属性。

- /** @ORM\Entity */
+ #[ORM\Entity]
  class Book {
-   /** 
-    * @ORM\Id
-    * @ORM\Column(type="string")
-    * @ORM\GeneratedValue
-    */
+   #[ORM\Id]
+   #[ORM\Column("string")]
+   #[ORM\GeneratedValue]
    private string $isbn;
  }

如果你的项目使用得Symfony 5.2以上的版本，可以直接将注释路由直接升级到属性路由。

// AFTER: annotations defined with PHP 8 attributes
use Symfony\Component\Routing\Annotation\Route;

class SomeController
{
    #[Route('/path', name: 'action')]
    public function someAction()
    {
        // ...
    }
}

Laravel框架三方包也提供了属性路由。

本网站的后台菜单也是通过属性生成。

未来的属性

属性可能是许多PHP功能的基石，而这些功能在理想情况下并未用接口“标记”。

在关于属性的建议中，它提到了使用属性来标记声明与JIT兼容/不兼容。另一个用例是＃[Deprecated]属性，该属性可用于声明引擎和用户范围的类/函数或其他任何不推荐使用的类/函数。最终可以撤消@deprecated DocBlock注释。

Drupal和Symfony对控制器，插件，渲染块等使用Doctrine Annotation。在适当的时候，它们都可以升级为Attributes。

本文大部分内容是通过此文章翻译过来。

PHP8之属性注解(Attributes)

什么是Attributes

其他语言的Attributes

属性与注释

以前的尝试

属性语法和功能

设计目标

属性可以解析为类名

属性可以具有参数

允许多个属性

DocBlock之前和之后的注释

属性示例

函数

类

函数方法参数

类属性

类常量

闭包

匿名类

使用DocBlocks

完整的例子

声明属性

属性类声明为final

可重复属性

属性类简介

反射API

getAttributes

ReflectionAttribute

属性过滤

属性对象实例

完整的反射示例

实际用例

从注释迁移到属性

未来的属性

推荐阅读

关于作者

骑驴找蚂蚁

文章目录

PHP8之属性注解(Attributes)

¶什么是Attributes

¶其他语言的Attributes

¶属性与注释

¶以前的尝试

¶属性语法和功能

¶设计目标

¶属性可以解析为类名

¶属性可以具有参数

¶允许多个属性

¶DocBlock之前和之后的注释

¶属性示例

¶函数

¶类

¶函数方法参数

¶类属性

¶类常量

¶闭包

¶匿名类

¶使用DocBlocks

¶完整的例子

¶声明属性

¶属性类声明为final

¶可重复属性

¶属性类简介

¶反射API

¶getAttributes

¶ReflectionAttribute

¶属性过滤

¶属性对象实例

¶完整的反射示例

¶实际用例

¶从注释迁移到属性

¶未来的属性

¶推荐阅读

关于作者

骑驴找蚂蚁

文章目录

什么是Attributes

其他语言的Attributes

属性与注释

以前的尝试

属性语法和功能

设计目标

属性可以解析为类名

属性可以具有参数

允许多个属性

DocBlock之前和之后的注释

属性示例

函数

类

函数方法参数

类属性

类常量

闭包

匿名类

使用DocBlocks

完整的例子

声明属性

属性类声明为final

可重复属性

属性类简介

反射API

getAttributes

ReflectionAttribute

属性过滤

属性对象实例

完整的反射示例

实际用例

从注释迁移到属性

未来的属性

推荐阅读