What is Ecotone Framework?

Ecotone is the PHP framework for durable workflows, event sourcing, Domain-Driven Design, reliable messaging, and asynchronous communication — one Composer package that adds sagas, orchestrators, aggregates, projections, outbox, retries, and CQRS to Laravel, Symfony, or Tempest through declarative PHP attributes. It runs on the database and broker you already operate; no separate workflow service, no replay-deterministic DSL, no engine-specific event log.

Do I need Temporal or a separate workflow engine to build durable workflows in PHP?

No. Ecotone delivers durable execution on the database and broker you already run. Sagas persist state per identifier, chained workflows survive crashes through the outbox plus async channel, saga timeouts use a #[Delayed] attribute, and Orchestrators (Enterprise) give declarative multi-step workflows. There is no separate cluster to operate, no RoadRunner or ext-grpc requirement, no replay-deterministic DSL — workflows are plain PHP classes with attributes. If you have already adopted Temporal, Ecotone still fits around it for CQRS, projections, distributed messaging, multi-tenant routing, and sagas that aren't full workflows.

Which message brokers does Ecotone work with?

RabbitMQ, Apache Kafka, Amazon SQS, Redis, and the database (DBAL outbox) are first-party — and Ecotone also integrates with Enqueue transports, Symfony Messenger transports, and Laravel Queue channels. Handler code is broker-agnostic: a single #[Asynchronous('channel')] attribute works the same across every transport. CombinedMessageChannel writes the message to the database for the outbox guarantee and dispatches execution on the broker, so outbox draining stays on the database and consumers scale horizontally on RabbitMQ / SQS / Kafka.

Can I use Ecotone with Laravel, Symfony, or Tempest?

Yes. Ecotone ships dedicated packages for Laravel, Symfony, and Tempest that make integration seamless. After installation, Command, Event, and Query buses are available out of the box in the dependency container — and for any other framework, Ecotone Lite provides a standalone integration via PSR-11.

Do I need to rewrite my application to use Ecotone?

No. Ecotone works alongside your existing application — you adopt it incrementally for the parts where messaging, sagas, event sourcing, or distributed messaging make sense, without rewriting what already works. Ecotone sits above Symfony Messenger and Laravel Queues, using them as transports underneath rather than replacing them.

Why pick Ecotone for Event Sourcing?

Ecotone provides a built-in event store on PostgreSQL or MySQL with #[EventSourcingAggregate], #[ProjectionV2] for read models (global, partitioned, or streaming), non-blocking gap detection that catches concurrent-transaction events without blocking concurrent writes, projections that can publish their own events so dependents react in the same flow instead of a separate eventually-consistent process (with rebuild auto-suppression), and end-to-end PII encryption across the event store, broker payloads, and structured logs. As event volume grows, projections scale from a single cursor to N parallel workers via partitioning — without changing your domain code.

Does Ecotone support building systems following Domain-Driven Design?

Ecotone's vocabulary is DDD vocabulary: #[Aggregate], Repository abstraction, #[Saga] as process managers, bounded-context isolation via the Distributed Bus, and Domain Events as first-class plain PHP classes. Where each building block is fully decoupled from the framework using declarative configuration. Ecotone is the only framework that makes DDD build blocks easily composable in Message-Driven systems, to not only ensure clear business logic, but to make the system build on top of reliable architecture.

PHP's architecture layer. Build features, not infrastructure.

From #[CommandHandler] on day one to sagas, orchestrators, event sourcing, outbox, and distributed messaging at scale — one package, same codebase, no forced migrations between growth stages.

Get started Documentation

Works on the Laravel, Symfony, or Tempest you already run · Install with Composer · Configure with PHP attributes

The layer you stop writing

Every arrow in your architecture is code someone has to write.

Communication, orchestration, and reliability don't come from your blocks — they live between them. Ecotone makes that layer a default, not a project.

Without Ecotone

