Laravel Event Sourcing

https://github.com/spatie/laravel-event-sourcing
Admin
This package provides an entry point for implementing event sourcing in Laravel, assisting with the...
Tokens:18,579
Snippets:228
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Package with Composer

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/installation-setup.md

Use this command to install the spatie/laravel-event-sourcing package via Composer.

```bash
composer require spatie/laravel-event-sourcing
```

--------------------------------

### Event Sourcing Configuration Example

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/installation-setup.md

This snippet shows a basic configuration for the event-sourcing package, including the event serializer and a list of event normalizers.

```php
'event_serializer' => Spatie\EventSourcing\EventSerializers\JsonEventSerializer::class,

    /*
     * These classes normalize and restore your events when they're serialized. They allow
     * you to efficiently store PHP objects like Carbon instances, Eloquent models, and
     * Collections. If you need to store other complex data, you can add your own normalizers
     * to the chain. See https://symfony.com/doc/current/components/serializer.html#normalizers
     */
    'event_normalizers' => [
        Spatie\EventSourcing\Support\CarbonNormalizer::class,
        Spatie\EventSourcing\Support\ModelIdentifierNormalizer::class,
        Symfony\Component\Serializer\Normalizer\DateTimeNormalizer::class,
        Symfony\Component\Serializer\Normalizer\ArrayDenormalizer::class,
        Spatie\EventSourcing\Support\ObjectNormalizer::class,
    ],

    /*
     * In production, you likely don't want the package to auto-discover the event handlers
     * on every request. The package can cache all registered event handlers.
     * More info:
     * https://spatie.be/docs/laravel-event-sourcing/v7/advanced-usage/discovering-projectors-and-reactors#content-caching-discovered-projectors-and-reactors
     *
     * Here you can specify where the cache should be stored.
     */
    'cache_path' => base_path('bootstrap/cache'),

    /*
     * When storable events are fired from aggregates roots, the package can fire off these
     * events as regular events as well.
     */

    'dispatch_events_from_aggregate_roots' => false,
];
```

--------------------------------

### Expose state and execute query

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/event-queries.md

Methods to expose the calculated state and an example of how to instantiate and use the query.

```php
class EarningsForProductAndPeriod extends EventQuery
{
    // …

    public function totalPrice(): int
    {
        return $this->totalPrice;
    }
}
```

```php
$report = new EarningsForProductAndPeriod(
    Period::make('2021-01-01', '2021-02-01'),
    $collectionOfProducts,
);

$report->totalPrice();
```

--------------------------------

### Define an AccountAggregateRoot

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/testing-aggregates.md

An example aggregate root class handling account balance logic and event recording.

```php
use Spatie\\\EventSourcing\\\AggregateRoots\\\AggregateRoot;

class AccountAggregateRoot extends AggregateRoot
{
    /** @var int */
    private $balance = 0;

    /** @var int */
    private $accountLimit = -5000;

    public function createAccount(string $name, string $userId)
    {
        $this->recordThat(new AccountCreated($name, $userId));

        return $this;
    }

    public function addMoney(int $amount)
    {
        $this->recordThat(new MoneyAdded($amount));

        return $this;
    }

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

    public function subtractMoney(int $amount)
    {
        $this->hasSufficientFundsToSubtractAmount($amount)
            ? $this->recordThat(new MoneySubtracted($amount))
            : $this->recordThat(new AccountLimitHit($amount));
    }

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

    private function hasSufficientFundsToSubtractAmount(int $amount): bool
    {
        return $this->balance - $amount >= $this->accountLimit;
    }
}
```

--------------------------------

### Example of a Storable Event Class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/preparing-events.md

A basic implementation of an event that extends `ShouldBeStored`, including constructor properties.

```php
namespace App\Events;

use Spatie\EventSourcing\StoredEvents\ShouldBeStored;

class MoneyAdded extends ShouldBeStored
{
    /** @var string */
    public $accountUuid;

    /** @var int */
    public $amount;

    public function __construct(string $accountUuid, int $amount)
    {
        $this->accountUuid = $accountUuid;

        $this->amount = $amount;
    }
}
```

--------------------------------

### Create an Account

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Initializes a new account using the createWithAttributes method.

```php
Account::createWithAttributes(['name' => 'Yoda']);
```

--------------------------------

### Publish and Run Migrations

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/installation-setup.md

Publish the event sourcing migrations and then run them to create the necessary database tables.

```bash
php artisan vendor:publish --provider="Spatie\EventSourcing\EventSourcingServiceProvider" --tag="event-sourcing-migrations"
php artisan migrate
```

--------------------------------

### Test Account Creation with Factories

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Demonstrates creating multiple accounts in a test environment using model factories.

```php
public function test_can_have_many_accounts()
{
    Account::factory()->times(5)->make()->each(function($account) {
        Account::createWithAttributes($account->toArray());
    });

    $this->assertCount(5, auth()->user()->accounts);
    $this->assertInstanceOf(Account::class, auth()->user()->accounts()->first());
}
```

--------------------------------

### Run Migrations

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Execute the artisan command to apply the new migration.

```bash
php artisan migrate
```

--------------------------------

### Create a projector via artisan

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Generates a new projector class in the app\Projectors directory.

```bash
php artisan make:projector AccountBalanceProjector
```

--------------------------------

### Create a reactor via Artisan

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Use the artisan command to scaffold a new reactor class in the app\Reactors directory.

```bash
php artisan make:reactor BigAmountAddedReactor
```

--------------------------------

### Implement Replay Lifecycle Hooks

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Define onStartingEventReplay in a projector to perform cleanup tasks like truncating tables before replay begins.

