From bdb280ebbc5d8a334803c2749c5de3541ced8bff Mon Sep 17 00:00:00 2001
From: codeliner <kontakt@codeliner.ws>
Date: Sun, 15 Oct 2017 00:23:40 +0200
Subject: [PATCH] Restructure docs

---
 docs/bookdown.json                            |   8 +-
 ...{event_store.md => event_store_plugins.md} |  32 ++---
 docs/implementations/bookdown.json            |   8 ++
 docs/introduction.md                          | 125 ++++++++++++++++++
 4 files changed, 155 insertions(+), 18 deletions(-)
 rename docs/{event_store.md => event_store_plugins.md} (89%)
 create mode 100644 docs/implementations/bookdown.json
 create mode 100644 docs/introduction.md

diff --git a/docs/bookdown.json b/docs/bookdown.json
index 77a7a56d..16e5b772 100644
--- a/docs/bookdown.json
+++ b/docs/bookdown.json
@@ -1,13 +1,17 @@
 {
   "title": "Event Store",
   "content": [
-    {"intro": "../README.md"},
-    {"event_store": "event_store.md"},
+    {"intro": "introduction.md"},
+    {"implementations": "implementations/bookdown.json"},
+    {"event_store_plugins": "event_store_plugins.md"},
     {"projections": "projections.md"},
+    {"standard_projections": "https://raw.githubusercontent.com/prooph/standard-projections/master/docs/bookdown.json"},
     {"upcasting": "upcasting.md"},
     {"interop_factories": "interop_factories.md"},
     {"migration": "migration.md"}
   ],
+  "tocDepth": 1,
+  "numbering": false,
   "target": "./html",
   "template": "../vendor/prooph/bookdown-template/templates/main.php"
 }
diff --git a/docs/event_store.md b/docs/event_store_plugins.md
similarity index 89%
rename from docs/event_store.md
rename to docs/event_store_plugins.md
index 4d59512f..da1683a4 100644
--- a/docs/event_store.md
+++ b/docs/event_store_plugins.md
@@ -1,20 +1,7 @@
-# Prooph Event Store
+# Plugins & Extensions
 
-Prooph Event Store is the central component of this package. If you are familiar with doctrine
-you can compare it with doctrine's EntityManager.
-However, Prooph Event Store is especially designed to add a centralized, event-driven system on top
-of different low level event stream persistence adapters (f.e. MySQL or Postgres).
-The event-driven store is the unique selling point of prooph/event-store compared to other libraries.
-So let's directly jump into it and see what you can do with it.
-
-## ReadOnlyEventStoreWrapper
-
-In case you need a read only event store, you can wrap your existing event store implementation with the
-ReadOnlyEventStoreWrapper.
-
-```php
-$readOnlyEventStore = new ReadOnlyEventStoreWrapper($eventStore);
-```
+A prooph Event Store can be expanded using plugins. Some plugins are provided by prooph but you can write your own ones
+to customize the event store using event hooks.
 
 ## Event Hooks
 
@@ -117,3 +104,16 @@ $plugin->attachToEventStore($eventStore);
 
 All internal metadata is prefixed with `_` (underscore), f.e. `_causation_id`. Do not use metadata keys starting with an
 underscore, as this is reserved for prooph internals.
