Provider Registration

💡 If you're already using the DomainFlow Application class, the System Events package will automatically integrate with it when you register the SystemEventsServiceProvider.

Registering the Service Provider

If you're using DomainFlow's Application container (core package), register the service provider like so:

use DomainFlow\SystemEvents\Provider\SystemEventsServiceProvider;

$app->registerProvider(new SystemEventsServiceProvider());

Once registered, the system event processor will automatically:

• Replay any buffered events (those fired before the provider was registered, e.g. during Application::__construct()) in their original firing order
• Listen to all future events via wildcard
• Write them to disk using your preferred format
• Isolate any processor failure so it never propagates into the code that fired the original event (see Processor-Failure Handling)

---

Constructor Options

SystemEventsServiceProvider accepts two optional constructor arguments:

public function __construct(
    ?Closure $onProcessingFailure = null,
    ?SystemEventFilterInterface $filter = null
)

Parameter	Type	Default	Description
$onProcessingFailure	Closure(Throwable, string): void | null	null	Invoked whenever the configured processor fails to process an event. Defaults to logging via error_log(). See Processor-Failure Handling.
$filter	SystemEventFilterInterface | null	null	Decides which event names actually reach the processor. null means every event is processed — identical to the pre-filter behavior. See Event Filtering.

Both options apply identically to buffered-event replay and to the live wildcard listener, so replay and live forwarding never disagree about which events are logged or how failures are handled.

Example: Custom Failure Hook and Filter

use DomainFlow\SystemEvents\Provider\SystemEventsServiceProvider;
use DomainFlow\SystemEvents\Filter\EventNamePatternFilter;

$app->registerProvider(new SystemEventsServiceProvider(
    onProcessingFailure: function (Throwable $e, string $eventName): void {
        // e.g. increment a metric, forward to a monitoring service
    },
    filter: new EventNamePatternFilter('payment.*', 'auth.*')
));

---

Configuring the Processor

By default, SystemEventProcessorInterface resolves to FileSystemEventProcessor. To use a different destination — or to fan an event out to multiple destinations via CompositeSystemEventProcessor — rebind it in the container before the provider's boot() runs:

$app->bind(SystemEventProcessorInterface::class, function () {
    return new CompositeSystemEventProcessor(
        new FileSystemEventProcessor(),
        new SomeOtherProcessor(),
    );
}, true);

$app->registerProvider(new SystemEventsServiceProvider());

See Fan-Out Processing for details.