Doctrine Annotations zu Attributes: Entity-Mapping migrieren, bevor du upgraden kannst

#Doctrine Annotations zu Attributes

Gründer & Lead Developer

Experte für Softwareentwicklung und Legacy-Code-Optimierung

LinkedIn

Wenn deine Symfony-Anwendung Entities noch mit Kommentaren im Stil von @ORM\Column und @ORM\ManyToOne mappt, kannst du nicht auf Doctrine ORM 3 upgraden, ohne vorher die Umstellung von Doctrine Annotations zu Attributes zu erledigen. ORM 3 hat den Annotation-Treiber komplett entfernt, und Symfony 7 hat das Paket doctrine/annotations aus seinen Standardabhängigkeiten gestrichen. Das Mapping-Format, das praktisch jedes Symfony-Projekt von etwa 2010 bis 2022 genutzt hat, ist künftig keine Option mehr. Damit ist diese Migration eine Voraussetzung und kein nettes Aufräumprojekt für später.

Die gute Nachricht: Der Großteil der Arbeit ist mechanisch. Die schlechte Nachricht: „Großteil" heißt nicht „alles", und die Teile, die nicht mechanisch sind, sind genau die, die dir in Produktion um die Ohren fliegen, wenn du sie überhastest.

Warum das nicht mehr optional ist

Doctrine hat das Annotation-Mapping in den 2.x-Releases jahrelang als deprecated markiert, und die meisten Teams haben den Hinweis so behandelt, wie die meisten Teams Deprecation-Hinweise behandeln: als Problem fürs nächste Quartal. Doctrine ORM 3 hat den doctrine/annotations-Treiber aus seinem Abhängigkeitsbaum entfernt. Ein Projekt, das auf ORM 2 festgepinnt ist, kann also weiter mit Annotations laufen, aber alles, was auf ORM 3 geht, muss stattdessen mit nativen PHP-8-Attributes mappen.

Symfony 7 hat unabhängig davon dieselbe Entscheidung getroffen. doctrine/annotations wird von symfony/framework-bundle nicht mehr vorausgesetzt, und neue Symfony-Skeletons kommen ohne das Paket. Wenn deine composer.json es noch als direkte Abhängigkeit führt, ist das meist ein Projekt, das seine Mapping-Strategie seit Symfony 4 oder 5 nicht mehr angefasst hat.

Am stärksten spürst du das beim Symfony-Upgrade-Pfad, den wir in unserem Leitfaden zum Upgrade auf Symfony 7 beschrieben haben: Du kannst dieses Upgrade, oder den parallelen Wechsel auf Doctrine ORM 3, nicht abschließen, solange noch Annotation-Mapping im Code steckt. Die Umstellung muss zuerst passieren, als eigener Pull Request, bevor das Framework-Upgrade landet.

Doctrine Annotations zu Attributes: Was sich im Mapping ändert

PHP-Attributes und Doctrine Annotations beschreiben dieselben Metadaten. Die Syntax ist eine andere, und auch die Art, wie PHP sie liest.

Eine Annotation lebt in einem Docblock-Kommentar:

/**
 * @ORM\Entity(repositoryClass=InvoiceRepository::class)
 * @ORM\Table(name="invoices")
 */
class Invoice
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private int $id;

    /**
     * @ORM\ManyToOne(targetEntity=Client::class, inversedBy="invoices")
     * @ORM\JoinColumn(nullable=false)
     */
    private Client $client;
}

Ein Attribute ist ein natives PHP-Sprachkonstrukt, das die Engine selbst parst, statt eines Docblock-Readers:

#[ORM\Entity(repositoryClass: InvoiceRepository::class)]
#[ORM\Table(name: 'invoices')]
class Invoice
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private int $id;

    #[ORM\ManyToOne(targetEntity: Client::class, inversedBy: 'invoices')]
    #[ORM\JoinColumn(nullable: false)]
    private Client $client;
}

Zwei Unterschiede verursachen die meisten echten Bugs bei dieser Migration. Erstens nutzen Annotation-Argumente =, Attribute-Argumente dagegen :. Wer Code von Hand kopiert und den Unterschied übersieht, bekommt einen Parse-Fehler, den die IDE womöglich erst zur Laufzeit meldet. Zweitens werden Attributes beim Kompilieren vom PHP-Parser validiert. Ein Tippfehler im Argumentnamen eines Attributes scheitert also laut, während derselbe Tippfehler in einem Annotation-Docblock oft still scheitert, weil der Annotation-Reader von Doctrine nachsichtiger mit unbekannten Schlüsseln umgeht.