```php
namespace App\Projectors;

use App\Account;

// ...

class AccountBalanceProjector extends Projector
{
    // ...

    public function onStartingEventReplay()
    {
        Account::truncate();
    }
}
```

--------------------------------

### Publish Configuration File

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/installation-setup.md

Publish the configuration file for the event sourcing package to customize its settings.

```bash
php artisan vendor:publish --provider="Spatie\EventSourcing\EventSourcingServiceProvider" --tag="event-sourcing-config"
```

--------------------------------

### Replay events via Artisan

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Commands to trigger event replay for all or specific projectors.

```bash
php artisan event-sourcing:replay
```

```bash
php artisan event-sourcing:replay App\\Projectors\\AccountBalanceProjector
```

```bash
php artisan event-sourcing:replay App\\Projectors\\AccountBalanceProjector App\\Projectors\\AnotherProjector
```

--------------------------------

### Implement resetState in Projector

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Optional method to reset projector state before a full replay.

```php
public function resetState(?string $aggregateUuid = null): void
{
    // reset your projector
}
```

--------------------------------

### Create an AccountBalanceProjector

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

This projector class handles account lifecycle and balance update events by type-hinting the corresponding event classes.

```php
namespace App\Projectors;

use App\Account;
use App\Events\AccountCreated;
use App\Events\AccountDeleted;
use App\Events\MoneyAdded;
use App\Events\MoneySubtracted;
use Spatie\EventSourcing\EventHandlers\Projectors\Projector;

class AccountBalanceProjector extends Projector
{
    public function onAccountCreated(AccountCreated $event)
    {
        (new Account($event->accountAttributes))->writeable()->save();
    }

    public function onMoneyAdded(MoneyAdded $event)
    {
        $account = Account::uuid($event->accountUuid);

        $account->balance += $event->amount;

        $account->writeable()->save();
    }

    public function onMoneySubtracted(MoneySubtracted $event)
    {
        $account = Account::uuid($event->accountUuid);

        $account->balance -= $event->amount;

        $account->writeable()->save();
    }

    public function onAccountDeleted(AccountDeleted $event)
    {
        Account::uuid($event->accountUuid)->writeable()->delete();
    }
}
```

--------------------------------

### Replay with custom storage model

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Specify a custom model for event storage when replaying.

```bash
php artisan event-sourcing:replay --stored-event-model=App\\Models\\AccountStoredEvent
```

--------------------------------

### Implement TransactionCountProjector

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Create a projector that listens for MoneyAdded and MoneySubtracted events to update the transaction count.

```php
namespace App\Projectors;

use App\Events\MoneyAdded;
use App\Events\MoneySubtracted;
use App\TransactionCount;
use Spatie\EventSourcing\Models\StoredEvent;
use Spatie\EventSourcing\EventHandlers\Projectors\Projector;

class TransactionCountProjector extends Projector
{
    public function onMoneyAdded(MoneyAdded $event)
    {
        $transactionCounter = TransactionCount::firstOrCreate(['account_uuid' => $event->accountUuid]);

        $transactionCounter->count += 1;

        $transactionCounter->writeable()->save();
    }

    public function onMoneySubtracted(MoneySubtracted $event)
    {
        $transactionCounter = TransactionCount::firstOrCreate(['account_uuid' => $event->accountUuid]);

        $transactionCounter->count += 1;

        $transactionCounter->writeable()->save();
    }
}
```

--------------------------------

### Replay Events

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Run the artisan command to replay past events through the projector.

```bash
php artisan event-sourcing:replay App\\Projectors\\TransactionCountProjector
```

--------------------------------

### Handle a single event with __invoke

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Configure a projector to handle a single event type by defining the $handleEvent property and an __invoke method.

```php
// in a projector

// ...

protected $handleEvent =  MoneyAdded::class,

public function __invoke(MoneyAdded $event)
{
}
```

--------------------------------

### Fire Events

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Create accounts using the Account model.

```php
Account::createWithAttributes(['name' => 'Luke']);
Account::createWithAttributes(['name' => 'Leia']);
```

--------------------------------

### Implement Projection-Aware Factories

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Shows a trait-based approach to handle model creation within factories for event-sourced models.

```php
// Trait file:
trait SupportsProjections
{
    public function newModel(array $attributes = [])
    {
        return Factory::newModel([
            'uuid' => fake()->uuid(),
            ...$attributes,
        ])->writeable();
    }
}

// Factory file:
class AccountFactory extends Factory
{
    use SupportsProjections;

    public function definition(): array
    {
        return [...];
    }
}

// Test file:
public function test_can_have_many_accounts()
{
    Account::factory()->times(5)->create();
}
```

--------------------------------

### Default Configuration File Content

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/installation-setup.md

This is the default content of the `config/event-sourcing.php` file. It outlines various settings for auto-discovery, projectors, reactors, queues, and storage models.