Order

Stock

Invoice

Every new feature adds more arrows. Every arrow is code you write, test, and maintain.

With Ecotone

Order

Stock

Invoice

Ecotone

routing·orchestration·workflows·delivery·retries·dead letters·outbox·scaling·failure isolation·async test support

You write the blocks — Ecotone provides the communication, reliability, and scale.

Drops into your stack

Your framework stays.
Your ORM, queues, and deploy stay too.

Ecotone is a Composer package that adds architecture on top of what you already run. Business logic as POPOs, messaging topology as attributes, your existing Laravel, Symfony, Tempest, or PSR-11 container underneath.

Business logic layer

Your Business Logic

Aggregates·Command / Event / Query Handlers·Projections·Workflows

Plain PHP classes with attributes — no base classes, no framework coupling

Architecture layer

Ecotone

Provides the layer where aggregates, projections, message handlers, sagas, and workflows meet and exchange messages.

Each block stays whole on its own — communication, reliability, and scalability are the layer's defaults, not code you write.

Messaging CQRS Event Sourcing Workflows Resilience

Application level

Laravel Symfony Tempest Other

The basics of the application stack

Your framework keeps doing what it does best: HTTP · Security · ORM / Active Record · Auth · Transport (Laravel Queue / Symfony Messenger) · Views · DI Container

Infrastructure level

Redis Kafka RabbitMQ and more

Your existing Message Broker

Ecotone runs messaging on the broker you already operate — and lets you switch brokers freely, without changing your business logic.

Proof in code

This is all the code it takes.

A Composer package, not a rewrite. Your Eloquent models and Doctrine entities become aggregates as-is, and #[Asynchronous] rides the queue or transport you already run — no new broker required.

Start with one attribute

Two attributes turn an ordinary service into a typed command/query bus. No aggregates, no event sourcing, no broker.

OrderService.php

// Start with one attribute — no aggregates, no event sourcing, no broker.

class OrderService
{
    #[CommandHandler]
    public function placeOrder(PlaceOrder $command): void
    {
        $this->orders[$command->orderId] = $command->productName;
    }

    #[QueryHandler]
    public function getOrder(GetOrder $query): string
    {
        return $this->orders[$query->orderId];
    }
}

Grow into production patterns

When you need async, it's one attribute more — retries, dead letter queue, and tracing included, on the queue you already run.

OrderService.php

// Asynchronous command handler — that's the entire setup

#[Asynchronous('orders')]
#[CommandHandler]
public function placeOrder(PlaceOrder $command): void
{
    $order = Order::create($command->orderId, $command->items);
    $this->orderRepository->save($order);
}

// Ecotone handles the rest:
// ✓ Async on the broker or queue you already run
//   (Laravel Queue, Symfony Messenger, RabbitMQ, Kafka, SQS, Redis, DBAL)
// ✓ Automatic retries on failure
// ✓ Dead letter queue if all retries fail
// ✓ Message tracing and correlation

Show integration — pick your framework, then an example, to see the real code.

Install is one line — a Symfony bundle entry, Laravel auto-discovery, or a composer require ecotone/tempest on Tempest. The tables Ecotone needs (outbox, dead-letter, deduplication, event store, projection cursors) live in your own database and are created by ecotone:migration:database:setup — or dumped as SQL into your existing migrations.

Testing

One testing model for every flow

Your tests run through the same messaging pipeline as production — bus routing, async channels, event propagation — all in one process. Send a message, run the flow, assert the result. The test shape never changes.

Extract exactly the flow you care about and test it in isolation:

OrderServiceTest.php

// Test a specific flow in isolation — only the services you need

$ecotone = EcotoneLite::bootstrapFlowTesting([OrderService::class]);

$ecotone->sendCommand(new PlaceOrder('order-1'));

$this->assertEquals('placed', $ecotone->sendQueryWithRouting('order.getStatus', 'order-1'));

