Laravel Broadway

Laravel Broadway is an adapter for the Broadway package.

It binds all needed interfaces for Broadway.

For reference, I've built a demo laravel application that uses this package and some event sourcing techniques.

Laravel 5 compatible package

Installation

Install via composer

composer require nwidart/laravel-broadway=~1.0

Service Providers

Laravel 5.5 (Auto discovery)

If you are using Laravel 5.5, this package provides auto discovery, meaning you can start coding – the Global Service Provider is already added. In case you need just some Service Providers, please add the following section to your applications composer.json:

 "extra": {
    "laravel": {
      "dont-discover": [
        "nWidart/Laravel-broadway"
      ]
    }
  }

Laravel 5.4

To finish the installation you need to add the service providers.

You have a choice here, you can either use the main Service Provider which will load the following:

• CommandBus
• EventBus
• Serializers
• EventStorage
• ReadModel
• MetadataEnricher
• Support (UuidGenerators,...)

Or choose to use only the Service providers you need. Don't know what you need ? Use the Global Service Provider provided.

Global Service Provider

   Nwidart\LaravelBroadway\LaravelBroadwayServiceProvider::class

Separate Service Providers

• CommandBus

  Nwidart\LaravelBroadway\Broadway\CommandServiceProvider::class

• EventBus

  Nwidart\LaravelBroadway\Broadway\EventServiceProvider::class

• Serializers

  Nwidart\LaravelBroadway\Broadway\SerializersServiceProvider::class

• EventStorage

  Nwidart\LaravelBroadway\Broadway\EventStorageServiceProvider::class

• ReadModel

  Nwidart\LaravelBroadway\Broadway\ReadModelServiceProvider::class

• MetadataEnricher

  Nwidart\LaravelBroadway\Broadway\MetadataEnricherServiceProvider::class

• Support

  Nwidart\LaravelBroadway\Broadway\SupportServiceProvider::class

(Optional) Publish configuration file and migration

php artisan vendor:publish

This will publish a config/broadway.php file and a database/migrations/create_event_store_table.php file.

(Optional) Run migration

Last step, run the migration that was published in the last step to create the event_store table.

If you haven't published the vendor files, you can use the command explained below:

php artisan broadway:event-store:migrate table_name

Configuration

Event Store

To create the event store you can call the following command:

php artisan broadway:event-store:migrate table_name

In the configuration file, you can choose which driver to use as an event store and which connection to use.

'event-store' => [
    'table' => 'event_store',
    'driver' => 'dbal',
    'connection' => 'default',
],

Once done, you can bind your EventStoreRepositories in a Service Provider like so:

$this->app->bind(\Modules\Parts\Repositories\EventStorePartRepository::class, function ($app) {
    $eventStore = $app[\Broadway\EventStore\EventStore::class];
    $eventBus = $app[\Broadway\EventHandling\EventBus::class];
    return new MysqlEventStorePartRepository($eventStore, $eventBus);
});

For an in memory Event Store, all you need to do is change the driver in the configuration file and probably add a new event store repository implementation with an adequate name.

Read Model

To set a read model in your application you first need to set the wanted read model in the package configuration.

Once that's done you can bind your ReadModelRepositories in a Service Provider like so:

$this->app->bind(\Modules\Parts\Repositories\ReadModelPartRepository::class, function ($app) {
    $serializer = $app[\Broadway\Serializer\Serializer::class];
    return new ElasticSearchReadModelPartRepository($app['Elasticsearch'], $serializer);
});

For an In Memory read model as an example:

$this->app->bind(\Modules\Parts\Repositories\ReadModelPartRepository::class, function ($app) {
    $serializer = $app[\Broadway\Serializer\Serializer::class];
    return new InMemoryReadModelPartRepository($app['Inmemory'], $serializer);
});

See the demo laravel application and specifically the Service Provider for a working example.

Registering subscribers

Command handlers

To let broadway know which handlers are available you need to bind in the Laravel IoC container a key named broadway.command-subscribers as a singleton.

It's important to know Command Handlers classes in broadway need to get a Event Store repository injected.

Now just pass either an array of command handlers to the laravelbroadway.command.registry key out the IoC Container or just one class, like so:

$partCommandHandler = new PartCommandHandler($this->app[\Modules\Parts\Repositories\EventStorePartRepository::class]);
$someOtherCommandHandler = new SomeOtherCommandHandler($this->app[\Modules\Things\Repositories\EventStoreSomeRepository::class]);

$this->app['laravelbroadway.command.registry']->subscribe([
    $partCommandHandler,
    $someOtherCommandHandler
]);

// OR

$this->app['laravelbroadway.command.registry']->subscribe($partCommandHandler);
$this->app['laravelbroadway.command.registry']->subscribe($someOtherCommandHandler);

Event subscribers

This is pretty much the same as the command handlers, except that the event subscriber (or listener) needs an Read Model repository.

Example:

$partsThatWereManfacturedProjector = new PartsThatWereManufacturedProjector($this->app[\Modules\Parts\Repositories\ReadModelPartRepository::class]);
$someOtherProjector = new SomeOtherProjector($this->app[\Modules\Things\Repositories\ReadModelSomeRepository::class]);

$this->app['laravelbroadway.event.registry']->subscribe([
    $partsThatWereManfacturedProjector,
    $someOtherProjector
]);

// OR

$this->app['laravelbroadway.event.registry']->subscribe($partsThatWereManfacturedProjector);
$this->app['laravelbroadway.event.registry']->subscribe($someOtherProjector);

Metadata Enricher

Broadways event store table comes with a field called "metadata". Here we can store all kind of stuff which should be saved together with the particular event, but which is does not fit to the domain aka the payload.

For example you like to store the ID of the current logged-in user or the IP or ...

Broadway uses Decorators to manipulate the event stream. A decorator consumes one or more Enrichers, which provide the actual data (user ID, IP). Right before saving the event to the stream, the decorator will loop through the registered enrichers and apply the data.

The following example assumes you added the global ServiceProvider of this package or at least the Nwidart\LaravelBroadway\Broadway\MetadataEnricherServiceProvider.

First we create the enricher. In this example lets assume we are interested in the logged-in user. The enricher will add the user ID to the metadata and returns the modified metadata object. However, in some cases – like in Unit Tests - there is no logged-in user available. To tackle this, the user ID can injected via constructor.

// CreatorEnricher.php

class CreatorEnricher implements MetadataEnricher
{
    /** @var int $creatorId */
    private $creatorId;


    /**
     * The constructor
     *
     * @param int $creatorId
     */
    public function __construct($creatorId = null)
    {
        $this->creatorId = $creatorId;
    }


    /**
     * @param Metadata $metadata
     * @return Metadata
     */
    public function enrich(Metadata $metadata)
    {
        if ($this->creatorId !== null) {
            $id = $this->creatorId;
        } else {
            $id = Auth::user()->id;
        }

        return $metadata->merge(Metadata::kv('createorId', $id));
    }
}

Second you need to register the Enricher to the decorator and pass the decorator to your repository

// YourServiceProvider.php

/**
 * Register the Metadata enrichers
 */
private function registerEnrichers()
{
    $enricher = new CreatorEnricher();
    $this->app['laravelbroadway.enricher.registry']->subscribe([$enricher]);
}

$this->app->bind(\Modules\Parts\Repositories\EventStorePartRepository::class, function ($app) {
    $eventStore = $app[\Broadway\EventStore\EventStore::class];
    $eventBus = $app[\Broadway\EventHandling\EventBus::class];
    
    $this->registerEnrichers();
    
    return new MysqlEventStorePartRepository($eventStore, $eventBus, $app[Connection::class], [$app[EventStreamDecorator::class]);
});

To retrieve the metadata you need to pass the DomainMessage as the 2nd parameter to an apply*-method in your projector.

// PartsThatWhereCreatedProjector.php

public function applyPartWasRenamedEvent(PartWasRenamedEvent $event, DomainMessage $domainMessage)
{
	$metaData = $domainMessage->getMetadata()->serialize();
	$creator = User::find($metaData['creatorId']);    
	
	// Do something with the user
}

All the rest are conventions from the Broadway package.

Changelog

License (MIT)