Technische Dokumentation

Diese Seite richtet sich an Entwickler, die den Kompatibilitätsfilter in einem eigenen Plugin erweitern oder an bestimmten Stellen in die Plugin-Logik eingreifen wollen.

Wir empfehlen Erweiterungen grundsätzlich als eigenes Plugin, das den Kompatibilitätsfilter als Abhängigkeit aufführt. Direkte Änderungen an den Plugin-Dateien gehen beim nächsten Update verloren.

Umgebungsvariablen

Ein Teil des Plugin-Verhaltens lässt sich per Umgebungsvariable steuern. Alle Flags werden über den Service OncoCompatibilityFilter\Service\Config\EnvFlags bereitgestellt und sollten nicht per getenv() aus dem Anwendungscode gelesen werden.

Setzen lassen sich die Variablen wie gewohnt in .env oder .env.local.

Variable	Typ	Default	Zweck
`ONCO_COMPI_DO_NOT_USE_ID_CRITERIA`	bool	`false`	Deaktiviert die ID-basierte Optimierung beim Aufbau der Filter-Criteria. Nur als Notfall-Schalter gedacht.
`ONCO_COMPI_USE_SALES_CHANNEL_AVAILABILITY`	bool	`false`	Berücksichtigt bei der Objekt-Auswahl die Sales-Channel-spezifische Verfügbarkeit.
`ONCO_COMPI_HAS_KBA_FORM`	bool	`false`	Aktiviert das KBA-Suchformular im Frontend.
`ONCO_COMPI_NO_KBA_RESULT_URL`	string	`null`	Ziel-URL, auf die weitergeleitet wird, wenn eine KBA-Suche kein Ergebnis liefert.
`ONCO_COMPI_SHOW_SELECTED_DROPDOWNS`	bool	`false`	Zeigt die Filter-Dropdowns auch dann, wenn bereits ein Objekt ausgewählt ist (vorausgefüllt).
`ONCO_COMPI_RANDOM_ORDER_DROPDOWNS`	bool	`false`	Erlaubt die Auswahl der Filter-Ebenen in beliebiger Reihenfolge statt streng Ebene für Ebene.
`ONCO_COMPI_ADMIN_OBJECT_SEARCH_LIMIT`	int	`20`	Maximale Trefferanzahl pro Seite bei der Objektsuche in der Administration (z. B. bei der manuellen Artikel-Zuordnung). Weitere Treffer werden per „Mehr anzeigen“ nachgeladen. Werte `<= 0` fallen auf `20` zurück.
`ONCO_COMPI_HAS_CUSTOM_SORTING`	bool	`false`	Aktiviert die Events `ObjectChildrenLoadedEvent` und `ObjectLevelOptionsLoadedEvent`, mit denen die Reihenfolge der Objekte in den Dropdowns per eigenem Subscriber bestimmt werden kann. Siehe Eigene Sortierung.

Custom Events

Das Plugin bietet auch Events, auf die ihr in eigenen Subscribern reagieren könnt.

`CompleteObjectNameEvent`

FQCN: OncoCompatibilityFilter\Event\CompleteObjectNameEvent

Wird für jedes Objekt ausgelöst, bevor dessen vollständiger Anzeigename (z. B. Hersteller A Modell X 2020) gerendert wird. Listener können den Namen verändern, bevor er ins Frontend oder in die Administration zurückgegeben wird.

Payload:

Getter	Typ	Beschreibung
`getName()`	`string`	Der aktuell zusammengesetzte Name.
`setName(string)`	`void`	Überschreibt den Namen mit einer eigenen Zeichenkette.
`getObject()`	`ObjectEntity`	Das Objekt, für das der Name erzeugt wird.
`getObjectPathArray()`	`array`	Hierarchischer Pfad (Array mit `name`-Keys pro Ebene).

Beispiel-Subscriber:

use OncoCompatibilityFilter\Event\CompleteObjectNameEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CustomObjectNameSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [CompleteObjectNameEvent::class => 'onCompleteName'];
    }

    public function onCompleteName(CompleteObjectNameEvent $event): void
    {
        $path = $event->getObjectPathArray();
        $event->setName(implode(' » ', array_column($path, 'name')));
    }
}

`ObjectListingCriteriaEvent`

FQCN: OncoCompatibilityFilter\Event\ObjectListingCriteriaEvent

Wird auf der Objekt-Landingpage (/compatibility-object/{objectId}) ausgelöst, unmittelbar bevor die Produkt-Criteria an das Shopware-Listing übergeben wird. Die Filter des Kompatibilitätsfilters sind zu diesem Zeitpunkt bereits gesetzt. Listener können die Criteria ergänzen, z. B. um zusätzliche Filter, Sortierungen oder Assoziationen.

Payload:

Getter	Typ	Beschreibung
`getCriteria()`	`Criteria`	Die Produkt-Criteria, die anschließend geladen wird (mutierbar).
`getObjectId()`	`string`	ID des ausgewählten Objekts.
`getObject()`	`?ObjectEntity`	Das ausgewählte Objekt, sofern es geladen werden konnte.
`getSalesChannelContext()`	`SalesChannelContext`	Der aktuelle Sales-Channel-Kontext.
`getRequest()`	`Request`	Der aktuelle HTTP-Request.

Beispiel-Subscriber:

use OncoCompatibilityFilter\Event\ObjectListingCriteriaEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class OnlyActiveProductsSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [ObjectListingCriteriaEvent::class => 'onListingCriteria'];
    }

    public function onListingCriteria(ObjectListingCriteriaEvent $event): void
    {
        $event->getCriteria()->addFilter(new EqualsFilter('active', true));
    }
}

Eigene Sortierung der Dropdowns

Standardmäßig werden die Objekte in den Filter-Dropdowns alphabetisch nach Name sortiert; bestehen alle Einträge einer Ebene ausschließlich aus Zahlen, wird numerisch sortiert. Reicht das nicht aus (z. B. Baujahre absteigend, Hersteller nach eigener Priorität, Sonderfälle wie „Sonstige“ ans Ende), kann die Sortierung per Subscriber übernommen werden.

Dazu muss die Umgebungsvariable ONCO_COMPI_HAS_CUSTOM_SORTING=1 gesetzt sein. Erst dann werden die beiden folgenden Events ausgelöst. Gleichzeitig wird die numerische Fallback-Sortierung des Plugins abgeschaltet, damit sie die vom Subscriber festgelegte Reihenfolge nicht wieder überschreibt. Der Subscriber ist also für die komplette Reihenfolge verantwortlich.

Note

Die beiden Events decken unterschiedliche Pfade ab. Je nachdem, ob ONCO_COMPI_RANDOM_ORDER_DROPDOWNS genutzt wird, müsst ihr auf eines oder beide Events reagieren.

`ObjectChildrenLoadedEvent`

FQCN: OncoCompatibilityFilter\Event\ObjectChildrenLoadedEvent
Voraussetzung: ONCO_COMPI_HAS_CUSTOM_SORTING=1

Wird ausgelöst, nachdem die Kind-Objekte einer Ebene geladen wurden, also bei der klassischen Auswahl Ebene für Ebene (Storefront-Dropdowns, AJAX-Nachladen der nächsten Ebene, Objekt-Landingpage sowie die Objektauswahl in der Administration). Listener können die Liste in PHP neu anordnen, wenn sich die gewünschte Reihenfolge nicht als DAL-Sortierung ausdrücken lässt.

Payload:

Getter	Typ	Beschreibung
`getChildren()`	`ObjectEntity[]`	Die geladenen Kind-Objekte, bereits nach Name sortiert.
`setChildren(array)`	`void`	Überschreibt die Liste mit der eigenen Reihenfolge.
`getParentId()`	`?string`	ID des Eltern-Objekts; `null` auf der obersten Ebene.
`getContext()`	`Context`	Der DAL-Kontext.
`getSalesChannelContext()`	`?SalesChannelContext`	Der Sales-Channel-Kontext; `null`, wenn der Aufruf aus der Administration kommt.

Beispiel-Subscriber (Zahlen absteigend, alles andere alphabetisch):

use OncoCompatibilityFilter\Event\ObjectChildrenLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ChildrenSortSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [ObjectChildrenLoadedEvent::class => 'onChildrenLoaded'];
    }

    public function onChildrenLoaded(ObjectChildrenLoadedEvent $event): void
    {
        $children = $event->getChildren();

        usort($children, static function ($a, $b): int {
            $aNumeric = is_numeric($a->getName());
            $bNumeric = is_numeric($b->getName());

            if ($aNumeric && $bNumeric) {
                return (int) $b->getName() <=> (int) $a->getName();
            }

            return strnatcasecmp($a->getName(), $b->getName());
        });

        $event->setChildren($children);
    }
}

`ObjectLevelOptionsLoadedEvent`

FQCN: OncoCompatibilityFilter\Event\ObjectLevelOptionsLoadedEvent
Voraussetzung: ONCO_COMPI_HAS_CUSTOM_SORTING=1 und ONCO_COMPI_RANDOM_ORDER_DROPDOWNS=1

Wird pro Ebene ausgelöst, nachdem die erreichbaren Optionen für die Dropdowns in beliebiger Reihenfolge ermittelt wurden. In diesem Modus arbeitet das Plugin nicht mit Entities, sondern nur mit den eindeutigen Namen pro Ebene. Dieses Event ist daher der einzige Eingriffspunkt für die Sortierung auf diesem Pfad.

Payload:

Getter	Typ	Beschreibung
`getNames()`	`list<string>`	Die erreichbaren Optionsnamen der Ebene, nach Name sortiert.
`setNames(array)`	`void`	Überschreibt die Liste mit der eigenen Reihenfolge.
`getLevel()`	`int`	Die Ebene, für die die Optionen geladen wurden (beginnend bei `1`).
`getSelected()`	`array<string, string\\|null>`	Aktuelle Auswahl pro Ebene, z. B. `['level1' => 'Hersteller A', 'level2' => null]`.
`getSalesChannelContext()`	`SalesChannelContext`	Der aktuelle Sales-Channel-Kontext.

Beispiel-Subscriber (Ebene 3 absteigend sortieren):

use OncoCompatibilityFilter\Event\ObjectLevelOptionsLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class LevelOptionsSortSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [ObjectLevelOptionsLoadedEvent::class => 'onLevelOptionsLoaded'];
    }

    public function onLevelOptionsLoaded(ObjectLevelOptionsLoadedEvent $event): void
    {
        if ($event->getLevel() !== 3) {
            return;
        }

        $names = $event->getNames();
        rsort($names, SORT_NATURAL | SORT_FLAG_CASE);
        $event->setNames($names);
    }
}

ACL-Rechte

Die Administration-UI nutzt zwei Berechtigungen, die in eigenen Rollen vergeben werden können:

onco_compatibility_filter:read
onco_compatibility_filter:write

Fehlt euch etwas?

Wenn ihr zusätzliche Events oder Erweiterungsmöglichkeiten braucht, sprecht uns an. Wir erweitern die öffentliche API gerne, wenn ein konkreter Use Case dahinter steht.