Rector für die mechanische Umstellung

Rector hat ein eigenes Regelset genau für diese Migration, und bei einer typischen Entity mit Standard-Doctrine-Mappings bringt es dich automatisch den größten Teil des Weges. Den allgemeinen Ablauf haben wir in unserem Leitfaden zu Rector für Legacy-PHP beschrieben, und die Doctrine-spezifische Konfiguration ist eine kurze Ergänzung dieses Setups:

use Rector\Doctrine\Set\DoctrineSetList;

$rectorConfig->sets([
    DoctrineSetList::ANNOTATIONS_TO_ATTRIBUTES,
]);

Lässt du das auf ein echtes Entity-Verzeichnis los, konvertiert Rector @ORM\Column, @ORM\Id, @ORM\GeneratedValue, die Beziehungs-Mappings (@ORM\ManyToOne, @ORM\OneToMany, @ORM\ManyToMany), Index- und Unique-Constraint-Definitionen sowie Lifecycle-Callbacks korrekt. In den mittelgroßen Symfony-Codebasen, an denen wir arbeiten, wird die große Mehrheit der Mapping-Zeilen sauber und ohne Handarbeit umgestellt, weil Standard-Spalten- und Beziehungs-Mappings einem kleinen, vorhersehbaren Satz von Mustern folgen, mit dem ein regelbasiertes Tool gut umgehen kann.

Starte immer zuerst mit --dry-run und prüf den Diff Entity für Entity, statt einer grünen Pipeline blind zu vertrauen. Rector bricht nicht bei Code ab, den es nicht versteht, aber es hinterlässt manchmal eine Mischung aus alter und neuer Syntax in einer Datei, wenn ein Docblock etwas enthält, das es nicht sauber parsen kann. Eine gemischte Datei ist schlimmer als eine unkonvertierte, weil sie fertig aussieht.

Wo Rector nicht helfen kann

Die restlichen 15 % ballen sich meist an drei Stellen.

Eigene oder projektspezifische Annotations sind die häufigste Lücke. Wenn dein Team eigene Annotation-Klassen für Fachkonzepte geschrieben hat, etwa einen @Auditable-Marker oder eine @SoftDeletable-Trait-Annotation, weiß das Doctrine-Regelset von Rector nichts davon und lässt sie unangetastet. Das Attribute-Gegenstück musst du von Hand schreiben, inklusive der Attribute-Klasse selbst, falls es sie noch nicht gibt, und danach jede Entity anpassen, die die alte Annotation nutzt.

