如何用 php 8 中的新属性替换 phpdocs

Question

我正在使用拉拉维尔。我需要知道如何在 php 8 中使用属性编写 phpdoc。

/**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
      //Some code
      return [];
    }

有人可以解释一下上面的代码如何用属性来编写吗？

Answer 1

我相信您误解了属性的用途以及它们与文档块的关系。文档块有两种常见用途（用 标记的注释/** ... */）：

• 以大多数标准化的方式记录代码（因此称为“文档块”），可以通过各种工具（包括文档生成器和 IDE）读取。
• 向代码添加机器可读的注释，以便与可以基于这些注释自动生成行为的库和框架一起使用。例如，ORM 可能使用 的注释@TableName('Foo')将类链接到特定的数据库表，并生成适当的 SQL。

您所展示的示例是第一个用法。您所写的仍然是编写文档的正确方式（尽管请参阅下面的额外注释）。

PHP 8 的原生属性取代了第二种用法。由库决定要查找什么属性，但是以前@TableName('Foo')在文档块中查找的 ORM 现在可能会查找#[TableName('Foo')]本机属性。

与属性无关，但值得注意的是，文档中的类型信息越来越多地可以添加为由 PHP 本身检查的内联类型声明。例如，问题中的示例可以这样声明：

public function toArray(\Illuminate\Http\Request $request): array
{
    // ...
}

doc 块对于添加描述（例如，返回的数组中将包含什么？）以及 PHP 本身不支持的类型信息（例如，@return SomeClassName[]意味着“返回实例列表SomeClassName”）仍然很有用。