如何在php8中用新属性替换phpdocs

Question

我正在使用laravel。我需要知道如何使用attibutes在php8中编写phpdoc。

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

有人能解释一下如何用属性编写上面的代码吗。

Answer 1

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

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

您展示的示例是第一次使用。您所写的仍然是正确的文档编写方式(尽管请参阅下面的附加说明(。

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

---

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

public function toArray(IlluminateHttpRequest $request): array
{
// ...
}

doc块对于添加描述(例如，返回的数组中会有什么？(和PHP本机不支持的类型信息(例如，@return SomeClassName[]意味着"返回SomeClassName实例的列表"(仍然很有用。

Answer 2

有一种很棒的自动折射工具，叫做rector。它会让你的生活轻松很多。安装它，然后在根目录下创建一个rector.php文件，看起来应该像这样：

<?php
declare(strict_types=1);
use RectorConfigRectorConfig;
use RectorDoctrineSetDoctrineSetList;
use RectorSymfonySetSensiolabsSetList;
use RectorSymfonySetSymfonySetList;
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->paths([
__DIR__ . '/src', 
__DIR__ . '/tests'
]);
$rectorConfig->sets([
DoctrineSetList::ANNOTATIONS_TO_ATTRIBUTES,
SymfonySetList::ANNOTATIONS_TO_ATTRIBUTES,
SensiolabsSetList::FRAMEWORK_EXTRA_61,
]);
};

您可以在文档中找到大量的配置选项。

完成后，只需运行折射工具：

vendor/bin/rector process src