.PHP File Format – Attributes

Syntax

attribute-group:  #[ attribute {, attribute} [,] ]
attribute:        name [ ( arguments ) ]

#[MyAttribute]                      // no arguments
#[\MyExample\MyAttribute]           // fully qualified name
#[MyAttribute(1234)]                // positional argument
#[MyAttribute(value: 1234)]         // named argument
#[MyAttribute(MyAttribute::VALUE)]  // class constant
#[MyAttribute(100 + 200)]           // constant expression
#[First, Second(2)]                 // two attributes in one group
class Thing {}

• An attribute group goes before the declaration, before its modifiers. Several groups can be stacked.
• The name resolves to a class, by the normal name resolution rules. The name may be unqualified, qualified or fully qualified.
• Arguments are optional, and must be constant expressions. Positional and named arguments are both allowed. Since PHP 8.5 static closures and first-class callables are allowed too.
• The syntax is also a comment in older PHP versions, if the group is on a line of its own: PHP 7 reads #[...] as a # comment.

Targets

Attributes can be placed on classes (including interfaces, traits, enums and anonymous classes), functions, methods, closures, arrow functions, parameters, properties, class constants, enum cases and, since PHP 8.5, global constants.

#[A] function f(#[A] $param) {}
#[A] class C {
    #[A] public int $x;
    #[A] const K = 1;
    #[A] public function m() {}
}
enum E { #[A] case Z; }
$o = new #[A] class {};
$f = #[A] function () {};
$g = #[A] fn() => 1;
#[A] const G = 1;  // PHP 8.5

An attribute on a promoted constructor parameter applies to both the parameter and the property.

Declaring an attribute class

Any class marked with #[Attribute] can be used as an attribute. The attribute’s arguments are the constructor’s.

#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
final class Route
{
    public function __construct(
        public string $path,
        public array $methods = ['GET'],
    ) {}
}

class Pages
{
    #[Route('/home')]
    #[Route('/start', methods: ['GET', 'HEAD'])]
    public function home(): string { return 'hello'; }
}

The flags are checked when the attribute is instantiated, not when the code is compiled, for attributes defined in PHP code. Built-in attributes check their targets at compile time. #[\DelayedTargetValidation] (PHP 8.5) defers that to newInstance() as well.

Reading attributes

Reflection classes for classes, methods, functions, parameters, properties and constants have a getAttributes() method. It returns ReflectionAttribute objects, and an optional argument filters by class name.

$method = new ReflectionMethod(Pages::class, 'home');

foreach ($method->getAttributes(Route::class) as $attribute) {
    echo $attribute->getName();            // Route
    var_dump($attribute->getArguments());  // the arguments as written
    $route = $attribute->newInstance();    // calls the constructor
}

• getName() and getArguments() do not load the attribute class. Only newInstance() does, and that is where a missing class, a wrong target or bad arguments cause an Error.
• Class attributes are not inherited, so reflecting a subclass does not show its parent’s.

Built-in attributes

#[\NoDiscard('as the commit may fail')]
function commit(): bool { /* ... */ }

commit();         // warning
(void) commit();  // no warning
$ok = commit();   // no warning