```php
<?php

return [

    /*
     * These directories will be scanned for projectors and reactors. They
     * will be registered to Projectionist automatically.
     */
    'auto_discover_projectors_and_reactors' => [
        app()->path(),
    ],

    /*
     * This directory will be used as the base path when scanning
     * for projectors and reactors.
     */
    'auto_discover_base_path' => base_path(),

    /*
     * Projectors are classes that build up projections. You can create them by performing
     * `php artisan event-sourcing:create-projector`. When not using auto-discovery,
     * Projectors can be registered in this array or a service provider.
     */
    'projectors' => [
        // App\Projectors\YourProjector::class
    ],

    /*
     * Reactors are classes that handle side-effects. You can create them by performing
     * `php artisan event-sourcing:create-reactor`. When not using auto-discovery
     * Reactors can be registered in this array or a service provider.
     */
    'reactors' => [
        // App\Reactors\YourReactor::class
    ],

    /*
     * A queue is used to guarantee that all events get passed to the projectors in
     * the right order. Here you can set of the name of the queue.
     */
    'queue' => env('EVENT_PROJECTOR_QUEUE_NAME', null),

    /*
     * When a Projector or Reactor throws an exception the event Projectionist can catch it
     * so all other projectors and reactors can still do their work. The exception will
     * be passed to the `handleException` method on that Projector or Reactor.
     */
    'catch_exceptions' => env('EVENT_PROJECTOR_CATCH_EXCEPTIONS', false),

    /*
     * This class is responsible for storing events in the EloquentStoredEventRepository.
     * To add extra behaviour you can change this to a class of your own. It should
     * extend the \Spatie\EventSourcing\StoredEvents\Models\EloquentStoredEvent model.
     */
    'stored_event_model' => Spatie\EventSourcing\StoredEvents\Models\EloquentStoredEvent::class,

    /*
     * This class is responsible for storing events. To add extra behaviour you
     * can change this to a class of your own. The only restriction is that
     * it should implement \Spatie\EventSourcing\StoredEvents\Repositories\EloquentStoredEventRepository.
     */
    'stored_event_repository' => Spatie\EventSourcing\StoredEvents\Repositories\EloquentStoredEventRepository::class,

    /*
     * This class is responsible for storing snapshots. To add extra behaviour you
     * can change this to a class of your own. The only restriction is that
     * it should implement \Spatie\EventSourcing\Snapshots\EloquentSnapshotRepository.
     */
    'snapshot_repository' => Spatie\EventSourcing\Snapshots\EloquentSnapshotRepository::class,

    /*
     * This class is responsible for storing events in the EloquentSnapshotRepository.
     * To add extra behaviour you can change this to a class of your own. It should
     * extend the \Spatie\EventSourcing\Snapshots\EloquentSnapshot model.
     */
    'snapshot_model' => Spatie\EventSourcing\Snapshots\EloquentSnapshot::class,

    /*
     * This class is responsible for handling stored events. To add extra behaviour you
     * can change this to a class of your own. The only restriction is that
     * it should implement \Spatie\EventSourcing\StoredEvents\HandleDomainEventJob.
     */
    'stored_event_job' => Spatie\EventSourcing\StoredEvents\HandleStoredEventJob::class,

    /*
     * Similar to Relation::enforceMorphMap() this option will make sure that every event has a
     * corresponding alias defined. Otherwise, an exception is thrown
     * if you try to persist an event without alias.
     */
    'enforce_event_class_map' => false,

    /*
     * Similar to Relation::morphMap() you can define which alias responds to which
     * event class. This allows you to change the namespace or class names
     * of your events but still handle older events correctly.
     */
    'event_class_map' => [],

    /*
     * This class is responsible for serializing events. By default an event will be serialized
     * and stored as json. You can customize the class name. A valid serializer
     * should implement Spatie\EventSourcing\EventSerializers\EventSerializer.
     */

```

--------------------------------

### Define dynamic projector weight in PHP

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/making-sure-events-get-handled-in-the-right-order.md

Use the event class to determine the weight dynamically. The event parameter is null during reset operations.

```php
namespace App\Projectors;

use App\Events\MoneyAddedEvent;
use App\Events\MoneySubtractedEvent;
use Spatie\EventSourcing\EventHandlers\Projectors\Projector;
use Spatie\EventSourcing\StoredEvents\StoredEvent;

class MyProjector extends Projector
{
    public function getWeight(?StoredEvent $event): int
    {
        return match ($event?->event_class) {
            MoneyAddedEvent::class => 2,
            MoneySubtractedEvent::class => -2,
            default => 0,
        };
    }
    
    //
}
```

--------------------------------

### Add Multiple Projectors

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/adding-and-removing-projectors-and-reactors.md

Register multiple projector classes simultaneously by passing an array of class names to the `addProjectors` method. This is efficient for adding several projectors at once.

```php
Projectionist::addProjectors([
    AccountBalanceProjector::class,
    TransactionCountProjector::class,
]);
```

--------------------------------

### Define static projector weight in PHP

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/making-sure-events-get-handled-in-the-right-order.md

Implement the getWeight method to assign a static priority to a projector. Lower values are executed first.

```php
namespace App\Projectors;

use Spatie\EventSourcing\EventHandlers\Projectors\Projector;
use Spatie\EventSourcing\StoredEvents\StoredEvent;

class MyProjector extends Projector
{
    public function getWeight(?StoredEvent $event): int 
    {
        return 5;
    }
    
    //
}
```

--------------------------------

### Manually registering event handling methods

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Define the $handlesEvents array to map event classes to specific projector methods.

```php
namespace App\Projectors;

use App\Account;
use App\Events\MoneyAdded;
use Spatie\EventSourcing\EventHandlers\Projectors\Projector;

class AccountBalanceProjector extends Projector
{
    /*
     * Here you can specify which event should trigger which method.
     */
    protected array $handlesEvents = [
        MoneyAdded::class => 'onMoneyAdded',
    ];

    public function onMoneyAdded(MoneyAdded $event)
    {
        // do some work
    }
}
```

--------------------------------

### Delegate Aggregate Root Methods to Partials

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/aggregate-partials.md

Expose functionality on the aggregate root by calling the corresponding methods on the injected partial instance.

```php
class CartAggregateRoot extends AggregateRoot
{
    // …
    
    public function addItem(
        string $cartItemUuid,
        Product $product,
        int $amount
    ): self {
        $this->cartItems->addItem(
            $cartItemUuid,
            $product,
            $amount,
        );

        return $this;
    }
}
```

--------------------------------

### Register projectors in a ServiceProvider

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Manually register projectors using the Projectionist facade within a service provider.

```php
namespace App\Providers;

use App\Projectors\AccountBalanceProjector;
use Illuminate\Support\ServiceProvider;
use Spatie\EventSourcing\Facades\Projectionist;

class EventSourcingServiceProvider extends ServiceProvider
{
    public function register()
    {
        // adding a single projector
        Projectionist::addProjector(AccountBalanceProjector::class);

        // you can also add multiple projectors in one go
        Projectionist::addProjectors([
            AnotherProjector::class,
            YetAnotherProjector::class,
        ]);
    }
}
```

--------------------------------

### Handle Commands in Aggregate Partial

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/commands.md

Commands can also be mapped to aggregate partials to avoid manual method mapping.

```php
class CartItems extends AggregatePartial
{
    // …

    public function addItem(
        AddCartItem $addCartItem
    ): self {
        // …
    }
}
```

--------------------------------

### Create a Reactor class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/writing-your-first-reactor.md

Define a reactor that implements ShouldQueue to handle side effects asynchronously when a specific event occurs.

```php
namespace App\Reactors;

use App\Account;
use App\Events\MoneyAdded;
use App\Mail\BigAmountAddedMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;
use Spatie\EventSourcing\EventHandlers\Reactors\Reactor;

class BigAmountAddedReactor extends Reactor implements ShouldQueue
{
    public function onMoneyAdded(MoneyAdded $event)
    {
        if ($event->amount < 900) {
            return;
        }

        $account = Account::uuid($event->accountUuid);

        Mail::to('director@bank.com')->send(new BigAmountAddedMail($account, $event->amount));
    }
}
```

--------------------------------

### Implement a projector class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Defines a projector class that handles specific events via type-hinted methods.

```php
namespace App\Projectors;

use Spatie\EventSourcing\EventHandlers\Projectors\Projector;

class MyProjector extends Projector
{
    public function onEventHappened(EventHappened $event)
    {
        // do some work
    }
}
```

--------------------------------

### Implementing apply methods for state management

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/writing-your-first-aggregate.md

Use apply methods to update the aggregate's internal state based on historical events.

```php
// in our aggregate

private $balance = 0;

//...

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

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

--------------------------------

### Generate an aggregate class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/creating-and-configuring-aggregates.md

Use the artisan command to scaffold a new aggregate root class.

```bash
php artisan make:aggregate MyAggregate
```

--------------------------------

### Infer event handling method names

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Provide only the event class name to have the package automatically call a method prefixed with 'on'.

```php
// in a projector

// ...

protected array $handlesEvents = [
    /*
     * If this event is passed to the projector, the `onMoneyAdded` method will be called.
     */
    MoneyAdded::class,
];
```

--------------------------------

### Implement a reactor class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Define event handling methods by typehinting the event class in the reactor method signature.

```php
namespace App\Reactors;

class MyReactor
{
    public function onEventHappened(EventHappened $event)
    {

    }
}
```

--------------------------------

### Define a Command Object

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/commands.md

Use the HandledBy attribute to specify the aggregate root and AggregateUuid to identify the target instance.

```php
namespace Spatie\Shop\Cart\Commands;

use Spatie\Shop\Support\EventSourcing\Attributes\AggregateUuid;
use Spatie\Shop\Support\EventSourcing\Attributes\HandledBy;

#[HandledBy(CartAggregateRoot::class)]
class AddCartItem
{
    public function __construct(
        #[AggregateUuid] public string $cartUuid,
        public string $cartItemUuid,
        public Product $product,
        public int $amount,
    ) {
    }
}
```

--------------------------------

### Define an Event Query class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/event-queries.md

Initial structure for an EventQuery class that accepts a period and collection of products.

```php
namespace App\Reports;

use Illuminate\Support\Collection;
use Spatie\EventSourcing\EventHandlers\Projectors\EventQuery;
use Spatie\Period\Period;

class EarningsForProductAndPeriod extends EventQuery
{
    public function __construct(
        private Period $period,
        private Collection $products
    ) {
        // …
    }
}
```

--------------------------------

### Generate a Storable Event with Artisan

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/preparing-events.md

Use this command to quickly create a new event class that extends `ShouldBeStored`.

```bash
php artisan make:storable-event NameOfYourEvent
```

--------------------------------

### Create an aggregate snapshot

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/snapshots.md

Trigger a snapshot for an aggregate root to persist its current state to the database.

```php
$myAggregate = MyAggregate::retrieve($uuid);
$myAggregate->snapshot();
```

--------------------------------

### Handle Commands in Aggregate Root

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/commands.md

Add a method to the aggregate root that accepts the command object as an argument.

```php
class CartAggregateRoot extends AggregateRoot
{
    // …

    public function addItem(
        AddCartItem $addCartItem
    ): self {
        // …
    }
}
```

--------------------------------

### Map events to specific projector methods

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Explicitly define the method name to be called when an event occurs.

```php
// in a projector

// ...

protected array $handlesEvents = [
    MoneyAdded::class => 'onMoneyAdded',
];
```

--------------------------------

### Test aggregate behavior with fake

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/testing-aggregates.md

Use the fake() method to simulate aggregate state and assert recorded events.

```php
// in a PHPUnit test

/** @test */
public function it_can_subtract_money()
{
    AccountAggregateRoot::fake()
        ->given([new AccountCreated('Luke'), new MoneySubtracted(4999)])
        ->when(function (AccountAggregate $accountAggregate) {
            $accountAggregate->subtractMoney(1);
        })
        ->assertRecorded(new MoneySubtracted(1))
        ->assertNotRecorded(AccountLimitHit::class);
}

/** @test */
public function it_will_not_make_subtractions_that_would_go_below_the_account_limit()
{
    AccountAggregateRoot::fake()
        ->given([new AccountCreated('Luke'), new MoneySubtracted(4999)])
        ->when(function (AccountAggregate $accountAggregate) {
            $accountAggregate->subtractMoney(2);
        })
        ->assertRecorded(new AccountLimitHit(2))
        ->assertNotRecorded(MoneySubtracted::class);
}
```

--------------------------------

### Define an Aggregate Partial in PHP

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/aggregate-partials.md

Create a class extending AggregatePartial to manage specific domain logic and record events linked to the parent aggregate root.

```php
namespace Spatie\Shop\Cart\Partials;

use Spatie\EventSourcing\AggregateRoots\AggregatePartial;

class CartItems extends AggregatePartial
{
    private array $cartItems = [];

    public function isEmpty(): bool
    {
        return count($this->cartItems) === 0;
    }
    
    public function addItem(
        string $cartItemUuid,
        Product $product,
        int $amount
    ): self {
        $this->recordThat(new CartItemAdded(
            cartItemUuid: $cartItemUuid,
            productUuid: $product->uuid,
            amount: $amount,
        ));

        return $this;
    }

    protected function applyCartItemAdded(
        CartItemAdded $cartItemAdded
    ): void {
        $this->cartItems[$cartItemAdded->cartItemUuid] = null;
    }
}
```

--------------------------------

### Add Multiple Reactors

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/adding-and-removing-projectors-and-reactors.md

Add multiple reactor classes at once by providing an array of class names to the `addReactors` method. This simplifies the registration of several reactors.

```php
Projectionist::addReactors([
    SendMailReactor::class,
    SendPushNotificationReactor::class,
]);
```

--------------------------------

### Define static reactor weight

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Implement getWeight to return an integer, where lower values execute earlier. The default weight is 0.

```php
namespace App\Reactors;

use Spatie\EventSourcing\EventHandlers\Reactors\Reactor;
use Spatie\EventSourcing\StoredEvents\StoredEvent;

class MyReactor extends Reactor
{
    public function getWeight(?StoredEvent $event): int 
    {
        return 5;
    }
}
```

--------------------------------

### Implement Event Query constructor

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/event-queries.md

Querying the stored events table to filter and apply specific events within a defined period.

```php
// ...
use Spatie\EventSourcing\StoredEvents\Models\EloquentStoredEvent;

class EarningsForProductAndPeriod extends EventQuery
{
    public function __construct(
        private Period $period,
        private Collection $products
    ) {
        EloquentStoredEvent::query()
            // We're only interested in `OrderCreated` events
            ->whereEvent(OrderCreated::class)
            // And we only need events within a given period
            ->whereDate(
                'created_at', '>=', $this->period->getStart()
            )
            ->whereDate(
                'created_at', '<=', $this->period->getEnd()
            )
            ->each(
                fn (EloquentStoredEvent $event) => $this->apply($event->toStoredEvent())
            );
    }
}
```

--------------------------------

### Create accounts table migration

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Migration schema for storing account data with a UUID for identification.

```php
use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateAccountsTable extends Migration
{
    public function up()
    {
        Schema::create('accounts', function (Blueprint $table) {
            $table->increments('id');
            $table->string('uuid');
            $table->string('name');
            $table->integer('balance')->default(0);
            $table->timestamps();
        });
    }
}
```

--------------------------------

### Handling a single event with __invoke

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Use the $handleEvent property to route an event directly to the reactor's __invoke method.

```php
// in a reactor

// ...

protected $handleEvent =  MoneyAdded::class,

public function __invoke(MoneyAdded $event)
{
}
```

--------------------------------

### Using a dedicated class as an event handler

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Route events to a separate handler class instead of a method within the reactor.

```php
// in a reactor

// ...

protected array $handlesEvents = [
    /*
     * If this event is passed to the reactor, the `AddMoneyToAccount` class will be called.
     */ 
    MoneyAdded::class => SendMoneyAddedMail::class,
];
```

```php
use App\
Events\\MoneyAdded;

class SendMoneyAddedMail
{
    public function __invoke(MoneyAdded $event)
    {
        // do work to send a mail here
    }
}
```

--------------------------------

### Record an event

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/creating-and-configuring-aggregates.md

Use recordThat to register an event within the aggregate.

```php
// somewhere inside your aggregate
public function addMoney(int $amount)
{
    $this->recordThat(new MoneyAdded($amount));
}
```

--------------------------------

### Replay events

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/writing-your-first-reactor.md

Command to rebuild state without triggering reactors.

```bash
php artisan event-sourcing:replay
```

--------------------------------

### Register reactors in a ServiceProvider

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Manually register reactors using the Projectionist facade within a service provider's register method.

```php
namespace App\Providers;

use App\Projectors\AccountBalanceProjector;
use Illuminate\Support\ServiceProvider;
use Spatie\EventSourcing\Facades\Projectionist;

class EventSourcingServiceProvider extends ServiceProvider
{
    public function register()
    {
        // adding a single reactor
        Projectionist::addReactor(BigAmountAddedReactor::class);

        // you can also add multiple reactors in one go
        Projectionist::addReactors([
            AnotherReactor::class,
            YetAnotherReactor::class,
        ]);
    }
}
```

--------------------------------

### Apply events to build internal state

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/event-queries.md

Logic for processing specific events to update internal state variables.

```php
private int $totalPrice = 0;

