README

自 PHP 8.0 发布以来，越来越多的库、框架和工具已更新为使用属性而不是 PHPDoc 中的注释。

然而，静态分析工具如 PHPStan 并未过渡到属性，它们仍然依赖于 PHPDoc 中的注释来实现许多功能。

这是一组 RectorPHP 规则，允许我们将标准 PHP 静态分析注释转换为新的属性集，以替代这些注释。这些属性在此存储库中定义

示例

为了展示使用这些属性后的代码外观，我们可以查看以下示例。这是当前注释下的类外观

<?php

class ArrayAdder
{
    /** @var array<string>  */
    private array $result;

    /**
     * @param array<string> $array1
     * @param array<string> $array2
     * @return array<string>
     */
    public function addArrays(array $array1, array $array2): array
    {
        $this->result = $array1 + $array2;
        return $this->result;
    }
}

这是使用新属性的外观

<?php

use PhpStaticAnalysis\Attributes\Type;
use PhpStaticAnalysis\Attributes\Param;
use PhpStaticAnalysis\Attributes\Returns;

class ArrayAdder
{
    #[Type('array<string>')]
    private array $result;

    #[Param(array1: 'array<string>')]
    #[Param(array2: 'array<string>')]
    #[Returns('array<string>')]
    public function addArrays(array $array1, array $array2): array
    {
        $this->array = $array1 + $array2;
        return $this->array;
    }
}

安装

首先，为了使属性可用于您的代码库，请使用

composer require php-static-analysis/attributes

要使用这些规则，请安装此包

composer require --dev php-static-analysis/rector-rule

使用规则

要替换此包覆盖的所有注释，请使用其提供的集

use Rector\Config\RectorConfig;
use PhpStaticAnalysis\RectorRule\Set\PhpStaticAnalysisSetList;

return RectorConfig::configure()
    ->withSets([
        PhpStaticAnalysisSetList::ANNOTATIONS_TO_ATTRIBUTES
    ])
    ->withImportNames();

(我们建议您添加 withImportNames() 选项，以便属性不带完全限定名添加)

如果您只想替换一些注释并保留其他注释不变，请使用配置了所需注释的规则。例如，如果您只想替换 @return 和 @param 注释，请使用此配置

use Rector\Config\RectorConfig;
use Rector\Php80\ValueObject\AnnotationToAttribute;
use PhpStaticAnalysis\Attributes\Param;
use PhpStaticAnalysis\Attributes\Returns;
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;

return RectorConfig::configure()
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            new AnnotationToAttribute('param', Param::class),
            new AnnotationToAttribute('return', Returns::class),
        ]
    );

如果您想替换大多数注释但排除一些，可以使用 excludeAnnotations 配置参数，如下所示

use Rector\Config\RectorConfig;
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;

return RectorConfig::configure()
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            'excludeAnnotations' => ['throws', 'deprecated'],
        ]
    );

这将转换除 @throws 和 @deprecated 之外的所有注释

以下是可用的属性及其对应的 PHPDoc 注释

Param 和 ParamOut 属性的位置

默认情况下，Param 和 ParamOut 属性添加到 @param 或 @param-out 注释所在的方法/函数中。也可以将它们添加到函数中的相应参数。要激活此选项，请将以下代码添加到您的配置中

use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;
use Rector\Config\RectorConfig;
...

return RectorConfig::configure()
    ...
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            'addParamAttributeOnParameters' => true,
        ]
    );

Assert、AssertIfFalse 和 AssertIfTrue 属性的位置

默认情况下，Assert、AssertIfFalse 和 AssertIfTrue 属性添加到 @assert、@assert-if-false 或 @assert-if-true 注释所在的方法/函数中。也可以将它们添加到函数中的相应参数。要激活此选项，请将以下代码添加到您的配置中

use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;
use Rector\Config\RectorConfig;
...

return RectorConfig::configure()
    ...
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            'addAssertAttributeOnParameters' => true,
        ]
    );

用于方法/函数返回类型定义的属性

默认情况下，添加 RETURNS 属性以定义方法/函数的返回类型。也可以使用 Type 属性。要激活此选项，请将以下代码添加到您的配置中

use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;
use Rector\Config\RectorConfig;
...

return RectorConfig::configure()
    ...
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            'useTypeAttributeForReturnAnnotation' => true,
        ]
    );

用于定义类属性类型的属性

默认情况下，添加 Type 属性以定义类属性的类型。也可以使用 Property 属性。要激活此选项，请将以下代码添加到您的配置中

use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;
use Rector\Config\RectorConfig;
...

return RectorConfig::configure()
    ...
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            'usePropertyAttributeForVarAnnotation' => true,
        ]
    );

用于定义类类型定义的属性

默认情况下，会自动为类添加DefineType属性来定义类型。您可以使用Type属性代替。要启用此选项，请将以下代码添加到您的配置中

use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector;
use Rector\Config\RectorConfig;
...

return RectorConfig::configure()
    ...
    ->withConfiguredRule(
        AnnotationsToAttributesRector::class,
        [
            'useTypeAttributeForTypeClassAnnotation' => true,
        ]
    );

赞助本项目

如果您想支持本项目的开发，请考虑赞助我

php-static-analysis / rector-rule

维护者

详细信息