Extension Attributes in Adobe Commerce: Sauber und entkoppelt entwickeln

Willkommen zu diesem Beitrag, in dem wir uns mit dem praktischen Einsatz von Extension Attributes in Adobe Commerce (früher Magento) beschäftigen. Wenn du schon länger mit Magento 2 arbeitest, bist du Extension Attributes sicher bereits begegnet. Trotzdem überrascht es immer wieder, wie oft Entwickler deren wertvolle Vorteile übersehen — gerade im Vergleich zu veralteten Methoden der Entity-Erweiterung.

In diesem Artikel werfen wir ein genaueres Licht auf die Vorteile von Extension Attributes und zeigen dir, wie sie deine Entwicklungsprojekte bereichern können. Wir schauen uns ihre Integration in den Service Layer an und geben dir Einblicke, wie du sauberen, modularen Code ohne unnötige Abhängigkeiten auf andere Layer oder Extensions schreibst.

Egal ob du ein erfahrener Adobe Commerce Entwickler bist, der sein Verständnis vertiefen möchte, oder ein Neueinsteiger, der mehr lernen will — dieser Artikel führt dich zu einem tieferen Verständnis der Rolle von Extension Attributes in Adobe Commerce.

Lass uns gemeinsam in die Welt der Extension Attributes eintauchen und die praktischen Vorteile entdecken, die sie in deinen Entwicklungsalltag bringen. Los geht's!

Kapitel 1: Die Adobe Commerce Service Layer verstehen

Adobe Commerce besteht aus vier Architektur-Layern:

• Presentation Layer — der Einstiegspunkt für Benutzerinteraktionen mit Adobe Commerce.
• Service Layer — das "Bindeglied" zwischen den Layern, bestehend aus einer Reihe von APIs, über die Module und externe Systeme miteinander kommunizieren. Service Contracts kommen hier zum Einsatz.
• Domain Layer — enthält die Business-Logik des Moduls.
• Persistence Layer — die Ressourcenebene, die mit der Datenbank und anderen Speichern interagiert.

Weitere Details findest du hier: Architectural layers overview

Der Service Layer ist für das Verständnis von Extension Attributes essenziell — besonders das Prinzip der "Service Contracts", das als tragende Säule in Adobe Commerce gilt. Falls du mit "Service Contracts" noch nicht vertraut bist, empfehle ich dir diesen Artikel: Service contracts. Behalte dabei im Hinterkopf, dass es sich um eine Vereinbarung zwischen Systemteilen handelt — über die Liste der verfügbaren Funktionalitäten und wie diese aufgerufen werden. REST API und der API-Ordner in Modulen sind zwei gute Beispiele für die Implementierung von Service Contracts.

Der Service Layer ermöglicht es, langfristige, klar definierte Beziehungen zwischen Services aufzubauen — intern wie extern.

Wenn du deine Extension entwickelst und eine bestehende Systemfunktionalität ändern oder erweitern möchtest, solltest du dich auf den Service Layer stützen — und auf keinen anderen. Nur der Service Layer bietet die Garantie, stabil zu bleiben. Upgrades werden so zur Routine, da die API-Definition selten geändert wird. Ganz zu schweigen von den Vorteilen klar definierter Einstiegspunkte, ihrer Parameter und der vorhersehbaren Ausgabe.

Kapitel 2: Das Konzept der Extension Attributes erkunden

Stell dir vor, du arbeitest mit einer grundlegenden Entity wie einer Bestellung in Adobe Commerce. Diese Entity hat ihre eigene Tabelle namens sales_order und eine umfangreiche Liste vordefinierter Properties. Aber was, wenn du der Bestellungs-Entity eine weitere Property hinzufügen musst?

Klar, du könntest den einfachen Weg gehen und die sales_order-Tabelle direkt ändern und eigene Observer und Models für die neue Property implementieren. Das würde dich jedoch in den Domain Layer einer anderen Extension führen — und das ist keine gute Idee. Der Domain Layer anderer Module ist die letzte Option für eine Extension, da er sich durch neue Vendor-Releases häufig verändert. Es bedeutet, in das Innerste eines Systems einzugreifen, über das du keine Kontrolle hast — und damit Kompatibilitätsprobleme bei zukünftigen Upgrades zu riskieren. Open–closed principle — das System sollte für direkte Änderungen geschlossen, aber für Erweiterungen offen sein. Eine direkte Änderung der Entity würde bedeuten, das vom Vendor Magento kontrollierte System zu modifizieren — nicht du.

Wie können wir also eine Property mit den "richtigen" Werkzeugen zur Entity hinzufügen?

Die Antwort liegt in der Kraft der Extension Attributes. 🙌