Bring in async handlers, enable an in-memory channel, and verify the full flow:

OrderWithNotificationsTest.php

// Test the full async flow — in-memory channel, same process

$notifier = new InMemoryNotificationSender();

$ecotone = EcotoneLite::bootstrapFlowTesting(
    [OrderService::class, NotificationService::class],
    [NotificationSender::class => $notifier],
    enableAsynchronousProcessing: [
        SimpleMessageChannelBuilder::createQueueChannel('notifications')
    ]
);

$ecotone
    ->sendCommand(new PlaceOrder('order-1'))
    ->run('notifications');

$this->assertEquals(['order-1'], $notifier->getSentOrderConfirmations());

Swap the in-memory channel for DBAL, RabbitMQ, or Kafka in production — the test stays the same. Ecotone runs the consumer in-process, so switching transports never changes how you test.

The growth ladder

Each new stage is an attribute — not a rewrite.

Same classes, same codebase at every stage. The more advanced your needs get — interceptors, sagas, orchestration, event sourcing, multi-tenancy, PII encryption — the more Ecotone already has built in, on the same code.

1Day 1

#[CommandHandler]
#[QueryHandler]
#[EventHandler]
#[Aggregate]
#[Identifier]

Familiar handlers.

CQRS buses and aggregates, auto-wired from attributes. Five-minute start.

2Week 1

#[Asynchronous]
#[Deduplicated]
#[Scheduled]
#[Repository]
#[BusinessMethod]

Async & persistence.

Move work off the request cycle, and reach data through repositories and business-method interfaces — all declarative.

3Month 1+

#[Before]
#[Around]
#[Priority]
#[Delayed]
#[TimeToLive]

Intercept & tune delivery.

Cross-cutting concerns and delivery control — interceptors, priority, delays, time-to-live — declaratively.

4Month 6

#[Saga]
#[EventSourcingSaga]
#[InternalHandler]
#[Orchestrator] ✦
#[OrchestratorGateway] ✦

Long-running processes.

Sagas and orchestrators coordinate multi-step business flows, outbox-consistent.

5Year 1

#[EventSourcingAggregate]
#[Projection]
#[Distributed] ✦
#[MultiTenantConnection] ✦
#[Router]

Event sourcing & distribution.

Replayable aggregates, projections, cross-service messaging, and per-tenant connections — on the same code.

6Year 1+

#[Streaming] ✦
#[Partitioned] ✦
#[Sensitive] ✦
#[WithEncryptionKey] ✦
#[KafkaConsumer] ✦

Scale & protect.

Streaming and partitioned projections plus end-to-end PII encryption — Enterprise capabilities, same model.

✦ Enterprise capability — included with an Enterprise licence

Every other PHP alternative forces you to re-decide architecture at each column break — swap libraries, add glue, or stitch together a multi-package stack. No other single PHP package spans the full set of growth stages.

New to these patterns?

The vocabulary, in plain language

Every pattern above is something you have likely already built by hand — under a different name. Here is the translation.

CQRS

Commands change things, queries read things — each handled by a dedicated method instead of a fat controller.

You have built this as: Slim controllers calling service methods

Aggregate

The model that guards its own rules — “an order can only be cancelled before it ships.” Your Eloquent or Doctrine model, with the ifs in one place.

You have built this as: A model full of business-rule checks

Saga

A process that spans time: order placed → wait for payment → send reminder → cancel after 7 days. The state between steps is stored for you.

You have built this as: Status columns + scheduled jobs + listeners

Projection

A read table kept up to date automatically from events — the reporting view you rebuild with a cron job today.

You have built this as: A denormalized reporting table

Event Sourcing

Store every change as an event instead of overwriting the row — a full audit trail, and any view can be rebuilt from history.

You have built this as: An audit-log table, done thoroughly

Outbox

Your data and the messages about it are saved in one database transaction — so nothing is lost when the queue or broker hiccups.

