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 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:

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
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)

php-static-analysis / attributes

Maintainers

Details