Seit PHP 8.0 gibt es Attributes, eine native Möglichkeit, Metadaten an Klassen, Methoden, Eigenschaften, Parameter und Funktionen anzuhängen. Attributes ersetzen die früher üblichen Docblock-Annotations und werden direkt von PHP verarbeitet. Frameworks wie Laravel und Symfony nutzen Attributes für Routing, Validierung und Dependency Injection. In diesem Tutorial lernst du die Syntax, eingebaute Attributes, die Erstellung eigener Attribute-Klassen und das Auslesen per Reflection.
Zuerst wird das Grundkonzept von Attributes erklärt, bevor es um die Syntax, eingebaute Attributes und das Erstellen eigener Attribute-Klassen geht.
Was sind PHP Attributes?
Attributes sind strukturierte Metadaten, die an Code-Elemente angefügt werden. Sie haben keine direkte Auswirkung auf die Ausführung des Codes. Stattdessen werden sie per Reflection API ausgelesen und von Frameworks oder eigenem Code interpretiert. Attributes sind Klassen, die mit dem speziellen Marker #[Attribute] versehen sind. Sie wurden mit PHP 8.0 eingeführt und ersetzen zunehmend die früher gebräuchlichen Docblock-Annotations.
Syntax der Attributes
Attributes werden mit der Syntax #[AttributeName] direkt vor dem Code-Element platziert. Parameter können wie bei einem Konstruktoraufruf übergeben werden.
<?php
class Rechner
{
#[Deprecated(message: 'Verwende addiere() stattdessen')]
public function plus(int $a, int $b): int
{
return $this->addiere($a, $b);
}
public function addiere(int $a, int $b): int
{
return $a + $b;
}
}
Das Attribute #[Deprecated] markiert die Methode plus() als veraltet. PHP und Entwicklungsumgebungen können diese Information nutzen, um Warnungen auszugeben.
Eingebaute Attributes
PHP bringt einige Attributes von Haus aus mit, die ohne eigene Definition verwendet werden können.
#[Deprecated]
Markiert Funktionen, Methoden oder Klassen als veraltet. Ab PHP 8.4 erzeugt der Aufruf einer so markierten Funktion eine Deprecation-Warnung. Der Parameter message gibt an, welche Alternative verwendet werden soll.
#[Override]
Seit PHP 8.3 stellt #[Override] sicher, dass eine Methode tatsächlich eine Methode der Elternklasse überschreibt. Wenn die Elternklasse die Methode nicht hat, wirft PHP einen Fehler. Das verhindert Tippfehler in Methodennamen und erhöht die Sicherheit bei Refactoring.
#[SensitiveParameter]
Verhindert, dass ein Parameter in Stack-Traces oder Fehlermeldungen angezeigt wird. Das ist wichtig für Passwörter, API-Schlüssel und andere sensible Daten.
<?php
function anmelden(
string $benutzername,
#[SensitiveParameter] string $passwort
): bool {
/* Login-Logik */
return true;
}
Eigene Attribute-Klassen erstellen
Eigene Attributes werden als gewöhnliche PHP-Klassen definiert, die selbst mit #[Attribute] markiert sind.
Attribute-Klasse definieren
<?php
#[Attribute(Attribute::TARGET_METHOD)]
class Route
{
public function __construct(
public string $pfad,
public string $methode = 'GET'
) {}
}
class ApiController
{
#[Route('/benutzer', methode: 'GET')]
public function liste(): array
{
return ['Max', 'Anna'];
}
#[Route('/benutzer', methode: 'POST')]
public function erstellen(): void
{
/* Benutzer anlegen */
}
}
Die Attribute-Klasse Route wird mit #[Attribute(Attribute::TARGET_METHOD)] markiert. Der Parameter TARGET_METHOD legt fest, dass dieses Attribute nur an Methoden angebracht werden darf.
Ziele festlegen mit Attribute::TARGET_*
PHP bietet verschiedene Zieltypen, die bestimmen, wo ein Attribute verwendet werden darf:
Attribute::TARGET_CLASS für KlassenAttribute::TARGET_METHOD für MethodenAttribute::TARGET_PROPERTY für EigenschaftenAttribute::TARGET_PARAMETER für ParameterAttribute::TARGET_FUNCTION für FunktionenAttribute::TARGET_CLASS_CONSTANT für KlassenkonstantenAttribute::TARGET_ALL für alle Elemente (Standard)
Mehrere Ziele lassen sich mit dem Oder-Operator kombinieren: Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION. Wird kein Zieltyp angegeben, gilt standardmäßig Attribute::TARGET_ALL, und das Attribute kann an jedem beliebigen Code-Element platziert werden.
Wenn ein Attribute an einem nicht erlaubten Element verwendet wird, wirft PHP beim Instanziieren per Reflection einen Fehler. Die Einschränkung schützt vor versehentlicher Fehlplatzierung und dokumentiert gleichzeitig, für welche Elemente das Attribute gedacht ist.
Wiederholbare Attributes (IS_REPEATABLE)
Standardmäßig darf ein Attribute nur einmal pro Element verwendet werden. Mit Attribute::IS_REPEATABLE kann ein Attribute mehrfach auf dasselbe Element angewendet werden. Das ist nützlich, wenn ein Element mehrere Werte desselben Attributs tragen soll, beispielsweise mehrere Routen für dieselbe Controller-Methode.
<?php
#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
class Route
{
public function __construct(
public string $pfad,
public string $methode = 'GET'
) {}
}
class ApiController
{
#[Route('/benutzer')]
#[Route('/users')]
public function liste(): array
{
return ['Max', 'Anna'];
}
}
Beide Routen werden per Reflection als separate Attribute-Instanzen ausgelesen und können im Router unabhängig voneinander registriert werden.
Attributes per Reflection auslesen
Attributes werden erst bei Bedarf instanziiert, nämlich wenn sie per Reflection API ausgelesen werden. Das bedeutet, dass Attributes keine Performance-Kosten verursachen, solange sie nicht aktiv abgefragt werden.
<?php
$reflection = new ReflectionClass(ApiController::class);
foreach ($reflection->getMethods() as $method) {
$attributes = $method->getAttributes(Route::class);
foreach ($attributes as $attr) {
$route = $attr->newInstance();
echo $route->methode . ' ' . $route->pfad . PHP_EOL;
}
}
/* Ausgabe:
GET /benutzer
POST /benutzer */
Die Methode getAttributes() gibt ein Array von ReflectionAttribute-Objekten zurück. Mit newInstance() wird das Attribute instanziiert und der Konstruktor mit den angegebenen Parametern aufgerufen. Ab diesem Moment steht das Attribute als vollwertiges PHP-Objekt zur Verfügung. Ohne den Aufruf von newInstance() wird das Attribute nicht instanziiert, was bedeutet, dass Attributes keine Performance-Kosten verursachen, solange sie nicht aktiv per Reflection abgefragt werden.
Attributes vs. Annotations (Docblocks)
Vor PHP 8 wurden Metadaten häufig als Docblock-Annotations in Kommentaren hinterlegt (z.B. @Route, @Inject). Diese wurden von Frameworks per String-Parsing ausgelesen und waren fehleranfällig. Attributes bieten mehrere Vorteile gegenüber diesem Ansatz:
- Attributes sind native PHP-Syntax und werden vom Parser validiert.
- Tippfehler in Attribute-Namen führen zu einem Fehler statt zu stillem Versagen.
- Attributes sind echte Klassen und können typisierte Konstruktor-Parameter haben.
- IDE-Unterstützung mit Autovervollständigung und Refactoring funktioniert zuverlässig.
- Performance ist besser, da kein Parsing von Kommentarblöcken zur Laufzeit nötig ist.
Trotz dieser Vorteile sind Docblock-Annotations nicht vollständig verschwunden. Viele ältere Projekte verwenden sie weiterhin, und einige Tools wie PHPStan und Psalm nutzen Docblocks für erweiterte Typinformationen, die über die Möglichkeiten von PHP-Attributen hinausgehen. In neuen Projekten sollten jedoch Attributes bevorzugt werden, wo immer das möglich ist.
Attributes in der Praxis
Routing mit Attributes
Moderne PHP-Frameworks verwenden Attributes für die Definition von Routen direkt an Controller-Methoden. Statt einer separaten Routing-Konfiguration steht die Route direkt am Code, der sie verarbeitet. In Symfony ist das Attribute #[Route('/api/users', methods: ['GET'])] der empfohlene Weg zur Routendefinition. Das Prinzip der Colocation (Konfiguration dort, wo sie gebraucht wird) verbessert die Übersichtlichkeit und reduziert die Notwendigkeit, zwischen verschiedenen Dateien zu wechseln.
Validierung mit Attributes
Attributes eignen sich für die Definition von Validierungsregeln an Eigenschaften einer Klasse.
<?php
#[Attribute(Attribute::TARGET_PROPERTY)]
class MaxLength
{
public function __construct(
public int $laenge
) {}
}
class Benutzer
{
#[MaxLength(laenge: 50)]
public string $name;
#[MaxLength(laenge: 255)]
public string $email;
}
Ein Validator kann per Reflection die MaxLength-Attributes auslesen und die Werte entsprechend prüfen.
flowchart TD
A["#[Route('/api')]<br>Attribute am Code"] --> B["Reflection API"]
B --> C["getAttributes()"]
C --> D["newInstance()"]
D --> E["Route-Objekt<br>pfad: '/api'<br>methode: 'GET'"]
style A fill:#fcf,stroke:#333
Typische Fehler und Stolperfallen
Beim Arbeiten mit Attributes gibt es einige häufige Fehlerquellen:
- Vergessen von
#[Attribute] an der eigenen Attribute-Klasse. Ohne diese Markierung wirft PHP beim Instanziieren einen Fehler. - Die TARGET-Einschränkung wird vergessen, und das Attribute wird an einem nicht erlaubten Element platziert.
- Attributes werden erst bei Reflection instanziiert, nicht beim Laden der Klasse. Fehler im Konstruktor des Attributes treten erst auf, wenn
newInstance() aufgerufen wird. - Verwechslung von PHP-Attributes mit HTML-Attributen. Trotz des gleichen Namens haben sie nichts miteinander zu tun.
- Attributes sind kein Ersatz für Konfigurationsdateien in allen Fällen. Umgebungsabhängige Konfigurationen gehören weiterhin in externe Dateien.
Fazit
PHP Attributes sind eine leistungsfähige Ergänzung seit PHP 8.0. Sie ermöglichen es, Metadaten typsicher und nativ an Code-Elemente anzufügen. Eingebaute Attributes wie #[Deprecated], #[Override] und #[SensitiveParameter] decken häufige Anforderungen ab. Eigene Attribute-Klassen erweitern die Möglichkeiten für Routing, Validierung und andere Framework-Funktionalitäten. Per Reflection API lassen sie sich gezielt auslesen und verarbeiten. In modernen PHP-Projekten ersetzen Attributes zunehmend die früheren Docblock-Annotations.
