Konvertierung von PHP Klassen Annotationen in PHP-Attribute
Seit Jahren stützte sich Drupal auf die Bibliothek doctrine/annotations, um Plugin-Klassen mit Metadaten zu versehen. Dieser Ansatz funktioniert über Docblock-Kommentare – die /** ... */-Blöcke, die oberhalb von Klassendefinitionen angelegt sind. So praktisch diese Methode auch ist, hat sie mehrere Einschränkungen und wird in Zukunft durch PHP Attributes ersetzt werden.
In diesem Blogbeitrag werden die Änderungen anhand des bekannten migrate_plus Moduls näher beschrieben.
Die Veröffentlichung der Version 6.0.9 des Drupal-Moduls migrate_plus führte eine bedeutende Breaking Change ein, die Entwickler betrifft, die benutzerdefinierte Migrations-Plugins pflegen: Das Modul erlaubt nun, dass Plugins PHP-Attribute neben den älteren Doctrine-Annotationssyntax verwenden können.
Diese Umstellung ist nicht auf migrate_plus beschränkt, sondern spiegelt eine breitere Bewegung im gesamten Drupal-Ökosystem wider, Plugin-Definitionen mithilfe nativer Sprachfunktionen von PHP 8.1+ darzustellen.
Update zu Problemen mit migrate_plus DataParser-Plugins
Das Problem mit den nicht funktionierenden migrate_plus DataParser-Plugins in Version 6.0.9 war durch folgenden Fehler verursacht: Syntax error in DataParserPluginManager, der heute (23.01.2026) mit der Veröffentlichung der Version 6.0.10 behoben wurde.
Warum ist eine Umstellung auf PHP Attribute sinnvoll?
Bevor wir in die technische Umsetzung betrachten, ist es wichtig zu verstehen, warum dieser Breaking Change existiert und welches Problem es lösen soll.
Die Probleme mit Doctrine-Annotationen
Seit Jahren stützte sich Drupal auf die Bibliothek doctrine/annotations, um Plugin-Klassen mit Metadaten zu versehen. Dieser Ansatz funktioniert über Docblock-Kommentare – die /** ... */-Blöcke, die oberhalb von Klassendefinitionen angelegt sind. So praktisch diese Methode auch ist, hat sie mehrere Einschränkungen:
- Performance overhead. Annotationen werden zur Laufzeit interpretiert. Der zusätzliche Parsing-Schritt fügt während der Plugin-Erkennung Overhead hinzu, den Drupal zwar durch Caching abmildert, aber nicht vollständig beseitigen kann. Für große Sites mit vielen Plugins kann dies spürbare Auswirkungen haben.
- Fehleranfällige Syntax. Da Annotationen in Kommentaren existieren, sind sie anfällig für einfache Formatierungsfehler. Diese Fehler sind schwer zu debuggen, da sie zur Laufzeit auftreten und nicht während der statischen Analyse.
- Wartungsaufwand. Die Bibliothek doctrine/annotations wird nicht mehr aktiv gepflegt und wurde von ihren Maintainers als veraltet eingestuft.
- Begrenzte IDE-Integration. Da Annotationen in Kommentaren statt im Code stehen, können IDEs dafür nativ keine Autovervollständigung, Typ-Hinweise oder Navigationsfunktionen bereitstellen.
PHP-Attribute: Die Lösung des Problems
PHP 8.0 führte native Attribute ein. Damit wird ein Sprachfeature beschrieben, das speziell zur Lösung des Metadatenproblems entwickelt wurde. Während der anfänglichen Implementierung von PHP 8.0 die Unterstützung für verschachtelte Attribute fehlte (die für die komplexen Plugin-Metadaten von Drupal unerlässlich sind), fügte PHP 8.1 diese Fähigkeit hinzu und machte Attribute damit für die Anforderungen von Drupal nutzbar.
Attribute bieten mehrere Vorteile gegenüber Annotationen::
- Verarbeitung zur Zeit der Kompilierung. PHP verarbeitet Attribute während der Kompilierung, nicht zur Laufzeit. Dadurch entfällt der Parsing-Overhead vollständig und die Plugin-Erkennung wird schneller.
- Typsicherheit und Validierung. Da Attribute Teil der PHP-Sprache selbst sind, unterliegen sie derselben Validierung wie regulärer Code. Ungültige Syntax wird sofort erkannt und nicht erst später zur Laufzeit entdeckt.
- IDE-Unterstützung. Moderne IDEs erkennen Attribute als native Sprachkonstrukte und bieten vollständige Autovervollständigung, Type-Hinting und Code-Navigation.
- Klare Semantik. Die Verwendung der Syntax #[AttributeName] macht Metadaten eindeutig von Dokumentationskommentaren unterscheidbar. Der Code ist besser lesbar und wartbarer.
- Zukunftssicher. Während sich PHP weiterentwickelt, werden Attribute Teil dieser Entwicklung sein. Drupal wird somit nicht von einer Third-Party Bibliothek abhängig sein.
Step-by-Step Umstellung für migrate_plus
Als Beispiel für die Konvertierung nehmen wir ein einfaches migrate_plus-Plugin und zeigen, was geändert werden muss.
Step 1: Benutzerdefinierte migrate_plus-Plugins lokalisieren
Das migrate_plus Modul unterstützt die folgenden Plugintypen.
your_module/
├── src/
│ └── Plugin/
│ └── migrate_plus/
│ ├── data_parser/ (data parser plugins)
│ └── data_fetcher/ (data_fetcher plugins)
│ └── authentication/ (authentication plugins)Step 2: use Statements hinzufügen
Für unser Beispiel nehmen wir ein data_parser-Plugin. Hier müssen wir die nötigen use Statements hinzufügen.
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\migrate_plus\Attribute\DataParser;Step 3: Annotations in Attribute umwandeln
Docblock-Annotation entfernen und durch Attribut-Deklarationen ersetzen.
Vorher
/**
* Data parser plugin description.
*
* @DataParser(
* id = "my_data_parser_plugin_id",
* title = @Translation("My custom data parser plugin")
* )
*/
class MyDataParserPlugin implements DataParserPluginInterface {
// Plugin code.
}Nachher
/**
* Data parser plugin description.
*/
#[DataParser(
id: 'my_data_parser_plugin_id',
title: new TranslatableMarkup('My custom data parser plugin')
)]
class MyDataParserPlugin implements DataParserPluginInterface {
// Plugin code.
}Wesentliche Änderungen:
- Attributdefinitionen aus den Doctrine Annotations extrahieren
- Nutzung von id: anstelle von id =
- Änderung von "string" in 'string'
Step 4: Testen und überprüfen
Nachdem die Plugins entsprechend angepasst wurden, muss der Drupal Cache einmal neu aufgebaut werden.
drush cache:rebuildIm Anschluss kann geprüft werden, ob die Plugins wieder korrekt erkannt werden.
drush migrate:statusDies sollte keine Fehler verursachen und die Migration sollte ohne Probleme ausgeführt werden können.
Besonderheiten bei Update auf migrate_plus 6.0.9
Die Version 6.0.9 migrate_plus module bringt als Neuerung die Umstellung auf PHP Attributes mit sich ( d.o/3541220).
- Abwärtskompatibilität ist gegeben. Genau wie im Drupal-Core (wo Annotationen und Attribute nebeneinander existieren) ermöglicht migrate_plus 6.0.9 Plugins die Verwendung von Attributen und auch der alten, auf Annotationen basierenden Syntax.
- Betreffende Plugins sollten aktualisiert werden. Wenn bestehende Migration auf benutzerdefinierten Plugintypen basieren, sollten diese konvertiert werden. Selbst wenn Migrations-Plugins annotationsbasierte und attributbasierte Plugins mischen, ist man mit einer Konvertierung für die Zukunft besser gerüstet.
Weitere Quellen:
