Skip to main content

Event Filtering

By default, every event fired through DomainFlow Core's event dispatcher reaches the configured processor. If you only care about a subset of your application's events — say, everything under a payment.* or auth.* namespace — you can restrict that with a SystemEventFilterInterface.

The Filter Contract​

interface SystemEventFilterInterface
{
    public function shouldProcess(string $eventName): bool;
}

shouldProcess() returns true if the event should be forwarded to the processor, and false if it should be dropped. SystemEventsServiceProvider applies the filter identically to both buffered-event replay and the live wildcard listener, so replay and live forwarding never disagree about which events are logged.

The Built-In EventNamePatternFilter​

EventNamePatternFilter matches event names against a list of fnmatch()-style glob patterns (e.g. payment.*, auth.*). An event is processed if it matches at least one configured pattern.

use DomainFlow\SystemEvents\Filter\EventNamePatternFilter;

$filter = new EventNamePatternFilter('payment.*', 'auth.*');

$filter->shouldProcess('payment.charged'); // true
$filter->shouldProcess('auth.login');      // true
$filter->shouldProcess('cache.cleared');   // false

A pattern with no wildcard character matches only that exact event name.

No patterns configured

new EventNamePatternFilter() with no arguments rejects every event — it does not fall back to "allow all". If you want every event processed, don't pass a filter to the provider at all (the default null means unfiltered).

Wiring a Filter into the Provider​

Pass the filter to the filter constructor argument of SystemEventsServiceProvider:

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

$app->registerProvider(new SystemEventsServiceProvider(
    filter: new EventNamePatternFilter('payment.*', 'auth.*')
));

Once registered, only events matching payment.* or auth.* will be replayed or forwarded to the processor — everything else is silently dropped before it ever reaches processEvent().

Writing a Custom Filter​

Any object implementing SystemEventFilterInterface can be used, so you're not limited to glob matching — for example, filtering by an allow-list loaded from configuration, or by a regular expression:

use DomainFlow\SystemEvents\Interface\SystemEventFilterInterface;

final class RegexEventFilter implements SystemEventFilterInterface
{
    public function __construct(private readonly string $pattern)
    {
    }

    public function shouldProcess(string $eventName): bool
    {
        return preg_match($this->pattern, $eventName) === 1;
    }
}
$app->registerProvider(new SystemEventsServiceProvider(
    filter: new RegexEventFilter('/^(payment|auth)\./')
));