DfStreamCategoryTree Dokumentation für Shopware 6

DfStreamCategoryTree ergänzt den Bedingungs-Builder der dynamischen Produktgruppen von Shopware 6 um ein Feld Category (including subcategories). Ein Filter auf eine übergeordnete Kategorie schließt damit alle Produkte ihrer Unterkategorien ein, unabhängig von der Tiefe.

Das Problem, das dieses Plugin löst

Der native Bedingungs-Builder bietet ein Feld Categories, das die Association product.categoriesRo abfragt. Diese Association enthält ausschließlich die Kategorien, denen ein Produkt im Reiter Categories ausdrücklich zugewiesen wurde.

Ein sauber strukturierter Katalog ordnet Produkte den Blattkategorien zu. Ein Sneaker-Modell liegt in Herren / Schuhe / Sneaker, nicht in Herren. Ein Filter auf Herren liefert deshalb nur die wenigen Produkte, die direkt auf dieser Ebene zugeordnet sind, oft gar keine.

Der native Ausweg besteht darin, jede Unterkategorie manuell anzuhaken und die Stream-Konfiguration bei jeder Änderung des Kategoriebaums erneut zu öffnen. Dieses Plugin beseitigt diesen Pflegeaufwand.

Funktionsweise

Shopware pflegt bereits für jedes Produkt ein JSON-Feld namens categoryTree, das die IDs aller Kategorien des Pfades von der Wurzel bis zur Zuordnungskategorie enthält. Der native CategoryIndexer berechnet es bei jeder Kategorieverschiebung und jeder Änderung einer Produktzuordnung neu.

Ein equalsAny-Filter auf dieses Feld mit der ID einer übergeordneten Kategorie liefert daher alle Produkte, deren Pfad durch sie verläuft. Das Feld existiert und funktioniert im DAL einwandfrei, wird von der Administration jedoch nicht im Feldselektor des Bedingungs-Builders angeboten: es fehlt in der Allow-Liste des Services productStreamConditionService.

Das Plugin fügt dieser Allow-Liste einen Eintrag hinzu und liefert die passenden übersetzten Beschriftungen. Es bringt keinen Service-Decorator mit, keinen Listener auf Produkt-Events, keine Tabelle und keine Migration.

Voraussetzungen

• Selbst gehostetes Shopware 6.7.x
• PHP 8.2 oder höher
• Zugriff auf die Kommandozeile oder eine Deployment-Pipeline, die die Administration neu bauen kann

Das Plugin läuft nicht auf Shopware Cloud, da die von Shopware gehostete SaaS-Version keine Server-Plugins zulässt.

Installation

Per ZIP-Upload

1. Öffnen Sie in der Administration Extensions und danach My extensions
2. Klicken Sie auf Erweiterung hochladen und wählen Sie das Archiv DfStreamCategoryTree-1.0.0.zip
3. Installieren und aktivieren Sie das Plugin
4. Bauen Sie die Administration neu (siehe nächster Abschnitt)

Per Ordner-Deployment

Entpacken Sie das Archiv in das Verzeichnis für eigene Plugins Ihrer Instanz und führen Sie aus:

bin/console plugin:refresh
bin/console plugin:install --activate DfStreamCategoryTree
bin/console cache:clear

Administration neu bauen

Das Plugin verändert das Verhalten der Administrationsoberfläche. Nach der Installation ist einmalig ein Rebuild des Admin-Bundles nötig, sonst erscheint das neue Feld nicht im Bedingungsselektor.

bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear

In einer über eine Deployment-Pipeline verwalteten Produktivumgebung gehört dieser Schritt in der Regel bereits zum Standardablauf. Leeren Sie anschließend den Browser-Cache oder öffnen Sie die Administration in einem privaten Fenster, um sicher das aktualisierte Bundle zu laden.

Verwendung

Eine rekursive dynamische Gruppe anlegen

1. Öffnen Sie Kataloge und danach Dynamic product groups
2. Legen Sie eine neue Gruppe an oder öffnen Sie eine bestehende
3. Klappen Sie im Bedingungs-Builder den Feldselektor auf
4. Wählen Sie Category (including subcategories), direkt über dem ursprünglichen Eintrag Categories
5. Wählen Sie den Operator Is equal to any of
6. Wählen Sie im Wertefeld eine oder mehrere übergeordnete Kategorien
7. Speichern Sie und öffnen Sie den Reiter Preview, um die Anzahl der Treffer zu prüfen

