docs: add Laravel and Symfony projection quickstart examples (#666)

* feat: add Laravel Projection quickstart examples (DatabaseReadModel and EloquentReadModel)

Two runnable examples under quickstart-examples/Laravel/Projection/ that demonstrate the full
ProjectionV2 lifecycle (init → events → query → reset → backfill → delete) using a User
event-sourced aggregate with three domain events, showing direct-write and outputChannelName
patterns for read model construction.

* feat: add READMEs, CI wiring, licence headers and gitignore fixes for Laravel Projection examples

Adds beginner-friendly READMEs with 4 mermaid diagrams and 8-section skeletons for
DatabaseReadModel and EloquentReadModel, the top-level index README, CI entries in
quickstart-examples/composer.json tests:ci, Apache-2.0 licence headers on all PHP
source files, and storage/framework cache/ exclusions to prevent generated files
from being tracked by git.

* feat: add #[NamedEvent] to projection quickstart events

Decouple stored event identity from PHP class names so the event stream
stays readable across renames/moves. Stable names: user.was_registered,
user.name_was_changed, user.was_deactivated. READMEs explain why this
matters for any event you intend to keep on disk.

* docs: drop PostgreSQL-only pitfall callouts from projection READMEs

* refactor(EloquentReadModel): make read model a stateful #[Aggregate]

Replace the InternalHandler writer + plain Eloquent model with a single
UserReadModel class in App\ReadModel that is both #[Aggregate] and an
Eloquent Model. The projection now emits commands via outputChannelName
(matched on command FQCN) to #[CommandHandler] methods on the aggregate;
Ecotone handles load + save automatically. This demonstrates the
auto-load/save "sugar" on the read side that stateful aggregates provide
on the write side. Required symfony/expression-language for the
identifierMapping payload.userId expression.

* refactor(EloquentReadModel): drop command DTOs, project arrays directly

Replace the three Command DTO classes with plain associative arrays.
The projection now returns the row data as an array and routes via a
string outputChannelName matching the #[CommandHandler] routing key.
identifierMapping uses bracket expression syntax (payload['user_id'])
to read from the array on instance handlers. No DTO classes left.

* feat: add Symfony Projection quickstart examples (DatabaseReadModel + EntityReadModel)

Ports the two Laravel Projection examples to Symfony, providing complete
projection lifecycle examples using Doctrine DBAL (DatabaseReadModel) and
Doctrine ORM entities as stateful aggregates (EntityReadModel). Both examples
run cleanly inside docker and are wired into quickstart-examples/composer.json tests:ci.

* fixes

* refactor(EntityReadModel): match payload key to property name, drop identifierMapping

Project the user id as 'userId' (camelCase) so the array key matches the
aggregate's $userId PHP property; Ecotone now resolves the identifier
automatically and instance command handlers no longer need an explicit
identifierMapping. The Doctrine column name stays 'user_id' (DB convention).

* docs: note that projections can return a typed class instead of an array

Both EloquentReadModel and EntityReadModel READMEs now call out the
class-vs-array trade-off: arrays are dependency-free; typed command
classes give named fields and IDE/static-analysis support. Either form
reaches the same #[CommandHandler] over the same outputChannelName.

* refactor(projection-examples): drop backfill step from run_example scripts

run_example.php now walks six steps (delete → init → emit → query → reset → delete)
instead of seven. The backfill step exercised behaviour that is incompatible with
MySQL today (DDL inside the backfill transaction triggers an implicit commit), and
removing it lets three of the four examples run successfully on MySQL while keeping
the full picture on Postgres. READMEs updated: section 6 renamed to 'Reset vs Delete'
and a note added pointing readers at ecotone:projection:backfill for the historical-
event replay use case the script no longer demonstrates.

* fix(EntityReadModel): pre-create event stream + guard read-model DDL for MySQL

Doctrine ORM in DBAL 4 always wraps flush() in a savepoint when nested in
an outer transaction, and that savepoint is silently dropped by any DDL
MySQL implicit-commits (CREATE TABLE, DROP TABLE). Two paths inside the
example previously triggered DDL during step 3's command flow: the Prooph
event store's lazy stream table creation, and the projection's
#[ProjectionInitialization] / #[ProjectionDelete] hooks re-running their
CREATE/DROP statements.

Pre-create the event stream in step 2 (outside any transaction) so the
first commandBus->send doesn't trigger DDL. Guard the projection's init
and delete hooks with createSchemaManager()->tablesExist() so they only
emit DDL when the schema actually needs changing.

All four projection examples now pass on both Postgres and MySQL.

Author: dgafka

quickstart-examples/Laravel/Projection/DatabaseReadModel/README.md

@@ -0,0 +1,145 @@
+# Laravel Projection — Database Read Model
+
+## 1. What you'll learn
+
+This example shows how to build a **projection** (a read-optimised view) on top of an event-sourced `User` aggregate using Laravel and Ecotone. You will see how the projection's `#[ProjectionInitialization]` hook creates the storage, how `#[EventHandler]` methods react to each domain event, and how the projection lifecycle commands (init, delete, reset) let you wipe and recreate the read model whenever you need to.
+
+## 2. The problem this solves
+
+In a traditional application, if you need a new view on your data — say "all active users ordered by name" — you run a database migration and populate the new table. In an event-sourced system you still have every domain event ever emitted. You can **replay** them into any new shape without touching the write side. This is the projection pattern: the events are the truth; the read model is just a cache you can always discard and rebuild.
+
+## 3. How it fits together
+
+```mermaid
+flowchart LR
+    Client -->|send command| CommandBus
+    CommandBus -->|route| User["User\n#[EventSourcingAggregate]"]
+    User -->|return events| EventStore[(Event Store\nPostgreSQL)]
+    EventStore -->|stream| UserListProjection["UserListProjection\n#[ProjectionV2]"]
+    UserListProjection -->|INSERT / UPDATE| ReadModel[(user_list_database\ntable)]
+    Client -->|sendWithRouting| QueryBus
+    QueryBus -->|listActive| UserListProjection
+    UserListProjection -->|SELECT| ReadModel
+```
+
+*Files involved:*
+- `app/Domain/User.php` — aggregate that produces the events
+- `app/Domain/Event/` — `UserWasRegistered`, `UserNameWasChanged`, `UserWasDeactivated`
+- `app/ReadModel/UserListProjection.php` — projection that maintains `user_list_database`
+- `app/Infrastructure/EcotoneConfiguration.php` — wires the PostgreSQL connection
+
+## 4. Walkthrough of the code
+
+### 4.1 Domain — User aggregate
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant CommandBus
+    participant User
+    participant EventStore
+
+    Client->>CommandBus: RegisterUser(userId, name, email)
+    CommandBus->>User: register() static
+    User-->>EventStore: [UserWasRegistered]
+
+    Client->>CommandBus: ChangeUserName(userId, name)
+    CommandBus->>User: changeName()
+    User-->>EventStore: [UserNameWasChanged]
+
+    Client->>CommandBus: DeactivateUser(userId)
+    CommandBus->>User: deactivate()
+    User-->>EventStore: [UserWasDeactivated]
+```
+
+The `User` aggregate is annotated with `#[EventSourcingAggregate]`. Command handlers are `static` for creation (`register`) and instance methods for mutations (`changeName`, `deactivate`). Each handler returns an array of events. `#[EventSourcingHandler]` methods reconstruct aggregate state from stored events — they must have no side effects.
+
+Each event class is annotated with `#[NamedEvent('user.was_registered')]` (and so on). The name is what Ecotone stores alongside the event payload, so the recorded stream stays readable even if you later move or rename the PHP class. Without `#[NamedEvent]`, the fully-qualified class name is used — which couples your stored events to your namespace. For any event you intend to keep on disk, give it a stable name.
+
+### 4.2 The projection — direct database writes
+
+```mermaid
+flowchart TD
+    ES[(Event Store)] -->|UserWasRegistered| onRegistered["onRegistered()\n#[EventHandler]"]
+    ES -->|UserNameWasChanged| onNameChanged["onNameChanged()\n#[EventHandler]"]
+    ES -->|UserWasDeactivated| onDeactivated["onDeactivated()\n#[EventHandler]"]
+    onRegistered -->|INSERT| DB[(user_list_database)]
+    onNameChanged -->|UPDATE name| DB
+    onDeactivated -->|UPDATE active=false| DB
+```
+
+`UserListProjection` receives a `ConnectionInterface` (Laravel's default DB connection) injected by Ecotone's container. Each `#[EventHandler]` method writes directly to the `user_list_database` table. No DTO wiring, no intermediate services — this is the simplest possible pattern.
+
+### 4.3 Lifecycle hooks
+
+| Hook | Attribute | What it does |
+|------|-----------|--------------|
+| Initialise | `#[ProjectionInitialization]` | `CREATE TABLE IF NOT EXISTS user_list_database (...)` |
+| Delete | `#[ProjectionDelete]` | `DROP TABLE IF EXISTS user_list_database` |
+
+Resetting the projection is done by deleting and re-initialising it, which clears both the read model table and Ecotone's stored stream position for this projection. Future events flow into the empty projection synchronously as they're emitted.
+
+### 4.4 Querying the read model
+
+The `#[QueryHandler('user.listActive')]` method runs a simple `SELECT` via the `ConnectionInterface` and returns an array. Callers use the query bus:
+
+```php
+$rows = $queryBus->sendWithRouting('user.listActive');
+// $rows[0]['name'] === 'Alice Cooper'
+```
+
+The query handler lives on the same class as the event handlers. You can move it to a separate class if you want read/write separation at the class level.
+
+## 5. Running it
+
+```bash
+# Start services
+docker compose up -d app database
+
+# Enter the container
+docker compose exec app bash
+
+# Install and run
+cd quickstart-examples/Laravel/Projection/DatabaseReadModel
+composer update
+php run_example.php
+```
+
+The script exits 0 and prints a six-step ribbon showing each lifecycle phase.
+
+## 6. Reset vs Delete
+
+```mermaid
+stateDiagram-v2
+    [*] --> Gone: start (no projection)
+    Gone --> Empty: ecotone:projection:init
+    Empty --> Active: events emitted\n(handlers fire synchronously)
+    Active --> Empty: ecotone:projection:delete\n+ ecotone:projection:init\n(reset = clear rows + position)
+    Active --> Gone: ecotone:projection:delete
+    Gone --> [*]
+```
+
+| Command | Effect |
+|---------|--------|
+| `ecotone:projection:init` | Calls `#[ProjectionInitialization]`, records projection as known |
+| `ecotone:projection:delete` | Calls `#[ProjectionDelete]`, removes projection tracking |
+
+**Reset = delete + re-init.** This two-step approach makes the state transitions explicit: you see the table disappear, then reappear empty.
+
+> **Replaying historical events.** Ecotone ships `ecotone:projection:backfill` to replay everything in the event store into a projection. This example doesn't exercise it because synchronous projections naturally fill from events as they're emitted; backfill is what you reach for after a reset to rebuild from history, or when introducing a new projection over an existing event stream.
+
+## 7. When to choose this pattern
+
+Use `DatabaseReadModel` when:
+- You want the simplest possible implementation
+- Your read model logic is straightforward SQL
+- You don't need Eloquent features (observers, mutators, scopes)
+
+See [EloquentReadModel](../EloquentReadModel/README.md) when you want to use Eloquent's ORM features in your read model writers.
+
+## 8. Common pitfalls
+
+1. **Forgetting `CREATE TABLE IF NOT EXISTS`.** Without `IF NOT EXISTS` the `init` hook fails if the table already exists, for example after a partial run.
+2. **Querying before init.** If you call `user.listActive` before `ecotone:projection:init` the table does not exist and you get a DB error. Always initialise before querying.
+3. **Event store accumulates across runs.** This example cleans up the User aggregate stream at the start of `run_example.php`. In production you would never delete the event stream — that is your source of truth.
+4. **Projection name collisions.** The name `user_list_database` is unique to this example. If you run both examples simultaneously they write to separate tables and use separate projection tracking entries.

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/Command/ChangeUserName.php

@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain\Command;
+
+final readonly class ChangeUserName
+{
+    public function __construct(
+        public string $userId,
+        public string $name,
+    ) {
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/Command/DeactivateUser.php

@@ -0,0 +1,17 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain\Command;
+
+final readonly class DeactivateUser
+{
+    public function __construct(
+        public string $userId,
+    ) {
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/Command/RegisterUser.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain\Command;
+
+final readonly class RegisterUser
+{
+    public function __construct(
+        public string $userId,
+        public string $name,
+        public string $email,
+    ) {
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/Event/UserNameWasChanged.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain\Event;
+
+use Ecotone\Modelling\Attribute\NamedEvent;
+
+#[NamedEvent(self::EVENT_NAME)]
+final readonly class UserNameWasChanged
+{
+    public const EVENT_NAME = 'user.name_was_changed';
+
+    public function __construct(
+        public string $userId,
+        public string $name,
+    ) {
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/Event/UserWasDeactivated.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain\Event;
+
+use Ecotone\Modelling\Attribute\NamedEvent;
+
+#[NamedEvent(self::EVENT_NAME)]
+final readonly class UserWasDeactivated
+{
+    public const EVENT_NAME = 'user.was_deactivated';
+
+    public function __construct(
+        public string $userId,
+    ) {
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/Event/UserWasRegistered.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain\Event;
+
+use Ecotone\Modelling\Attribute\NamedEvent;
+
+#[NamedEvent(self::EVENT_NAME)]
+final readonly class UserWasRegistered
+{
+    public const EVENT_NAME = 'user.was_registered';
+
+    public function __construct(
+        public string $userId,
+        public string $name,
+        public string $email,
+    ) {
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Domain/User.php

@@ -0,0 +1,80 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Domain;
+
+use App\Domain\Command\ChangeUserName;
+use App\Domain\Command\DeactivateUser;
+use App\Domain\Command\RegisterUser;
+use App\Domain\Event\UserNameWasChanged;
+use App\Domain\Event\UserWasDeactivated;
+use App\Domain\Event\UserWasRegistered;
+use Ecotone\Modelling\Attribute\CommandHandler;
+use Ecotone\Modelling\Attribute\EventSourcingAggregate;
+use Ecotone\Modelling\Attribute\EventSourcingHandler;
+use Ecotone\Modelling\Attribute\Identifier;
+use Ecotone\Modelling\WithAggregateVersioning;
+
+#[EventSourcingAggregate]
+final class User
+{
+    use WithAggregateVersioning;
+
+    #[Identifier]
+    private string $userId;
+
+    private string $name;
+
+    private bool $active;
+
+    #[CommandHandler]
+    public static function register(RegisterUser $command): array
+    {
+        return [new UserWasRegistered($command->userId, $command->name, $command->email)];
+    }
+
+    #[CommandHandler]
+    public function changeName(ChangeUserName $command): array
+    {
+        if ($command->name === $this->name) {
+            return [];
+        }
+
+        return [new UserNameWasChanged($this->userId, $command->name)];
+    }
+
+    #[CommandHandler]
+    public function deactivate(DeactivateUser $command): array
+    {
+        if (! $this->active) {
+            return [];
+        }
+
+        return [new UserWasDeactivated($this->userId)];
+    }
+
+    #[EventSourcingHandler]
+    public function applyRegistered(UserWasRegistered $event): void
+    {
+        $this->userId = $event->userId;
+        $this->name = $event->name;
+        $this->active = true;
+    }
+
+    #[EventSourcingHandler]
+    public function applyNameChanged(UserNameWasChanged $event): void
+    {
+        $this->name = $event->name;
+    }
+
+    #[EventSourcingHandler]
+    public function applyDeactivated(UserWasDeactivated $event): void
+    {
+        $this->active = false;
+    }
+}

quickstart-examples/Laravel/Projection/DatabaseReadModel/app/Infrastructure/EcotoneConfiguration.php

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * licence Apache-2.0
+ */
+
+declare(strict_types=1);
+
+namespace App\Infrastructure;
+
+use Ecotone\Laravel\Config\LaravelConnectionReference;
+use Ecotone\Messaging\Attribute\ServiceContext;
+
+final readonly class EcotoneConfiguration
+{
+    #[ServiceContext]
+    public function databaseConnection(): LaravelConnectionReference
+    {
+        return LaravelConnectionReference::defaultConnection('pgsql');
+    }
+}