You have built this as: The “job dispatched but data rolled back” bug

No forced migrations

Most PHP tools cover one slice.
Ecotone delivers every slice itself, in one messaging model.

Ecotone delivers the building blocks itself — aggregates, sagas, projections, the outbox, CQRS, async, and distribution — composed through attributes on one messaging foundation, not assembled from separate libraries. Pick the category that matches your need: each comparison shows how Ecotone stacks up against the single-purpose tool you'd otherwise reach for.

Durable Workflows

vs Temporal PHP SDK · Durable Workflow (formerly Laravel Workflow) · Symfony Messenger alone · Laravel Queues / Horizon

See comparison →

Event Sourcing

vs Spatie laravel-event-sourcing · EventSauce · Patchlevel event-sourcing

See comparison →

Asynchronous Communication

vs Symfony Messenger alone · Laravel Queues / Horizon

See comparison →

Orchestration Layer

vs Temporal PHP SDK · Durable Workflow (formerly Laravel Workflow) · Symfony Messenger alone

See comparison →

Microservices

vs Symfony Messenger alone · Laravel Queues / Horizon

See comparison →

Domain-Driven Design

vs Spatie laravel-event-sourcing · EventSauce · Patchlevel event-sourcing

See comparison →

Complete standalone. Composable when you prefer. Ecotone covers the whole path — aggregate to broker to projection — and composes with any of the tools above when you already have a favourite for one layer.

Capabilities

Every pattern your domain will need — on one codebase

CQRS, event sourcing, sagas, outbox, EIP routing, multi-tenancy, distributed bus — all attribute-driven, all on the same messaging foundation.

Durable Workflows in Plain PHP

Crash-resistant multi-step processes on your existing database and broker. Sagas, orchestrators, chained workflows, outbox, and #[Delayed] timeouts — plain PHP attributes, no separate workflow service, no replay-deterministic DSL.

Reliable Messaging on Any Broker

RabbitMQ, Kafka, SQS, Redis, DBAL outbox. Move handlers to async with one attribute. CombinedMessageChannel writes the message in the same DBAL transaction as the business state, then forwards it to the broker for consumers to handle — an atomic outbox, so a broker outage can't lose it. Delivery is at-least-once, and built-in deduplication makes redelivery safe. Transports swap without code changes.

Resilience Defaults

Transactional outbox, DBAL dead-letter queue with replay, retries with exponential backoff, deduplication, OpenTelemetry on every handler — default behaviour, not assembly required.

Per-handler Failure Isolation

A copy of the message is dispatched to every handler. Each retries independently, fails independently — no shared envelope, no sibling re-runs. One failing subscriber doesn't abort the others.

Sagas & Workflows

Stateful long-running processes with compensation. Handler-chaining workflows for stateless pipelines. Saga timeouts in one #[Delayed] attribute. All declarative, all attribute-driven.

CQRS & Handlers

Command, query, and event bus — all auto-wired from your attributes. No registration, no factory classes, no container bindings.

Event Sourcing & Projections

Store events, not state. Aggregates, projections, replay, snapshotting. Partitioned + streaming projections so rebuilds parallelize across workers and catch up in real time — no single-process bottleneck.

Composable EIP Messaging

Pipe handlers together. Route by payload or headers. Split one message into many. Filter, enrich, transform — all as attributes, no glue code.

Custom Buses per Use Case

Extend CommandBus into use-case-specific interfaces. Attach retry, DLQ, and dedup as attributes directly on the interface declaration.

Multi-tenant Messaging

Tenant-isolated event streams, tenant-routed message channels, priority routing by customer status. Multi-tenancy as a topology property, not a WHERE clause.

Endpoint-ID Routing

Rename classes, move handlers, refactor namespaces — messages still route correctly. The endpoint ID is the contract; FQCN is not on the wire.

Compose Patterns Without Glue

