All articles

Build reusable PHP components

Declare a PHP Method Attribute and Read Its Arguments with Reflection

Learn to declare a PHP method attribute and use ReflectionMethod to read its name, named arguments, and constructed instance.

Editorial illustration for Declare a PHP Method Attribute and Read Its Arguments with Reflection

To add custom metadata to a PHP method, declare an attribute class, place it above the method, and read it through Reflection. The important distinction is between the arguments written in the attribute declaration and the object created when you call newInstance(). The metadata will not make the method do anything on its own; your application or framework must decide what to do with it.

Define the attribute class

PHP attributes were introduced in PHP 8.0, so the example below requires PHP 8.0 or newer. An attribute is backed by a class marked with the built-in #[Attribute] attribute. Give that marker Attribute::TARGET_METHOD to restrict Label to methods, then accept the metadata value in the constructor. The PHP attribute syntax reference explains that arguments supplied in an attribute declaration are passed to its constructor when Reflection requests an instance.

Here, Label has one public property, text. Its constructor stores the supplied string there. This keeps the value available to code that instantiates the attribute.

Attach it to a method and inspect it

This is one complete example. It defines the attribute, attaches it to Report::export(), and inspects that method. The opening <?php tag is included so the example can stand alone as a PHP file.

<?php

#[Attribute(Attribute::TARGET_METHOD)]
class Label
{
    public string $text;

    public function __construct(string $text)
    {
        $this->text = $text;
    }
}

class Report
{
    #[Label(text: 'export')]
    public function export(): void
    {
    }
}

$method = new ReflectionMethod(Report::class, 'export');
$attributes = $method->getAttributes(Label::class);

if ($attributes === []) {
    echo "No Label attribute on this method.\n";
} else {
    $attribute = $attributes[0];
    $arguments = $attribute->getArguments();
    $instance = $attribute->newInstance();

    echo "Attribute name: ", $attribute->getName(), "\n";
    echo "Argument text: ", $arguments['text'], "\n";
    echo "Instance text: ", $instance->text, "\n";
}

#[Label(text: 'export')] supplies export as the named argument text. The target restriction belongs on the attribute class declaration; the #[Label(...)] line is its use on a method. PHP supports named as well as positional attribute arguments, but the named form makes the intended constructor parameter visible at the method.

The attribute does not call export() or perform an export. It is metadata for code that chooses to read it. As the PHP attributes overview notes, attributes can be inspected at runtime through Reflection. That is the boundary between declaring this label and giving it an application-specific meaning.

Check what Reflection returned

ReflectionMethod identifies the method to inspect. Calling getAttributes(Label::class) filters its attributes by the custom class name and returns an array of matching ReflectionAttribute objects. In this example, the array contains the method's Label; an empty filtered array would mean this method has no matching Label attribute.

The two reads answer different questions. getName() identifies the attribute as Label, while getArguments() exposes the supplied arguments, here with the key text and value export. newInstance() constructs a Label using those arguments, so the resulting object's text property is export. The expected output for the example is:

Attribute name: Label
Argument text: export
Instance text: export

Read getArguments() when you need to inspect what was supplied in the declaration. Call newInstance() when you need the attribute object and its constructor-initialized state. The attribute syntax reference makes that constructor step explicit: Reflection passes the attribute arguments to the class constructor when an instance is requested.

← All articles