php-static-analysis / rector-rule
RectorPHP rule to convert PHPDoc annotations for static analysis to PHP attributes
Fund package maintenance!
carlos-granados
Installs: 5 019
Dependents: 1
Suggesters: 1
Security: 0
Stars: 12
Watchers: 0
Forks: 0
Open Issues: 0
Type:rector-extension
Requires
- php: >=8.0
- php-static-analysis/attributes: ^0.3.1 || dev-main
- php-static-analysis/node-visitor: ^0.3.1 || dev-main
- rector/rector: ^0.19 || ^1.0
Requires (Dev)
- php-static-analysis/phpstan-extension: dev-main
- php-static-analysis/psalm-plugin: dev-main
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.8
- phpunit/phpunit: ^9.0
- symplify/easy-coding-standard: ^12.1
- vimeo/psalm: ^5
- webmozart/assert: ^1.11
README
Since the release of PHP 8.0 more and more libraries, frameworks and tools have been updated to use attributes instead of annotations in PHPDocs.
However, static analysis tools like PHPStan have not made this transition to attributes and they still rely on annotations in PHPDocs for a lot of their functionality.
This is a set of RectorPHP rules that allows us to convert standard PHP static analysis annotations into a new set of attributes that replace these annotations. These attributes are defined in this repository
Example
In order to show how code would look with these attributes, we can look at the following example. This is how a class looks like with the current annotations:
<?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; } }
And this is how it would look like using the new attributes:
<?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; } }
Installation
First of all, to make the attributes available for your codebase use:
composer require php-static-analysis/attributes
To use these rules, install this package:
composer require --dev php-static-analysis/rector-rule
Using the rules
To replace all the annotations that this package covers, use the set provided by it:
use Rector\Config\RectorConfig; use PhpStaticAnalysis\RectorRule\Set\PhpStaticAnalysisSetList; return RectorConfig::configure() ->withSets([ PhpStaticAnalysisSetList::ANNOTATIONS_TO_ATTRIBUTES ]) ->withImportNames();
(We recommend that you add the withImportNames()
option so that attributes are not added with their fully qualified name)
If you only want to replace some annotations and leave the others as they are, use the rule configured with the annotations that you need. For example, if you only want to replace the @return
and @param
annotations, use this configuration:
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), ] );
If you want to replace most annotations but exclude a few, you can use the excludeAnnotations
config parameter like this:
use Rector\Config\RectorConfig; use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector; return RectorConfig::configure() ->withConfiguredRule( AnnotationsToAttributesRector::class, [ 'excludeAnnotations' => ['throws', 'deprecated'], ] );
That would convert all annotations except @throws
and @deprecated
These are the available attributes and their corresponding PHPDoc annotations:
Location of Param and ParamOut attributes
By default Param
and ParamOut
attributes are added on the method/function where the @param
or @param-out
annotation was located. It is possible to instead add them on the corresponding parameter in the function. To activate this option, add this code to your configuration:
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector; use Rector\Config\RectorConfig; ... return RectorConfig::configure() ... ->withConfiguredRule( AnnotationsToAttributesRector::class, [ 'addParamAttributeOnParameters' => true, ] );
Location of Assert, AssertIfFalse and AssertIfTrue attributes
By default Assert
, AssertIfFalse
and AssertIfTrue
attributes are added on the method/function where the @assert
, @assert-if-false
or @assert-if-true
annotation was located. It is possible to instead add them on the corresponding parameter in the function. To activate this option, add this code to your configuration:
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector; use Rector\Config\RectorConfig; ... return RectorConfig::configure() ... ->withConfiguredRule( AnnotationsToAttributesRector::class, [ 'addAssertAttributeOnParameters' => true, ] );
Attribute to use for the return type of methods and functions
By default Returns
attributes are added to define the return type of methods/functions. It is possible to use the Type
attribute instead. To activate this option, add this code to your configuration:
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector; use Rector\Config\RectorConfig; ... return RectorConfig::configure() ... ->withConfiguredRule( AnnotationsToAttributesRector::class, [ 'useTypeAttributeForReturnAnnotation' => true, ] );
Attribute to use for the type of class properties
By default Type
attributes are added to define the type of class properties. It is possible to use the Property
attribute instead. To activate this option, add this code to your configuration:
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector; use Rector\Config\RectorConfig; ... return RectorConfig::configure() ... ->withConfiguredRule( AnnotationsToAttributesRector::class, [ 'usePropertyAttributeForVarAnnotation' => true, ] );
Attribute to use for the definition of types for classes
By default DefineType
attributes are added to define a type for a class. It is possible to use the Type
attribute instead. To activate this option, add this code to your configuration:
use PhpStaticAnalysis\RectorRule\AnnotationsToAttributesRector; use Rector\Config\RectorConfig; ... return RectorConfig::configure() ... ->withConfiguredRule( AnnotationsToAttributesRector::class, [ 'useTypeAttributeForTypeClassAnnotation' => true, ] );
Sponsor this project
If you would like to support the development of this project, please consider sponsoring me