Extension Attributes bieten einen offiziellen Weg, Entities zu erweitern, ohne den Core-Code anzufassen. Statt die Entity-Tabelle direkt zu ändern, nutzen wir Extension Attributes, um neue Properties sauber und modular hinzuzufügen. Dadurch stellen wir sicher, dass unsere Änderungen mit den Architekturprinzipien des Systems im Einklang stehen — Kompatibilitätsprobleme werden reduziert und zukünftige Upgrades verlaufen reibungsloser.

Im nächsten Kapitel schauen wir uns an, wie Extension Attributes Hand in Hand mit dem Service Layer arbeiten, um Entities effektiv zu erweitern und eine flexible, skalierbare Codebasis zu erhalten.

Kapitel 3: Extension Attributes und Service Contracts

Extension Attributes bieten einen "legitimen" Weg, Service Contracts zu modifizieren und dabei die Abwärtskompatibilität für Anbieter und Konsumenten zu wahren. Obwohl das eine vereinfachte Definition ist, trifft sie den Kern der Extension Attributes in Adobe Commerce.

Extension Object: Composition over Inheritance nutzen

Adobe Commerce folgt dem Prinzip "Composition over Inheritance", um diese Flexibilität im Entwicklungsökosystem zu ermöglichen. Jede Entity, die Extension Attributes unterstützt, hat einen Setter und Getter für das Extension Object. Im Fall von Bestellungen ist das eine Instanz einer Klasse, die \Magento\Sales\Api\Data\OrderExtensionInterface implementiert.

Extension Attributes per XML konfigurieren

Das Verhalten des Extension Objects wird über einfache XML-Konfigurationen gesteuert. Dort legen wir fest, welche Extension Attributes hinzugefügt werden sollen, definieren ihre Typen und ordnen sie den jeweiligen Entities zu.

Zum Beispiel:

<!-- @see vendor/magento/module-sales/etc/extension_attributes.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:Api/etc/extension_attributes.xsd">
    <extension_attributes for="Magento\Sales\Api\Data\OrderInterface">
        <attribute code="shipping_assignments"
                   type="Magento\Sales\Api\Data\ShippingAssignmentInterface[]" />
    </extension_attributes>
</config>

Support für Extension Attributes: Die Rolle von ExtensibleDataInterface

Woher weiß Adobe Commerce, dass die Bestellungs-Entity Extension Attributes unterstützt?

\Magento\Sales\Api\Data\OrderInterface erweitert \Magento\Framework\Api\ExtensibleDataInterface, was Adobe Commerce signalisiert, dass die Bestellungs-Entity Extension Attributes haben wird. Die XML-Konfiguration legt fest, dass die Property shipping_assignments eines dieser Extension Attributes ist.

Generierte Service Contracts

Jetzt, wo Adobe Commerce von den Extension Attributes weiß — was passiert als nächstes?

Basierend auf den gesammelten XML-Konfigurationen aus extension_attributes.xml generiert Adobe Commerce \Magento\Sales\Api\Data\OrderExtensionInterface im Ordner generated/code.

Das generierte Interface sieht so aus:

<?php

interface OrderExtensionInterface extends \Magento\Framework\Api\ExtensionAttributesInterface
{
    /**
     * @return \Magento\Sales\Api\Data\ShippingAssignmentInterface[]|null
     */
    public function getShippingAssignments();

    /**
     * @param \Magento\Sales\Api\Data\ShippingAssignmentInterface[] $shippingAssignments
     * @return $this
     */
    public function setShippingAssignments($shippingAssignments);

    // ...
}

Zusätzlich wird auch die Implementierung des Contracts/Interface, \Magento\Sales\Api\Data\OrderExtension, generiert.

Zusammenfassung

Adobe Commerce hat für uns automatisch einen neuen Service Contract basierend auf unseren Konfigurationen generiert. Wir können diesen Contract jetzt nutzen, um mühelos Extension Attribute Werte für die Bestellungs-Entity zu setzen und abzurufen — ohne dabei andere Layer als den Service Layer des Magento_Sales-Moduls zu berühren.

Dieser elegante Ansatz macht dein neu hinzugefügtes Extension Attribute zu einem integralen Bestandteil der Service Contracts und des Service Layers. Es bleibt unabhängig von den Implementierungsdetails aller Module, Extensions oder des Systems selbst, über das du keine Kontrolle hast.

Herzlichen Glückwunsch, dass du dieses großartige Feature von Adobe Commerce nutzt!

Im nächsten Kapitel schauen wir uns an, wie du unerwünschte Abhängigkeiten bei der weiteren Implementierung von Extension Attributes vermeidest.

Kapitel 4: Daten für Extension Attributes speichern

Es ist nicht immer notwendig, Extension Attribute Daten persistent zu speichern. Manchmal reicht es aus, ihre Werte bei Bedarf on the fly zu berechnen. Lass uns aber davon ausgehen, dass wir ein Attribut tatsächlich speichern müssen.

Die wichtigsten Schritte beim Speichern von Extension Attribute Daten

Der Adobe Docs Artikel Add extension attributes to entities bietet eine umfassende Anleitung dazu. Hier eine kurze Zusammenfassung. Um Daten für ein Extension Attribute zu speichern, folgst du typischerweise diesen Schritten:

1. Erstelle ein Plugin, das den Save-Vorgang der Entity abfängt, die Extension Attribute Daten abruft und auf Ressourcenebene speichert.
2. Erstelle ein Plugin, das den Load-Vorgang der Entity abfängt, die Extension Attribute Daten abruft und die Entity über das Extension Object befüllt.

Es kann Variationen geben, aber das ist das grundlegende Szenario — und es erfordert mindestens zwei Plugins für das Speichern und Laden.

Wo speichert man Extension Attribute Daten?

Das ist eine hervorragende Frage, über die viele stolpern — aber nicht du! 😄

Eine Option wäre, die Extension Attribute Daten in derselben Tabelle wie die Entity zu speichern — zum Beispiel in der sales_order-Tabelle für Bestellungen. Dieser Ansatz führt jedoch zu einer Abhängigkeit vom Domain Layer des Magento_Sales-Moduls.

Und ja, du hast recht — das ist in unserem Paradigma nicht "erlaubt". Wir wollen die Software erweitern, nicht verändern.

Der beste Ansatz: Eigene Entity verwenden

Meiner Meinung nach ist der beste Ansatz, eine eigene Entity zum Speichern und Abrufen der Extension Attribute Daten zu haben. Es spielt dabei keine Rolle, welchen Persistence Layer du wählst — ob Datenbank, Session, Datei, API, Brieftauben oder Morse-Code auf Papier.

Das mag übertrieben klingen, ist aber der sinnvollste Weg, um unerwünschte Abhängigkeiten von unkontrollierbaren Systemteilen zu vermeiden. Deine Extension Attribute Implementierung sollte weder das Core-System beeinflussen noch das Open-Closed Principle verletzen. Indem du alle Verbindungen und Abhängigkeiten zum erweiterbaren Modul — bis auf die Extension Attributes Definition selbst — kappst, sicherst du die Integrität der Service Contracts und hältst das System im vorgesehenen Rahmen.

Dieser Ansatz ermöglicht dir eine saubere, entkoppelte Codebasis ohne unnötige Verflechtungen mit unkontrollierbaren Systemkomponenten.

Kapitel 5: Die wichtigsten Erkenntnisse

Zum Abschluss dieses Artikels über Extension Attributes in Adobe Commerce fassen wir die wichtigsten Punkte zusammen:

• 1. Service Layer und Service Contracts: Der Service Layer und Service Contracts sind hervorragende Grundlagen für die Erweiterung von Funktionalität. Sie bieten Stabilität, Vorhersehbarkeit und klare Definitionen — ideal für eine reibungslose Extension-Entwicklung.
• 2. Persistence, Domain und Presentation Layer: Dagegen eignen sich Persistence, Domain und Presentation Layer nicht für direkte Erweiterungen. Diese Layer können sich mit jedem Release ändern und sind damit weniger zuverlässig für die langfristige Extension-Entwicklung.
• 3. Extension Attributes und Service Contracts: Extension Attributes sind ein integraler Bestandteil des Service Layers und der Service Contracts. Ihr Einsatz ermöglicht eine effektive Extension-Entwicklung und erleichtert die Kommunikation zwischen Services in Adobe Commerce.
• 4. Extension Attributes nicht innerhalb der Entity speichern: Es ist entscheidend, Extension Attributes nicht innerhalb der Entity zu speichern, die du erweitern möchtest. Das würde eine Abhängigkeit vom Persistence Layer des erweiterbaren Moduls einführen und die Vorteile des Service Layers zunichte machen. Speichere Extension Attribute Daten stattdessen in einer eigenen Entity — für eine saubere, entkoppelte Architektur.

Wenn du diese Erkenntnisse beherzigst, kannst du robuste und skalierbare Extensions entwickeln, die mit den Prinzipien der Adobe Commerce Architektur im Einklang stehen. Denk daran: Der Service Layer und Service Contracts bieten ein stabiles Fundament, während Extension Attributes einen flexiblen und effektiven Ansatz zur Funktionserweiterung ermöglichen.

Danke, dass du mit uns Extension Attributes in Adobe Commerce erkundet hast. Wir hoffen, dieser Artikel war informativ und aufschlussreich für dich.

Happy developing!