Plugin-Sortierreihenfolge in Magento 2: Konflikte gezielt auflösen

1. Warum Plugin-Reihenfolge zum echten Problem wird

In einem kleinen Projekt mit wenigen eigenen Plugins ist die Plugin-Sortierreihenfolge selten ein Thema. Sobald ein Projekt aber wächst, mehrere Drittanbieter-Erweiterungen installiert werden und verschiedene Teams unabhängig voneinander Plugins auf dieselben Kernklassen registrieren, wird die Reihenfolge, in der diese Plugins ausgeführt werden, zu einem der subtilsten und am schwierigsten zu debuggenden Probleme in der gesamten Magento-Architektur. Anders als ein klassischer PHP-Fehler erzeugt eine falsche Plugin-Reihenfolge selten eine Exception, sondern meist ein leise falsches Ergebnis: ein Rabatt wird auf den Bruttopreis statt auf den Nettopreis angewendet, eine Validierung läuft nach statt vor einer Datenänderung, ein Cache wird invalidiert, bevor der eigentliche Schreibvorgang abgeschlossen ist.

Dieser Artikel setzt voraus, dass der Leser bereits weiß, was ein Plugin in Magento 2 ist und wie before, around und after grundsätzlich funktionieren. Der Fokus liegt ausschließlich auf dem Attribut sortOrder in di.xml, dem, was passiert, wenn zwei oder mehr Module dieselbe Methode mit widersprüchlichen oder undefinierten sortOrder-Werten patchen, und konkreten Techniken, um solche Plugin-Sortierreihenfolge-Konflikte zu diagnostizieren und zu beheben, auch wenn eines der beteiligten Module ein Drittanbieter-Paket ist, das nicht direkt editiert werden darf.

Die gute Nachricht vorweg: Magentos Interceptor-Mechanismus ist deterministisch. Es gibt keine "zufällige" Ausführungsreihenfolge, sondern eine klar definierte Regel, die auf sortOrder-Werten und, bei Gleichstand, auf der Modul-Ladereihenfolge basiert. Wer diese Regel versteht, kann jeden Plugin-Sortierreihenfolge-Konflikt systematisch statt durch Ausprobieren lösen.

2. Grundlagen: sortOrder in di.xml

Jedes Plugin wird in di.xml mit einem <plugin>-Element registriert, das optional ein sortOrder-Attribut trägt. Fehlt das Attribut, nimmt Magento implizit den Wert 0 an. Registrieren mehrere Module ein Plugin auf dieselbe Methode derselben Klasse, ohne jeweils einen expliziten sortOrder zu setzen, landen alle beim Default-Wert 0, und die tatsächliche Ausführungsreihenfolge wird dann durch die Modul-Ladereihenfolge bestimmt, also letztlich durch die sequence-Deklarationen in den jeweiligen module.xml-Dateien. Das ist der Kern vieler Plugin-Sortierreihenfolge-Probleme: Zwei unabhängige Modul-Autoren gehen beide implizit davon aus, "zuerst" zu laufen, ohne dass irgendjemand das explizit über sortOrder festgelegt hat.

Niedrigere sortOrder-Werte laufen grundsätzlich früher als höhere. Das gilt für before-Methoden in aufsteigender Reihenfolge, für after-Methoden in genau umgekehrter, absteigender Reihenfolge, und für around-Methoden als ineinander verschachtelte Aufrufe, bei denen das Plugin mit dem niedrigsten sortOrder am weitesten außen liegt. Diese Regeln werden in Abschnitt 3 anhand eines konkreten Beispiels durchgespielt, weil das reine Zahlenverständnis von "niedriger vor höher" in der Praxis nicht ausreicht, um komplexere Interceptor-Ketten korrekt vorherzusagen.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Catalog\Model\Product">
        <!-- No sortOrder given: defaults to 0, order vs. other unset plugins
             depends on module load order, not on this declaration -->
        <plugin name="vendor_tax_final_price" type="Vendor\Tax\Plugin\ProductPlugin"/>

        <!-- Explicit sortOrder: always runs after plugins with a lower value -->
        <plugin name="vendor_discount_final_price" type="Vendor\Discount\Plugin\ProductPlugin" sortOrder="20"/>
    </type>
</config>

3. Ausführungsmodell: before, around, after im Detail

Um Plugin-Sortierreihenfolge-Konflikte wirklich zu verstehen, hilft ein konkretes Beispiel mit drei Plugins auf derselben Methode: Plugin A mit sortOrder="10", Plugin B mit sortOrder="20", Plugin C mit sortOrder="30", alle drei mit before-, around- und after-Methoden. Die before-Methoden laufen in aufsteigender sortOrder-Reihenfolge: zuerst A, dann B, dann C, jeweils direkt vor dem Aufruf der Originalmethode beziehungsweise vor dem nächsten around in der Kette.

Die around-Methoden verschachteln sich dagegen wie Zwiebelschalen: Plugin A mit dem niedrigsten sortOrder liegt am weitesten außen, ruft also als Erstes $proceed() auf, was wiederum das around von Plugin B startet, das seinerseits $proceed() aufruft und damit Plugin C startet, das schließlich die Originalmethode aufruft. Die tatsächliche Ausführungsreihenfolge der around-Aufrufe ist also A, dann B, dann C, dann die Originalmethode, dann wieder C, dann B, dann A, symmetrisch wie beim Betreten und Verlassen verschachtelter Klammern. Die after-Methoden schließlich laufen in exakt umgekehrter, absteigender sortOrder-Reihenfolge: zuerst C, dann B, dann A.

declare(strict_types=1);

namespace Vendor\Discount\Plugin;

use Magento\Catalog\Model\Product;
use Closure;

/**
 * Demonstrates the before/around/after execution model with a single plugin.
 */
final class ProductPricePlugin
{
    /**
     * Runs before the original method, in ascending sortOrder order among all before-plugins.
     *
     * @param Product $subject The intercepted product instance
     * @param float $basePrice Argument passed to the original method
     * @return array{0: float} Adjusted argument array passed to the next plugin or the original method
     */
    public function beforeGetFinalPrice(Product $subject, float $basePrice): array
    {
        return [$basePrice]; // could adjust the argument here before it reaches the original method
    }

    /**
     * Wraps the original method call. Lower sortOrder plugins wrap outside higher sortOrder plugins.
     *
     * @param Product $subject The intercepted product instance
     * @param Closure $proceed Calls the next plugin in the chain, or the original method
     * @param float $basePrice Argument forwarded to the wrapped call
     * @return float Final result returned to the caller or to the next outer around-plugin
     */
    public function aroundGetFinalPrice(Product $subject, Closure $proceed, float $basePrice): float
    {
        $result = $proceed($basePrice);
        return $result; // could adjust the result here, wrapping the inner chain
    }

    /**
     * Runs after the original method, in descending sortOrder order among all after-plugins.
     *
     * @param Product $subject The intercepted product instance
     * @param float $result Result produced by the original method or the inner plugin chain
     * @return float Final adjusted result
     */
    public function afterGetFinalPrice(Product $subject, float $result): float
    {
        return $result; // could adjust the final result here
    }
}

4. Konfliktszenario: zwei Module patchen dieselbe Methode

Ein realistisches Konfliktszenario: Ein Rabatt-Modul Vendor\Discount registriert ein around-Plugin auf getFinalPrice(), das einen prozentualen Rabatt abzieht. Unabhängig davon registriert ein Steuer-Modul Vendor\Tax ebenfalls ein around-Plugin auf derselben Methode, das eine Steuer aufschlägt. Fachlich korrekt wäre: erst die Steuer auf den Nettopreis aufschlagen, dann den Rabatt auf den Bruttopreis anwenden, oder umgekehrt, je nach Geschäftsmodell, aber in jedem Fall in einer bewussten, definierten Reihenfolge.

Registrieren beide Module ihr Plugin ohne expliziten sortOrder, entscheidet allein die Modul-Ladereihenfolge, welches der beiden zuerst greift, und diese Reihenfolge kann sich bei einem Composer-Update, einer neuen Modulversion oder sogar bei einer scheinbar harmlosen Änderung an einer dritten, unbeteiligten module.xml unbemerkt verschieben. Das Ergebnis: Ein Preis, der gestern noch korrekt war, weicht nach einem Deployment plötzlich um wenige Cent ab, ohne dass eine Zeile Code in den beiden beteiligten Plugins geändert wurde. Das ist der klassische, schwer reproduzierbare Plugin-Sortierreihenfolge-Konflikt, der in Code-Reviews fast nie auffällt, weil beide Plugins isoliert betrachtet völlig korrekt aussehen.

5. Diagnose mit dev:di:info

Der erste Schritt bei jedem Verdacht auf einen Plugin-Sortierreihenfolge-Konflikt ist bin/magento dev:di:info <Klasse>. Der Befehl listet alle auf eine Klasse registrierten Plugins samt ihres tatsächlichen sortOrder-Werts und in der final berechneten Ausführungsreihenfolge auf, noch bevor überhaupt eine Zeile Quellcode geöffnet werden muss. Das ist deutlich schneller als eine manuelle Suche durch alle di.xml-Dateien im Projekt, gerade wenn ein Drittanbieter-Modul beteiligt ist, dessen Quellcode man nicht auswendig kennt.

bin/magento dev:di:info "Magento\Catalog\Model\Product"

# Example output showing the conflict:
# Plugins for Magento\Catalog\Model\Product::getFinalPrice:
#   plugin_name                          sortOrder   instance
#   ------------------------------------  ----------  ----------------------------------------
#   vendor_discount_final_price          10          Vendor\Discount\Plugin\ProductPricePlugin
#   vendor_tax_final_price               10          Vendor\Tax\Plugin\ProductPricePlugin
#
# WARNING: two plugins share the same sortOrder (10) on the same method.
# Effective execution order for tied values is determined by module
# sequence in app/etc/config.php, not by di.xml alone.

# Narrow the check to a single plugin type for a focused diagnosis
bin/magento dev:di:info "Magento\Catalog\Model\Product" | grep -A2 "final_price"

Aus diesem Output lassen sich zwei Dinge sofort ableiten: erstens, ob überhaupt mehrere Plugins auf derselben Methode registriert sind, und zweitens, ob identische oder fehlende sortOrder-Werte eine unklare Reihenfolge erzeugen. In der Praxis ist dev:di:info der erste Befehl, den man bei jedem Verdacht auf einen Plugin-Sortierreihenfolge-Konflikt ausführen sollte, noch vor dem Lesen des Quellcodes einzelner Plugins.

6. Fix ohne fremden Code zu ändern

Der naheliegende, aber falsche Reflex ist, die di.xml des Fremdmoduls direkt im vendor-Verzeichnis zu bearbeiten. Das funktioniert bis zum nächsten composer update, danach ist die Änderung verloren und der Konflikt kehrt kommentarlos zurück. Der korrekte Weg führt über ein eigenes, kleines Modul, das ein zusätzliches Plugin mit einem bewusst gewählten sortOrder registriert, kombiniert mit einer <sequence>-Deklaration in der eigenen module.xml, die auf beide Fremdmodule verweist. Diese Sequence beeinflusst zwar nicht direkt die sortOrder-Werte selbst, wohl aber die Reihenfolge, in der Magento die di.xml-Dateien beim Kompilieren zusammenführt, und damit die deterministische Auflösung von Gleichständen bei identischem sortOrder.

Für das konkrete Beispiel aus Abschnitt 4 bedeutet das: Ein eigenes Modul Vendor\PriceOrderFix registriert ein zusätzliches, eigenes around-Plugin mit einem niedrigeren sortOrder als beide Fremdmodule, das die gewünschte Ausführungsreihenfolge erzwingt, indem es sich außen um beide Fremdmodule legt und deren Berechnungen in der fachlich korrekten Reihenfolge orchestriert, statt sich auf die zufällige Modul-Ladereihenfolge zu verlassen.

<!-- Vendor/PriceOrderFix/etc/module.xml: loads after both conflicting vendor modules -->
<module name="Vendor_PriceOrderFix">
    <sequence>
        <module name="Vendor_Discount"/>
        <module name="Vendor_Tax"/>
    </sequence>
</module>

<!-- Vendor/PriceOrderFix/etc/di.xml: enforces a defined order with the lowest sortOrder -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Catalog\Model\Product">
        <plugin name="vendor_price_order_fix" type="Vendor\PriceOrderFix\Plugin\PriceOrderFixPlugin" sortOrder="1"/>
    </type>
</config>

Dieser Fix ist deployment-sicher, weil er komplett im eigenen Modul liegt und ein Composer-Update des Drittanbieter-Pakets die Lösung nicht zerstören kann. Der Preis dafür ist ein zusätzliches, kleines Modul im Projekt, dessen einziger Zweck die Konfliktauflösung ist, ein akzeptabler Kompromiss angesichts der Alternative, direkt in vendor-Code einzugreifen.

7. disable="true" gezielt einsetzen

