PHP-Attribute zur Laufzeit auswerten: ReflectionAttribute richtig einsetzen

1. Warum Attribute erst zur Laufzeit ihren Wert entfalten

Ein PHP-Attribut ist zunächst nichts weiter als deklarative Metadaten, die neben einer Klasse, Methode, Property oder einem Parameter im Quellcode stehen. Solange niemand diese Metadaten ausliest, hat ein Attribut keinerlei Effekt auf das Programm, es wird vom PHP-Parser lediglich erkannt und in die kompilierten Metadaten der Klasse aufgenommen. Der eigentliche Nutzen entsteht erst, wenn Code zur Laufzeit gezielt nach diesen Attributen sucht, sie ausliest und auf Basis der gefundenen Informationen Entscheidungen trifft.

Dieser Artikel setzt voraus, dass eigene Attribute bereits definiert sind, etwa mit #[Attribute] auf einer Klasse, und konzentriert sich vollständig auf die zweite Hälfte des Themas: Wie liest man Attribute zur Laufzeit zuverlässig und performant aus? Die zentrale Klasse dafür ist ReflectionAttribute, ein oft unterschätztes Bindeglied zwischen der reinen Deklaration eines Attributs im Code und einer konkreten, nutzbaren PHP-Instanz zur Laufzeit.

In der Praxis begegnet einem das Auswerten von Attributen überall dort, wo Frameworks auf Konfigurationsdateien verzichten wollen: Routing-Definitionen direkt an Controller-Methoden, Validierungsregeln direkt an Klassen-Properties, Serialisierungs-Hinweise direkt an Datenfeldern. All diese Muster funktionieren nur, weil zur Laufzeit zuverlässig aus dem deklarierten Attribut eine echte, mit Argumenten befüllte Objektinstanz entsteht.

2. ReflectionAttribute: die Brücke zur Attribut-Instanz

ReflectionAttribute wird nicht direkt instanziiert, sondern über getAttributes() von einem beliebigen Reflection-Objekt geliefert, das Attribute tragen kann: ReflectionClass, ReflectionMethod, ReflectionProperty, ReflectionParameter und weitere. Jeder Aufruf von getAttributes() liefert ein Array aus ReflectionAttribute-Objekten, eines pro deklariertem Attribut an dieser Stelle, unabhängig davon, ob das Attribut später überhaupt instanziiert wird.

Das ist ein wichtiger Unterschied zu einem naiven Vorgehen: Man bekommt zunächst nur Metadaten über das Attribut, nicht automatisch eine Instanz der zugrunde liegenden Klasse. Der Grund ist Performance: Nicht jeder Aufrufer braucht tatsächlich eine Instanz, manchmal reicht der reine Name des Attributs. ReflectionAttribute::getName() liefert genau diesen Namen, ohne dass PHP dafür den Konstruktor der Attribut-Klasse ausführen muss.

<?php

declare(strict_types=1);

#[Attribute(Attribute::TARGET_PROPERTY)]
final class Validate
{
    public function __construct(
        public readonly string $rule,
        public readonly ?string $message = null,
    ) {
    }
}

final class RegisterRequest
{
    #[Validate('email', message: 'Ungültige E-Mail-Adresse')]
    public string $email = '';

    #[Validate('min_length:8')]
    public string $password = '';
}

$reflection = new ReflectionClass(RegisterRequest::class);

foreach ($reflection->getProperties() as $property) {
    // getAttributes() returns metadata objects, not instances yet
    foreach ($property->getAttributes() as $attribute) {
        echo $property->getName() . ' -> ' . $attribute->getName() . PHP_EOL;
    }
}

3. Attribute nach Typ filtern mit IS_INSTANCEOF

In realen Anwendungen tragen Klassen und Properties häufig mehrere unterschiedliche Attribute gleichzeitig, etwa eines für Validierung und eines für Serialisierung. Wer nur an einem bestimmten Attribut-Typ interessiert ist, sollte nicht alle Attribute abrufen und manuell filtern, sondern getAttributes() direkt mit einem Klassennamen und dem Flag ReflectionAttribute::IS_INSTANCEOF aufrufen. Das liefert nur Attribute, die exakt diesen Typ haben oder eine Unterklasse davon sind, und ist deutlich lesbarer als eine nachträgliche Filterung per array_filter.

Das IS_INSTANCEOF-Flag ist besonders wertvoll, wenn ein System mehrere verwandte Attribut-Typen unterstützt, etwa eine abstrakte Rule-Basisklasse mit konkreten Unterklassen wie EmailRule und LengthRule. Ohne dieses Flag müsste der aufrufende Code jeden konkreten Attribut-Namen einzeln kennen, mit dem Flag genügt die Kenntnis der gemeinsamen Basisklasse oder des gemeinsamen Interfaces.

