[DOCS] rewrite getting started guide

docs/_data/menu.yml

@@ -9,14 +9,10 @@ EventSauce:
     Changelog: '/docs/changelog/'
     <span class="github-link-icon"><img class="w-5 h-5 mr-1" src="/static/github.svg" /></span> Github: 'https://github.com/eventsaucephp/eventsauce'
 
-Stop Russia's Aggression:
-  Support Ukraine: https://savelife.in.ua/en/
-
 Getting Started:
-    1. Create an Aggregate Root: '/docs/event-sourcing/create-an-aggregate-root/'
-    2. Create Events and Commands: '/docs/event-sourcing/create-events-and-commands/'
-    3. Configure Persistence: '/docs/event-sourcing/configure-persistence/'
-    4. Bootstrap: '/docs/event-sourcing/bootstrap/'
+  1. Intro and install: '/docs/getting-started/introduction/'
+  2. Create an Aggregate Root: '/docs/getting-started/create-aggregate-root/'
+  3. Implement your first method: '/docs/getting-started/implement-your-first-method/'
 
 Serialization:
   Object Mapper: '/docs/serialization/object-mapper/'

docs/docs/event-sourcing/1-creating-an-aggregate-root.md

@@ -1,6 +1,5 @@
 ---
 permalink: /docs/event-sourcing/create-an-aggregate-root/
-redirect_from: /docs/getting-started/create-an-aggregate-root/
 title: Creating an Aggregate Root
 ---
 

docs/docs/event-sourcing/2-create-events-and-commands.md

@@ -1,6 +1,5 @@
 ---
 permalink: /docs/event-sourcing/create-events-and-commands/
-redirect_from: /docs/getting-started/create-events-and-commands/
 title: Create events and commands
 ---
 

docs/docs/event-sourcing/3-configure-persistence.md

@@ -1,6 +1,5 @@
 ---
 permalink: /docs/event-sourcing/configure-persistence/
-redirect_from: /docs/getting-started/configure-persistence/
 title: Configure Persistence
 ---
 

docs/docs/event-sourcing/4-bootstrap.md

@@ -1,6 +1,5 @@
 ---
 permalink: /docs/event-sourcing/bootstrap/
-redirect_from: /docs/getting-started/bootstrap/
 title: Bootstrap
 alternate_title: Bootstrapping EventSauce
 ---

docs/docs/getting-started/0-getting-started.md

@@ -0,0 +1,29 @@
+---
+permalink: /docs/getting-started/introduction/
+redirect_from: /docs/getting-started/
+title: Getting Started
+---
+
+EventSauce is a pragmatic yet robust event sourcing library for PHP. At the heart of the library
+are a set of simple interfaces that make it easy to adapt many types of infrastructure. A set of
+ready-made components is there to speed up implementation. This guide will walk you through
+the steps needed to set yourself up to start event sourcing. The guide will only focus on
+what is relevant to setting up the library. Although there are some framework bindings available,
+this guide will use a framework-agnostic point of view. You are expected to make the translation
+on how to configure this in your framework of choice.
+
+In this guide we'll walk to initial setup, setting up tests for your aggregates, and wiring it
+to infrastructure. Let's get started!
+
+## Installation
+
+To get started, first install EventSauce into your PHP project using
+[composer](https://getcomposer.org).
+
+```bash
+composer require eventsauce/eventsauce
+```
+
+This package contains the core of EventSauce, the interfaces, and generic tools.
+
+Next up, create your first [aggregate root](/docs/getting-started/create-aggregate-root/)!

docs/docs/getting-started/1-create-your-aggregate-root.md

@@ -0,0 +1,31 @@
+---
+permalink: /docs/getting-started/create-aggregate-root/
+title: Create an Aggregate Root
+---
+
+Our first step is to create an event-sourced aggregate root. This is the domain model
+we'll create that internally uses events. An aggregate root constructs itself from a
+series of historical events. Inset of mutating properties directly, it uses events to
+capture what is happening.
+
+Simplified, you can say that a `historical events => model` and `model + action = new events`.
+
+EventSauce represents an aggregate root internally as an interface. Your model will be an
+implementation of that interface. To make it easy, a default implementation is supplied in
+the form of a trait, preventing you from having to write some boilerplate code.
+
+```php
+namespace YourCompany\YourBusinessProcess;
+
+use EventSauce\EventSourcing\AggregateRoot;
+use EventSauce\EventSourcing\AggregateRootBehaviour;
+
+/**
+
+class AccountCreation implements AggregateRoot
+{
+    use AggregateRootBehaviour;
+}
+```
+
+Next up, implement your first [method](/docs/getting-started/implement-your-first-method/)!

docs/docs/getting-started/2-implement-your-first-method.md

@@ -0,0 +1,83 @@
+---
+permalink: /docs/getting-started/implement-your-first-method/
+title: Implement your first method
+---
+
+In event sourcing, actions performed on entities (aggregate roots) record events
+to capture the outcome of said action. The event captures the intent of the moment
+in time, along with any relevant context. In EventSauce events are represented as
+simple PHP classes/objects.
+
+As an example, let's implement an account creation flow. The flow is a multistep process
+that results in an account being created. Our flow is short and simple, but you can imagine
+more elaborate flows being modelled in a similar manner. In this example, our flow consists
+of: 
+
+1. starting the account creation process
+2. specifying login credentials
+3. accepting the terms and finalizing the process
+
+The code below is the body of our `AccountCreation` class.
+```php
+private string|null $email = null;
+private string|null $passwordHash = null;
+private bool $finalized = false;
+private bool $credentialsProvided = false;
+
+// start the creation process
+public static function startAccountCreation(ApplicationId $id): AccountCreation
+{
+    $process = new AccountCreation($id);
+    $process->recordThat(AccountCreationHasStarted());    
+
+    return $process;
+}
+
+public function useLoginCredentials(
+    string $email,
+    string $password,
+    PasswordEncoder $passwordEncoder,
+): void {
+    $this->guardAgainstChangingFinalizedAccount();
+
+    if (strlen($password) < 8) {
+        throw InvalidPasswordProvided::becauseItIsTooShort($password);
+    }
+
+    $passwordHash = $passwordEncoder->encodePassword($password);
+
+    $this->recordThat(
+        new LoginCredentialsWereProvided($email, $passwordHash)
+    );
+}
+
+protected function applyLoginCredentialsWereProvided(
+    LoginCredentialsWereProvided $event
+) {
+    $this->credentialProvided = true;
+    $this->email = $event->email();
+    $this->passwordHash = $event->passwordHash();
+}
+
+public function finalizeAccount(
+    bool $acceptTerms,
+    AccountRepository $accounts,
+): void {
+    $this->guardAgainstChangingFinalizedAccount();
+
+    if ( ! $acceptTerms) {
+        throw UnableToFinalizeAccount::termsWereNotAccepted();
+    }
+
+    if ( ! $this->credentialsProvided) {
+        throw UnableToFinalizeAccount::credentialsWereNotProvided();
+    }
+}
+
+private function guardAgainstChangingFinalizedAccount(): void
+{
+    if ($this->finalized) {
+        throw new UnableToChangeFinalizedAccount();
+    }
+}
+```