Eine zweite Technik zur Konfliktauflösung ist disable="true" im eigenen <plugin>-Element, das ein Plugin eines Fremdmoduls für die eigene di.xml-Deklaration deaktiviert, ohne dessen Code zu verändern. Das ist sinnvoll, wenn eines der beiden konkurrierenden Plugins in einem bestimmten Kontext schlicht nicht laufen soll, etwa weil die eigene, kundenspezifische Preislogik die Standardberechnung des Fremdmoduls komplett ersetzen soll, statt sie nur umzusortieren.

Das Risiko dieses Ansatzes: Ein späteres Update des Fremdmoduls kann den name-Wert des deaktivierten Plugins ändern, wodurch die disable="true"-Deklaration ins Leere läuft, ohne dass Magento einen Fehler meldet, das deaktivierte Plugin läuft dann einfach wieder mit. Deshalb sollte jede disable="true"-Deklaration mit einem Kommentar dokumentiert werden, der auf die konkrete Modulversion verweist, gegen die sie getestet wurde, und in automatisierten Tests nach jedem Composer-Update erneut verifiziert werden.

<!-- Disables a third-party plugin entirely, tested against vendor/tax-module 2.3.1 -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Catalog\Model\Product">
        <plugin name="vendor_tax_final_price" disable="true"/>
    </type>
</config>

8. Konventionen zur Vermeidung künftiger Konflikte

Die wirksamste Maßnahme gegen künftige Plugin-Sortierreihenfolge-Konflikte ist eine team- oder projektweite Konvention für sortOrder-Werte. Statt Werte wie 1, 2, 3 zu vergeben, empfiehlt sich ein Raster mit Lücken, etwa 10, 20, 30, damit später ein zusätzliches Plugin mit einem Zwischenwert wie 15 eingefügt werden kann, ohne bestehende Werte anpassen zu müssen. Größere Agenturen reservieren zusätzlich ganze Zahlenbereiche pro Modul-Familie, etwa 100 bis 199 für alle Preisberechnungs-Plugins und 200 bis 299 für alle Validierungs-Plugins, damit die grobe Kategorie eines Plugins allein am sortOrder-Wert ablesbar ist.

Ebenso wichtig ist die Dokumentation der bewussten Entscheidung in einer Architecture Decision Record oder zumindest einem ausführlichen Kommentar direkt in der di.xml, wenn eine bestimmte Reihenfolge fachlich zwingend erforderlich ist. Ein Kommentar wie "Muss vor der Steuerberechnung laufen, da sonst der Rabatt fälschlich auf den Bruttopreis angewendet wird" spart dem nächsten Entwickler, der Jahre später an dieser Stelle etwas ändert, genau die Debugging-Zeit, die ohne diese Information für eine erneute Analyse nötig wäre.

9. Vergleich: riskante vs. robuste Ansätze

Die folgende Übersicht fasst zusammen, welche Ansätze im Umgang mit Plugin-Sortierreihenfolge-Konflikten riskant sind und welche sich in der Praxis als robust erwiesen haben.

Der gemeinsame Nenner aller robusten Ansätze: Die Kontrolle über die Plugin-Sortierreihenfolge liegt explizit im eigenen, versionierten Code, statt implizit von einer zufälligen Modul-Ladereihenfolge oder unveränderten Drittanbieter-Dateien abzuhängen.

10. Zusammenfassung

Die Plugin-Sortierreihenfolge in Magento 2 folgt einem deterministischen, aber leicht zu übersehenden Modell: before-Methoden laufen aufsteigend nach sortOrder, around-Methoden verschachteln sich wie Zwiebelschalen mit dem niedrigsten Wert außen, after-Methoden laufen absteigend. Konflikte entstehen fast immer, wenn mehrere Module dieselbe Methode ohne expliziten sortOrder patchen und sich unbewusst auf die Modul-Ladereihenfolge verlassen. bin/magento dev:di:info ist der zentrale Diagnosebefehl, um solche Konflikte in Sekunden statt durch manuelle Codesuche aufzudecken.

Fremdmodul-Konflikte lassen sich zuverlässig über ein eigenes, kleines Modul mit passender sequence und gezieltem sortOrder lösen, ohne vendor-Code zu verändern und damit ein Composer-Update zu riskieren. Wer zusätzlich projektweite Konventionen für sortOrder-Bereiche etabliert und bewusste Reihenfolge-Entscheidungen dokumentiert, reduziert die Wahrscheinlichkeit künftiger Plugin-Sortierreihenfolge-Konflikte erheblich, statt sie erst nach dem nächsten Deployment im Produktivbetrieb zu entdecken.

11. FAQ: Plugin-Sortierreihenfolge in Magento 2