Validator- und Serializer-Gruppen sind die zweite Lücke, und die, die am ehesten einen Produktionsbug auslöst, den niemand bemerkt, bis eine Formularvalidierung still nicht mehr greift. Symfonys Validierungs-Constraints und Serializer-Gruppen unterstützen beide die Annotation-Syntax (@Assert\NotBlank, @Groups({"invoice:read"})), und beide haben Attribute-Gegenstücke (#[Assert\NotBlank], #[Groups(['invoice:read'])]). Das Doctrine-Regelset von Rector fasst diese nicht an, solange du nicht zusätzlich die Symfony-spezifischen Regelsets für Validator- und Serializer-Attributes aktivierst. Und selbst dann lohnt es sich, gruppierte Annotations mit mehreren Gruppennamen in einem Docblock von Hand zu prüfen, denn die geänderte Array-Syntax ist eine bequeme Stelle, um still eine Gruppe zu verlieren.

Mapped Superclasses und Trait-basiertes Mapping sind die dritte. Wenn Entities Spaltendefinitionen über einen Trait oder eine @ORM\MappedSuperclass teilen, verarbeitet Rector jede Datei einzeln. Es kann dann im Trait eine korrekte Attribute-Umstellung erzeugen und gleichzeitig übersehen, dass der Docblock des Traits auch Annotations auf Klassenebene trug, die in die Klasse wandern müssen, die den Trait nutzt, und nicht in den Trait selbst.

Die Alternative: XML-Mapping

Doctrine unterstützt neben Annotations und Attributes weiterhin XML-Mapping-Dateien als dritte Option, und für eine bestimmte Art von Projekt lohnt es sich, das statt einer vollständigen Attribute-Umstellung zu erwägen. Wenn deine Entities generiert oder stark templatebasiert sind, zum Beispiel aus einem Database-First-Scaffold, trennt XML-Mapping die Metadaten komplett vom Code und du musst während der Migration gar keine PHP-Klassen anfassen.

Für die meisten handgeschriebenen Symfony-Anwendungen ist das der falsche Tausch. Mit XML-Mapping verraten dir deine Entity-Klassen ihr eigenes Mapping nicht mehr, was Code Reviews und die Navigation in der IDE verschlechtert, und kaum jemand entscheidet sich künftig noch dafür. Wir erwähnen es vor allem, weil Teams es manchmal vorschlagen, um die Migration zu „umgehen". Gut zu wissen ist von Anfang an: Es tauscht eine Wartungslast gegen eine andere, statt die Arbeit zu beseitigen.

Das Ergebnis prüfen

Doctrine bringt für genau diese Art von Änderung eine eingebaute Prüfung mit:

php bin/console doctrine:schema:validate

Der Befehl vergleicht deine Mapping-Metadaten mit dem tatsächlichen Datenbankschema und mit den internen Konsistenzregeln von Doctrine. Er findet einen falschen Spaltentyp, eine fehlende inverse Seite einer Beziehung oder ein Mapping, das nicht mehr auf eine gültige Klasse auflöst. Führ ihn vor der Migration als Ausgangswert aus und dann erneut nach jedem Konvertierungs-Batch. So bleibt ein Problem, das die Umstellung eingeführt hat, auf die Entities beschränkt, die du in diesem Batch angefasst hast, statt in einem Berg von Änderungen unterzugehen.

Einen vollständigen Ersatz für deine Testsuite ist das nicht. doctrine:schema:validate prüft strukturelle Konsistenz, kein Anwendungsverhalten. Eine Validierungsgruppe, die still einen Constraint verloren hat, besteht die Schema-Validierung und bricht trotzdem zur Laufzeit die Formularvalidierung. Lass deshalb auch deine bestehende funktionale Testsuite gegen die konvertierten Entities laufen, besonders alles, was Serialisierung oder Formularübermittlung abdeckt.

In kleinen Pull Requests vorgehen

Der Fehler, den wir bei dieser Migration am häufigsten sehen, ist keine schlechte Konvertierung. Es ist ein riesiger Pull Request über 150 Entities, der zu groß ist, als dass ihn jemand ordentlich reviewen könnte. Er wird auf Vertrauen genehmigt und gemergt, und der Bug in der Validierungsgruppe taucht drei Wochen später in Produktion auf, ohne einen klaren Diff, auf den man zeigen könnte.

Teil die Arbeit nach Fachbereichen statt nach Dateianzahl auf: Rechnungs-Entities in einen Pull Request, User- und Auth-Entities in einen zweiten, Katalog-Entities in einen dritten. Lass Rector auf jeden Batch einzeln laufen, führ nach jedem Batch doctrine:schema:validate aus und prüf die Validator- und Serializer-Annotations in genau diesem Batch von Hand, denn die hat Rector nicht für dich umgestellt. Eine Reviewerin, die den ganzen Diff in einem Rutsch lesen kann, findet den verlorenen Gruppennamen, den ein durchgewunkener Diff mit 4.000 Zeilen nie zeigt.

Für diese Migration gibt es keine Frist, die eine laufende Anwendung erzwingt, denn Annotation-Mapping funktioniert auf ORM 2 und älteren Symfony-Versionen unbegrenzt weiter. Die Frist setzt das Upgrade, das du als nächstes machen willst. Die Attribute-Umstellung jetzt in bewussten, reviewbaren Batches zu erledigen, ist deutlich günstiger, als später festzustellen, dass sie dein Upgrade auf Symfony 7 oder Doctrine ORM 3 blockiert, dann unter mehr Zeitdruck und mit weniger Wissen darüber, warum eine bestimmte Annotation so geschrieben wurde.

Wenn du diese Umstellung in einer großen Legacy-Codebasis vor dir hast und vor dem Merge ein zweites Paar Augen auf die Sonderfälle bei Validator und Serializer möchtest, schreib Wolf-Tech. Wir machen diese Art von Migration im Rahmen unserer Legacy-Code-Modernisierung und schauen uns lieber deinen Batch-Plan an, bevor die Pull Requests rausgehen, als hinterher eine verlorene Validierungsgruppe zu debuggen. Mehr dazu, wie wir arbeiten, findest du auf wolf-tech.io.