From cd3663c4066ad62c53ff61a68e88130a736ced9a Mon Sep 17 00:00:00 2001 From: David Badura Date: Sun, 25 Dec 2022 20:23:46 +0100 Subject: [PATCH] improve some docs --- README.md | 3 +- docs/pages/aggregate.md | 2 +- docs/pages/index.md | 5 +- docs/pages/message_decorator.md | 91 +++++++++++++++++++++++++-------- 4 files changed, 74 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index c9c894f4c..c3ecc4afb 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,10 @@ A lightweight but also all-inclusive event sourcing library with a focus on deve * Everything is included in the package for event sourcing * Based on [doctrine dbal](https://github.com/doctrine/dbal) and their ecosystem * Developer experience oriented and fully typed -* [Snapshots](https://patchlevel.github.io/event-sourcing-docs/latest/snapshots/) system to quickly rebuild the aggregates +* [Snapshots](https://patchlevel.github.io/event-sourcing-docs/latest/snapshots/) and [Split-Stream](https://patchlevel.github.io/event-sourcing-docs/latest/split_stream/) system to quickly rebuild the aggregates * [Pipeline](https://patchlevel.github.io/event-sourcing-docs/latest/pipeline/) to build new [projections](https://patchlevel.github.io/event-sourcing-docs/latest/projection/) or to migrate events * [Projectionist](https://patchlevel.github.io/event-sourcing-docs/latest/projectionist/) for managed, versioned and asynchronous projections * [Scheme management](https://patchlevel.github.io/event-sourcing-docs/latest/store/) and [doctrine migration](https://patchlevel.github.io/event-sourcing-docs/latest/migration/) support -* [Splitting the eventstream](https://patchlevel.github.io/event-sourcing-docs/latest/split_stream/) * Dev [tools](https://patchlevel.github.io/event-sourcing-docs/latest/watch_server/) such as a realtime event watcher * Built in [cli commands](https://patchlevel.github.io/event-sourcing-docs/latest/cli/) with [symfony](https://symfony.com/) diff --git a/docs/pages/aggregate.md b/docs/pages/aggregate.md index 4a4b5f4e7..69cf9b3f7 100644 --- a/docs/pages/aggregate.md +++ b/docs/pages/aggregate.md @@ -509,7 +509,7 @@ final class NameChanged !!! note - You can find out more about event normalizer [here](./events.md#normalizer). + You can find out more about normalizer [here](./normalizer.md). There are also cases where business rules have to be defined depending on the aggregate state. Sometimes also from states, which were changed in the same method. diff --git a/docs/pages/index.md b/docs/pages/index.md index 235c06f41..715d39131 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -7,9 +7,10 @@ A lightweight but also all-inclusive event sourcing library with a focus on deve * Everything is included in the package for event sourcing * Based on [doctrine dbal](https://github.com/doctrine/dbal) and their ecosystem * Developer experience oriented and fully typed -* [Snapshots](snapshots.md) system to quickly rebuild the aggregates +* [Snapshots](snapshots.md) and [Split-Stream](split_stream.md) system to quickly rebuild the aggregates * [Pipeline](pipeline.md) to build new [projections](projection.md) or to migrate events -* [Scheme management](store.md) and [doctrine migration](store.md) support +* [Projectionist](projectionist.md) for managed, versioned and asynchronous projections +* [Scheme management](store.md) and [doctrine migration](migration.md) support * Dev [tools](watch_server.md) such as a realtime event watcher * Built in [cli commands](cli.md) with [symfony](https://symfony.com/) diff --git a/docs/pages/message_decorator.md b/docs/pages/message_decorator.md index 6b9c89d00..878aff309 100644 --- a/docs/pages/message_decorator.md +++ b/docs/pages/message_decorator.md @@ -4,34 +4,56 @@ There are usecases where you want to add some extra context to your events like for your domain. With `MessageDecorator` we are providing a solution to add this metadata to your events. The metadata will also be persisted in the database and can be retrieved later on. -## Create own decorator +## Built-in decorator -You can also use this feature to add your own metadata to your events. For this the have an extra methods on `Message` -to add data `withCustomHeader` and to read this data later on `customHeader`. +We offer a few decorators that you can use. + +### RecordedOnDecorator + +Each message needs a `RecordedOn` time. The `RecordedOnDecorator` is needed so that this is added to the message. +This decorator needs a [clock](clock.md) implementation. ```php -use Patchlevel\EventSourcing\EventBus\Message; +use Patchlevel\EventSourcing\Clock\SystemClock; +use Patchlevel\EventSourcing\EventBus\Decorator\RecordedOnDecorator; -final class OnSystemRecordedDecorator implements MessageDecorator -{ - public function __invoke(Message $message): Message - { - return $message->withCustomHeader('system', 'accounting_system'); - } -} +$clock = new SystemClock(); +$decorator = new RecordedOnDecorator($clock); ``` -!!! note +!!! warning - The Message is immutable, for more information look up [here](event_bus.md#message). + A `RecordedOn` time must always be created. + Either this decorator must always be added or an appropriate replacement must be provided. -!!! tip +### SplitStreamDecorator - You can also set multiple headers with `withCustomHeaders` which expects an hashmap. +In order to use the [split stream](split_stream.md) feature, the `SplitStreamDecorator` must be added. + +```php +use Patchlevel\EventSourcing\EventBus\Decorator\SplitStreamDecorator; +use Patchlevel\EventSourcing\Metadata\Event\AttributeEventMetadataFactory; + +$eventMetadataFactory = new AttributeEventMetadataFactory(); +$decorator = new SplitStreamDecorator($eventMetadataFactory); +``` -## Use own decorator +### ChainMessageDecorator -To use your own message decorator, you have to pass it to the `DefaultRepositoryManager`. +To use multiple decorators at the same time, one can use the `ChainMessageDecorator`. + +```php +use Patchlevel\EventSourcing\EventBus\Decorator\ChainMessageDecorator; + +$decorator = new ChainMessageDecorator([ + $decorator1, + $decorator2, +]); +``` + +## Use decorator + +To use the message decorator, you have to pass it to the `DefaultRepositoryManager`. ```php use Patchlevel\EventSourcing\EventBus\Decorator\ChainMessageDecorator; @@ -40,7 +62,7 @@ use Patchlevel\EventSourcing\Repository\DefaultRepositoryManager; $decorator = new ChainMessageDecorator([ new RecordedOnDecorator($clock), - new OnSystemRecordedDecorator() + new SplitStreamDecorator($eventMetadataFactory) ]); $repositoryManager = new DefaultRepositoryManager( @@ -56,10 +78,35 @@ $repository = $repositoryManager->get(Profile::class); !!! warning - We also use the decorator to fill in the `recordedOn` time. - If you want to add your own decorator, then you need to make sure to add the `RecordedOnDecorator` as well. - You can e.g. solve with the `ChainMessageDecorator`. + We also use the decorator to fill in the `RecordedOn` time. + If you want to add your own decorator or the SplitStreamDecorator, + then you need to make sure to add the `RecordedOnDecorator` as well. + +!!! note + + You can find out more about repository [here](repository). + +## Create own decorator + +You can also use this feature to add your own metadata to your events. For this the have an extra methods on `Message` +to add data `withCustomHeader` and to read this data later on `customHeader`. + +```php +use Patchlevel\EventSourcing\EventBus\Message; + +final class OnSystemRecordedDecorator implements MessageDecorator +{ + public function __invoke(Message $message): Message + { + return $message->withCustomHeader('system', 'accounting_system'); + } +} +``` !!! note - You can find out more about repository [here](repository). \ No newline at end of file + The Message is immutable, for more information look up [here](event_bus.md#message). + +!!! tip + + You can also set multiple headers with `withCustomHeaders` which expects an hashmap.