PHP Static Analysis Attributes

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 or Psalm or IDEs like PhpStorm or VS Code have not made this transition to attributes and they still rely on annotations in PHPDocs for a lot of their functionality.

This library aims to provide a set of PHP attributes which could replace the most commonly used annotations accepted by these tools and will aim to provide related repositories with the extensions or plugins that would allow these attributes to be used in these tools.

In particular, these repositories are:

• PHPStan extension
• Psalm plugin
• RectorPHP rules to migrate annotations to attributes

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 the first array
     * @param array<string> $array2 the second array
     * @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>')] // the first array
    #[Param(array2: 'array<string>')] // the second array
    #[Returns('array<string>')]
    public function addArrays(array $array1, array $array2): array
    {
        $this->array = $array1 + $array2;
        return $this->array;
    }
}

Installation

To use these attributes, require this library in Composer:

composer require php-static-analysis/attributes

And then install any needed extensions/plugins for the tools that you use.

List of implemented attributes

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
Immutable	@immutable
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 @type

PhpStorm Support

A plugin that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and enabling PHPStan support in PhpStorm (as described here). You will then be able to see errors and messages related to these attributes in your code.

Alternatively install Psalm, our Psalm extension and enable Psalm support in PhpStorm (as described here)

VS Code Support

An extension that fully supports these attributes will need to be created. Until this is ready you can get partial support by installing PHPStan, our PHPStan extension and a VS Code extension that supports PHPStan (for example this one). When you enable the extension you will be able to see errors and messages related to these attributes in your code.

Alternatively install Psalm, our Psalm extension and a VS Code extension that supports Psam (for example this one)

Sponsor this project

If you would like to support the development of this project, please consider sponsoring me