<?php

declare(strict_types=1);

function findValidationAttributes(ReflectionProperty $property): array
{
    // Only fetch attributes matching Validate or a subclass of it
    return $property->getAttributes(Validate::class, ReflectionAttribute::IS_INSTANCEOF);
}

$reflection = new ReflectionClass(RegisterRequest::class);

foreach ($reflection->getProperties() as $property) {
    $validationAttributes = findValidationAttributes($property);

    if ($validationAttributes === []) {
        continue;
    }

    echo $property->getName() . ' has ' . count($validationAttributes) . ' validation rule(s)' . PHP_EOL;
}

4. Argumente auslesen: getArguments() versus newInstance()

Sobald man ein ReflectionAttribute-Objekt hat, gibt es zwei grundsätzlich unterschiedliche Wege, an die eigentlichen Werte zu kommen. getArguments() liefert die rohen, im Code übergebenen Argumente als assoziatives beziehungsweise gemischtes Array zurück, ohne den Konstruktor der Attribut-Klasse auszuführen. newInstance() hingegen erzeugt tatsächlich ein Objekt der Attribut-Klasse, ruft dabei deren Konstruktor auf und gibt eine vollständig initialisierte Instanz zurück.

Die Wahl zwischen beiden hat spürbare Konsequenzen. getArguments() ist schneller, weil kein Konstruktor läuft, aber man verliert jede Typprüfung und Validierungslogik, die im Konstruktor der Attribut-Klasse stecken könnte. newInstance() ist langsamer, garantiert aber, dass das Ergebnis ein valides Objekt der Attribut-Klasse ist, inklusive aller Konstruktor-Invarianten. Für Validierungs- und Routing-Systeme, bei denen Korrektheit wichtiger ist als der letzte Performance-Vorteil, ist newInstance() fast immer die richtige Wahl.

<?php

declare(strict_types=1);

$reflection = new ReflectionClass(RegisterRequest::class);
$property = $reflection->getProperty('email');

foreach ($property->getAttributes(Validate::class) as $attribute) {
    // Raw arguments, no constructor call, no type checking
    $raw = $attribute->getArguments();
    var_dump($raw); // ['email', 'message' => 'Ungültige E-Mail-Adresse']

    // Full instance, constructor runs, readonly properties are set
    $instance = $attribute->newInstance();
    echo $instance->rule . PHP_EOL;    // email
    echo $instance->message . PHP_EOL; // Ungültige E-Mail-Adresse
}

5. Repeatable Attributes: mehrere Instanzen verarbeiten

Standardmäßig darf ein Attribut an einer bestimmten Stelle im Code nur einmal deklariert werden. Für Fälle wie mehrere Routen auf derselben Methode oder mehrere Validierungsregeln auf demselben Feld ist das zu einschränkend. PHP löst das über das Flag Attribute::IS_REPEATABLE, das bei der Definition des Attributs gesetzt wird. Ist dieses Flag gesetzt, akzeptiert der Parser mehrere Deklarationen desselben Attributs an derselben Stelle, und getAttributes() liefert entsprechend mehrere ReflectionAttribute-Objekte zurück.

Ein typisches Beispiel ist ein Route-Attribut, das eine Controller-Methode für mehrere HTTP-Methoden oder mehrere URL-Pfade gleichzeitig registrierbar macht. Ohne IS_REPEATABLE müsste man entweder ein Array als Konstruktor-Argument übergeben, was die Lesbarkeit im Vergleich zu mehreren eigenständigen Attribut-Deklarationen verschlechtert, oder auf mehrere unterschiedlich benannte Attribute ausweichen, was ebenfalls unelegant ist.

<?php

declare(strict_types=1);

#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
final class Route
{
    public function __construct(
        public readonly string $method,
        public readonly string $path,
    ) {
    }
}

final class OrderController
{
    #[Route('GET', '/orders')]
    #[Route('GET', '/orders/list')]
    public function index(): array
    {
        return [];
    }
}

$method = new ReflectionMethod(OrderController::class, 'index');

foreach ($method->getAttributes(Route::class) as $attribute) {
    $route = $attribute->newInstance();
    echo $route->method . ' ' . $route->path . PHP_EOL;
}

6. Praxisbeispiel: ein attributbasierter Validator

Ein realistischer Anwendungsfall für ausgewertete Attribute ist ein einfacher Validator, der Regeln direkt an den Properties eines Datenobjekts liest, statt eine separate Validierungskonfiguration zu pflegen. Der Validator iteriert über alle Properties einer Klasse, liest die Validate-Attribute mit newInstance() aus und wendet die jeweilige Regel auf den aktuellen Wert der Property an. Fehlt ein Wert oder verletzt er die Regel, wird die im Attribut hinterlegte Fehlermeldung gesammelt.

