From c788813973f5c85052d6941a7a8637b7e2abb5ef Mon Sep 17 00:00:00 2001 From: David Badura Date: Wed, 3 Apr 2024 10:22:47 +0200 Subject: [PATCH] add message docs --- docs/mkdocs.yml | 1 + docs/pages/event_bus.md | 75 +---------------------------- docs/pages/getting_started.md | 4 +- docs/pages/message.md | 90 +++++++++++++++++++++++++++++++++++ 4 files changed, 94 insertions(+), 76 deletions(-) create mode 100644 docs/pages/message.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 66ba1427a..879fa0d65 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -81,6 +81,7 @@ nav: - Aggregate: aggregate.md - Events: events.md - Repository: repository.md + - Message: message.md - Store: store.md - Event Bus: event_bus.md - Subscription: subscription.md diff --git a/docs/pages/event_bus.md b/docs/pages/event_bus.md index de0d58a8c..68f51e549 100644 --- a/docs/pages/event_bus.md +++ b/docs/pages/event_bus.md @@ -4,81 +4,8 @@ This library uses the core principle called [event bus](https://martinfowler.com For all events that are persisted (when the `save` method has been executed on the [repository](./repository.md)), the event wrapped in a message will be dispatched to the `event bus`. All listeners are then called for each -event/message. +message. -## Message - -A `Message` contains the event and related meta information as headers. A `Message` contains only two properties, first -the `event` and second the `headers`. Internally we are also using the `headers` to store meta information for -the `Message` for example: - -* aggregate name -* aggregate id -* playhead -* recorded on - -Each event is packed into a message and dispatched using the event bus. - -```php -use Patchlevel\EventSourcing\Clock\SystemClock; -use Patchlevel\EventSourcing\Message\Message; - -$clock = new SystemClock(); -$message = Message::create(new NameChanged('foo')) - ->withAggregateName('profile') - ->withAggregateId('bca7576c-536f-4428-b694-7b1f00c714b7') - ->withPlayhead(2) - ->withRecordedOn($clock->now()); - -$eventBus->dispatch($message); -``` -!!! note - - The message object is immutable. - -You don't have to create the message yourself, it is automatically created, saved and dispatched in -the [repository](repository.md). - -### Custom headers - -As already mentioned, you can enrich the `Message` with your own meta information. This is then accessible in the -message object and is also stored in the database. - -```php -use Patchlevel\EventSourcing\Message\Message; - -$message = Message::create(new NameChanged('foo')) - // ... - ->withHeader('application-id', 'app'); -``` -!!! note - - You can read about how to pass additional headers to the message object in the [message decorator](message_decorator.md) docs. - -You can also access your custom headers. For this case there is also a method to only retrieve the headers which are not -used internally. - -```php -$message->header('application-id'); // app -$message->customHeaders(); // ['application-id' => 'app'] -``` -If you want *all* the headers you can also retrieve them. - -```php -$headers = $message->headers(); -/* -[ - 'aggregateName' => 'profile', - 'aggregateId' => '1', - // {...}, - 'application-id' => 'app' -] -*/ -``` -!!! warning - - Relying on internal meta data could be dangerous as they could be changed. So be cautios if you want to implement logic on them. - ## Event Bus The event bus is responsible for dispatching the messages to the listeners. diff --git a/docs/pages/getting_started.md b/docs/pages/getting_started.md index ce17d13a9..63e4eb9cc 100644 --- a/docs/pages/getting_started.md +++ b/docs/pages/getting_started.md @@ -306,7 +306,7 @@ $projectorRepository = new MetadataSubscriberAccessorRepository([ $projectionStore = new DoctrineSubscriptionStore($connection); -$projectionist = new DefaultSubscriptionEngine( +$engine = new DefaultSubscriptionEngine( $eventStore, $projectionStore, $projectorRepository, @@ -386,7 +386,7 @@ $hotels = $hotelProjection->getHotels(); ``` !!! warning - You need to run the projectionist to update the projections. + You need to run the subscription engine to update the projections. !!! note diff --git a/docs/pages/message.md b/docs/pages/message.md new file mode 100644 index 000000000..7612ef28e --- /dev/null +++ b/docs/pages/message.md @@ -0,0 +1,90 @@ +# Message + +A `Message` contains the event and related meta information as headers. + +```php +use Patchlevel\EventSourcing\Message\Message; + +$message = Message::create(new NameChanged('foo')); +``` + + + +```php +use Patchlevel\EventSourcing\Aggregate\AggregateHeader; +use Patchlevel\EventSourcing\Clock\SystemClock; +use Patchlevel\EventSourcing\Message\Message; + +$clock = new SystemClock(); +$message = Message::create(new NameChanged('foo')) + ->withHeader(new AggregateHeader( + aggregateName: 'profile', + aggregateId: 'bca7576c-536f-4428-b694-7b1f00c714b7', + playhead: 2, + recordedOn: $clock->now(), + )); +``` + +!!! note + + The message object is immutable. It creates a new instance with the new data. + +!!! note + + You don't have to create the message yourself, it is automatically created, saved and dispatched in + the [repository](repository.md). + +## Built-in headers + +The message object has some built-in headers which are used internally. + +* `AggregateHeader` - Contains the aggregate name, aggregate id, playhead and recorded on. +* `ArchivedHeader` - Flag if the message is archived. +* `NewStreamStartHeader` - Flag if the message is the first message in a new stream. + +## Custom headers + +As already mentioned, you can enrich the `Message` with your own meta information. This is then accessible in the +message object and is also stored in the database. + +```php +use Patchlevel\EventSourcing\Message\Message; + +$message = Message::create(new NameChanged('foo')) + // ... + ->withHeader('application-id', 'app'); +``` +!!! note + + You can read about how to pass additional headers to the message object in the [message decorator](message_decorator.md) docs. + +You can also access your custom headers. For this case there is also a method to only retrieve the headers which are not +used internally. + +```php +$message->header('application-id'); // app +$message->customHeaders(); // ['application-id' => 'app'] +``` +If you want *all* the headers you can also retrieve them. + +```php +$headers = $message->headers(); +/* +[ + 'aggregateName' => 'profile', + 'aggregateId' => '1', + // {...}, + 'application-id' => 'app' +] +*/ +``` +!!! warning + + Relying on internal meta data could be dangerous as they could be changed. So be cautios if you want to implement logic on them. + +## Learn more + +* [How to decorate messages](message_decorator.md) +* [How to use outbox pattern](outbox.md) +* [How to use processor](subscription.md) +* [How to use subscriptions](subscription.md)