spatie/laravel-event-sourcing

The spatie/laravel-event-sourcing package serves as an entry point for implementing event sourcing within Laravel applications. It provides the necessary infrastructure to set up and manage the core components of an event-sourced system:

• Aggregates: The domain objects that handle commands and record events.
• Projectors: Components that listen to events to build read models (projections).
• Reactors: Components that listen to events to trigger side effects (like sending emails or calling external APIs).

Event sourcing is particularly useful if your application requires auditing (understanding why a state changed), needs to make decisions based on historical data, or requires flexible reporting capabilities for data that isn't yet fully defined.

The spatie/laravel-event-sourcing package provides a framework for implementing event sourcing within Laravel applications. It facilitates the management of aggregates, projectors, and reactors.

When to use event sourcing:

• When your application needs to make decisions based on historical data.
• When you have strict auditing requirements (understanding why a state changed is as important as the state itself).
• When you anticipate future reporting needs but are currently unsure of the specific data requirements.

A reactor is a class used to handle side effects (e.g., sending emails, notifications, or making API calls) in response to events.

Key Characteristics

• Side Effect Isolation: Unlike projectors, reactors are not called when replaying events. They only trigger when the original event occurs in real-time. This prevents side effects from being duplicated during a replay.
• Queueing: Because side effects (like API calls) can be slow, it is highly recommended that all reactors implement the Illuminate\Contracts\Queue\ShouldQueue interface. Implementing this marker interface tells the package to handle the reactor via a queued job rather than executing it synchronously.

A reactor is a class that listens for incoming events.

Key distinction: Unlike projectors, reactors will not be called when events are replayed. They are only triggered when the original event fires in real-time. This makes them suitable for side effects like sending emails or triggering external integrations that should not be repeated during a replay.

Reactors can be created using the Artisan command:

php artisan make:reactor BigAmountAddedReactor

When an aggregate is retrieved, all its past events are replayed. To rebuild the internal state of the aggregate (e.g., a balance or a counter), you must implement apply methods following the naming convention apply<EventClassName>.

These methods are automatically called by the package during the event replay process, allowing you to update private instance variables based on the data contained within the events.

class AccountAggregate extends AggregateRoot
{
    private int $balance = 0;

    public function applyMoneyAdded(MoneyAdded $event)
    {
        $this->balance += $event->amount;
    }

    public function applyMoneySubtracted(MoneySubtracted $event)
    {
        $this->balance -= $event->amount;
    }
}

When catch_exceptions is set to true, any exception thrown by a projector or reactor triggers the Spatie\EventSourcing\Events\EventHandlerFailedHandlingEvent. You can listen for this event to monitor or log failures. The event provides access to the following properties:

• eventHandler: The specific projector or reactor instance that failed.
• storedEvent: The Spatie\EventSourcing\Models\StoredEvent instance that was being processed.
• exception: The actual exception that was thrown.

An Event Query is a class that represents an in-memory projection. When an event query is instantiated, it queries relevant events from the database and applies them internally to build a specific state.

Key Characteristics

• Read-Only: Event queries should only ever be used to read data and must never result in changes to the system state.
• In-Memory Projections: They build state by iterating over events and applying them to internal properties.
• Data Set Limitations: Event queries are only viable for limited data sets. Querying over periods containing millions of events can cause performance issues. They are best suited for smaller reports or specific time windows (e.g., a month or two).

use Spatie\EventSourcing\EventHandlers\Projectors\EventQuery;

class MyQuery extends EventQuery
{
    // Implementation details...
}

By default, the package uses Reflection to store all public properties in the snapshot. If you need to control exactly what data is persisted or how it is restored, you can override the getState() and useState() methods on your Aggregate class.

getState

Override this method to define which data should be saved in the snapshot. It must return an array.

useState

Override this method to define how the state array should be applied back to the aggregate instance when it is being rehydrated.

// Example of overriding getState to control snapshot data
protected function getState(): array
{
    return [
        'some_property' => $this->someProperty,
    ];
}

// Example of overriding useState to restore state
protected function useState(array $state): void
{
    $this->someProperty = $state['some_property'];
}