Aggregate publishes event. Saga subscribes by attribute. Projection subscribes by attribute. Async handler subscribes by attribute. The attribute is the wiring.

Framework-portable Business Code

Same aggregates, handlers, sagas, and projections run on Laravel, Symfony, Tempest, or any PSR-11 container. Hedge against framework changes over a decade.

End-to-end PII Protection

One #[Sensitive] attribute encrypts a field in the event store, on the wire over RabbitMQ / SQS / Redis / Kafka / DBAL outbox, and in your structured logs — because all serialization flows through one shared conversion pipeline.

Projections That Publish Their Own Events

A projection can publish its own event the moment it applies a change — so dependent logic reacts in the same flow instead of a separate eventually-consistent process; sagas, event handlers, and other projections subscribe via the normal #[EventHandler]. Rebuild a projection? Emission is automatically suppressed, so downstream consumers aren't flooded with duplicate historical events while the read model catches up.

Runs on the Brokers You Already Have

First-party packages for RabbitMQ, Kafka, SQS, Redis, and DBAL. Ecotone fits your existing stack — no new cluster to operate, no migration of your message infrastructure.

Correlation & Causation, Automatic

Correlation IDs and parent-message IDs propagate from command to every emitted event without middleware. Your OpenTelemetry spans stitch themselves end-to-end — no bundle to install, no stamps to remember.

Blue-Green Projection Rebuild

Rebuild a projection on a new version in parallel — concurrent async backfill partitioned by aggregate ID scales rebuilds to millions of events across N workers. The live projection keeps serving queries until the atomic flip.

Self-Healing Projections

Projections are trigger-based: on every run they read from the Event Store at their last committed position. Crash at event #42? Fix the bug, deploy, and the projection catches up automatically — no manual reset, no backfill script.

Built For Your Stack

What Ecotone brings to your stack

Laravel handles HTTP beautifully. But the moment you need event sourcing, sagas, or multi-step workflows — you're stitching packages together. Ecotone gives you one coherent model: aggregates, projections, outbox, and more — all attribute-driven, all testable in-process, all running on the Laravel queues you already have.

Your Eloquent model is the aggregate

#[Asynchronous] rides your Laravel queue — Redis, database, SQS

Auto-discovered — zero config to start

Where it fits

Built for systems where failure is
regulated, expensive, or public

Per-handler isolation, the transactional outbox, end-to-end PII encryption, deduplication — the defaults that matter when a dropped or double-processed message is a real-world incident, not a log line.

Payment gateways

Where retried handlers cannot double-charge, and the outbox must guarantee that every committed transaction produces exactly one downstream message.

Credit card systems

Where transaction loss is catastrophic, and every state change must be auditable and replayable.

Certification authorities

Whose entire business depends on reconstructible, tamper-evident audit trails; the event log is the audit log.

E-commerce platforms

Orchestrating order → payment → fulfillment → notification as declarative sagas with compensation.

Public transportation subscription systems

Managing nationwide transit subscriptions (create, renew, terminate) with distributed bus integration to Java and PHP services over Kafka.

Two-sided marketplaces

Coordinating customer orders, provider subscriptions, lead distribution, and B2B enterprise partnerships on one event-driven backbone.

Ecosystem

Enterprise Patterns Across Ecosystems

Every mature platform has this. Now PHP does too.

Ecosystem	Framework	Enterprise Patterns
Java	Spring	Axon Framework
.NET	ASP.NET	NServiceBus / MassTransit
PHP	Laravel / Symfony / Tempest	Ecotone

Apache 2.0

Open source, free for commercial use

550,000+

Packagist Downloads

Years of Active Development

1.325.0

Latest release · 7 days ago

last commit today

No breaking changes across major versions

Ecotone follows a stability commitment — your business code keeps working across releases, so upgrades are safe to apply.

A funded model, built in the open