// …

protected function applyOrderCreated(OrderCreated $orderCreated): void 
{
    $orderLines = collect(
        $orderCreated->orderData->orderLineData
    );

    $totalPriceForOrder = $orderLines
        // We're only interested in orders for a given product 
        ->filter(function (OrderLineData $orderLineData) {
            return $this->products->first(
                fn(Product $product) =>$orderLineData->productEquals($product)
            ) !== null;
        })
        // We the price of the relevant lines together
        ->sum(
            fn(OrderLineData $orderLineData) => $orderLineData->totalPriceIncludingVat
        );

    // Finally, we increment our total price, the grand total of all relevant events
    $this->totalPrice += $totalPriceForOrder;
}
```

--------------------------------

### Add a Single Reactor

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/adding-and-removing-projectors-and-reactors.md

Dynamically add a single reactor class to the Projectionist. This allows for fine-grained control over which reactors are active, beneficial for testing.

```php
Projectionist::addReactor(SendMailReactor::class);
```

--------------------------------

### Mapping events to specific reactor methods

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Explicitly define which method handles a specific event using the $handlesEvents property.

```php
// in a reactor

// ...

protected array $handlesEvents = [
    MoneyAdded::class => 'onMoneyAdded',
];
```

--------------------------------

### BrokeReactor to send email and fire event

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/thinking-in-events.md

This reactor listens for MoneySubtracted events. If an account is broke and has not had a 'BrokeMailSent' event recorded, it sends a 'BrokeMail' and then dispatches a 'BrokeMailSent' event.

```php
namespace App\Reactors;

// ...

class BrokeReactor implements EventHandler
{
    use HandlesEvents;

    public function onMoneySubtracted(MoneySubtracted $event)
    {
        $account = Account::uuid($event->accountUuid);

        /*
         * Don't send a mail if an account isn't broke
         */
        if (! $account->isBroke()) {
            return;
        }

        /*
         * Don't send a mail if it was sent already
         */
        if ($account->broke_mail_sent) {
            return;
        }

        Mail::to($account->email)->send(new BrokeMail($account));

        /*
         * Send out an event so the projector can modify the state.
         */
        event(new BrokeMailSent($account->uuid));
    }
}
```

--------------------------------

### Interact with and persist aggregates

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/writing-your-first-aggregate.md

Retrieve an aggregate by UUID, perform actions, and call persist to save recorded events.

```php
AccountAggregate::retrieve($uuid)
    ->createAccount('my account', auth()->user()->id)
    ->persist();
```

```php
AccountAggregate::retrieve($uuid)
    ->addMoney(123)
    ->persist();
```

```php
AccountAggregate::retrieve($uuid)
    ->subtractMoney(456)
    ->persist();
```

--------------------------------

### Perform Transactions

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Execute money transactions on existing accounts.

```php
$account = Account::where(['name' => 'Luke'])->first();
$anotherAccount = Account::where(['name' => 'Leia'])->first();

$account->addMoney(1000);
$anotherAccount->addMoney(500);
$account->subtractMoney(50);
```

--------------------------------

### Define an aggregate root class

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/creating-and-configuring-aggregates.md

Extend the AggregateRoot class to create your custom aggregate.

```php
namespace App\Aggregates;

use Spatie\EventSourcing\AggregateRoots\AggregateRoot;


class MyAggregate extends AggregateRoot
{
}
```

--------------------------------

### Define dynamic reactor weight

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Use the event class to determine weight dynamically, allowing specific events to be prioritized differently.

```php
namespace App\Reactors;

use App\Events\MoneyAddedEvent;
use App\Events\MoneySubtractedEvent;
use Spatie\EventSourcing\EventHandlers\Reactors\Reactor;
use Spatie\EventSourcing\StoredEvents\StoredEvent;

class MyReactor extends Reactor
{
    public function getWeight(?StoredEvent $event): int
    {
        return match ($event?->event_class) {
            MoneyAddedEvent::class => 2,
            MoneySubtractedEvent::class => -2,
            default => 0,
        };
    }
}
```

--------------------------------

### Link Aggregate Partial to Aggregate Root

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/aggregate-partials.md

Register the partial as a protected property within the AggregateRoot constructor to enable automatic event dispatching.

```php
class CartAggregateRoot extends AggregateRoot
{
    protected CartItems $cartItems;

    public function __construct()
    {
        $this->cartItems = new CartItems($this);
    }
}
```

--------------------------------

### Manually registering event handling methods in a Reactor

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/creating-and-configuring-reactors.md

Define the $handlesEvents property to map event classes to specific handler methods within a reactor class.

```php
namespace App\Reactors;

use App\Events\MoneyAdded;

class BigAmountAddedReactor
{
    /*
     * Here you can specify which event should trigger which method.
     */
    protected array $handlesEvents = [
        MoneyAdded::class => 'onMoneyAdded',

    ];

    public function onMoneyAdded(MoneyAdded $event)
    {
        // do some work
    }
}
```

--------------------------------

### Add a Single Projector

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/adding-and-removing-projectors-and-reactors.md

Use this method to add a single projector class to the Projectionist. This is useful for dynamically registering projectors, especially in testing scenarios.

```php
Projectionist::addProjector(TransactionCountProjector::class);
```

--------------------------------

### Create Migration for Transaction Count

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Define the database schema for storing transaction counts.

```php
use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateTransactionsCountTable extends Migration
{
    public function up()
    {
        Schema::create('transactions_count', function (Blueprint $table) {
            $table->increments('id');
            $table->string('account_uuid');
            $table->integer('count')->default(0);
            $table->timestamps();
        });
    }
}
```

--------------------------------

### AccountBalanceProjector to handle BrokeMailSent event

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/thinking-in-events.md

This projector listens for the BrokeMailSent event and marks the account as having had the broke mail sent. It also resets this flag when the balance goes back to zero or above.

```php
// ...

