Merge pull request #46 from patchlevel/add-aggregate-dokumentation

DavidBadura · web-flow · commit 5eb9730cd0cb · 2022-01-10T11:47:22.000+01:00
add aggregate documentation
diff --git a/README.md b/README.md
@@ -34,6 +34,7 @@ this [installation documentation](docs/installation.md).
 We recommend reading the documentation for the [library](https://github.com/patchlevel/event-sourcing) first, 
 as this documentation only deals with bundle integration.
 
+* [Aggregate](docs/aggregate.md)
 * [Repository](docs/repository.md)
 * [Event Bus](docs/event_bus.md)
 * [Processor](docs/processor.md)
@@ -149,6 +150,7 @@ use Patchlevel\EventSourcing\Aggregate\AggregateChanged;
 use Patchlevel\EventSourcing\Aggregate\AggregateRoot;
 use Symfony\Component\Uid\Uuid;
 
+#[Aggregate(name: 'hotel')]
 final class Hotel extends AggregateRoot
 {
     private Uuid $id;
@@ -231,42 +233,9 @@ final class Hotel extends AggregateRoot
 }
 ```
 
-> :book: You can find out more about aggregates 
-> and events in the library [documentation](https://github.com/patchlevel/event-sourcing#documentation).
+> :warning: The attribute variant is only available since v1.2. Switch to the v1.1 branch to read the older documentation.
 
-Next we have to make our aggregate known:
-
-```yaml
-patchlevel_event_sourcing:
-  aggregates:
-    hotel:
-      class: App\Domain\Hotel\Hotel
-```
-
-or by adding the corresponding aggregate attribute.
-The snapshotStore is optional and `null` by default.
-
-```php
-namespace App\Domain\Hotel;
-
-use Patchlevel\EventSourcing\Aggregate\AggregateChanged;
-use Patchlevel\EventSourcing\Aggregate\AggregateRoot;
-use Patchlevel\EventSourcingBundle\Attribute\Aggregate;
-
-#[Aggregate(name: 'hotel', snapshotStore: 'default')]
-final class Hotel extends AggregateRoot
-{
-    protected function apply(AggregateChanged $event): void
-    {
-    
-    }
-
-    public function aggregateRootId(): string
-    {
-        return '1';
-    }
-}
-```
+> :book: You can find out more about aggregates [here](./docs/aggregate.md).
 
 ### Define projections
 
diff --git a/docs/aggregate.md b/docs/aggregate.md
@@ -0,0 +1,81 @@
+# Aggregate
+
+> Aggregate is a pattern in Domain-Driven Design. A DDD aggregate is a cluster of domain objects
+> that can be treated as a single unit. [...]
+>
+> :book: [DDD Aggregate - Martin Flower](https://martinfowler.com/bliki/DDD_Aggregate.html)
+
+You can find out more about the aggregates in the library [documentation](https://github.com/patchlevel/event-sourcing#documentation). 
+This documentation is limited to bundle integration.
+
+## Register aggregates
+
+So that the necessary service such as the repositories are available, 
+you have to register all aggregates.
+
+You can do this in the Yaml definition by listing all aggregates with names and the associated class.
+
+```yaml
+patchlevel_event_sourcing:
+  aggregates:
+    hotel:
+      class: App\Domain\Hotel\Hotel
+```
+
+Or you use the attribute variant (since v1.2). 
+Here you have to give all aggregates the `Aggregate` attribute and give the associated name.
+
+```php
+namespace App\Domain\Hotel;
+
+use Patchlevel\EventSourcing\Aggregate\AggregateRoot;
+use Patchlevel\EventSourcingBundle\Attribute\Aggregate;
+
+#[Aggregate(name: 'hotel')]
+final class Hotel extends AggregateRoot
+{
+    // ...
+}
+```
+
+So that the bundle knows where to look, you also have to specify a path.
+
+```yaml
+patchlevel_event_sourcing:
+  aggregates_paths: '%kernel.project_dir%/src'
+```
+
+> :book: You can also define multiple paths by specifying an array.
+
+## Use snapshots
+
+You can also tell each aggregate that it should use snapshots 
+so that the rebuilding of the state is faster.
+
+To do this, a snapshot store must first be defined. 
+You can read that [here](snapshots.md).
+
+And then you can define the snapshot on the aggregates.
+
+```yaml
+patchlevel_event_sourcing:
+  aggregates:
+    hotel:
+      class: App\Domain\Hotel\Hotel
+      snapshot: default
+```
+
+If you are using attributes then you have to put the snapshot there.
+
+```php
+namespace App\Domain\Hotel;
+
+use Patchlevel\EventSourcing\Aggregate\SnapshotableAggregateRoot;
+use Patchlevel\EventSourcingBundle\Attribute\Aggregate;
+
+#[Aggregate(name: 'hotel', snapshotStore: 'default')]
+final class Hotel extends SnapshotableAggregateRoot
+{
+   // ...
+}
+```
diff --git a/docs/installation.md b/docs/installation.md
@@ -44,6 +44,7 @@ Now you have to add a minimal configuration file here `config/packages/patchleve
 
 ```yaml
 patchlevel_event_sourcing:
+    aggregates_paths: '%kernel.project_dir%/src'
     connection:
         url: '%env(EVENTSTORE_URL)%'
 ```
diff --git a/docs/snapshots.md b/docs/snapshots.md
@@ -46,6 +46,23 @@ patchlevel_event_sourcing:
             snapshot_store: default
 ```
 
+If you are using attributes then you have to put the snapshot there.
+
+```php
+namespace App\Domain\Profile;
+
+use Patchlevel\EventSourcing\Aggregate\SnapshotableAggregateRoot;
+use Patchlevel\EventSourcingBundle\Attribute\Aggregate;
+
+#[Aggregate(name: 'profile', snapshotStore: 'default')]
+final class Profile extends SnapshotableAggregateRoot
+{
+    // ...
+}
+```
+
+> :book: You can find out more about the attributes [here](aggregate.md).
+
 ## Batch (since v1.2)
 
 So that not every write process also writes to the cache at the same time, 
