Ecotone is an architecture layer for asynchronous messaging in PHP. It adds the primitives a dispatcher alone doesn't ship — transactional outbox, per-handler failure isolation, deduplication, multi-tenant routing, and consistent #[Asynchronous] / #[Delayed] / #[Priority] / #[TimeToLive] semantics across every broker. Existing Symfony Messenger transports and Laravel Queue channels stay in place as the underlying transport when they're already configured; the architectural primitives sit on top.

For a PHP team building asynchronous messaging — background jobs, event-driven side effects, scheduled work, retries with exponential backoff, multi-broker estates, multi-tenant routing — Ecotone moves any handler to async with one attribute (#[Asynchronous('channel')]), gives you the outbox in one configuration line (CombinedMessageChannel), and exposes #[Delayed], #[Priority], #[TimeToLive], and scheduled messages through one consistent attribute model (each broker's own primitive — RabbitMQ delayed exchange, SQS message timer, Redis sorted-set + polling — is what does the actual waiting underneath). RabbitMQ, Apache Kafka, Amazon SQS, Redis, DBAL, Symfony Messenger transports, Laravel Queue channels — handler code is broker-agnostic.

The competition is Symfony Messenger and Laravel Queues / Horizon — mature dispatchers that don't ship the architectural primitives (outbox, per-handler isolation, deduplication, multi-tenant routing) that production async messaging adds on top. This page walks the differences.

The Problem You Recognize

You added async processing to handle background work — emails, payment processing, data syncing. New problems appeared:

• Failed jobs disappear silently or retry forever. No visibility into why.

• A duplicate webhook hits the same handler twice — double charges or duplicate emails.

• Going async required touching every handler — queue config, serialization, retry logic per handler.

What the Industry Calls It

Asynchronous communication (also: async messaging, message-driven architecture) — applications communicate by passing messages through a broker rather than synchronous calls. Patterns layered on top include:

• Outbox — atomic publication of a message together with the database write that produced it.

• Per-handler failure isolation — a copy of every message dispatched to each handler, so one failing subscriber doesn't trigger sibling re-runs.

• Idempotency / deduplication — handlers tolerate duplicate delivery without producing duplicate side effects.

The PHP options are Symfony Messenger (the de-facto Symfony dispatcher), Laravel Queues with Horizon (the Laravel-native job runner with the Horizon operator UI), and Ecotone — which adds an architectural layer above them.

How Ecotone Solves It

Async with one attribute, on any broker

The handler is broker-agnostic. Switching from Redis to RabbitMQ is a #[ServiceContext] configuration change — no handler code touched.

Outbox in one DBAL transaction, execution on the broker

CombinedMessageChannel writes the message to the database in the same DBAL transaction as the business write, then dispatches actual handler execution onto the broker. One outbox poller drains the database (low traffic, single workload). Many consumers handle the broker side (high traffic, horizontally scalable). The dual-write problem is solved at the primitive level.

Per-handler failure isolation by default

Each subscriber gets its own copy of the message. If reserveStock fails, only reserveStock retries — sendConfirmation is unaffected. This is the architectural difference from Symfony Messenger's single-envelope dispatch model: in Messenger, the first throwing consumer aborts dispatch for siblings and retry re-runs every consumer.

Delayed, priority, TTL, scheduled — uniform across brokers

#[Delayed] accepts a TimeSpan, an exact DateTimeImmutable, or an expression (#[Delayed(expression: 'payload.dueDate')]). The delay is per-handler on the async channel — the same event can fire one handler immediately and another in 24 hours. Priority, TTL, and scheduled messages have the same shape across every broker; the broker's native primitives (RabbitMQ delayed exchange, SQS message timer, Redis sorted-set + polling worker) are abstracted behind one attribute model.

Dynamic Channels — multi-tenant routing in one deployment (Enterprise)

tenant_resolved is a dynamic channel whose actual destination resolves at runtime — based on a header, payload field, or expression. One handler, N tenants, isolated per-tenant queues. No fork in handler code; no namespace-per-tenant infrastructure.

Retry, error channels, dead letter — at the channel, not per handler

Configure recovery policy once at the channel level. Every handler on that channel inherits exponential-backoff retry, an error channel, and a DBAL-backed dead-letter queue with replay. No per-handler boilerplate.

How It Compares

Existing Messenger and Horizon investments stay in place — Ecotone uses Messenger transports and Laravel Queue channels underneath when they're already configured — and adds the primitives (outbox, per-handler isolation, deduplication, multi-tenant routing) that the dispatchers don't ship.

Next Steps

• — #[Asynchronous], pollers, async event handlers

• — #[Delayed] with TimeSpan, DateTime, and expressions

• — CombinedMessageChannel

Every feature in Ecotone exists to solve a real problem that PHP developers face as their applications grow. Find the situation that matches yours:

Ecotone exposes hooks at every step of a message's lifecycle. Use Interceptors (Before/Around/After/Presend) to add cross-cutting behaviour like logging, authorization, retries, or transactions without touching your handlers. Use Message Headers to read and write metadata that flows alongside the payload. Use Custom Gateways to attach policies (retries, dedup, error channels) to typed bus interfaces.

Demo

Read Blog Post

Building Blocks: Aggregates, Sagas, Event Sourcing

Demo

Read Blog Post

Read more about Scheduling in PHP and Ecotone

Store events instead of current state — get a full audit trail and rebuildable read models for free.

Demo

Read Blog Post

Cross-service messaging with guaranteed delivery — send commands and share events between PHP services.

Demo

Read Blog Post

Automatic retries, dead letter queues, and message replay — production resilience without per-handler boilerplate.

Demo

Read Blog Post

Demo

Read Blog Post

Read more about Doctrine ORM Ecotone

You inject CommandBus into a controller. Three controllers later, every call site has the magic-string 'ticket.create' and a new CreateTicket(...). The bus signature is mixed → mixed. There's no single place that documents what your domain can do, no IDE help, and refactoring the CreateTicket class is a search-and-replace across the codebase.

A Business Interface is your domain's typed API: interface TicketApi { public function create(CreateTicket $cmd): TicketId; public function close(#[Identifier] string $id): void; }. Ecotone delivers the implementation. Your controllers, console commands, and subscribers all depend on TicketApi — and onboarding a new developer becomes a one-file question: "what can the Ticket module do?".

This works for sending commands, executing queries, and operating on databases — keeping your application code focused on intent rather than wiring.

How to use

If you're looking for a way to start and get familiar with Ecotone. Then Ecotone provides different ways to do so:

• - Tutorial will introduce you to Ecotone's fundamentals and will help you build understanding of the Messaging concepts.

Demo Message Bus

Demo Publishing Events

Message Bus Demo

Publishing Events Demo

Get started with Ecotone

The best way to get started with Ecotone is to actually build something realistic. Therefore we will build a small back-end for Shopping System during this tutorial. The techniques we will learn in the tutorial are fundamental to building any application using Ecotone.

Read sections first to get more details about Aggregates.

Aggregate Query Action

Aggregate actions are defined using public method (non-static). Ecotone will ensure loading in order to execute the query method.

And then we call it from Query Bus:

Ecotone comes with inbuilt repositories, so we don't need to configure Repositories ourselves. It often happen that those are similar between projects, therefore it may be that there is no need to roll out your own.

Inbuilt Repositories

Ecotone provides inbuilt repositories to get you started quicker. This way you can enable given repository and start implementing higher level code without worrying about infrastructure part.

You're handling order processing: charge the card, reserve stock, schedule shipping, send a confirmation. The steps span hours or days, run across services, and any one of them can fail. State columns like is_payment_processed, retry_count, step_completed_at start appearing on the Order table — and the workflow ends up tangled across listeners, jobs, and cron sweepers.

A Saga is a class that owns a long-running business process. It listens for events, decides what to do next, dispatches commands, and persists its own state between steps. Where an Aggregate protects the invariants of a single thing, a Saga coordinates the steps that move many things forward.

Access attribute from interceptor

We may access attribute from the intercepted endpoint in order to perform specific action

then we would have an Message Endpoint using this Attribute:

and it can be used in the intereceptors by type hinting given parameter:

You want a transaction wrapper, but only for handlers running asynchronously — synchronous Command handlers already get one from your Command Bus. Or you want to log async-only metrics, swap connections per-tenant, or apply rate-limiting to background work without touching synchronous flows. Pointing the interceptor at the AsynchronousRunningEndpoint class targets only the async path.

Read for an introduction to Interceptors.

Intercepting Asynchronous Endpoints

The Problem

You store the current state of your entities, but not how they got there. When a customer disputes a charge, you can't answer "what exactly happened?" Rebuilding read models after a schema change means writing migration scripts by hand. Auditors ask for a complete trail of changes and you piece it together from application logs.

Ecotone comes with full automation for setting up Event Sourcing for us. This we can we really easily roll out new features with Event Sourcing with just minimal or none setup at all.

Install Event Sourcing Support

Before we will start, let's first install Event Sourcing module, which will provide us with all required components:

We need to configure in order to make use of it.

Ecotone PDO Event Sourcing does provide support for three databases:

The Problem

You're a year into your Order system. Compliance asks: "show me everything that happened to order #4192, with timestamps, in order." You can't — the orders table only stores the current row. The audit log you bolted on is missing two columns and the listener that wrote to it crashed silently in 2023.

Once you decide to store events, you have to decide how — what database table holds them, how aggregate identity and version are constrained at the storage layer, what happens when you rename a class, and how PII fields are encrypted. This section covers those choices.

The pages below are mostly independent — read the one that matches the problem in front of you:

How Ecotone lays out events on disk: simple append-only streams, partitioned streams (one stream per aggregate with version uniqueness), or a single global stream. Pick the one that matches your concurrency and ordering needs.

When you already store events somewhere else (EventSauce, Patchlevel, your own table) and want Ecotone to read/write through that storage instead of its built-in event store.

You renamed App\Order\Order to App\Sales\Order — now production events still reference the old class.

Changes in the Application will happen. After some time we may want to refactor namespaces, change the name of Aggregate or an Event. However those kind of changes may break our system, if we already have production data which references to any of those. Therefore to make our Application to immune to future changes we need a way to decouple the code from the data in the storage, and this is what Ecotone provides.

Custom Stream Name

Our Event Stream name by default is based on the Aggregate Class name. Therefore to make it immune to changes we may provide custom Stream Name. To do it we will apply Stream attribute to the aggregate:

The Problem You Recognize

Your application started clean, but as features grew, the boundaries blurred. Controllers handle business logic. Services read and write in the same method. Event listeners trigger side effects that nobody can trace.

In Laravel, you might have a 300-line Controller that validates input, queries the database, applies business rules, dispatches jobs, and returns a response — all in one method.

In Symfony, you might have a service class with 10 injected dependencies, where changing how orders are placed breaks the order listing page because both share the same service.

The symptoms are familiar:

• New developers take weeks to understand what happens when a user places an order

• Testing a single business rule requires setting up the entire framework

• A change in one area causes failures in unrelated features

What the Industry Calls It

CQRS — Command Query Responsibility Segregation. Separate the code that changes state (commands) from the code that reads state (queries). Add event handlers for side effects. Each handler has one job.

How Ecotone Solves It

With Ecotone, you organize your code around Command Handlers, Query Handlers, and Event Handlers — each responsible for exactly one thing. Ecotone wires them together automatically through PHP attributes:

No base classes. No interfaces to implement. Your existing Laravel or Symfony services stay exactly where they are — you add attributes to give them clear responsibilities.

Next Steps

• — Learn how to define and dispatch commands

• — Separate your read models

• — React to domain events

The Problem You Recognize

A customer disputes a charge. Your support team asks "what exactly happened to this order?" The answer requires reading application logs, database timestamps, and hoping someone didn't overwrite the data.

Your read models need a schema change. You write a migration script, but there's no way to verify the migrated data is correct — the original events that created it are gone. You store the current state, but not how you got there.

The symptoms:

• No history — you know what the current price is, but not what it was yesterday

• Risky migrations — changing the read model means writing one-off scripts and praying

• Compliance gaps — auditors ask for a complete trail of changes and you can't provide one

What the Industry Calls It

Event Sourcing — instead of storing the current state, store the sequence of events that led to it. Rebuild any view of the data by replaying events. Get a complete, immutable audit trail for free.

How Ecotone Solves It

Ecotone provides Event Sourcing as a first-class feature with built-in projections. Your aggregate records events instead of mutating state:

Build read models (projections) that can be rebuilt at any time from the event history:

Works with Postgres, MySQL, and MariaDB for event storage. Projections can write to any storage you choose.

Next Steps

• — How Event Sourced Aggregates work

• — Build and rebuild read models

• — Evolve your events safely

The Problem You Recognize

Your monolith is splitting into services. Or you already have multiple services and they need to talk to each other.

The current approach: HTTP calls between services. When Service B is down, Service A fails too. You've built custom retry logic, custom serialization, and custom routing for each service pair. There's no guaranteed delivery — if a request fails, the data is lost unless you built a custom retry mechanism.

The symptoms:

• Cascading failures — one service going down takes others with it

• Custom glue code per service pair — serialization, routing, error handling

• No event sharing — services can't subscribe to each other's events without point-to-point integrations

• Broker lock-in — switching from RabbitMQ to SQS means rewriting integration code

What the Industry Calls It

Distributed Messaging — services communicate through a message broker with guaranteed delivery, event sharing, and transport abstraction.

How Ecotone Solves It

Ecotone's Distributed Bus lets services send commands and publish events to each other through message brokers. Your application code stays the same — Ecotone handles routing, serialization, and delivery:

Supports RabbitMQ, Amazon SQS, Redis, and Kafka — swap transports without changing application code.

Next Steps

• — Cross-service messaging

• — Consuming from external sources

• — Publishing to external targets

Demo

Read Blog Post

Read more about Event Handling in PHP and Ecotone

Code Example

Let's create Event Order was placed.

And Event Handler that will be listening to the OrderWasPlaced.

Running The Example

Setup for tutorial

Depending on the preferences, we may choose tutorial version for

• Symfony

1. Use to download starting point in order to start tutorial

2. Run command line application to verify if everything is ready.

Read Aggregate Introduction first for more details about Aggregates.

The Problem

Every Command Handler does the same three lines: findById, do something, save. After ten handlers, that's thirty lines of identical glue. And the moment your aggregate becomes a Doctrine entity (or an Eloquent model), persistence concerns start leaking into the domain — fields exist to please the ORM, tests need a real database, and migrating to a different storage means rewriting every aggregate.

How Ecotone Solves It

A Repository is the seam between your domain (which only knows aggregates) and your storage (Doctrine, Eloquent, Document Store, Event Store). Ecotone provides built-in repositories for each — pick one, point Ecotone at it, and your aggregates stay free of @ORM\Entity and extends Model. The fetch/save boilerplate disappears entirely; Ecotone wraps every command in load → call → save automatically.

Typical Aggregate Flow

Repositories retrieve and save the aggregate to persistent storage. The typical flow for calling an aggregate method looks like:

By setting up Repository we provide Ecotone with functionality to fetch and store the Aggregate , so we don't need to write the above orchestration code anymore.

Ecotone's Aggregate Flow

If our class is defined as Aggregate, Ecotone will use Repository in order fetch and store it, whenever the Command is sent via Command Bus.

Now when we will send the Command, Ecotone will use ticketId from the Command to fetch related Ticket Aggregate, and will called assignWorker passing the Command. After this is completed it will use the repository to store changed Aggregate instance.

Therefore from high level nothing changes:

This way we don't need to write orchestration level code ourselves.

Converting Results

In rich business domains we will want to work with higher level objects than associate arrays. Suppose we have PersonNameDTO and defined Ecotone's Converter for it.

class PersonNameDTOConverter
{
    #[Converter]
    public function from(PersonNameDTO $personNameDTO): array
    {
        return [
            "person_id" => $personNameDTO->getPersonId(),
            "name" => $personNameDTO->getName()
        ];
    }

    #[Converter]
    public function to(array $personNameDTO): PersonNameDTO
    {
        return new PersonNameDTO($personNameDTO['person_id'], $personNameDTO['name']);
    }
}

Converting to Collection of Objects

Ecotone will read the Docblock and based on that will deserialize Result Set from database to list of PersonNameDTO.

Converting to single Object

Using combination of First Row Fetch Mode, we can get first row and then use it for conversion to PersonNameDTO.

Converting Iterator

For big result set we may want to avoid fetching everything at once, as it may consume a lot of memory. In those situations we may use Iterator Fetch Mode, to fetch one by one. If we want to convert each result to given Class, we may define docblock describing the result:

Each returned row will be automatically convertered to PersonNameDTO.

Converting to specific Media Type Format

We may return the result in specific format directly. This is useful when Business Method is used on the edges of our application and we want to return the result directly.

In this example, result will be returned in application/json.\

You want webhook commands to retry 3 times and dedup on paymentId, but internal admin commands to fail fast with no retry. Both go through your CommandBus. Extending the bus interface lets you declare a WebhookCommandBus extends CommandBus, attach #[InstantRetry] and #[Deduplicated] directly to it, and inject the typed bus where you want those policies — same handlers, different policies, no runtime branching.

For better understanding, please read Interceptors section before going through this chapter.

Intercepting Gateways

Suppose we want to add custom logging, whenever any Command is executed. We know that CommandBus is a interface for sending Commands, therefore we need to hook into that Gateway.

Intercepting Gateways, does not differ from intercepting Message Handlers.

Building customized Gateways

We may also want to have different types of Message Buses for given Message Type. For example we could have EventBus with audit which we would use in specific cases. Therefore we want to keep the original EventBus untouched, as for other scenarios we would simply keep using it.

To do this, we will introduce our new EventBus:

That's basically enough to register our new interface. This new Gateway will be automatically registered in our DI container, so we will be able to inject it and use.

Now as this is separate interface, we can point interceptor specifically on this

Pointcut by attributes

We could of course intercept by attributes, if we would like to make audit functionality reusable

and then we pointcut based on the attribute

Asynchronous Gateways

Gateways can also be extended with asynchronous functionality on which you can read more in .

The Problem

You store the current state but not how you got there. When a customer disputes a charge, you can't answer "what exactly happened?" Rebuilding read models after a schema change means writing migration scripts by hand.

How Ecotone Solves It

Ecotone's Event Sourced Aggregates store events instead of current state. Every state change is an immutable event in a stream. Projections rebuild read models from event history — change the schema, replay the events, get a correct read model.

Before diving into this section be sure to understand how Aggregates works in Ecotone based on .

Difference between Aggregate Types

Ecotone provides higher level abstraction to work with Event Sourcing, which is based on Event Sourced Aggregates. Event Sourced Aggregate just like normal Aggregates protect our business rules, the difference is in how they are stored.

State-Stored Aggregates

Normal Aggregates are stored based on their current state:

Yet if we change the state, then our previous history is lost:

Having only the current state may be fine in a lot of cases and in those situation it's perfectly fine to make use of . This is most easy way of dealing with changes, we change and we forget the history, as we are interested only in current state.

Event Sourcing Aggregate

When we are interested in history of changes, then Event Sourced Aggregate will help us. Event Sourced Aggregates are stored in forms of Events. This way we preserve all the history of given Aggregate:

When we change the state the previous Event is preserved, yet we add another one to the audit trail (Event Stream).

This way all changes are preserved and we are able to know what was the historic changes of the Product.

Event Stream

The audit trail of all the Events that happened for given Aggregate is called Event Stream. Event Stream contains of all historic Events for all instance of specific Aggregate type, for example all Events for Product Aggregate

Let's now dive a bit more into Event Streams, and what they actually are.

As mentioned earlier, Events are stored in form of a Event Stream. Event Stream is audit of Events, which happened in the past. However to protect our business invariants, we may want to work with current state of the Aggregate to know, if given action is possible or not (business invariants).

Business Invariants

Business Invariants in short are our simple "if" statements inside the Command Handler in the Aggregate. Those protect our Aggregate from moving into incorrect state. With State-Stored Aggregates, we always have current state of the Aggregate, therefore we can check the invariants right away. With Event-Sourcing Aggregates, we store them in form of an Events, therefore we need to rebuild our Aggregate, in order to protect the invariants.

Suppose we have Ticket Event Sourcing Aggregate.

For this Ticket we do allow for assigning an Person to handle the Ticket. Let's suppose however, that Business asked us to allow only one Person to be assigned to the Ticket at time. With current code we could assign unlimited people to the Ticket, therefore we need to protect this invariant.

To check if whatever Ticket was already assigned to a Person, our Aggregate need to have state applied which will tell him whatever the Ticket was already assigned. To do this we use EventSourcingHandler attribute passing as first argument given Event class. This method will be called on reconstruction of this Aggregate. So when this Aggregate will be loaded, if given Event was recorded in the Event Stream, method will be called:

Then this state, can be used in the Command Handler to decide whatever we can trigger an action or not:

The Problem You Recognize

You added async processing to handle background work — sending emails, processing payments, syncing data. But now you have new problems:

• Failed jobs disappear silently or retry forever with no visibility

The Problem You Recognize

Your order fulfillment process spans 6 steps across 4 services. The subscription lifecycle involves payment processing, provisioning, notifications, and grace periods. User onboarding triggers a welcome email, account setup, and a follow-up sequence.

The logic for these processes is spread across:

To use Ecotone's Aggregate functionality, we need a registered repository. Ecotone comes with built-in support for popular persistence options like Doctrine ORM, Eloquent, and document stores, so there's a good chance we can use what we already have without extra work. If our storage solution isn't supported yet, or if we have specific requirements, we can easily register our own custom repository by following the steps in this section. This flexibility means we're not locked into any particular database or ORM—we can use whatever fits our project best.

Repository for State-Stored Aggregate

State-Stored Aggregate are normal Aggregates, which are stored using Standard Repositories. Therefore to configure Repository for your Aggregate, create a class that extends

Two ways of setting up Event Sourced Aggregates

There are two ways we can configure our Aggregate to record Events.

In general having streams in need for snapshots may indicate that our model needs revisiting. We may cut the stream on some specific event and begin new one, like at the end of month from all the transactions we generate invoice and we start new stream for next month. However if cutting the stream off is not an option for any reason, we can use snapshots to avoid loading all events history for given Aggregate. Every given set of events snapshot will be taken, stored and retrieved on next calls, to fetch only events that happened after that.

Setting up

EventSourcingConfiguration provides the following interface to set up snapshots.

In its lifetime events may change. In order to track those changes Ecotone provides possibility of versioning events.

Value given with Revision attribute will be stored by Ecotone in events metadata. Attribute is used only when event is saved in event store. In order to read it, you can access events metadata, e.g. in event handler.

[Enterprise] Accessing Metadata in Event Sourcing Handler

A consumer crashes mid-handler. The Stripe webhook arrives twice. A notify-customer job fails forever and you can't tell why. Two workers race on the same aggregate and one's update gets silently overwritten. This section is the toolbox for everything that goes wrong after a message is dispatched.

Ecotone provides solutions across three concerns:

• Self-healing (, , )

Ecotone is the PHP architecture layer that grows with your system without rewrites. One Composer package adds CQRS, event sourcing, sagas, projections, outbox, EIP routing, and distributed messaging to Laravel or Symfony via declarative PHP attributes — no rewrite, no bespoke glue.

Pick your stack below. Symfony and Laravel get dedicated integration packages with auto-configuration; any other framework (or no framework) runs on Ecotone Lite through a PSR-11 container.

Prerequisites

Before installing Ecotone, ensure you have:

• PHP 8.1 or higher

• Composer installed

• A properly configured PHP project with PSR-4 autoloading

Install for Symfony

Step 1: Install the Ecotone Symfony Bundle using Composer

Step 2: Verify Bundle Registration

If you're using Symfony Flex (recommended), the bundle will auto-configure. If auto-configuration didn't work, manually register the bundle in config/bundles.php:

Step 3: Verify Installation

Run this command to check if Ecotone is properly installed:

Install for Laravel

Step 1: Install the Ecotone Laravel Package

Step 2: Verify Provider Registration

The service provider should be automatically registered via Laravel's package discovery. If auto-registration didn't work, manually add the provider to config/app.php:

Step 3: Verify Installation

Run this command to check if Ecotone is properly installed:

Install Ecotone Lite (No framework)

If you're using no framework or framework different than Symfony or Laravel, then you may use Ecotone Lite to bootstrap Ecotone.

With Custom Dependency Container

If you already have Dependency Container configured, then:

Load namespaces

By default Ecotone will look for Attributes only in Classes provided under "classesToResolve". If we want to look for Attributes in given set of Namespaces, we can pass it to the configuration.

With no Dependency Container

You may actually run Ecotone without any Dependency Container. That may be useful for small applications, testing or when we want to run some small Ecotone's script.

Ecotone Lite Application

You may use out of the box Ecotone Lite Application, which provide you with Dependency Container.

Common Installation Issues

"Class not found" errors

Problem: Ecotone can't find your classes with attributes. Solution: Make sure your classes are in the correct namespace and directory structure matches your PSR-4 autoloading configuration.

Bundle/Provider not registered

Problem: Ecotone commands are not available. Solution:

• For Symfony: Check that the bundle is listed in config/bundles.php

• For Laravel: Check that the provider is in config/app.php or that package discovery is enabled

Permission errors

Problem: Cache directory is not writable. Solution: Ensure your web server has write permissions to the cache directory (usually var/cache for Symfony or storage/framework/cache for Laravel).

Separate the code that changes state from the code that reads it — clear command and query handlers with zero boilerplate.

Demo

Read Blog Post

Code Example

Registering Command Handlers

Let's create PlaceOrder Command that will place an order in our system.

And Command Handler that will handle this Command

Registering Query Handlers

Let's define GetOrder Query that will find our placed order.

And Query Handlerthat will handle this query

Running The Example

Make any handler async with a single attribute — retries, error handling, and dead letter included automatically.

Demo

Read Blog Post

Code Example

Let's create Event Order was placed.

And Event Handler that will be listening to the OrderWasPlaced.

Let's Ecotone that we want to run this Event Handler Asynchronously using

Running The Example

Read Aggregate Introduction sections first to get more details about Aggregates.

Publishing Events from Aggregate

To tell Ecotone to retrieve Events from your Aggregate add trait WithEvents which contains two methods: recordThat and getRecordedEvents.

After importing trait, Events will be automatically retrieved and published after handling Command in your Aggregate.

Subscribing to Event from your Aggregate

Sometimes you may have situation, where Event from one Aggregate will actually change another Aggregate. In those situations you may actually subscribe to the Event directly from Aggregate, to avoid creating higher level boilerplate code.

In those situations however you need to ensure event contains of reference id, so Ecotone knows which Aggregate to load from the database.

Sending Named Events

You may subscribe to Events by names, instead of the class itself. This is useful in cases where we want to decoupled the modules more, or we are not interested with the Event Payload at all. For Events published from your Aggregate, it's enough to provide NamedEvent attribute with the name of your event.

And then you can subscribe to the Event using name

Create an Aggregate by another Aggregate

There may be a scenario where the creation of an Aggregate is conditioned by the current state of another Aggregate.

Ecotone provides a possibility for that and lets you focus more on domain modeling rather than technical nuances you may face trying to implement an actual use case.

This case is supported by both Event Sourcing and State-based Aggregates.

Create a State-based Aggregate

It is possible to send a command to an Aggregate and expect a State-based Aggregate to be returned.

Create an Event Sourcing Aggregate

It is also possible to send a command to an Aggregate and expect the Event Sourcing Aggregate to be returned.

Events handling

Both of the Aggregates (called and result) can still record their Events using an Internal Recorder. Recorded Events will be published after the operation is persisted in the database.

Persisting a state change

In the case of an Event Sourcing Aggregate recording an event indicates a state change of that Aggregate.

Also, when calling a State-based Aggregate its state may be changed before returning the newly created Aggregate. E.g. you want to save a reference to the newly created Aggregate.

Ecotone will try to persist both called and returned Aggregates.

Default flow

In default flow there is no need to fetch or store Aggregates, because this is done for us. We simply need to trigger an Command via CommandBus. However in some cases, you may want to retake orchestration flow and do it directly. For that cases Business Repository Interface or Instant Fetch Aggregate can help you.

Business Repository Interface

Special type of is Repository. This Interface allows us to simply load and store our Aggregates directly. In situations when we call Command directly in our Aggregates we won't be in need to use it. However for some specific cases, where we need to load Aggregate and store it outside of Aggregate's Command Handler, this business interface becomes useful.

Ecotone will read type hint to understand which Aggregate you would like to fetch or save.

Pure Event Sourced Repository

When using Pure Event Sourced Aggregate, instance of Aggregate does not hold recorded Events. Therefore passing aggregate instance would not contain any information about recorded events. For Pure Event Sourced Aggregates, we can use direct event passing to the repository:

Instant Fetch Aggregate

Fetch aggregates directly in your handlers without repository injection boilerplate. Aggregates arrive automatically via the #[Fetch] attribute, keeping handler code focused on business logic.

You'll know you need this when:

• Every aggregate command handler follows the same pattern: inject repository, fetch aggregate, call method, save

• Repository injection boilerplate obscures the actual business logic in your handlers

• You want your domain code to express "what happens" without "how to load it"

To do instant fetch of Aggregate we will be using Fetch Attribute. Suppose we want PlaceOrder Command Handler, and we want to fetch User Aggregate:

Fetch using to evaluate the expression given inside the Attribute. For example having above "payload.userId" and following Command:

Ecotone will use userId from the Command to fetch User Aggregate instance. &#xNAN;"payload" is special variable within expression that points to our Command, therefore whatever is available within the Command is available for us to do the fetching. This provides quick way of accessing related Aggregates without the need to inject Repositories.

Allowing non existing Aggregates

By default Ecotone will throw Exception if Aggregate is not found, we can change the behaviour simply by allowing nulls in our method declaration:

Accessing Message Headers

We can also use Message Headers to fetch our related Aggregate instance:

Using External Services

In some cases we may not have enough information to provide correct Identifier, for example that may require some mapping in order to get the Identifier. For this cases we can use "reference" function to access any Service from Depedency Container in order to do the mapping.

Be sure to read CQRS Introduction before diving in this chapter.

Execute your Business Actions via Interface

Business Interface aims to reduce boilerplate code and make your domain actions explicit. In Application we describe an Interface, which executes Business methods. Ecotone will deliver implementation for this interface, which will bind the interface with specific actions. This way we can get rid of delegation level code and focus on the things we want to achieve. For example, if we don't want to trigger action via Command/Query Bus, we can do it directly using our business interface and skip all the Middlewares that would normally trigger during Bus execution. There are different types of Business Interfaces and in this chapter we will discuss the basics of build our own Business Interface, in next sections we will dive into specific types of business interfaces: Repositories and Database Layers.

Command Interface

Let's take as an example creating new Ticket

We may define interface, that will call this Command Handler whenever will be executed.

This way we don't need to use Command Bus and we can bypass all Bus related interceptors.

The attribute #[BusinessMethod] tells Ecotone that given Interface is meant to be used as entrypoint to Messaging and which Message Handler it should send the Message to. Ecotone will provide implementation of this interface directly in our Dependency Container.

Aggregate Command Interface

We may also execute given Aggregate directly using Business Interface.

Then we define interface:

Query Interface

Defining Query Interface works exactly the same as Command Interface and we may also use it with Aggregates.

Then we may call this Query Handler using Interface

Result Conversion

If we have registered then we let Ecotone do conversion to Message Handler specific format:

Then we may call this Query Handler using Interface

Ecotone will use defined Converter to convert array to TicketDTO.

Payload Conversion

If we have registered then we let Ecotone do conversion to Message Handler specific format:

Then we may call this Query Handler using Interface

Ecotone will use defined Converter to convert array to CreateTicket command class.

Working with Event Sourcing Aggregates

Just as with Standard Aggregate, ES Aggregates are called by Command Handlers, however what they return are Events and they do not change their internal state.

#[EventSourcingAggregate]
class Product
{
    use WithAggregateVersioning;

    #[Identifier]
    private string $id;

    #[CommandHandler]
    public static function create(CreateProduct $command) : array
    {
        return [new ProductWasCreated($command->id, $command->name, $command->price)];
    }
}

When this Aggregate will be called via Command Bus with CreateProduct Command, it will then return new ProductWasCreated Event.

Event Stream

Aggregates under the hood make use of Partition persistence strategy (Refer to ). This means that we need to know:

• Aggregate Version

• Aggregate Id

• Aggregate Type

Aggregate Version

To find out about current version of Aggregate Ecotone will look for property marked with Version Attribute.

We don't to add this property directly, we can use trait instead:

Anyways, this is all we need to do, as Ecotone will take care of reading and writing to this property. This way we can focus on the business logic of the Aggregate, and Framework will take care of tracking the version.

Aggregate Id (Partition Key)

We need to tell to Ecotone what is the Identifier of our Event Sourcing Aggregate. This is done by having property marked with Identifier in the Aggregate:

As Command Handlers are pure and do not change the state of our Event Sourcing Aggregate, this means we need a different way to mutate the state in order to assign the identifier. For changing the state we use EventSourcingHandler attribute, which tell Ecotone that if given Event happens, then trigger this method afterwards:

We will explore how applying Events works more in .

Aggregate Type

Aggregate Type will be the same as Aggregate Class. We can decouple the class from the Aggregate Type, more about this can be found in "" section.

Recording Events in the Event Stream

So when this Command Handler happens:

What actually will happen under the hood is that this Event will be applied to the Event Stream:

As storing in Event Store is abstracted away, the code stays clean and contains only of the business part. We can the Stream Name, Aggregate Type and even Event Names when needed.

Ecotone comes with inbuilt Event Sourcing repository after Event Sourcing package is installed. However you want to roll out your own storage for Events, or maybe you already use some event-sourcing framework and would like to integrate with it. For this you can take over the control by introducing your own Event Sourcing Repository.

Custom Event Sourcing Repository

We do start by implementing EventSourcingRepository interface:

interface EventSourcedRepository
{
    1. public function canHandle(string $aggregateClassName): bool;
    
    2. public function findBy(string $aggregateClassName, array $identifiers, int $fromAggregateVersion = 1) :  EventStream;

    3. public function save(array $identifiers, string $aggregateClassName, array $events, array $metadata, int $versionBeforeHandling): void;
}

1. canHandle - Tells whatever given Aggregate is handled by this Repository

2. findBy - Method returns previously created events for given aggregate. Which Ecotone will use to reconstruct the Aggregate.

3. save - Stores events recorded by Event Sourced Aggregate

and then we need to mark class which implements this interface as Repository

Storing Events

Ecotone provides enough information to decide how to store provided events.

Identifiers will hold array of identifiers related to given aggregate (e.g. ["orderId" ⇒ 123]). Events will be list of Ecotone's Event classes, which contains of payload and metadata, where payload is your Event class instance and metadata is specific to this event. Metadata as parameter is generic metadata available at the moment of Aggregate execution. Version before handling on other hand is the version of the Aggregate before any action was triggered on it. This can be used to protect from concurrency issues.

The structure of Events is as follows:

Core metadata

It's worth to mention about Ecotone's Events and especially about metadata part of the Event. Each metadata for given Event contains of three core Event attributes:

"_aggregate_id" - This provides aggregate identifier of related Aggregate

"_aggregate_version" - This provides version of the related Event (e.g. 1/2/3/4)

"_aggregate_type" - This provides type of the Aggregate being stored, which can be customized

Aggregate Type

If our repository stores multiple Aggregates is useful to have the information about the type of Aggregate we are storing. However keeping the class name is not best idea, as simply refactor would break our Event Stream. Therefore Ecotone provides a way to mark our Aggregate type using Attribute

This now will be passed together with Events under _aggregate_type metadata.

Named Events

In Ecotone we can name the events to avoid storing class names in the Event Stream, to do so we use NamedEvent.

then when events will be passed to save method, they will automatically provide this name under eventName property.

Snapshoting

With custom repository we still can use inbuilt . To use it for customized repository we will use BaseEventSourcingConfiguration.

Ecotone then after fetching snapshot, will load events only from this given moment using `fromAggregateVersion`.

Testing

If you want to test out your flow and storing with your custom Event Sourced Repository, you should disable default in memory repository

Persistence Strategy

Describes how streams with events will be stored. Each Event Stream is separate Database Table, yet how those tables are created and what are constraints do they protect depends on the persistence strategy.

Simple Stream Strategy

This is the basics Stream Strategy which involves no constraints. This means that we can append any Events to it without providing any additional metadata.

Now as this is free append involves no could re-run this code apply exactly the same Event. This can sounds silly, but it 's make it useful for particular cases. It make it super easy to append new Events. We basically could just add this action in our code and keep applying Events to the Event Stream, we don't need to know context of what happened before.

This is useful for scenarios where we just want to store information without putting any business logic around this. It could be used to continues stream of information like:

• Temperature changes

• Counting car passing by in traffic jam

• Recording clicks and user views.

Partition Stream Strategy

This the default persistence strategy. It does creates partitioning within Event Stream to ensure that we always maintain correct history within partition. This way we can be sure that each Event contains details on like Aggregate id it does relate to, on which version it was applied, to what Aggregate it references to.

The tricky part here is that we need to know Context in order to apply the Event, as besides the Aggregate Id, we need to provide Version. To know the version we need to be aware of last previous applied Event.

This Stream Strategy is great whenever business logic is involved that need to be protected. This solves for example the problem of concurrent access on the database level, as we for example can't store Event for same Aggregate Id and Version twice in the Event Stream. We would use it in most of business scenarios where knowing previous state in order to make the decision is needed, like:

• Check if we can change Ticket based on status

• Performing invocing from previous transactions

• Decide if Order can be shipped

Stream Per Aggregate Strategy

This is similar to Partition strategy, however each Partition is actually stored in separate Table, instead of Single One.

This can be used when amount of partitions is really low and volume of events within partition is huge.

Custom Strategy

You may provide your own Customer Persistence Strategy as long as it implements PersistenceStrategy.

Setting global Persistence Strategy

To set given persistence strategy as default, we can use ServiceContext:

Multiple Persistence Strategies

Once set, the persistence strategy will apply to all streams in your application. However, you may face a situation when you need to have a different strategy for one or more of your streams.

The above will make the Simple Stream Strategy as default however, for some_stream Event Store will use the Aggregate Stream Strategy.

The Problem

Your projection's table schema changed, or you found a bug in a handler and the read model has wrong data. How do you set up, tear down, and rebuild projections without writing manual SQL scripts?

Ecotone provides lifecycle hooks — methods on your projection class that are called at specific moments — and CLI commands to trigger them.

Lifecycle Hooks

Initialization

Called when the projection is first set up. Use it to create tables, indexes, or any storage structure:

Delete

Called when the projection is permanently removed. Clean up all storage:

Reset

Called when the projection needs to be rebuilt from scratch. Clear the data but keep the structure:

After a reset, the projection's position is set back to the beginning. The next trigger will replay all events from the start.

Flush

Called after each batch of events is processed. Useful for flushing buffers or intermediate state:

See for how batching and flushing work together.

CLI Commands

Initialize a Projection

Delete a Projection

Calls #[ProjectionDelete] and removes all tracking state:

Backfill a Projection

Populates a fresh projection with historical events. See for details:

Rebuild a Projection (Enterprise)

Resets the projection and replays all events. See for details:

Automatic vs Manual Initialization

By default, projections auto-initialize the first time an event triggers them. This means you don't need to run any CLI command — the #[ProjectionInitialization] method is called automatically.

If you need manual control (for example, during ), you can disable auto-initialization:

Reset and Trigger

To rebuild a projection manually, you can reset it (clears data and position) and then trigger it (starts processing from the beginning):

1. Reset — calls #[ProjectionReset], clears position to the beginning

2. Trigger — starts processing events from position 0, rebuilding the entire Read Model

This is useful when you've fixed a bug in a handler and need to reprocess all events to correct the data.

The Problem

Your service classes mix reading and writing. A single change to how orders are placed breaks the order listing page. Business rules are scattered across controllers, listeners, and services — there's no clear boundary between "what changes state" and "what reads state."

How Ecotone Solves It

Ecotone introduces Command Handlers for state changes, Query Handlers for reads, and Event Handlers for reactions. Each has a single responsibility, wired automatically through PHP attributes. No base classes, no framework coupling — just clear separation of concerns on top of your existing Laravel or Symfony application.

In this chapter we will cover process of handling and dispatching Messages with Ecotone. We will discuss topics like Commands, Events and Queries, Message Handlers, Message Buses, Aggregates and Sagas. You may be interested in theory - chapter first.

Materials

Demo implementation

Links

• [Article]

• [Article]

• [Article]

The Problem You Recognize

You're a technical lead or architect evaluating whether PHP can handle enterprise-grade architecture. Your team knows PHP well, but the business is growing — you need CQRS, Event Sourcing, distributed messaging, multi-tenancy, and production resilience.

The alternative is migrating to Java (Spring + Axon) or .NET (NServiceBus, MassTransit). That means retraining your team, rewriting your application, and losing PHP's development speed.

Be sure to read before diving in this chapter.

Handling Queries

External Query Handlers are Services available in your dependency container, which are defined to handle Queries.

The Problem

You have an Order model. The rule "an order can only be paid once" lives in the OrderController::pay() action. There's another check in the Stripe webhook listener. There's a third in the admin override controller. A new developer adds a fourth code path — a console command that updates the row directly — and skips the check. Production ships double-paid orders.

The root cause: anyone in the codebase can write $order->status = 'paid'

Ecotone allows to work with Database using DbalBusinessMethod. The goal is to create abstraction which significantly reduce the amount of boilerplate code required to implement data access layers. Thanks to Dbal based Business Methods we are able to avoid writing integration and transformation level code and focus on the Business part of the system. To make use of Dbal based Business Method, .

Write Business Methods

Let's consider scenario where we want to store new record in Persons table. To make it happen just like with Business Method we will create an Interface, yet this time we will mark it with

When loading Aggregates or Sagas we need to know what Identifier should be used for that. This depending on the business feature we work may require different approaches. In this section we will dive into different solutions which we can use.

Auto-Mapping from the Command/Event

Ecotone resolves the mapping automatically, when Identifier in the Aggregate/Saga is named the same as the property in the Command/Event.

then, if Message has productId, it will be used for Mapping:

Three Shapes of Durable Workflows

Every multi-step business process has one of three shapes. Pick the one that matches yours — all three are durable, all three survive crashes and deploys, all three run on the database and broker you already operate.

We may happen to face Errors on different stage of our Workflows. This may happen due to coding error and due to Network and Integration problems as well. Whatever the problem is, we want to be able to recover from that, or to be able to execute compensation action that will handle this failure.

Ecotone provides different ways to deal with the problems and depending on the context, we may want to choose different solution.

Uncovered Business Scenarios

It happens that uncovered business scenario are treated as failures. This may happen for example when Customer have made two payments for the same Order and our system basically throws an Exception.

Your audit interceptor needs currentUserId. The handler doesn't take it as an argument — and you don't want to thread it through every Command DTO just to satisfy an audit concern. Headers are the side-channel: pass currentUserId as a header at dispatch time and read it from any interceptor or handler downstream. They flow with the message through synchronous and asynchronous channels alike, automatically mapped through your Message Broker on the wire.

Passing headers to Bus:

The Problem

You have existing projections using the old #[Projection] API and want to migrate to #[ProjectionV2]. Do you need to migrate data? Will there be downtime?

The Problem

Your projection needs data from multiple aggregates — orders AND payments — or you want to handle only specific events instead of everything in the stream. How do you control what events reach your projection and how they are routed?