Introduction

A "module extension" makes it possible to extend and manipulate the behaviour of the output-module. In contrast to the "mapping-extension", which allows to map _ additional_ entities, a module-extension is mainly used to extend already existing entities that are mapped by the output-module. You can also manipulate api requests and add custom validation for entities. The Shopware 6 module provides events from three categories:

Mapping Events can be used to manipulate entities generated by the module.
API events can be used to manipulate requests to the Shopware API and evaluate responses.
Flow events inform about started and finished subsections.
Settings events can be used to update configurations in Shopware before and after the module execution

This page provides a general overview of the events provided by the module.
A guide on how to develop a module extension is available as well.

Mapping-Events

Corrupted Entity Event Every time a corrupted entity (= entity, that could not be sent to shopware in a retry individually) an event is dispatched: Synqup\Modules\Shopware6Bundle\Output\Core\SyncApiProcessor\CorruptedEntityDetectedEvent. You can use this event if you want to implement an individual subscriber to handle corrupt documents.

Background - The Mapping Process

A document goes through several steps during the mapping process before it is actually sent to Shopware via Sync API. Each step dispatches different events for each document. The following steps are performed:

Validation: Checks whether the document can be transferred to Shopware without errors. This step dispatches a ShopwareEntityValidationEvent.
Generation: The source document is used to generate an object of type Entity (which is based on the Shopware entities of the Shopware core). This step generates a ShopwareEntityGeneratedEvent.
Transformation: The generated object of type Entity is transformed into an array. You can access this array with the ShopwareEntityTransformedEvent.
API-Request: The array is added to a request to the Sync API of Shopware. The API dispatches several API events.

Difference between parent and embedded entities

The module distinguishes between "parent" entities (e.g. customers) and "embedded" entities (e.g. customer addresses). Embedded
entities are part of their parents and therefore are not transformed and sent on their own. This affects the generated events:
The ShopwareEntityTransformedEvent is not generated for embedded entities.

ShopwareEntityValidationEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Mapping\ShopwareEntityValidationEvent

A ShopwareEntityValidationEvent is dispatched for each source document. This event can be used to define custom validation rules on which a document should be flagged as invalid.
Any document flagged as invalid by the output-module will not be sent to Shopware. It is not possible to make an invalid object valid again.
This event is dispatches for both parent and embedded entities. If an embedded entity is marked as invalid, the parent entity is invalid as well.

ShopwareEntityTransformedEvent & ShopwareEntityGeneratedEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Mapping\ShopwareEntityTransformedEvent
Synqup\Modules\Shopware6Bundle\Output\Core\Events\Mapping\ShopwareEntityGeneratedEvent

The ShopwareEntityGeneratedEvent and ShopwareEntityTransformedEvent are usable to manipulate entities before they are sent to the shop. The following dispatching rules apply to these events:

There is one ShopwareEntityGeneratedEvent for each generated Entity object (for embedded entities as well)
There is one ShopwareEntityTransformedEvent for each transformed Entity array (parent entities only)

Important: These events are handled after validation. So there is no automatic validation of the changes applied to the entities. Incorrect entities can lead to the failure of an API request.

ShopwareEntityGeneratedEvent

There is one ShopwareEntityGeneratedEvent for each generated Entity. The ShopwareEntityGeneratedEvent contains the generated Entity. There is one event for every entity (parent and embedded) that is generated by the output-module.

ShopwareEntityTransformedEvent

There is one ShopwareEntityTransformedEvent dispatches for each transformed Entity. The event contains the generated Shopware Entity as an array. This array will actually be embedded to the API request that creates or updates the entity eventually.

This event is generated for parent entities only (e.g. customers). An embedded entity (e.g. customer addresses) is transformed
together with the main object and therefore does not dispatch an event.

When to use which event?

If you only want to read data from generated entities you can use both events. However, if you want to manipulate generated entities, the ShopwareEntityTransformedEvent is preferable as it provides better control over the data that is actually sent to Shopware.

Background: The module uses annotations to generate and transform documents to Shopware objects. Those objects were generated from
the Shopware core, therefore it is possible to edit a field that is not annotated. Changes that are made to such fields are lost
during the transformation. Furthermore, it is possible that slight changes are still made to the entities during the transformation.

Note: You can access and set custom fields with the ShopwareEntityGeneratedEvent.

API-Events

The following events are described in the order in which they are generated when an API request is sent.

SendingApiRequestEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Api\SendingApiRequestEvent

Dispatched before an API request is converted to a Guzzle request and sent to Shopware. Makes it possible to manipulate a request prepared by the module, e.g. to adjust the request URL or to add/remove headers.

SentApiRequestEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Api\SentApiRequestEvent

Dispatched after a request has been sent to the Shopware 6 API using Guzzle. At the time of the event, there no response available for the request yet.

ProcessingApiResponseEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Api\ProcessingApiResponseEvent

Dispatched as soon as response was received. Triggered before the module evaluates the response (it does not matter if the response contains an error or not).

ProcessedApiResponseEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Api\ProcessedApiResponseEvent

Dispatched once the API client has processed a response from the Shopware API. Contains the response generated by the module and
thus the data received from Shopware.

Flow events

Flow events can be used as starting points for module extensions.

SubmoduleStartedEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Flow\SubmoduleStartedEvent.

Triggered as soon as the module dispatches the first message / after the start message was handled. At the time of the event, the
module context has already been generated.

ProgressInitializationFinishedEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Flow\ProgressInitializationFinishedEvent.

Dispatched as soon as all subsections were initialized with a progress (i.e. as soon as the module subsection init-progress is completed).

SubsectionStartedEvent / SubsectionFinishedEvent

Synqup\Modules\Shopware6Bundle\Output\Core\Events\Flow\SubsectionStartedEvent
Synqup\Modules\Shopware6Bundle\Output\Core\Events\Flow\SubsectionFinishedEvent

Dispatched when a "parent" subsection is started or any subsection is finished.

Settings Events

This type of event can be used to update settings (e.g. plugin configurations) in Shopware. There are two events available:

Synqup\Modules\Shopware6Bundle\Core\Events\Settings\ShopwareSettingsUpdateCollectorEventAfter
Synqup\Modules\Shopware6Bundle\Core\Events\Settings\ShopwareSettingsUpdateCollectorEventBefore

The combination of these events can be used to update settings before and after the module execution. The following subscriber updates the shop setting 'core.mailerSettings.disableDelivery' before and after the module execution.


namespace ...;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Synqup\Modules\Shopware6Bundle\Core\Events\Settings\ShopwareSettingsUpdateCollectorEventBefore;
use Synqup\Modules\Shopware6Bundle\Core\Events\Settings\ShopwareSettingsUpdateCollectorEventAfter;

class UpdateShopSettingsExampleSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            ShopwareSettingsUpdateCollectorEventBefore::class => 'before',
            ShopwareSettingsUpdateCollectorEventAfter::class  => 'after'
        ];
    }

    public function before(ShopwareSettingsUpdateCollectorEventBefore $event): void
    {
        $event->addSettingsUpdate('core.mailerSettings.disableDelivery', false);
    }

    public function after(ShopwareSettingsUpdateCollectorEventAfter $event): void
    {
        $event->addSettingsUpdate('core.mailerSettings.disableDelivery', true);
    }
}

On this page

#Introduction

#Mapping-Events

#Background - The Mapping Process

#ShopwareEntityValidationEvent

#ShopwareEntityTransformedEvent & ShopwareEntityGeneratedEvent

#ShopwareEntityGeneratedEvent

#ShopwareEntityTransformedEvent

#When to use which event?

#API-Events

#SendingApiRequestEvent

#SentApiRequestEvent

#ProcessingApiResponseEvent

#ProcessedApiResponseEvent

#Flow events

#SubmoduleStartedEvent

#ProgressInitializationFinishedEvent

#SubsectionStartedEvent / SubsectionFinishedEvent

#Settings Events