+
+## ReadOnlyEventStoreWrapper
+
+The event store interface is divided into read-only methods, see `Prooph\EventStore\ReadOnlyEventStore` and write methods
+see `Prooph\EventStore\EventStore`. This distinction is useful in situations where you want to enforce ready-only access to 
+the event store.
+
+In case you need a read only event store, you can wrap your existing event store implementation with the
+ReadOnlyEventStoreWrapper.
+
+```php
+$readOnlyEventStore = new ReadOnlyEventStoreWrapper($eventStore);
+```
diff --git a/docs/implementations/bookdown.json b/docs/implementations/bookdown.json
new file mode 100644
index 00000000..ed83c9c1
--- /dev/null
+++ b/docs/implementations/bookdown.json
@@ -0,0 +1,8 @@
+{
+  "title": "Implementations",
+  "tocDepth": 1,
+  "numbering": false,
+  "content": [
+    {"pdo_event_store": "https://raw.githubusercontent.com/prooph/pdo-event-store/master/docs/bookdown.json"}
+  ]
+}
\ No newline at end of file
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 00000000..426d310f
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,125 @@
+# Introduction
+
+Prooph Event Store is capable of persisting event messages that are organized in streams. `Prooph\EventStore\EventStore`
+itself is an interface with implementations available for different databases. 
+
+## Quickstart
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Prooph\EventStore\QuickStart;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+require_once __DIR__ . '/../examples/event/QuickStartSucceeded.php';
+
+use ArrayIterator;
+use Prooph\Common\Event\ActionEvent;
+use Prooph\Common\Event\ProophActionEventEmitter;
+use Prooph\EventStore\ActionEventEmitterEventStore;
+use Prooph\EventStore\InMemoryEventStore;
+use Prooph\EventStore\QuickStart\Event\QuickStartSucceeded;
+use Prooph\EventStore\Stream;
+use Prooph\EventStore\StreamName;
+use Prooph\EventStore\TransactionalActionEventEmitterEventStore;
+
+/**
+ * Here we use the InMemoryEventStore but in a real project
+ * you need to chose another implementation.
+ * 
+ * The InMemoryEventStore is good for testing purposes, though.
+ *
+ * Prooph\Common\Event\ActionEventEmitter is an interface
+ * that encapsulates functionality of an event dispatcher.
+ * You can use the one provided by prooph/common or
+ * you write a wrapper for the event dispatcher used
+ * by your web framework.
+ */
+$eventEmitter = new ProophActionEventEmitter(TransactionalActionEventEmitterEventStore::ALL_EVENTS);
+
+$eventStore = new ActionEventEmitterEventStore(new InMemoryEventStore(), $eventEmitter);
+
+/**
+ * We need a test event so let's create one.
+ *
+ * As a bare minimum events need to implement
+ * Prooph\Common\Messaging\Message.
+ *
+ * Note: It is possible to use your own events
+ * in your domain and use a translator to
+ * convert them. We'll come to that later.
+ */
+$quickStartSucceeded = QuickStartSucceeded::withSuccessMessage('It works');
+
+/**
+ * Events are organized in so called event streams.
+ * An event stream is a logical unit for a group of events.
+ */
+$streamName = new StreamName('event_stream');
+
+$singleStream = new Stream($streamName, new ArrayIterator());
+
+/**
+ * As we are using the InMemoryEventStore we have to create the event stream
+ * each time running the quick start. With a real persistence adapter this
+ * is not required. In this case you should create the stream once. For example
+ * with the help of a migration script.
+ *
+ * Note: For more details see the docs of the adapter you want to use.
+ */
+$eventStore->create($singleStream);
+
+/**
+ * Next step would be to commit the transaction.
+ * But let's attach a plugin first that prints some information about currently added events.
+ * Plugins are simple event listeners. See the docs of prooph/common for more details about event listeners.
+ */
+$eventStore->attach(
+    ActionEventEmitterEventStore::EVENT_APPEND_TO, // InMemoryEventStore provides event hooks
+    function (ActionEvent $actionEvent): void {
+        /**
+         * In the *appendTo* action event a plugin has access to
+         * all recorded events which were added in the current committed transaction.
+         * It is the ideal place to attach a domain event dispatcher.
+         * We only use a closure here to print the recorded events in the terminal
+         */
+        $recordedEvents = $actionEvent->getParam('streamEvents');
+
+        foreach ($recordedEvents as $recordedEvent) {
+            echo sprintf(
+                "Event with name %s was recorded. It occurred on %s ///\n\n",
+                $recordedEvent->messageName(),
+                $recordedEvent->createdAt()->format('Y-m-d H:i:s')
+            );
+        }
+    },
+    -1000 // low priority, so after action happened
+);
+
+/**
+ * Now we can easily add events to the stream ...
+ */
+$eventStore->appendTo($streamName, new ArrayIterator([$quickStartSucceeded /*, ...*/]));
+
+/**
+ * Once committed you can of course also load a set of events or the entire stream
+ * Use $eventStore->loadEventsByMetadataFrom($streamName, $metadata, $minVersion);
+ * to load a list of events
+ *
+ * or the $eventStore->load($streamName); to get all events
+ */
+$persistedEventStream = $eventStore->load($streamName);
+
+foreach ($persistedEventStream as $event) {
+    if ($event instanceof QuickStartSucceeded) {
+        echo $event->getText();
+    }
+}
+
+```
+
+## Video Introduction
+
+[![Prooph Event Store v7](https://img.youtube.com/vi/QhpDIqYQzg0/0.jpg)](https://www.youtube.com/watch?v=QhpDIqYQzg0)
\ No newline at end of file