GITBOOK-893: No subject

Author: dgafka

SUMMARY.md

@@ -59,11 +59,12 @@
       * [Working with Aggregates](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/working-with-aggregates.md)
       * [Applying Events](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/applying-events.md)
       * [Different ways to Record Events](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/different-ways-to-record-events.md)
-      * [Making Stream immune to changes](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/making-stream-immune-to-changes.md)
-      * [Snapshoting](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/snapshoting.md)
     * [Working with Metadata](modelling/event-sourcing/event-sourcing-introduction/working-with-metadata.md)
     * [Event versioning](modelling/event-sourcing/event-sourcing-introduction/event-versioning.md)
     * [Event Stream Persistence](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy.md)
+      * [Event Sourcing Repository](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/event-sourcing-repository.md)
+      * [Making Stream immune to changes](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/making-stream-immune-to-changes.md)
+      * [Snapshoting](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/snapshoting.md)
       * [Persistence Strategies](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/persistence-strategies.md)
       * [Event Serialization and PII Data (GDPR)](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/event-serialization-and-pii-data-gdpr.md)
   * [Projection Introduction](modelling/event-sourcing/setting-up-projections/README.md)

enterprise.md

@@ -9,9 +9,9 @@ Ecotone comes with two plans:
 * **Ecotone Enterprise** is based Enterprise licence. It does provide more advanced features that help building larger scale systems, optimize resource costs and speed up daily development even more than the basic functionality.
 
 {% hint style="success" %}
-Each Enterprise feature is marked with hint on the documentation page. Enterprise features can't be run without licence key.\
+Each Enterprise feature is marked with hint on the documentation page. Enterprise features can only be run with licence key.\
 Enterprise Licence Keys will be sold at **https://ecotone.tech** in early **2025**.\
-Stay tuned by [subscribe to mailing list](https://blog.ecotone.tech/#/portal).
+Stay tuned by [subscribing to mailing list](https://blog.ecotone.tech/#/portal).
 {% endhint %}
 
 ## Available Enterprise Features

modelling/command-handling/repository.md

@@ -131,25 +131,7 @@ final class EcotoneTicketRepository implements StandardRepository
 }
 ```
 
-## Repository for Event Sourced Aggregate
-
-```php
-interface EventSourcedRepository
-{
-    public function canHandle(string $aggregateClassName): bool;
-    
-    1 public function findBy(string $aggregateClassName, array $identifiers) :  EventStream;
-
-    2 public function save(array $identifiers, string $aggregateClassName, array $events, array $metadata, int $versionBeforeHandling): void;
-}
-```
-
-Event Sourced Repository  instead of working with aggregate instance, works with events. 
-
-1. `findBy method` returns previously created events for given aggregate. 
-2. `save method` gets array of events to save returned by `CommandHandler` after performing an action
-
-### Set up your own Implementation
+## Set up your own Implementation
 
 When your implementation is ready simply mark it with `#[Repository]` attribute:
 