class AccountBalanceProjector extends Projector
{
    public function onBrokeMailSent(BrokeMailSent $event)
    {
        $account = Account::uuid($event->accountUuid);

        $account->broke_mail_sent = true;

        $account->writeable()->save();
    }

    public function onMoneyAdded(MoneyAdded $event)
    {
        $account = Account::uuid($event->accountUuid);

        $account->balance += $event->amount;

        /*
         * If the balance is above zero again, set the broke_mail_sent
         * flag to false again, so we can send another mail
         * when the balance goes below zero again.
         */
        if ($account->balance >= 0) {
            $account->broke_mail_sent = false;
        }

        $account->writeable()->save();
    }
}
```

--------------------------------

### Adding business rule validation to command methods

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/writing-your-first-aggregate.md

Implement checks within command methods to prevent invalid state transitions or event recording.

```php
public function subtractAmount(int $amount)
{
    if (! $this->hasSufficientFundsToSubtractAmount($amount) {
        throw CouldNotSubtractMoney::notEnoughFunds($amount);
    }

    $this->recordThat(new MoneySubtracted($amount));
}

private function hasSufficientFundsToSubtractAmount(int $amount): bool
{
    return $this->balance - $amount >= $this->accountLimit;
}
```

--------------------------------

### Dispatch Commands via CommandBus

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/commands.md

Inject the CommandBus into controllers or services to dispatch command objects.

```php
class CartController
{
    public function addCartItem(
        Request $request,
        CommandBus $commandBus
    ): void {
        $commandBus->dispatch(new AddCartItem(
            cartUuid: /* … */,
            cartItemUuid: /* … */,
            product: /* … */,
            amount: /* … */,
        ));
    }
}
```

--------------------------------

### Check Replay Status

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Use the Projectionist facade to determine if events are currently being replayed.

```php
Spatie\EventSourcing\Facades\Projectionist::isReplaying(); // returns a boolean
```

--------------------------------

### Define a stored event

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/creating-and-configuring-aggregates.md

Events must implement the ShouldBeStored interface to be persisted.

```php
use Spatie\EventSourcing\StoredEvents\ShouldBeStored;

class MoneyAdded extends ShouldBeStored
{
    /** @var int */
    private $amount

    public function __construct(int $amount)
    {
        $this->amount = $amount;
    }
}
```

--------------------------------

### Recording events when business rules are violated

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/writing-your-first-aggregate.md

Record specific events when a business rule is hit, ensuring the aggregate state is persisted.

```php
public function subtractAmount(int $amount)
{
    if (! $this->hasSufficientFundsToSubtractAmount($amount) {
        $this->recordThat(new AccountLimitHit($amount));

        // persist the aggregate so the record event gets persisted
        $this->persist();

        throw CouldNotSubtractMoney::notEnoughFunds($amount);
    }

    $this->recordThat(new MoneySubtracted($amount));
}
```

--------------------------------

### Laravel Horizon Configuration for Event Sourcing

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/installation-setup.md

This snippet demonstrates how to configure a supervisor in Laravel Horizon to process event-sourcing queues. It ensures that only one process handles the queue at a time for ordered event processing.

```php
'environments' => [
    'production' => [

        // ...

        'event-sourcing-supervisor-1' => [
            'connection' => 'redis',
            'queue' => [env('EVENT_PROJECTOR_QUEUE_NAME')],
            'balance' => 'simple',
            'processes' => 1,
            'tries' => 3,
        ],
    ],

    'local' => [

        // ...

        'event-sourcing-supervisor-1' => [
            'connection' => 'redis',
            'queue' => [env('EVENT_PROJECTOR_QUEUE_NAME')],
            'balance' => 'simple',
            'processes' => 1,
            'tries' => 3,
        ],
    ],
],

```

--------------------------------

### Trigger an event to invoke the reactor

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-reactors/writing-your-first-reactor.md

Execute business logic that triggers the event handled by the reactor.

```php
$account = Account::createWithAttributes(['name' => 'Rey']);
$account->addMoney(1000);
```

--------------------------------

### Add isBroke method to Account model

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/thinking-in-events.md

Adds a helper method to the Account model to determine if an account's balance is negative.

```php
// ...

class Account extends Projection
{
    // ...

    public function isBroke(): bool
    {
        return $this->balance < 0;
    }
}
```

--------------------------------

### Map events to dedicated handler classes

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/creating-and-configuring-projectors.md

Use the $handlesEvents array to delegate event processing to a specific class.

```php
// in a projector

// ...

protected array $handlesEvents = [
    /*
     * If this event is passed to the projector, the `AddMoneyToAccount` class will be called.
     */
    MoneyAdded::class => AddMoneyToAccount::class,
];
```

```php
use App\Events\MoneyAdded;

class AddMoneyToAccount
{
    public function __invoke(MoneyAdded $event)
    {
        $event->account->addMoney($event->amount);
    }
}
```

--------------------------------

### Retrieve an aggregate

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/creating-and-configuring-aggregates.md

Methods for loading an aggregate instance by its UUID.

```php
MyAggregate::retrieve($uuid)
```

```php
$myAggregate = new MyAggregate();
$myAggregate->loadUuid($uuid);
```

```php
public function handle(MyAggregate $aggregate) {
    $aggregate->load($uuid);
    
    // ...
}
```

--------------------------------

### Implement the EventSerializer interface

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/using-your-own-event-serializer.md

Define a custom serializer by implementing the required serialize and deserialize methods.

```php
namespace Spatie\\\EventSourcing\\\EventSerializers;

use Spatie\\\EventSourcing\\\ShouldBeStored;

interface EventSerializer
{
    public function serialize(ShouldBeStored $event): string;

    public function deserialize(string $eventClass, string $json, int $version, ?string $metadata = null): ShouldBeStored;
}
```

--------------------------------

### Replay for specific aggregate

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Limit the replay process to events associated with a specific aggregate UUID.

```bash
php artisan event-sourcing:replay --aggregate-uuid=12345678-1234-1234-1234-1234567890ab
```

--------------------------------

### Customize aggregate snapshot state

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/snapshots.md

Override getState and useState methods to control which properties are serialized and restored during snapshotting.

```php
protected function getState(): array
{
    $class = new ReflectionClass($this);

    return collect($class->getProperties(ReflectionProperty::IS_PUBLIC))
        ->reject(fn (ReflectionProperty $reflectionProperty) => $reflectionProperty->isStatic())
        ->mapWithKeys(function (ReflectionProperty $property) {
            return [$property->getName() => $this->{$property->getName()}];
        })->toArray();
}
```

```php
protected function useState(array $state): void
{
    foreach ($state as $key => $value) {
        $this->$key = $value;
    }
}
```

--------------------------------

### Perform manual assertions with then

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/testing-aggregates.md

Use the then() method to perform custom assertions on values returned from the when() closure.

```php
/** @test */
public function it_will_not_make_subtractions_that_would_go_below_the_account_limit()
{
    AccountAggregateRoot::fake()
        ->given([new AccountCreated('Luke'), new MoneySubtracted(4999)])
        ->when(function (AccountAggregate $accountAggregate) {
            $accountAggregate->subtractMoney(2);

            return $accountAggregate->uuid();
        })
        ->then(function($aggregateRootUuid) {
            // …
        });
}
```

--------------------------------

### Tracking state across multiple events

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/writing-your-first-aggregate.md

Maintain counters or state variables to trigger additional events based on historical occurrences.

```php
private $accountLimitHitCount = 0;

// we need to add this method to count the amount of this the limit was hit
public function applyAccountLimitHit()
{
    $this->accountLimitHitCount++;
}

public function subtractAmount(int $amount)
{
    if (! $this->hasSufficientFundsToSubtractAmount($amount) {
        $this->recordThat(new AccountLimitHit($amount));

        if ($this->accountLimitHitCount === 3) {
            $this->recordThat(new LoanProposed());
        }

        // persist the aggregate so the record events gets persisted
        $this->persist();

        throw CouldNotSubtractMoney::notEnoughFunds($amount);
    }

    $this->recordThat(new MoneySubtracted($amount));
}
```

--------------------------------

### Persist an aggregate

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-aggregates/creating-and-configuring-aggregates.md

Persist the aggregate to save recorded events to the database.

```php
MyAggregate::retrieve($uuid) // will cause all events for this uuid to be fed to the `apply*` methods
   // call methods that record events
   ->persist(); //
```

--------------------------------

### Perform Account Transactions

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Retrieves an account and executes money addition and subtraction operations.

```php
$yetAnotherAccount = Account::where(['name' => 'Yoda'])->first();

$yetAnotherAccount->addMoney(1000);
$yetAnotherAccount->subtractMoney(50);
```

--------------------------------

### Enforce Event Class Map Usage

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/using-aliases-for-stored-event-classes.md

Enable `enforce_event_class_map` in the configuration to ensure every event has an alias. An exception will be thrown if an event is persisted without an assigned alias.

```php
    /*
     * Similar to Relation::enforceMorphMap() this option will make sure that every event has a
     * corresponding alias defined. Otherwise, an exception is thrown
     * if you try to persist an event without alias.
     */
    'enforce_event_class_map' => true,
```

--------------------------------

### Preserve Event Timestamps on Models

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/replaying-events.md

Manually set created_at and updated_at using the stored event's timestamp to ensure model consistency during replays.

```php
public function onAccountCreated(AccountCreated $event) {
        Account::create(array_merge($event->accountAttributes, ['created_at' => $event->createdAt(), 'updated_at' => $event->createdAt()]));
}
```

--------------------------------

### Define TransactionCount Model

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/using-projectors/writing-your-first-projector.md

Create the model class for the transactions_count table.

```php
namespace App;

use Spatie\EventSourcing\Projections\Projection;

class TransactionCount extends Projection
{
    protected $table = 'transactions_count';
    protected $guarded = [];
}
```

--------------------------------

### Define Event Class Aliases

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/using-aliases-for-stored-event-classes.md

Configure aliases for event classes in the `event-sourcing.php` config file. This allows you to change event class names or namespaces while still handling older events correctly.

```php
    /*
     * Similar to Relation::morphMap() you can define which alias responds to which
     * event class. This allows you to change the namespace or classnames
     * of your events but still handle older events correctly.
     */
    'event_class_map' => [
        'money_added' => \App\Events\MoneyAddedEvent::class,
    ],
```

--------------------------------

### Specify a Custom Queue for an Event

Source: https://github.com/spatie/laravel-event-sourcing/blob/main/docs/advanced-usage/preparing-events.md

Override the default queue for an event by defining a public `$queue` property within the event class.

```php
namespace App\Events;

use Spatie\EventSourcing\StoredEvents\ShouldBeStored;

class MyEvent extends ShouldBeStored
{
    public $queue = 'alternativeQueue';

    ...
}
```
Tokens:
Raw