Update README.md

Signed-off-by: Pascal Cremer <pascal.cremer@geekcell.io>

Author: b00gizm

README.md

@@ -2,6 +2,17 @@
 
 This Symfony bundle augments [geekcell/php-ddd](https://github.com/geekcell/php-ddd) with framework-specific implementations to enable seamless [domain driven design](https://martinfowler.com/tags/domain%20driven%20design.html) in a familiar environment.
 
+---
+
+- [Installation](#installation)
+- [Generator Commands](#generator-commands)
+- [Building Blocks](#building-blocks)
+    - [Model & Repository](#model--repository)
+    - [AggregateRoot & Domain Events](#aggregateroot--domain-events)
+    - [Command & Query](#command--query)
+    - [Controller](#controller)
+    - [Resource](#resource)
+
 ## Installation
 
 To use this bundle, require it in Composer
@@ -10,18 +21,62 @@ To use this bundle, require it in Composer
 composer require geekcell/ddd-bundle
 ```
 
-## Quickstart
+## Generator Commands
+
+This bundle adds several [MakerBundle](https://symfony.com/bundles/SymfonyMakerBundle/current/index.html) commands to generate commonly used components.
+
+In order to use them in your Symfony project, you need to require it with composer first
+
+```bash
+composer require symfony/maker-bundle
+```
+
+## Building Blocks
 
-- [Aggregate Root](#aggregate-root)
-- [Repositories](#repositories)
-- [Command & Query Bus](#command--query-bus)
-- [Supporting Tools](#supporting-tools)
+### Model & Repository
 
-## Aggregate Root
+The **domain model** is a representation of the domain concepts and business logic within your project. The **repository** on the other hand is an abstraction layer that provides a way to access and manipulate domain objects without exposing the details of the underlying data persistence mechanism (such as a database or file system).
 
-Extend from `AggregateRoot` to record and commit domain events. Domain events must implement the (marker) interface `DomainEvent`. Events will be dispatched via the currently configured Symfony event dispatcher.
+Since Doctrine is the de-facto persistence layer for Symfony, this bundle also provides an (opinionated) implementation for a Doctrine-based repository.
 
-### Example Usage
+#### Generator Command(s)
+
+This command can be used to generate:
+
+- The domain model class.
+- A repository class for the model.
+- The model's identity class as value object (optional).
+- A Doctrine database entity configuration, either as annotation or separate config file (optional).
+- A custom Doctrine type for the model's identity class (optional).
+
+```bash
+Description:
+  Creates a new domain model class
+
+Usage:
+  make:ddd:model [options] [--] [<name>]
+
+Arguments:
+  name                               The name of the model class (e.g. Customer)
+
+Options:
+      --aggregate-root               Marks the model as aggregate root
+      --entity=ENTITY                Use this model as Doctrine entity
+      --with-identity=WITH-IDENTITY  Whether an identity value object should be created
+      --with-suffix                  Adds the suffix "Model" to the model class name
+```
+
+### AggregateRoot & Domain Events
+
+Optionally, by inheriting from `AggregateRoot`, you can make a model class an **aggregate root**, which is used to encapsulate a group of related objects, along with the behavior and rules that apply to them. The aggregate root is usually responsible for managing the lifecycle of the objects within the aggregate, and for coordinating any interactions between them.
+
+The `AggregateRoot` base class comes with some useful functionality to record and dispatch **domain events**, which represent significant occurrences or state changes within the domain of a software system.
+
+#### Generator Command(s)
+
+N/A
+
+#### Example Usage
 
 ```php
 use GeekCell\Ddd\Contracts\Domain\Event as DomainEvent;
@@ -56,33 +111,51 @@ _Hint: If you want to dispatch an event directly, use `AggregateRoot::dispatch()
 
 If you cannot (or don't want to) extend from `AggregateRoot`, you can alternative use `DispatchableTrait` to add dispatching capabilities to any class. The former is however the recommended way.
 
-## Repositories
+### Command & Query
+
+You can use `CommandBus` and `QueryBus` as services to implement [CQRS](https://martinfowler.com/bliki/CQRS.html). Internally, both buses will use the [Symfony messenger](https://symfony.com/doc/current/messenger.html) to dispatch commands and queries.
+
+#### Generator Command(s)
+
+These commands can be used to generate:
+
+- A command and command handler class.
+- A query and query handler class.
+
+The query / command generated is just an empty class. The handler class is registered as a message handler for the configured [Symfony Messenger](https://symfony.com/doc/current/messenger.html).
 
-_coming soon..._
+```bash
+Description:
+  Creates a new query|command class and handler
 
-## Command & Query Bus
+Usage:
+  make:ddd:query|command [<name>]
 
-You can use `CommandBus` and `QueryBus` as services to implement [CQRS](https://martinfowler.com/bliki/CQRS.html). Internally, both buses will use the [Symfony messenger](https://symfony.com/doc/current/messenger.html) as "backend".
+Arguments:
+  name                     The name of the query|command class (e.g. Customer)
+```
 
-## Example Usage
+#### Example Usage
 
 ```php
 // src/Application/Query/TopRatedBookQuery.php
+
 use GeekCell\Ddd\Contracts\Application\Query;
 
-class TopRatedBooksQuery implements Query
+readonly class TopRatedBooksQuery implements Query
 {
     public function __construct(
-        private readonly string $category,
-        private readonly int $sinceDays,
-        private readonly int $limit = 10,
+        public string $category,
+        public int $sinceDays,
+        public int $limit = 10,
     ) {
     }
 
     // Getters etc.
 }
 
 // src/Application/Query/TopRatedBookQueryHandler.php
+
 use GeekCell\Ddd\Contracts\Application\QueryHandler;
 
 #[AsMessageHandler]
@@ -96,14 +169,15 @@ class TopRatedBookQueryHandler implements QueryHandler
     public function __invoke(TopRatedBookQuery $query)
     {
         $books = $this->repository
-            ->findTopRated($query->getCategory(), $query->getSinceDays())
-            ->paginate($query->getLimit());
+            ->findTopRated($query->category, $query->sinceDays)
+            ->paginate($query->limit);
 
         return $books;
     }
 }
 
 // src/Infrastructure/Http/Controller/BookController.php
+
 use GeekCell\Ddd\Contracts\Application\QueryBus;
 
 class BookController extends AbstractController
@@ -124,97 +198,14 @@ class BookController extends AbstractController
 }
 ```
 
-## Supporting Tools
-
-### Facades
-
-Facades are heavily inspired by [Laravel's Facades](https://laravel.com/docs/facades) and are more or less singletons on steroids. They are basically a shortcut to services inside the DIC.
-
-```php
-use GeekCell\DddBundle\Support\Facades\EventDispatcher;
-
-EventDispatcher::dispatch($someEvent);
-
-// same as: $container->get('event_dispatcher')->dispatch($someEvent);
-```
-
-You can create your own facades by extending from `Facade` and implementing the `Facade::getFacadeAccessor()` method to return the DIC service alias.
-
-```php
-use GeekCell\DddBundle\Support\Facades\Facade;
-
-class Logger extends Facade
-{
-    protected static function getFacadeAccessor(): string
-    {
-        return 'logger';
-    }
-}
-```
-
-Although facades are better testable than regular singletons, it is highly recommended to only use them sparringly and always prefer normal dependency injection when possible.
-
-## Generator Commands
-
-This bundle adds several [maker bundle](https://symfony.com/bundles/SymfonyMakerBundle/current/index.html) commands to generate commonly used components.
-
-### Model / Repository
-
-This command can be used to generate:
-
-- The domain model class.
-- A repository class for the model.
-- The model's identity class as value object (optional).
-- A Doctrine database entity configuration, either as annotation or separate config file (optional).
-- A custom Doctrine type for the model's identity class (optional).
-
-#### Command Output
-
-```bash
-Description:
-  Creates a new domain model class
-
-Usage:
-  make:ddd:model [options] [--] [<name>]
-
-Arguments:
-  name                               The name of the model class (e.g. Customer)
-
-Options:
-      --aggregate-root               Marks the model as aggregate root
-      --entity=ENTITY                Use this model as Doctrine entity
-      --with-identity=WITH-IDENTITY  Whether an identity value object should be created
-      --with-suffix                  Adds the suffix "Model" to the model class name
-```
-
-### Query / Command
-
-These commands can be used to generate:
-
-- A query and query handler class.
-- A command and command handler class.
-
-The query / command generated is just an empty class. The handler class is registered as a message handler for the configured [Symfony Messenger](https://symfony.com/doc/current/messenger.html).
-
-#### Command Output
-
-```bash
-Description:
-  Creates a new query|command class and handler
-
-Usage:
-  make:ddd:query|command [<name>]
+### Controller
 
-Arguments:
-  name                     The name of the query|command class (e.g. Customer)
-```
+A standard Symfony controller, but augmented with command and query bus(es).
 
-### Controller
+#### Generator Command
 
 This command can be used to generate a controller with optional `QueryBus` and `CommandBus` dependencies.
 
-#### Command Output
-
 ```bash
 Description:
   Creates a new controller class
@@ -232,9 +223,11 @@ Options:
 
 ### Resource
 
-This command can be used to generate an [Api Platform](https://api-platform.com/) resource. Minimum required version is [2.7](https://api-platform.com/docs/core/upgrade-guide/#api-platform-2730) for the PHP attributes support.
+An [API Platform](https://api-platform.com/) resource, but instead of using the standard approach of using a combined entity/resource approach, it is preferred to separate model (domain layer) and API Platform specific resource (infrastructure layer)
+
+#### Generator Command
 
-#### Command Output
+Minimum required API Platform version is [2.7](https://api-platform.com/docs/core/upgrade-guide/#api-platform-2730) for the [new metadata system](https://api-platform.com/docs/core/upgrade-guide/#apiresource-metadata).
 
 ```bash
 Description: