Merge pull request #18 from patchlevel/add-more-docs

add more docs

README.md

@@ -8,15 +8,18 @@ a symfony integration of a small lightweight [event-sourcing](https://github.com
 
 ## Installation
 
-```
+```bash
 composer require patchlevel/event-sourcing-bundle
 ```
 
-If you don't use the symfony flex recipe for this bundle, you need to follow
+> :warning: If you don't use the symfony flex recipe for this bundle, you need to follow
 this [installation documentation](docs/installation.md).
 
 ## Documentation
 
+We recommend reading the documentation for the [library](https://github.com/patchlevel/event-sourcing) first, 
+as this documentation only deals with bundle integration.
+
 * [Repository](docs/repository.md)
 * [Event Bus](docs/event_bus.md)
 * [Processor](docs/processor.md)

composer.json

@@ -2,7 +2,7 @@
   "name": "patchlevel/event-sourcing-bundle",
   "type": "symfony-bundle",
   "license": "MIT",
-  "description": "todo",
+  "description": "symfony bundle for patchlevel/event-sourcing",
   "keywords": [
     "event-sourcing"
   ],
@@ -18,8 +18,8 @@
     }
   ],
   "require": {
-    "php": "^7.4|^8.0",
-    "ext-json": "^7.4|^8.0",
+    "php": "~7.4.0|~8.0.0",
+    "ext-json": "~7.4.0|~8.0.0",
     "doctrine/dbal": "^3.1.4",
     "patchlevel/event-sourcing": "^1.0.0",
     "psr/simple-cache": "^1.0.1",
@@ -30,7 +30,7 @@
     "symfony/console": "^4.4.18|^5.1.10"
   },
   "require-dev": {
-    "ext-pdo_sqlite": "^7.4|^8.0",
+    "ext-pdo_sqlite": "~7.4.0|~8.0.0",
     "doctrine/migrations": "^3.3",
     "infection/infection": "^0.21.5",
     "patchlevel/coding-standard": "^1.1.1",

docs/event_bus.md

@@ -0,0 +1,45 @@
+# Event Bus
+
+This library uses the core principle called [event bus](https://martinfowler.com/articles/201701-event-driven.html).
+
+For all events that are persisted (when the `save` method has been executed on the [repository](./repository.md)),
+the event will be dispatched to the `event bus`. All listeners are then called for each event.
+
+## Symfony Event Bus
+
+To use the [Symfony Messager](https://symfony.com/doc/current/messenger.html), 
+you have to define it in messenger.yaml.
+It's best to call the bus "event.bus".
+An event bus can have 0 or n listener for an event. 
+So "allow_no_handlers" has to be configured.
+
+```yaml
+framework:
+    messenger:
+        buses:
+            event.bus:
+                default_middleware: allow_no_handlers
+```
+
+We can then use this message or event bus in event sourcing:
+
+```yaml
+patchlevel_event_sourcing:
+    event_bus:
+        service: event.bus
+```
+
+## Command Bus
+
+If you use a command bus or cqrs as a pattern, then you should define a new message bus. 
+The whole thing can look like this:
+
+```yaml
+framework:
+    messenger:
+        default_bus: command.bus
+        buses:
+            command.bus: ~
+            event.bus:
+                default_middleware: allow_no_handlers
+```

docs/installation.md

@@ -1,15 +1,61 @@
+# Installation
 
-### Define your aggregates with class namespace and the table name
+If you are not using a symfony [flex](https://github.com/symfony/flex) 
+or the [recipes](https://flex.symfony.com/) for it, 
+then you have to carry out a few installation steps by hand.
 
-Class `App\Domain\Profile\Profile` is from the [libraries example](https://github.com/patchlevel/event-sourcing#define-aggregates) and is using the table name `profile`
+## Require package
 
+The first thing to do is to install packet if it has not already been done.
+
+```bash
+composer require patchlevel/event-sourcing-bundle
+```
+
+> :book: how to install [composer](https://getcomposer.org/doc/00-intro.md)
+
+## Enable bundle
+
+Then we have to activate the bundle in the `config/bundles.php`:
+
+```php
+return [
+    Patchlevel\EventSourcingBundle\PatchlevelEventSourcingBundle::class => ['all' => true],
+];
+```
+
+If you don't have `config/bundles.php` then you need to add the bundle in the kernel:
+
+```php
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            new Patchlevel\EventSourcingBundle\PatchlevelEventSourcingBundle(),
+        ];
+    }
+}
 ```
+
+## Configuration file
+
+Now you have to add a minimal configuration file here `config/packages/patchlevel_event_sourcing.yaml`.
+
+```yaml
 patchlevel_event_sourcing:
     connection:
         url: '%env(EVENTSTORE_URL)%'
-    store:
-        type: multi_table
-    aggregates:
-        profile:
-            class: App\Domain\Profile\Profile
 ```
+
+## Dotenv
+
+Finally we have to fill the ENV variable with a connection url.
+
+```dotenv
+EVENTSTORE_URL: mysql://user:secret@localhost/app
+```
+
+> :book: You can find out more about what a connection url looks like [here](https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url).
+
+Now you can go back to [getting started](https://github.com/patchlevel/event-sourcing-bundle#getting-started).

docs/processor.md

@@ -0,0 +1,50 @@
+# Processor
+
+The `processor` is a kind of [event bus](./event_bus.md) listener that can execute actions on certain events.
+A process can be for example used to send an email when a guest is checked in:
+
+```php
+namespace App\Domain\Hotel\Listener;
+
+use App\Domain\Hotel\Event\GuestIsCheckedIn;
+use Patchlevel\EventSourcing\Aggregate\AggregateChanged;
+use Patchlevel\EventSourcing\EventBus\Listener;
+use Symfony\Component\Mailer\MailerInterface;
+use Symfony\Component\Mime\Email;
+
+final class SendCheckInEmailListener implements Listener
+{
+    private MailerInterface $mailer;
+
+    private function __construct(MailerInterface $mailer) 
+    {
+        $this->mailer = $mailer;
+    }
+
+    public function __invoke(AggregateChanged $event): void
+    {
+        if (!$event instanceof GuestIsCheckedIn) {
+            return;
+        }
+
+        $email = (new Email())
+            ->from('[email protected]')
+            ->to('[email protected]')
+            ->subject('Guest is checked in')
+            ->text(sprintf('A new guest named "%s" is checked in', $event->guestName()));
+
+        $this->mailer->send($email);
+    }
+}
+```
+
+If you have the symfony default service setting with `autowire`and `autoconfiger` enabled, 
+the processor is automatically recognized and registered at the `Listener` interface. 
+Otherwise you have to define the processor in the symfony service file:
+
+```yaml
+services:
+    App\Domain\Hotel\Listener\SendCheckInEmailListener:
+      tags:
+        - event_sourcing.processor
+```