Du übernimmst eine Magento-2-Codebase. Um schnell zu verstehen, womit du es zu tun hast, fährst du den einen Befehl, der nie lügt: find app/code -name di.xml | xargs grep -l '<preference'. Raus kommt eine Liste mit Dutzenden Treffern, und ein einzelnes Modul bringt es allein auf über zwanzig Preferences. Nach dem dritten Bildschirm hörst du auf zu scrollen. Im README stand davon kein Wort.
<preference> selbst ist nicht das Problem. An der richtigen Stelle ist es genau das richtige Werkzeug. Das Problem ist, <preference> als Reflex für „hier will ich Verhalten ändern" einzusetzen, wenn ein Plugin oder ein Event Observer denselben Job ohne die Nebenkosten erledigt hätte. Wenn wir so eine Codebase auf den Tisch bekommen, haben sich diese Kosten meist schon über drei Jahre und sieben Entwickler aufsummiert, und keiner weiß mehr, welche Preferences tragend sind und welche nur Experimente waren, die es versehentlich in Production geschafft haben.
TL;DR
- Die Reihenfolge, die zählt: Observer zuerst, Plugin an zweiter Stelle, Preference als letztes Mittel. Observer sind die Event-Hooks, für die das Framework gebaut wurde. Plugins sind ein komponierbarer Weg, Verhalten zu verändern. Preferences ersetzen eine Klasse global und sollten die Ausnahme bleiben, mit guter Begründung.
-
Eine
<preference>in derdi.xmltauscht eine Klasse systemweit aus. Jedesnew $classim Code bekommt deine Ersatzklasse, überall, egal ob der Aufrufer damit rechnet oder nicht. - Ein Plugin auf derselben Klasse wrappt nur Methoden. Es lässt sich mit anderen Plugins kombinieren, übersteht Signaturänderungen im Core deutlich robuster und hindert niemanden daran, die Klasse ebenfalls zu erweitern.
-
Preference ist die richtige Wahl bei abstrakten Factories, Adaptern hinter einem Interface und einer kleinen Gruppe von Service-Contract-Implementierungen. Die falsche Wahl ist sie bei Core-Models, HTTP-Controllern, Blocks und fast allem unter
Magento\Framework\. -
Vier Fehlermuster sehen wir immer wieder: zwei Module überschreiben dieselbe Klasse und einer gewinnt einfach still, Upgrade-Verfall, wenn sich eine Core-Methodensignatur ändert, Security-Plugins, die durch wirkungslose Stubs ersetzt werden, und Kindklassen, die
parent::__construct()auskommentiert haben, um einer geänderten Argumentliste aus dem Weg zu gehen. - Der Audit dazu ist billig: ein Grep, ein Nachmittag Lesearbeit, eine Tabelle mit „safe / risky / incident" pro Treffer. Mehr Aufwand ist es nicht.
Observer, Plugin und <preference>: der Unterschied auf DI-Ebene
Magento gibt dir drei Erweiterungspunkte an die Hand, und die sind alles andere als gleichwertig.
Ein Event Observer (events.xml plus Observer-Klasse) feuert, sobald das Framework ein benanntes Event dispatcht. Er ist genau dafür gedacht, auf Dinge zu reagieren, die bereits passiert sind: Bestellung aufgegeben, Produkt gespeichert, Kunde eingeloggt. Observer verändern keine Rückgabewerte, wrappen keine Konstruktoren und geraten mit nichts in Konflikt. Sie sind der reibungsloseste Erweiterungspunkt und sollten immer deine erste Wahl sein.
Ein Plugin (in der di.xml über einen <type>-Knoten deklariert) wrappt eine konkrete Methode einer Klasse, ohne die Klasse selbst zu ersetzen. Hooks wie beforeSave, aroundExecute oder afterGetName legen sich um die Methode. Das Originalobjekt bleibt erhalten, der Originalkonstruktor läuft unverändert durch, und mehrere Plugins aus mehreren Modulen stapeln sich in einer klar definierten sortOrder. Greif zu Plugins, wenn du Methoden-Input oder -Output verändern musst und kein passendes Event existiert.
Eine <preference> sagt dem DI-Compiler von Magento: „Immer wenn jemand den Object Manager nach einer Instanz von Klasse A fragt, gib ihm stattdessen eine Instanz von Klasse B." Das ist ein globaler Klassentausch zur Compile-Zeit. new \Magento\Catalog\Model\Product(...) liefert selbst im Core-Code deine Product-Subklasse zurück, weil der Object Manager die Preference aufgelöst hat. Das ist die letzte Option, und nur für die engen Fälle weiter unten.
Der Unterschied zwischen Plugin und Preference zeigt sich an drei Stellen, an denen es wirklich wehtut:
Komposition. Zwei Module können Plugins auf derselben Methode deklarieren, und beide laufen. Zwei Module können keine Preferences auf derselben Klasse deklarieren und erwarten, dass beide laufen. Einer gewinnt, still, abhängig von der Modul-Ladereihenfolge.
Upgrade-Angriffsfläche. Ein Plugin interessiert sich für die Signatur einer einzigen Methode. Eine Preference interessiert sich für die komplette Klasse: Konstruktorargumente, Methodensignaturen, sogar die Reihenfolge privater Properties, auf die irgendwo per Reflection zugegriffen wird. Ändert Magento 2.4.7 ein Konstruktorargument an einem Core-Model, bricht jede Preference auf diesem Model, oder, schlimmer, sie hinkt nur noch.
Auffindbarkeit. Ein Plugin taucht im Stacktrace unter seinem eigenen Klassennamen auf. Eine Preference ersetzt die Klasse komplett: Der Stacktrace zeigt zwar deine Klasse, aber ohne einen eigenen Marker findet keine Code-Suche den Override, es sei denn, sie durchsucht gezielt die di.xml.
Wann <preference> tatsächlich die richtige Wahl ist
Magento selbst liefert Preferences aus. Die Regel lautet nicht „nie verwenden", sondern „nur dort verwenden, wo es der dafür vorgesehene Erweiterungspunkt ist".
Zwei Szenarien, in denen Preference die richtige Antwort ist:
-
Abstrakte Factories und Interfaces ohne Default.
Magento\Framework\Filesystem\DriverInterfacewird mitFileals Default ausgeliefert, festgezurrt über eine Preference. Genau dafür ist der DI-Mechanismus im Core gebaut. - Adapter-Klassen hinter einem Service Contract. Wenn du den Search-Client-Adapter oder den Messaging-Queue-Treiber durch eine eigene Implementierung ersetzt, ist Preference die idiomatische Wahl, weil das Interface der eigentliche Vertrag ist und der Adapter nur ein Implementierungsdetail.
Ist die Klasse, die du preferencen willst, konkret statt abstrakt, greif stattdessen zu Observer oder Plugin. Passt keins von beiden sauber, ist das ein Signal, dass das Design überdacht werden muss, nicht ein Signal, zur Preference zu greifen.
Fehlermuster 1: zwei Module, ein Gewinner, stiller Datenverlust
Zwei Marketplace-Module deklarieren beide eine <preference> für Magento\Catalog\Model\Product. Modul A überschreibt die Klasse, um beim Speichern die Groß-/Kleinschreibung von SKUs zu normalisieren. Modul B überschreibt dieselbe Klasse, um einen eigenen Attribute-Observer nachzurüsten. Der DI-Compiler entscheidet sich für eines der beiden, je nach Modul-Ladereihenfolge. Die Logik des anderen Moduls ist ab sofort still unerreichbar. Keine Warnung beim Kompilieren, keine Zeile im Log. Einfach ein Feature, das gestern noch lief und heute nicht mehr.
Wir haben das zwischen zwei Inhouse-Modulen erlebt, zwischen Inhouse-Code und einer Marketplace-Extension und zwischen zwei Marketplace-Extensions. Das Symptom ist immer dasselbe: „hat auf Staging funktioniert, ist in Production kaputt" nach einem Deploy, der die Modul-Ladereihenfolge verschoben hat. Oder „läuft auf Dev, läuft nicht auf Prod", weil die composer.lock anders aufgelöst hat.
<preference> gibt es kein Äquivalent zu sortOrder bei Plugins. Zwei konkurrierende Preferences lassen sich nicht per Konfiguration auflösen. Der einzige Fix ist, eine davon zu entfernen, meistens indem du sie in ein Plugin oder einen Event Observer umbaust. Wer stattdessen mit noch mehr Preferences dagegenhält, landet irgendwann bei Dutzenden Preferences in einer einzigen Codebase.
Fehlermuster 2: Upgrade-Verfall
Preferences hängen eng an den Signaturen der überschriebenen Klasse: Konstruktorargumente, öffentliche Methodensignaturen, manchmal auch protected Methods, die die Kindklasse überschreibt. Bringt Magento ein Minor-Release, das ein Pflicht-Argument zum Konstruktor einer Core-Klasse hinzufügt, muss jede Preference auf diese Klasse angepasst werden, sonst scheitert die DI-Kompilierung.
In der Praxis kommt das „hinkt nur noch" häufiger vor als das „scheitert komplett". Entwickler patchen den akuten Compile-Fehler, indem sie das fehlende Argument einfach ergänzen, oft ohne nachzulesen, wofür es eigentlich gedacht war oder es korrekt durchzureichen. Die Klasse kompiliert, die Klasse läuft. Das Verhalten, das das neue Argument eigentlich aktivieren sollte, bleibt still deaktiviert, weil die Preference-Implementierung es gar nicht nutzt.
Deshalb bekommen preference-lastige Codebases über die Jahre eine ganz eigene Textur. Nach jedem Upgrade hören kleine Stücke Core-Verhalten auf zu funktionieren, und keiner merkt es, weil jedes für sich genommen unscheinbar ist. In Summe bekommst du einen Shop, in dem gefühlt die Hälfte der Plattform-Features leise vor sich hin tot ist.
Fehlermuster 3: Security-Plugins still ausgehebelt
Die fieseste Variante von Fehlermuster 1. Statt dass sich zwei Business-Logik-Module um Product streiten, hängt ein Custom-Modul eine Preference an ein Magento-Security-Plugin und ersetzt es durch ein Nichtstun.
Das Standardbeispiel: Magento\ReCaptchaWebapiRest\Plugin\RestValidationPlugin. Eine Preference zeigt auf eine Custom-Klasse, die einfach nichts tut und zurückkehrt, und schaltet damit die reCAPTCHA-Validierung auf jedem REST-basierten Login-Flow ab. Im Admin-UI steht reCAPTCHA weiterhin auf aktiviert. Die Config sieht sauber aus. Das Plugin wird zur Laufzeit einfach umgangen, still, und kein Health-Check schlägt Alarm.
Das größere Prinzip dahinter: Jede <preference>, die auf eine Magento\*\Plugin\*-Klasse zielt, ist ein Warnsignal. Plugins existieren, weil das Framework genau dieses Verhalten komponierbar halten will. Ein Plugin durch eine Preference zu ersetzen heißt im Grunde „Komposition ist mir egal, ich will dieses Verhalten komplett für mich allein", was manchmal berechtigt ist und meistens nicht.
Fehlermuster 4: kaputte Konstruktorketten
Das Muster: Ein Modul-Autor schreibt eine Kindklasse, die eine Magento-Framework-Klasse per Preference ersetzen soll. Die Framework-Klasse hat jede Menge Konstruktorargumente. Die alle sauber durchzureichen ist mühsam. Also lässt der Autor parent::__construct() entweder komplett weg, ruft es nur mit einer Teilmenge der Argumente auf, oder kommentiert es „nur vorübergehend" aus und deployt trotzdem.
Konkret gesehen haben wir das bei Magento\Framework\Stdlib\Cookie\PhpCookieManager, bei TransportBuilder und bei genug Core-Collections, dass es kein Einzelfall ist. Jeder Entwickler, der später die Kindklasse liest, sieht den auskommentierten Parent-Aufruf und fragt sich, ob das Absicht war. Einkommentieren will niemand, „könnte ja was kaputtmachen". Also bleibt es auskommentiert. Die Klasse funktioniert in den meisten Flows, weil die meisten Flows genau das nicht anfassen, was parent::__construct eigentlich initialisiert hätte. Die Flows, die es doch anfassen, brechen subtil, in Production, viel später.
Der Fix ist immer derselbe: den parent::__construct()-Aufruf mit allen Pflichtargumenten wiederherstellen, Tests laufen lassen, die Tests reparieren, die dabei brechen. Der Bug, den der auskommentierte Aufruf kaschiert hat, ist meistens ein Konstruktorargument, das in einem Magento-Release neu dazukam und nicht zu dem passte, was die Kindklasse übergeben hat. Das eigentliche Signatur-Mismatch lösen, nicht das Symptom.
So auditierst du die Preferences, die schon in deiner Codebase stecken
Den einen Befehl fahren. Jeden Treffer klassifizieren. Das ist der ganze Audit.
1find app/code -name di.xml | xargs grep -l '<preference' | while read f; do echo "--- $f ---"; grep -oE '<preference[^>]+for="[^"]+"[^>]+type="[^"]+"' "$f"; done
Ausgabe in eine Tabelle kopieren. Drei Spalten: Modul, Zielklasse, dein Urteil. Als Urteil gibt es drei Optionen:
- SAFE. Ziel ist ein Interface ohne Default, ein Adapter hinter einem Contract oder eine Factory. Die Preference macht genau das, wofür sie gedacht ist.
- RISKY. Ziel ist eine konkrete Core-Klasse. Die Preference funktioniert heute vielleicht einwandfrei, ist aber bei jedem künftigen Upgrade ein Wartungsrisiko. Kandidat für ein Plugin-Refactoring.
-
INCIDENT. Ziel ist eine Plugin-Klasse, besonders ein Security-Plugin. Ziel ist eine
Magento\Framework\*-Klasse. Oder die Kindklasse enthält ein auskommentiertesparent::__construct(). Heute lesen, heute fixen.
Eine Codebase mit dreißig-plus Preferences hat von jeder Sorte eine Handvoll. Die INCIDENT-Zeilen fliegen sofort raus. Die RISKY-Zeilen wandern mit einer Schätzung für den Plugin-Umbau ins Refactoring-Backlog. Die SAFE-Zeilen bleiben, wie sie sind, werden aber dokumentiert, damit der nächste Entwickler weiß, warum sie da sind.
<preference> deployen, verifizieren, dass der neue Code tatsächlich zuerst greift, und erst dann die Preference löschen. Wer die Preference vorher entfernt, liefert eine Regression aus.
Weiterführende Artikel
- Observer-Rekursion in Magento 2: die versteckten Kosten von sales_order_save_after. Preference-lastige Codebases liefern häufig auch Observer-Kaskaden-Muster mit aus. Findest du eins, prüf gleich auf das andere.
Die Preference-Audit-Checkliste
-
Jede Preference in der Codebase erfassen
Führ
find app/code -name di.xml | xargs grep -l '<preference'aus und extrahier die for/type-Paare. vendor/ bleibt beim ersten Durchgang meist außen vor, ist aber einen zweiten Grep wert, wenn du ein Vendor-Modul im Verdacht hast. -
Jede als SAFE, RISKY oder INCIDENT klassifizieren
Interface ohne Default oder Adapter hinter einem Service Contract = SAFE. Konkrete Core-Klasse = RISKY. Plugin-Klasse oder Ziel unter
Magento\Framework\*= INCIDENT. Auskommentiertesparent::__construct()in der Kindklasse = INCIDENT, unabhängig vom Ziel. -
Auf konkurrierende Preferences für dieselbe Klasse prüfen
Die extrahierte Zielklassen-Spalte auf Duplikate greppen. Jede Zielklasse mit mehr als einer Preference-Deklaration bedeutet, dass ein Modul still den Kürzeren zieht. Das fixt du, bevor irgendwas anderes ausgeliefert wird.
-
INCIDENT-Zeilen zuerst abarbeiten
Die Kindklasse lesen. Überspringt sie
parent::__construct, stellst du den Aufruf wieder her und lässt die Test-Suite laufen. Zielt sie auf ein Security-Plugin, verifizierst du, dass der Ersatz wirklich das Richtige tut, oder baust ihn zu einem sauberen Plugin um. -
Die RISKY-Umbauten planen
Für jede RISKY-Zeile den Aufwand für das Plugin-Refactoring schätzen. Die meisten Preferences auf konkrete Core-Klassen lassen sich zu ein oder zwei Plugins umbauen (
beforeSave/afterLoad/aroundExecute), mit einem Bruchteil des Upgrade-Risikos. Priorisier danach, wie oft die Klasse in Hot Paths aufgerufen wird. -
Die SAFE-Zeilen dokumentieren
Trag in der di.xml einen Kommentar ein, der erklärt, warum jede SAFE-Preference die idiomatische Wahl ist. Dein zukünftiges Ich, oder der nächste Entwickler, wird es dir in 18 Monaten danken, wenn die Frage wieder aufkommt.
-
Einen CI-Guard gegen neue Preferences einbauen
Ein einfacher Check, der den Build scheitern lässt, sobald in einem PR eine neue
<preference>auftaucht, ohne dass ein verlinktes Issue die SAFE-Einstufung begründet. So wächst der Preference-Bestand nicht wieder nach. -
Bei jedem Magento-Minor-Release neu auditieren
Jedes Magento-Upgrade ändert Konstruktorsignaturen an manchen Core-Klassen. Fahr die Erfassung vor und nach dem Upgrade erneut. Jede Preference, deren Zielklasse ein neues Pflichtargument bekommen hat, braucht Aufmerksamkeit.
Dreißig Preferences in einer Codebase sind ein eigenes Refactoring-Projekt
Wir machen Magento-2-Code-Audits und Custom-Development-Projekte, die aus einer Preference-Inventur einen Plugin-Migrationsplan machen. Du bekommst die Tabelle, die Umbau-Schätzungen und die PRs. Kein 80-seitiges PDF.