@@ -191,3 +173,7 @@ However, if we register multiple Repositories, then we need to take over the pro
 
 * In case of [Custom Repositories](repository.md#set-up-your-own-implementation) we do it using **canHandle** method.
 * In case of inbuilt Repositories, we should follow configuration section for given type
+
+## Repository for Event Sourced Aggregate
+
+Custom repository for Event Sourced Aggregates is described in more details under [Event Sourcing Repository section](../event-sourcing/event-sourcing-introduction/persistence-strategy/event-sourcing-repository.md).

modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/working-with-aggregates.md

@@ -84,7 +84,7 @@ We will explore how applying Events works more in [next section](applying-events
 ### Aggregate Type
 
 Aggregate Type will be the same as Aggregate Class. \
-We can decouple the class from the Aggregate Type, more about this can be found in "[Making Stream immune to changes](making-stream-immune-to-changes.md)" section.
+We can decouple the class from the Aggregate Type, more about this can be found in "[Making Stream immune to changes](../persistence-strategy/making-stream-immune-to-changes.md)" section.
 
 ### Recording Events in the Event Stream
 
@@ -117,4 +117,4 @@ $eventStore->appendTo(
 ```
 
 As storing in Event Store is abstracted away, the code stays clean and contains only of the business part. \
-We can [customize](making-stream-immune-to-changes.md) the Stream Name, Aggregate Type and even Event Names when needed.
+We can [customize](../persistence-strategy/making-stream-immune-to-changes.md) the Stream Name, Aggregate Type and even Event Names when needed.

modelling/event-sourcing/event-sourcing-introduction/event-versioning.md

@@ -79,5 +79,5 @@ class Product
 
 {% hint style="success" %}
 We may inject any type of Header that was stored together with the Event. \
-This means inbuilt headers like **timestamp**, **id**, **correlationId are avaiable** out of the box**.**
+This means inbuilt not only headers like **timestamp**, **id**, **correlationId are avaiable** out of the box, but also custom headers provided by the application (e.g. userId).
 {% endhint %}

modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/event-sourcing-repository.md

@@ -0,0 +1,140 @@
+# Event Sourcing Repository
+
+Ecotone comes with inbuilt Event Sourcing repository after [Event Sourcing package is installed](../../installation.md). However you want to roll out your own storage for Events, or maybe you already use some event-sourcing framework and would like to integrate with it. \
+For this you can take over the control by introducing your own Event Sourcing Repository.
+
+{% hint style="warning" %}
+Using Custom Event Sourcing Repository will not allow you to make use of [inbuilt projection system](../../setting-up-projections/). Therefore consider configuring your own Event Sourcing Repository only if you want  to build your own projecting system.
+{% endhint %}
+
+## Custom Event Sourcing Repository
+
+We do start by implementing **EventSourcingRepository** interface:
+
+```php
+interface EventSourcedRepository
+{
+    1. public function canHandle(string $aggregateClassName): bool;
+    
+    2. public function findBy(string $aggregateClassName, array $identifiers, int $fromAggregateVersion = 1) :  EventStream;
+
+    3. public function save(array $identifiers, string $aggregateClassName, array $events, array $metadata, int $versionBeforeHandling): void;
+}
+```
+
+1. **canHandle** - Tells whatever given Aggregate is handled by this Repository
+2. **findBy** - Method returns previously created events for given aggregate. Which Ecotone will use to reconstruct the Aggregate. 
+3. **save** - Stores events recorded by Event Sourced Aggregate
+
+and then we need to mark class which implements this interface as **Repository**
+
+```php
+#[Repository]
+class CustomEventSourcingRepository
+```
+
+## Storing Events
+
+Ecotone provides enough information to decide how to store provided events. 
+
+```php
+public function save(
+    array $identifiers, 
+    string $aggregateClassName, 
+    array $events, 
+    array $metadata, 
+    int $versionBeforeHandling
+): void;
+```
+
+Identifiers will hold array of **identifiers** related to given aggregate (e.g. _\["orderId" ⇒ 123]_). \
+**Events** will be list of Ecotone's Event classes, which contains of **payload** and **metadata,** where payload is your Event class instance and metadata is specific to this event. \
+**Metadata** as parameter is generic metadata available at the moment of Aggregate execution.\
+**Version** before handling on other hand is the version of the Aggregate before any action was triggered on it. This can be used to protect from concurrency issues.
+
+The structure of Events is as follows:
+
+```php
+class Event
+{
+    private function __construct(
+        private string $eventName, // either class name or name of the event
+        private object $payload, // event object instance
+        private array $metadata // related metadata
+    )
+}
+```
+
+### Core metadata
+
+It's worth to mention about Ecotone's Events and especially about metadata part of the Event.\
+Each metadata for given Event contains of three core Event attributes:
+
+**"\_aggregate\_id" -** This provides aggregate identifier of related Aggregate
+
+**"\_aggregate\_version" -** This provides version of the related Event (e.g. 1/2/3/4)
+
+**"\_aggregate\_type" -** This provides type of the Aggregate being stored, which can be customized
+
+### Aggregate Type
+
+If our repository stores multiple Aggregates is useful to have the information about the type of Aggregate we are storing. However keeping the class name is not best idea, as simply refactor would break our Event Stream. Therefore Ecotone provides a way to mark our Aggregate type using Attribute
+
+```php
+#[EventSourcingAggregate]
+#[AggregateType("basket")]
+class Basket
+```
+
+This now will be passed together with Events under **\_aggregate\_type** metadata.
+
+### Named Events
+
+In Ecotone we can name the events to avoid storing class names in the Event Stream, to do so we use NamedEvent.
+
+```php
+#[NamedEvent("order_was_placed")]
+class OrderWasPlaced
+```
+
+then when events will be passed to save method, they will automatically provide this name under **eventName** property.
+
+## Snapshoting
+
+With custom repository we still can use inbuilt [Snapshoting mechanism](snapshoting.md). To use it for customized repository we will use **BaseEventSourcingConfiguration**.
+
+```php
+#[ServiceContext]
+public function configuration()
+{
+    return BaseEventSourcingConfiguration::withDefaults()
+            ->withSnapshotsFor(Basket::class, thresholdTrigger: 100);
+}
+```
+
+Ecotone then after fetching snapshot, will load events only from this given moment using **\`fromAggregateVersion\`.**
+
+```php
+public function findBy(
+    string $aggregateClassName, 
+    array $identifiers, 
+    int $fromAggregateVersion = 1
+) 
+```
+
+## Testing
+
+If you want to test out your flow and storing with your custom Event Sourced Repository, you should disable default in memory repository
+
+```php
+$repository = new CustomEventSourcingRepository;
+$ecotoneLite = EcotoneLite::bootstrapFlowTesting(
+    [OrderAggregate::class, CustomEventSourcingRepository::class],
+    [CustomEventSourcingRepository::class => $repository],
+    addInMemoryEventSourcedRepository: false,
+);
+
+$ecotoneLite->sendCommand(new PlaceOrder());
+
+$this->assertNotEmpty($repository->getEvents());
+```

modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/making-stream-immune-to-changes.md renamed to modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/making-stream-immune-to-changes.md

@@ -61,3 +61,13 @@ class BasketWasCreated
 ```
 
 This way Ecotone will do the mapping before storing an Event and when retrieving the Event in order to deserialize it to correct class.
+
+## Testing
+
+It's worth to remember that if we want test storing Events using provided Event Named, we need to add them under recognized classes, so Ecotone knows that should scan those classes for Attributes:
+
+```php
+$ecotoneLite = EcotoneLite::bootstrapFlowTesting(
+    [Basket::class, BaskeWasCreated::class],
+);
+```

modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/snapshoting.md renamed to modelling/event-sourcing/event-sourcing-introduction/persistence-strategy/snapshoting.md

@@ -7,16 +7,13 @@ description: PHP Event Sourcing Snapshoting
 In general having streams in need for snapshots may indicate that our model needs revisiting. \
 We may cut the stream on some specific event and begin new one, like at the end of month from all the transactions we generate invoice and we start new stream for next month. \
 \
-However if cutting the stream off is not an option for any reason, we snapshot aggregate state at given point of time, so we can skip previous events. \
-This process continues on predefined threshold, like every 1000 events. 
+However if cutting the stream off is not an option for any reason, we can use snapshots to avoid loading all events history for given Aggregate. Every given set of events snapshot will be taken, stored and retrieved on next calls, to fetch only events that happened after that.
 
 ## Setting up 
 
 `EventSourcingConfiguration` provides the following interface to set up snapshots.
 
 ```php
-use Ecotone\Messaging\Store\Document\DocumentStore;
-
 class EventSourcingConfiguration
 {
     public const DEFAULT_SNAPSHOT_TRIGGER_THRESHOLD = 100;
@@ -51,3 +48,13 @@ Ecotone make use of [Document Store](../../../../messaging/document-store.md) to
 \
 If you want to clean the snapshots, you can do it manually. Snapshots are stored in `aggregate_snapshots` collection.
 {% endhint %}
+
+## Snapshot threshold
+
+Threshold states at which interval snapshots should be done. Therefore with below configuration:
+
+```php
+->withSnapshotsFor(Ticket::class, 500)
+```
+
+snapshots will be done every 500 events. Then when snapshot will be loaded, it will start loading the events from event number 501 for given Aggregate instance.

quick-start-php-ddd-cqrs-event-sourcing/README.md

@@ -17,7 +17,7 @@ If you're looking on way to start and get to familiar with Ecotone. Then Ecotone
 * [Subscribe to Mailing list](https://blog.ecotone.tech/#/portal) - Join mailing list to stay up to date with Ecotone changes and latest articles and features.
 
 {% hint style="success" %}
-Ecotone does not bind given features to specific Framework. Whatever you use Laravel or Symfony or Lite (no external framework), all examples will be able to work in your Application. \
+Some demo and quick-start examples which are done using specific framework integration. However Ecotone does not bind given set of features to specific solution. Whatever you use Laravel or Symfony or Lite (no external framework), all features will in same way. \
 \
-Therefore feel encouraged to test examples, even if they are in different Framework than one you use, as you will be able to use them same way in your Application.
+Therefore feel encouraged to test out examples, even if they are not framework of your choose.
 {% endhint %}