Awesome
PHP Static Analysis Attributes PHPStan Extension
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 PHPStan extension that allows PHPStan to understand a new set of attributes that replace the PHPDoc 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 this extension, require it in Composer:
composer require --dev php-static-analysis/phpstan-extension
If you also install phpstan/extension-installer then you're all set!
<details> <summary>Manual installation</summary>If you don't want to use phpstan/extension-installer
, include extension.neon
in your project's PHPStan config:
includes:
- vendor/php-static-analysis/phpstan-extension/extension.neon
</details>
Using the extension
This extension works by interacting with the parser that PHPStan uses to parse the code and replacing the new Attributes with PHPDoc annotations that PHPStan can understand. The functionality provided by the attribute is exactly the same as the one provided by the corresponding PHPDoc annotation.
These are the available attributes and their corresponding PHPDoc annotations:
Attribute | PHPDoc Annotations |
---|---|
Assert | @assert |
AssertIfFalse | @assert-if-false |
AssertIfTrue | @assert-if-true |
DefineType | @type |
Deprecated | @deprecated |
Immmutable | @immmutable |
ImportType | @import-type |
Impure | @impure |
Internal | @internal |
IsReadOnly | @readonly |
Method | @method |
Mixin | @mixin |
Param | @param |
ParamOut | @param-out |
Property | @property @var |
PropertyRead | @property-read |
PropertyWrite | @property-write |
Pure | @pure |
RequireExtends | @require-extends |
RequireImplements | @require-implements |
Returns | @return |
SelfOut | @self-out @this-out |
Template | @template |
TemplateContravariant | @template-contravariant |
TemplateCovariant | @template-covariant |
TemplateExtends | @extends @template-extends |
TemplateImplements | @implements @template-implements |
TemplateUse | @use @template-use |
Throws | @throws |
Type | @var @return |
Sponsor this project
If you would like to support the development of this project, please consider sponsoring me