Verfügbare Operatoren

• Is equal to any of: das Produkt gehört zum Teilbaum mindestens einer ausgewählten Kategorie
• Is not equal to any of: das Produkt gehört zu keinem der ausgewählten Teilbäume, nützlich um eine ganze Abteilung von einer Aktion auszunehmen

Mit anderen Bedingungen kombinieren

Das Feld verhält sich wie jede andere Stream-Bedingung. Es lässt sich frei mit Hersteller, Preis, Lagerbestand, Eigenschaften und Tags kombinieren und funktioniert in den verschachtelten AND- und OR-Gruppen des Builders.

Typische Konfiguration für einen Abverkauf: Category (including subcategories) is equal to any of Herren, UND Stock is greater than 0, UND Price is greater than 50.

Wo die Gruppe eingesetzt werden kann

• Navigationskategorieseiten, die von einer dynamischen Gruppe gespeist werden
• Produktblöcke in Shopping Experiences
• Bedingungen von Promotion-Regeln
• Automatisches Cross-Selling auf der Produktseite
• Jede Integration, die einen Product Stream über die Admin API oder die Store API konsumiert

Nutzung über die Admin API

Da das Feld nativ im DAL liegt, funktioniert eine direkt per API gesetzte Bedingung auch ohne das Plugin. Das Plugin macht den Filter in der Oberfläche sichtbar und bearbeitbar, was zählt, sobald ein Marketing-Team die Gruppen ohne API verwaltet.

POST /api/product-stream
{
  "name": "Gesamte Abteilung Herren",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Ohne installiertes Plugin funktioniert ein Stream mit diesem Filter weiterhin auf DAL-Ebene, sein Feld lässt sich im Bedingungs-Builder jedoch nicht anzeigen.

Fehlerbehebung

Das Feld erscheint nicht im Selektor

In den allermeisten Fällen wurde die Administration nach der Installation nicht neu gebaut. Führen Sie die Abfolge bundle:dump, build-administration und cache:clear erneut aus und laden Sie die Administration mit geleertem Browser-Cache neu. Prüfen Sie außerdem unter Extensions und My extensions, ob das Plugin aktiv ist.

Die Gruppe liefert weiterhin falsche Produkte

Stellen Sie sicher, dass Sie das neue Feld und nicht den ursprünglichen Eintrag Categories gewählt haben, da beide im Selektor nebeneinander stehen. Öffnen Sie danach ein erwartetes Produkt und prüfen Sie, ob es einer Unterkategorie der gewählten übergeordneten Kategorie zugeordnet und im betreffenden Verkaufskanal aktiv und sichtbar ist.

Ein kürzlich verschobenes Produkt taucht nicht auf

Das Feld categoryTree wird vom nativen CategoryIndexer neu berechnet. Wenn die Message Queue hinterherhinkt oder die Indizierung pausiert wurde, erzwingen Sie eine Neuindizierung:

bin/console dal:refresh:index --only=product.indexer,category.indexer

Zurücksetzen nach einem Shopware-Update

Bauen Sie nach einem Minor-Versionssprung von Shopware die Administration neu, damit das Plugin seinen Allow-Listen-Eintrag erneut registriert. Mehr ist nicht nötig, da das Plugin keine Daten speichert.

Deinstallation

Deaktivieren und deinstallieren Sie das Plugin über Extensions oder per Kommandozeile. Das Plugin legt keine Tabelle an und speichert keine Konfiguration, die Deinstallation ist daher vollständig neutral.

bin/console plugin:deactivate DfStreamCategoryTree
bin/console plugin:uninstall DfStreamCategoryTree

Bereits mit dem Filter konfigurierte dynamische Gruppen funktionieren weiter: die Bedingung ist als Standard-DAL-Filter gespeichert und wird weiterhin von der nativen Engine ausgewertet. Es verschwindet lediglich die Anzeige des Feldes im Bedingungs-Builder, wodurch der Filter bis zur erneuten Aktivierung des Plugins nicht über die Oberfläche bearbeitet werden kann. Es gehen keine Daten verloren.

Bekannte Einschränkungen

• Das Plugin wirkt nicht auf Listing-Filter der Storefront oder die Facettennavigation, die auf einem anderen Mechanismus beruhen
• Es verändert den Algorithmus der Kategorieindizierung nicht, sondern nutzt das Feld, das Shopware ohnehin erzeugt
• Es läuft nicht auf Shopware Cloud