Der entscheidende Vorteil gegenüber einer externen Konfigurationsdatei liegt in der Nähe von Regel und Feld: Ändert sich das Datenmodell, ändert sich die Validierungsregel direkt daneben im selben Quellcode, ohne eine zweite Datei synchron halten zu müssen. Genau dieses Muster nutzen moderne Validierungsbibliotheken in Symfony und Laravel, wobei sie intern exakt dieselbe Kombination aus getAttributes() und newInstance() einsetzen, die hier gezeigt wird.

7. Praxisbeispiel: attributbasiertes Routing

Attributbasiertes Routing ist ein weiteres verbreitetes Muster, bei dem statt einer zentralen Routing-Datei jede Controller-Methode ihre eigene Route-Deklaration direkt am Code trägt. Beim Start der Anwendung durchsucht ein Router alle Controller-Klassen, liest deren Methoden per ReflectionClass::getMethods() aus und sammelt für jede Methode die Route-Attribute in eine zentrale Routing-Tabelle. Dieser Aufbauschritt läuft idealerweise nur einmal, nicht bei jedem einzelnen Request.

Der Router selbst nutzt die gesammelten Route-Instanzen danach nur noch als reine Datenstruktur, ganz ohne weitere Reflection-Aufrufe im heißen Pfad. Diese Trennung, Reflection nur beim Aufbau, direkter Array-Zugriff bei jedem Request, ist entscheidend für die Performance eines attributbasierten Routers und wird im nächsten Abschnitt vertieft.

8. Performance: Attribut-Lookups cachen

Das Auswerten von Attributen über ReflectionAttribute ist nicht kostenlos: getAttributes() durchsucht die kompilierten Metadaten der Klasse, und newInstance() ruft zusätzlich den Konstruktor der Attribut-Klasse auf. In einem Routing-System mit hunderten Controller-Methoden, das bei jedem Request neu Routen aus Attributen aufbaut, summiert sich dieser Aufwand spürbar. Die Standardlösung ist, das Ergebnis der Attribut-Auswertung einmalig zu berechnen und danach in einem Cache abzulegen, etwa als serialisiertes Array in einer Datei oder in einem Objekt-Cache wie APCu.

Wichtig dabei ist die Unterscheidung zwischen Entwicklungs- und Produktionsumgebung: Während der Entwicklung soll sich eine Änderung an einem Attribut sofort auswirken, in Produktion hingegen ist der Cache genau der Grund, warum das System performant bleibt. Frameworks lösen das meist über einen Warmup-Befehl, der den Attribut-Cache einmal beim Deployment aufbaut, kombiniert mit einer Prüfung auf Dateiänderungszeitpunkte während der Entwicklung.

9. Attribute im Vergleich zu Docblock-Annotationen

Vor der Einführung nativer PHP-Attribute in PHP 8.0 wurden vergleichbare Metadaten häufig über Docblock-Kommentare in Freitextform abgebildet, etwa @Route("/orders"), und von Bibliotheken wie doctrine/annotations zur Laufzeit per Regex oder Docblock-Parser ausgewertet. Die folgende Tabelle stellt beide Ansätze gegenüber.

Die Tabelle macht deutlich, warum native PHP-Attribute Docblock-Annotationen in modernen Codebasen weitgehend abgelöst haben: Sie sind vom Sprachparser validiert, typisiert und ohne Zusatzbibliothek per ReflectionAttribute auswertbar, während Docblock-Annotationen immer eine separate Parsing-Schicht benötigten.

10. Zusammenfassung

Ein PHP-Attribut entfaltet seinen Wert erst, wenn Code es zur Laufzeit über ReflectionAttribute ausliest. getAttributes() liefert Metadaten-Objekte, getArguments() die rohen Konstruktor-Argumente ohne Typprüfung, und newInstance() eine vollständig validierte Instanz der Attribut-Klasse. Das Flag IS_INSTANCEOF filtert nach Typ inklusive Vererbung, das Flag IS_REPEATABLE erlaubt mehrere Deklarationen desselben Attributs an derselben Stelle.

In der Praxis entstehen aus dieser Kombination attributbasierte Validatoren und Router, die Konfiguration direkt neben den Code bringen, statt sie in separaten Dateien zu pflegen. Weil das Auswerten von Attributen über die Reflection API messbaren Overhead verursacht, gehört Caching der Auswertungsergebnisse in jedes produktive System, das Attribute in großem Umfang nutzt.

11. FAQ: PHP-Attribute zur Laufzeit auswerten