Behind Ecotone stands SimplyCodedSoftware and its open-source contributors. Every Enterprise licence directly supports continued development.

Commercial support, Support Agreements, and workshops

Available for teams running Ecotone in production. Consulting, onboarding workshops, and Support Agreements: a guaranteed next-business-day response and prioritised fixes for framework defects.

AI-Ready

Your AI assistant gets Ecotone right

Ecotone's contract sits on the method — typed, explicit, local — so agents read real signatures instead of guessing. With Agentic Skills, MCP, and llms.txt included, your AI writes idiomatic Ecotone code from day one.

Typed contracts, correct code

A #[CommandHandler] on a typed method is a contract your agent reads right where it's editing. Real signatures produce code that compiles and behaves — instead of plausible-looking calls that only fail at runtime.

Agentic Skills

Ready-to-use skills that teach any coding agent how to correctly write handlers, aggregates, sagas, projections, and tests. Your AI generates idiomatic Ecotone code from the start.

MCP & llms.txt

Your AI assistant reads Ecotone's documentation directly — via Model Context Protocol and llms.txt. Accurate, current answers in Claude Code, Cursor, Windsurf, GitHub Copilot, and others.

Wiring that stays put

Attribute wiring lives on the method — not in convention files that move between framework versions. What your AI learned yesterday still works after every upgrade, so generated code lands in the right place every time.

Grows with you

Ecotone supports you — no matter the scale.

The free core carries real production systems — async messaging, the outbox, retries, sagas, event sourcing. And when your system reaches truly demanding scale, Ecotone Enterprise provides the solutions built for it: partitioned and streaming projections, Kafka, the Distributed Bus, Orchestrators, end-to-end PII encryption.

Same attributes, same classes, same development model — from your first handler to your most demanding system.

See pricing Enterprise capabilities

Ready to Get Started?

Add Ecotone to your existing Laravel, Symfony, or Tempest project in minutes.

composer require ecotone/laravel

Get started Explore examples

PHP's architecture layer. Build features, not infrastructure.

Every arrow in your architecture is code someone has to write.

Your framework stays.Your ORM, queues, and deploy stay too.

This is all the code it takes.

Start with one attribute

Grow into production patterns

One testing model for every flow

Each new stage is an attribute — not a rewrite.

The vocabulary, in plain language

Most PHP tools cover one slice.Ecotone delivers every slice itself, in one messaging model.

Durable Workflows

Event Sourcing

Asynchronous Communication

Orchestration Layer

Microservices

Domain-Driven Design

Every pattern your domain will need — on one codebase

Durable Workflows in Plain PHP

Reliable Messaging on Any Broker

Resilience Defaults

Per-handler Failure Isolation

Sagas & Workflows

CQRS & Handlers

Event Sourcing & Projections

Composable EIP Messaging

Custom Buses per Use Case

Multi-tenant Messaging

Endpoint-ID Routing

Compose Patterns Without Glue

Framework-portable Business Code

End-to-end PII Protection

Projections That Publish Their Own Events

Runs on the Brokers You Already Have

Correlation & Causation, Automatic

Blue-Green Projection Rebuild

Self-Healing Projections

What Ecotone brings to your stack

Built for systems where failure isregulated, expensive, or public

Payment gateways

Credit card systems

Certification authorities

E-commerce platforms

Public transportation subscription systems

Two-sided marketplaces

Enterprise Patterns Across Ecosystems

No breaking changes across major versions

A funded model, built in the open

Commercial support, Support Agreements, and workshops

Your AI assistant gets Ecotone right

Typed contracts, correct code

Agentic Skills

MCP & llms.txt

Wiring that stays put

Ecotone supports you — no matter the scale.

Ready to Get Started?

Your framework stays.
Your ORM, queues, and deploy stay too.

Most PHP tools cover one slice.
Ecotone delivers every slice itself, in one messaging model.

Built for systems where failure is
regulated, expensive, or public