Ein eigenes Flow-Builder-Ereignis in Shopware: was ein Plugin dafür liefern muss
Damit Händler im Flow Builder auf ein Ereignis aus Ihrem Plugin reagieren können, braucht es drei Dinge: eine Ereignisklasse, eine Anmeldung beim Ereignissammler und die richtigen Aware-Schnittstellen. Gelesen im Kern von Shopware 6.6 und 6.7, das Beispiel gegen den echten Kern ausgeführt, umgesetzt in unserem Wunschlisten-Plugin.

Der Flow Builder ist nur so nützlich wie seine Auslöser. Der Kern bringt viele mit: Bestellung eingegangen, Kunde registriert, Zahlungsstatus geändert. Was in einem Plugin passiert, kennt er nicht — es sei denn, das Plugin meldet es an. Wie der Flow Builder aus Sicht des Händlers funktioniert, beschreibt der Ratgeber Flow Builder: Auslöser, Aktionen und Grenzen. Hier geht es um die andere Seite: was ein Plugin liefern muss, damit ein eigenes Ereignis dort als Auslöser erscheint.
Grundlage ist der Quelltext von Shopware 6.6 und 6.7, abgeglichen mit den Versionen 6.6.10.31 und 6.7.16.0 am 11.11.2026, und unser eigenes Wunschlisten-Plugin, das elf solche Ereignisse anmeldet. Die Codebeispiele unten haben wir gegen den echten Kern von 6.6 und 6.7 ausgeführt.
Drei Bausteine
| Baustein | Aufgabe |
|---|---|
Ereignisklasse mit FlowEventAware | trägt Namen, Kontext und die Daten, die ein Flow nutzen darf |
Anmeldung über BusinessEventCollectorEvent | macht das Ereignis in der Auslöserliste sichtbar |
| Aufruf über den Event-Dispatcher | löst das Ereignis im richtigen Moment aus |
Fehlt die Anmeldung, läuft das Ereignis zwar durch das System, der Händler kann es aber nicht auswählen. Fehlt der Aufruf, steht der Auslöser in der Liste und löst nie aus.
Die Ereignisklasse
FlowEventAware verlangt zwei Methoden: getName() und die statische Methode getAvailableData(). Dazu kommt getContext() aus der Elternschnittstelle ShopwareEvent. Ein Beispiel für ein erfundenes Rücksende-Plugin:
<?php declare(strict_types=1);
namespace Beispiel\Ruecksendung\Event;
use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Content\Flow\Dispatching\Aware\ScalarValuesAware;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Shopware\Core\Framework\Event\EventData\ScalarValueType;
use Shopware\Core\Framework\Event\FlowEventAware;
use Shopware\Core\Framework\Event\SalesChannelAware;
use Symfony\Contracts\EventDispatcher\Event;
class RuecksendungAngelegtEvent extends Event implements
FlowEventAware, SalesChannelAware, CustomerAware, ScalarValuesAware
{
public const EVENT_NAME = 'beispiel_ruecksendung.angelegt';
public function __construct(
private readonly Context $context,
private readonly string $salesChannelId,
private readonly string $customerId,
private readonly string $nummer,
) {
}
public function getName(): string { return self::EVENT_NAME; }
public function getContext(): Context { return $this->context; }
public function getSalesChannelId(): string { return $this->salesChannelId; }
public function getCustomerId(): string { return $this->customerId; }
public function getValues(): array { return ['nummer' => $this->nummer]; }
public static function getAvailableData(): EventDataCollection
{
return (new EventDataCollection())
->add('customer', new EntityType(CustomerDefinition::class))
->add('nummer', new ScalarValueType(ScalarValueType::TYPE_STRING));
}
}
Die Anmeldung
Der Kern sammelt seine eigenen Ereignisse aus einer festen Liste, dazu die Ereignisse aktiver Apps, und feuert danach das BusinessEventCollectorEvent. Dort hängt sich das Plugin mit einem Subscriber ein:
<?php declare(strict_types=1);
namespace Beispiel\Ruecksendung\Subscriber;
use Beispiel\Ruecksendung\Event\RuecksendungAngelegtEvent;
use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class FlowEventSubscriber implements EventSubscriberInterface
{
public function __construct(private readonly BusinessEventCollector $collector)
{
}
public static function getSubscribedEvents(): array
{
return [BusinessEventCollectorEvent::NAME => 'onCollect'];
}
public function onCollect(BusinessEventCollectorEvent $event): void
{
$definition = $this->collector->define(RuecksendungAngelegtEvent::class);
if ($definition !== null) {
$event->getCollection()->set($definition->getName(), $definition);
}
}
}
Registriert wird der Subscriber als Service mit dem Tag kernel.event_subscriber, der BusinessEventCollector kommt als Argument hinein. Hier als Resources/config/services.php:
<?php declare(strict_types=1);
use Beispiel\Ruecksendung\Subscriber\FlowEventSubscriber;
use Shopware\Core\Framework\Event\BusinessEventCollector;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
return static function (ContainerConfigurator $container): void {
$container->services()
->set(FlowEventSubscriber::class)
->args([service(BusinessEventCollector::class)])
->tag('kernel.event_subscriber');
};
Die gleiche Registrierung in einer services.xml funktioniert in 6.6 und 6.7 ebenfalls. Ab 6.7.14.0 meldet der Kern für XML-Dateien aber einen Hinweis auf veraltete Technik: In 6.8 sollen sie nicht mehr geladen werden. Für neue Plugins ist die PHP-Datei deshalb die bessere Wahl.
BusinessEventCollector::define() liest auch die Schnittstellen der Klasse aus. Jede Schnittstelle mit dem Attribut IsFlowEventAware landet in der Aware-Liste des Auslösers, einmal als Kurzname (customerAware) und einmal als voller Klassenname. Für das Beispiel oben liefert define() in 6.6 und 6.7 dieselbe Liste: salesChannelAware, customerAware und scalarValuesAware, jeweils mit vollem Namen. Diese Liste entscheidet später, welche Aktionen der Händler wählen darf.
Der Kern nutzt denselben Weg übrigens selbst: Die Statusauslöser, etwa für Bestell-, Zahlungs- und Versandstatus, meldet er ebenfalls über das BusinessEventCollectorEvent an.
In unserem Wunschlisten-Plugin steht genau dieses Muster: Ein FlowEventSubscriber führt die elf Ereignisklassen in einer Konstante und meldet jede über define() an. So können Daten und Schnittstellen nicht vom Code der Klasse abweichen.
Aware-Schnittstellen: was ein Flow mit dem Ereignis anfangen kann
Beim Auslösen speichert der Kern nicht das ganze Ereignis, sondern vor allem Kennungen und einfache Werte. Dafür gibt es je Schnittstelle einen Speicher („Storer“), etwa CustomerStorer, ProductStorer, OrderStorer, MailStorer oder ScalarValuesStorer. Entitäten wie den Kunden lädt der Kern erst nach, wenn eine Bedingung oder Aktion sie abruft.
| Schnittstelle | was der Kern speichert | wozu |
|---|---|---|
CustomerAware | Kunden-ID | Voraussetzung für Kundenaktionen wie Tag setzen oder Kundengruppe ändern |
ProductAware | Produkt-ID | Produktdaten in Mailvorlagen, keine Kernaktion verlangt sie |
SalesChannelAware | nichts Eigenes | steht nur in der Aware-Liste, keine Kernaktion verlangt sie |
MailAware | Empfänger, Kopie, Blindkopie, Verkaufskanal | Voraussetzung für die Aktion „E-Mail senden“ |
ScalarValuesAware | einfache Werte aus getValues() | Zahlen und Texte wie alter und neuer Preis |
Bei unserem Beispiel speichert der Kern deshalb genau zwei Dinge: die Werte aus getValues() und die Kunden-ID. Den Verkaufskanal speichert er nicht, weil die Klasse MailAware nicht implementiert. Das haben wir in 6.6 und 6.7 nachgestellt.
SendMailAction meldet als Anforderung MailAware. Die Administration prüft beim Zusammenstellen eines Flows, ob eine der Anforderungen einer Aktion in der Aware-Liste des Auslösers steht. Fehlt MailAware, wird die Aktion nicht angeboten. Das gilt auch für unser Beispiel oben: Ohne MailAware gibt es dort keine Mail-Aktion. Wer eine braucht, ergänzt MailAware mit getMailStruct() für die Empfänger und getSalesChannelId() für den Kanal. Wirft getMailStruct() eine MailEventConfigurationException, greift der Kern beim Wiederherstellen auf die Bestellung oder den Kunden zurück, wenn das Ereignis diese mitbringt.
Auslösen
Ausgelöst wird mit dem normalen Event-Dispatcher, im Plugin über den Service event_dispatcher:
$this->eventDispatcher->dispatch(
new RuecksendungAngelegtEvent($context, $salesChannelId, $customerId, $nummer),
RuecksendungAngelegtEvent::EVENT_NAME
);
Der Kern registriert seinen FlowDispatcher als Dekorator vor dem Event-Dispatcher. Er lässt zuerst die normalen Listener laufen. Danach reicht er jedes Ereignis, das FlowEventAware implementiert, an die Flows weiter, die auf den Namen aus getName() hören. Der Name im zweiten Argument von dispatch() spielt dafür keine Rolle, das haben wir nachgestellt. Ausnahmen: Das Ereignis wurde gestoppt, oder der Kontext trägt den Zustand SKIP_TRIGGER_FLOW.
Eine Entscheidung liegt beim Plugin: Was passiert, wenn die Daten für das Ereignis nicht vollständig sind? Wir behandeln das Flow-Ereignis als Nebenwirkung. Fehlt etwa der Verkaufskanal einer Liste, feuern wir nichts. Die eigentliche Aktion des Kunden darf daran nicht scheitern.
Wie der Auslöser im Flow Builder heißt
Die Administration zerlegt den Namen an den Punkten und baut daraus einen Baum. Für jeden Teil sucht sie einen Textbaustein, zum Beispiel unter sw-flow.triggers.<teil> in Camel-Case. Findet sie keinen, zeigt sie den Teil mit Leerzeichen statt Unter- und Bindestrichen. Aus beispiel_ruecksendung.angelegt wird dann „beispiel ruecksendung / angelegt“. Lesbare deutsche Namen liefert das Plugin über eigene Textbausteine der Administration.
Unterschiede zwischen 6.6 und 6.7
In 6.6.10.6, 6.6.10.31, 6.7.2.2 und 6.7.16.0 sind FlowEventAware, die Arbeitsweise von BusinessEventCollector::define(), die verwendeten Aware-Schnittstellen und die Anforderung MailAware der Mail-Aktion gleich. Das Beispiel liefert in allen vier Versionen dasselbe Ergebnis. Unterschiede haben wir an diesen Stellen gefunden:
- 6.7 enthält zusätzlich einen
TimezoneStorer, der für Ereignisse mitMailAwaredie Zeitzone speichert, 6.6 nicht. - Ab 6.7.12.0 gibt es außerdem
SalesChannelContextAwaremit einem eigenen Speicher, der den Verkaufskanal festhält. 6.7.11.0 und 6.6 kennen ihn nicht. - 6.7 kennt den Feature-Schalter
FLOW_EXECUTION_AFTER_BUSINESS_PROCESS, standardmäßig aus. Ist er an, stellt der Kern Flows in eine Warteschlange und führt sie nach dem eigentlichen Vorgang aus. In 6.7.2.2 heißt er noch „experimentell“, in 6.7.16.0 beschreibt Shopware ihn als künftigen Standard für 6.8. In 6.6 gibt es ihn nicht. - Ab 6.7.14.0 gelten
services.xml-Dateien in Plugins als veraltet (siehe oben).
Ob sich ein Plugin in beiden Versionen installieren lässt, entscheidet die Versionsangabe in der composer.json, nicht der Flow-Code. Was eine solche Angabe zusagt, erklärt der Ratgeber Was eine Versionsangabe im Plugin wirklich zusagt.
Eine Checkliste vor der Veröffentlichung
Kurz geprüft
- Name als Konstante, mit Plugin-Präfix, und nach der ersten Veröffentlichung nicht mehr ändern.
getAvailableData()beschreibt jedes Feld, das ein Flow nutzen soll.- Aware-Schnittstellen nach den Aktionen wählen, die Händler brauchen — für Mails
MailAware. - Anmeldung über
BusinessEventCollectorEventunddefine(), nicht von Hand zusammengebaut. - In einer Testumgebung die Auslöserliste zählen und einen Flow mit der gewünschten Aktion durchspielen.
- Textbausteine für lesbare Namen mitliefern.
Ob eine Funktion besser als App oder als Plugin gebaut wird, beantwortet der Ratgeber App oder Plugin in Shopware.
Ein eigenes Flow-Ereignis ist eine Klasse, eine Anmeldung und ein Dispatch. Was der Händler damit tun kann, entscheiden die Aware-Schnittstellen — und der Name ist ein Versprechen, das bleibt.
Häufige Fragen
- Brauche ich für ein eigenes Ereignis eine App oder ein Plugin?
- Beides geht. Apps melden Ereignisse in der Datei Resources/flow.xml im Abschnitt flow-events an, im Kern landen sie in der Tabelle app_flow_event. Dieser Artikel beschreibt den Weg im Plugin, mit einer eigenen PHP-Klasse.
- Warum fehlt die Aktion „E-Mail senden“ bei meinem Auslöser?
- Die Aktion verlangt die Schnittstelle MailAware. Die Administration bietet eine Aktion nur an, wenn mindestens eine ihrer Anforderungen in der Aware-Liste des Auslösers steht. Implementiert Ihr Ereignis MailAware nicht, erscheint die Aktion nicht in der Auswahl.
- Kann ich ein Ereignis später umbenennen?
- Technisch ja, praktisch sollten Sie es nicht tun. Gespeicherte Flows verweisen auf den Namen. Nach einer Umbenennung löst der alte Flow nicht mehr aus, ohne dass jemand eine Fehlermeldung sieht.
- Warum zeigt der Flow Builder meinen Auslöser mit technischem Namen?
- Die Administration zerlegt den Namen an den Punkten und sucht für jeden Teil einen Textbaustein. Findet sie keinen, zeigt sie den Teil mit Leerzeichen statt Unter- und Bindestrichen. Für lesbare Namen liefert das Plugin eigene Textbausteine mit.
- Wird mein Flow auch ausgelöst, wenn ich das Ereignis an einer anderen Stelle feuere?
- Ja. Der Kern hängt sich als Dekorator vor den Event-Dispatcher. Jedes Ereignis, das FlowEventAware implementiert und über den Dispatcher läuft, wird an die Flows mit seinem Namen aus getName() weitergereicht, solange es nicht gestoppt wurde und der Kontext das Auslösen nicht ausdrücklich unterdrückt.
