DEV Community: Dariusz Gafka

How Ecotone Confirms 10,000 Messages in 64ms

Dariusz Gafka — Tue, 11 Aug 2026 19:51:14 +0000

One PHP process published 10,000 messages to Kafka, waited for the broker to confirm every single one, and stopped the clock at 64 milliseconds. That is 157,266 confirmed messages per second, from PHP, with no delivery guarantee traded away. This post is the receipts: what I measured, how, and what surprised me along the way.

TL;DR: Ecotone's high-throughput publishing sends messages as provider-native batches and collects all broker confirmations before the business operation completes. Measured from one PHP process: Kafka 157,266 msg/s, Redis 115,638, RabbitMQ 67,143 (amqp-ext), Postgres 53,711, SQS 7,549 — every message individually confirmed before the operation completes.

ℹ️ Note: High-throughput publishing is a paid Ecotone Enterprise capability. A trial licence is available at ecotone.tech/pricing#trial, so every number below is reproducible on your machine.

How I measured
What each provider can actually do
The numbers
Where each number comes from: the two mechanisms
Draining an outbox: the other half of the path
What actually happens to a published message
The code behind the benchmark
Common questions

How I measured

I did not want to claim a number I could not hand to a skeptic. So the benchmark is a runnable demo — public at github.com/SimplyCodedSoftware/ecotone-publishing-throughput-demo — a Docker Compose setup with Kafka, RabbitMQ (on both Enqueue AMQP transports), LocalStack SQS, Redis and Postgres, plus one PHP process that publishes 10,000 messages and awaits every broker confirmation before stopping the clock, reporting the median of five iterations.

The rules I held myself to:

The guarantee is constant. Every scenario waits for per-message broker confirmation. Comparing confirmed publishing against unconfirmed publishing would make the numbers look better and mean nothing.
Warm, isolated runs. Each provider is measured on its own, best warm run reported, with the stable band across repeated runs recorded next to it.
One PHP process. No worker pools, no parallel producers. The point is what a single process can do.

ℹ️ Note: Prerequisites for running it yourself — Docker Compose and an Ecotone Enterprise trial licence from ecotone.tech/pricing#trial. PHP itself runs inside the demo's containers.

What each provider can actually do

The numbers below only make sense with one thing said up front: high-throughput publishing is two independent mechanisms, not one, and a provider only gets the mechanism its protocol has.

Provider	Batching	Non-blocking confirmation
Kafka	native batch produce	delivery reports collected at the end
RabbitMQ	one publisher-confirms round trip	confirms collected at the end
SQS	native batch send requests, sent concurrently	responses collected at the end
Postgres	one multi-row INSERT	not offered — the INSERT confirms itself
Redis	one scripted round trip	not offered — the reply is the confirmation

Redis and Postgres confirm the write in the reply to the write, so there is nothing to defer — batching is their entire feature, and their configuration call takes no parameters. That is why they show one fast scenario in the results and the other three providers show two.

The numbers

Best isolated warm runs, one PHP process, 10,000 messages per run, median of five, brokers running locally:

Provider	Batched publishing (absolute)	Band across isolated runs
Kafka	157,266 msg/s — 10,000 confirmed in 64ms	98,962–157,266
Redis	115,638 msg/s — 10,000 confirmed in 86ms	111,374–115,638
RabbitMQ (amqp-ext)	67,143 msg/s — 10,000 confirmed in 149ms	62,854–67,143
Postgres	53,711 msg/s	48,887–53,711
RabbitMQ (amqp-lib)	36,294 msg/s	31,222–36,294
SQS (LocalStack)	7,549 msg/s	7,190–7,549

Two things in this table surprised me.

First, Redis lands second overall at 115,638 msg/s, behind only Kafka — despite having no deferred-confirmation mode at all. Redis acknowledges each command in its reply, so there is nothing to defer and batching is the entire feature; the same is true of Postgres at 53,711. The "boring" providers benefit as much as the streaming ones.

Second, RabbitMQ appears twice, because the two Enqueue AMQP transports are genuinely different code paths: amqp-lib hands the whole batch to the socket in a single write, amqp-ext writes per message — and amqp-ext still wins by roughly 1.8×, because php-amqplib encodes the AMQP protocol in pure PHP and that overhead costs more than the single socket write saves. It stays the recommended transport, and it is the one the RabbitMQ numbers here quote; both transports support the full feature set.

For context on why this matters: publishing one message at a time is round-trip-bound. Each publish serializes, sends, waits for the broker's confirmation, and only then starts the next one. Ten thousand of those waits, one after another, is what makes the per-message path take seconds. The sequencing is the cost. That is the cap being removed here — the common expectation for confirmed publishing from PHP is a few hundred messages per second.

Where each number comes from: the two mechanisms

The headline row is both mechanisms at once. Measured separately, they buy different things — worth knowing before you decide which switch you need.

Batching — gather and send together. Everything the handler published during the operation is collected and handed to the channel as one message instead of N sends; the provider maps it onto its own batch primitive. N round-trips become one, and the application never builds a batch. Redis and Postgres isolate this mechanism perfectly, since it is the only one they have:

Provider	Per-message	Batched
Redis	32,184 msg/s	115,638 msg/s
Postgres	16,421 msg/s	53,711 msg/s

Collapsing round-trips is worth the most exactly where the infrastructure is least forgiving: the less headroom the storage has, the more of the per-message path is pure waiting.

Non-blocking confirmation — stop waiting between messages. Every message is still written on its own, but the process no longer waits for each confirmation before writing the next: Kafka produces without flushing and drains delivery reports as it goes, RabbitMQ coalesces its publisher confirms, SQS dispatches requests concurrently. The waiting happens once, at the end of the scope, before the transaction commits:

Provider	Per-message	Non-blocking confirm
Kafka	9,053 msg/s	23,421 msg/s — 2.6x
RabbitMQ (amqp-ext)	13,754 msg/s	20,261 msg/s — 1.5x
RabbitMQ (amqp-lib)	9,776 msg/s	15,252 msg/s — 1.6x
SQS (LocalStack)	660 msg/s	1,143 msg/s — 1.7x

Every transport gains here, and the size of the gain tells you where it was spending its time. Kafka's 2.6x is the outlier: producing without flushing lets the client keep working while delivery reports drain behind it. The AMQP transports and SQS land between 1.5x and 1.7x, because each message is still its own write and only the confirmation wait gets coalesced.

Both, which is the default. The batch removes the round-trips, the deferred confirmation removes the waiting between what is left, and every confirmation is still collected before the transaction commits — Kafka 157,266 msg/s, RabbitMQ (amqp-ext) 67,143, RabbitMQ (amqp-lib) 36,294, SQS 7,549. Those are the rows in the table above.

Draining an outbox: the other half of the path

Every number above measures the write into the broker. Systems that use the outbox pattern have a second leg to pay for: the message is committed into the database with the business change, and a separate process relays it onward. That relay normally consumes the outbox like any other channel — one message per poll cycle, deserialized and republished on its own.

The same demo times that leg (./run.sh outbox). Batched forwarding replaces the outbox consumer with a publishing endpoint that claims rows straight from the database, groups them by target and hands over whole batches in wire format; the target has high-throughput publishing on, so a claim becomes one native broker batch. 10,000 messages waiting in the outbox:

Target	Message by message	Batched, 100 rows per cycle	One claim of 10,000
Kafka	34.49s — 290 msg/s	0.318s — 31,461 msg/s	0.200s — 50,052 msg/s
RabbitMQ	29.75s — 336 msg/s	0.393s — 25,418 msg/s	0.264s — 37,808 msg/s
Redis	29.35s — 341 msg/s	0.293s — 34,093 msg/s	0.232s — 43,063 msg/s
SQS (LocalStack)	43.67s — 229 msg/s	1.889s — 5,293 msg/s	1.472s — 6,794 msg/s

Message by message, every row pays a poll cycle, a deserialize, its own transaction and its own publish — around 3ms each, more on SQS where each publish is an HTTP round trip. Batched forwarding claims rows in blocks and hands the target whole batches, which is the entire difference.

Which is the finding I did not expect: the relay was the bottleneck, not the broker. Every target lands within a tenth of a second of the others once the rows are claimed in one batch — except SQS, whose API caps a batch request at 10 entries, so 10,000 messages are still 1,000 HTTP round trips.

Batch size is a smaller knob than the batching itself: a hundred cycles of a hundred rows cost 1.3x to 1.6x what a single claim of 10,000 does, depending on the target, and the single claim buys that by holding the whole batch in memory inside one transaction. Delivery guarantees do not move either way. A failed delivery is released for redelivery rather than duplicating what already went out, and a connection failure rolls the cycle back for a clean retry.

What actually happens to a published message

The mechanism in one sentence: the waiting happens once, at the end. Messages fire to the broker the instant your handler emits them and travel while it keeps working; Ecotone collects every confirmation once, right before the transaction commits.

The business operation cannot complete until every confirmation is in hand. If a delivery fails, the operation fails, or the specific failed message routes to the error channel — individually, not as a whole batch. The consumer side never knows batching happened: it sees individual messages, retries individual messages, dead-letters individual messages.

What you observe when logging is exactly the order the test suite asserts:

transaction started
command handler executed
published batch of 2 messages to broker
delivery confirmations awaited
transaction committed

Confirmations are awaited once, after the handler finishes and before the commit — not per message.

The code behind the benchmark

The scenario behind the headline number is two lines:

// From the runnable throughput demo
$publisher->publishDeferred(buildBatch(), MediaType::TEXT_PLAIN)->resolve();
// Kafka: 10,000 confirmed in 64ms — 157,266 msg/sec

publishDeferred returns a Future; resolve() blocks until every broker confirmation arrives.

That is the explicit form. The form most applications will use requires no publishing code at all — a handler that publishes events stays exactly as it always was:

#[CommandHandler]
public function place(PlaceOrder $command, EventBus $eventBus): void
{
    $eventBus->publish(new OrderWasPlaced($command->orderId));
    $eventBus->publish(new OrderConfirmationRequested($command->orderId));
}

No batch objects, no futures. The handler publishes events one call at a time, as before.

High-throughput publishing is switched on in configuration, per channel or publisher:

final class MessagingConfiguration
{
    // Events published from handlers are gathered, sent as one
    // native batch, and confirmed before the operation completes
    #[ServiceContext]
    public function ordersChannel(): KafkaMessageChannelBuilder
    {
        return KafkaMessageChannelBuilder::create('orders')
            ->withHighThroughputPublishing();
    }

    // Message Publisher — enables publishDeferred() with a Future
    #[ServiceContext]
    public function orderPublisher(): AmqpMessagePublisherConfiguration
    {
        return AmqpMessagePublisherConfiguration::create()
            ->withHighThroughputPublishing();
    }
}

One builder call per channel. The same call maps to each broker's native batching underneath.

Each provider gets what it does best under that one API: Kafka produces without flushing per message, RabbitMQ defers confirms, SQS sends native batch requests concurrently, Postgres writes one multi-row INSERT, Redis pipelines commands. The handler code never sees the difference.

Common questions

Were these runs against remote brokers?
No — brokers ran on the same machine, which is the right setup for measuring the publishing path itself. Over a real network the round-trip per message gets more expensive, not less, so per-message publishing degrades further while the batched path pays that latency once per batch.

Do any of these numbers skip broker confirmations?
No. Every scenario awaits per-message broker confirmation before the clock stops. A failed delivery fails the operation or routes that specific message to the error channel. That constraint is held constant across every broker and transport in the table.

Why is SQS so much slower than the others?
SQS itself caps how many entries fit in one native batch request, so more round-trips remain per 10,000 messages. It still lands at 7,549 msg/s confirmed — well above what a per-message loop achieves against the same endpoint.

Do my consumers need to understand batches?
No. Batching never survives the wire. Consumers receive individual messages; retries and dead-lettering operate on individual messages. Nothing downstream changes.

Run it yourself

Numbers you cannot reproduce are just claims. The demo is public at github.com/SimplyCodedSoftware/ecotone-publishing-throughput-demo: Docker Compose, five brokers, six configurations, one PHP process, and the clock only stops when the last confirmation arrives. Request a trial licence, run it on your laptop, and see where your band lands.

Explore the Ecotone docs

Trial licences are available at ecotone.tech/pricing#trial.

What throughput do you actually get out of PHP publishing in your own stack? The demo runs on any machine with Docker — I would genuinely like to see numbers that disagree with mine.

Originally published at blog.ecotone.tech.

Tempest + Ecotone: One Declarative Foundation

Dariusz Gafka — Thu, 30 Jul 2026 20:08:57 +0000

Updated on 2026-07-22

Tempest describes itself as a framework designed to get out of your way — you write application code, and discovery finds it. Ecotone sits one layer higher and makes the matching promise: full business focus — you write business logic, and the architecture wiring is handled. Those are two phrasings of one foundation idea, declarative configuration: you declare intent in code, and the framework derives everything else. This article is about what happens when the two meet — composer require ecotone/tempest does not add a dependency so much as install an architecture layer into the foundation. I know how this architecture behaves — I did not build a shop to find out. I built it because code snippets stop being enough at exactly this point: you have to see the layers in a real application, click through it, and break it yourself. So this article walks a working e-commerce shop, receipts included, down to the class count. One thing before we start: Ecotone is my framework, and it has a paid Enterprise tier, so audit the claims below with that in mind.

TL;DR: Tempest and Ecotone are built on the same foundation — declarative configuration. Tempest applies it to the application layer and gets out of your way; Ecotone applies it to the architecture layer and enables full business focus. composer require ecotone/tempest installs that layer into Tempest: CQRS, async processing with retries and a dead letter, event sourcing, projections, workflows, per-message delayed delivery, and an outbox with deduplication for free — and a runnable e-commerce demo shows what that looks like in practice: the entire messaging layer is roughly a dozen application classes.

One foundation: declarative configuration
Installing the architecture layer
The shop, concept by concept
The count
What this does not solve
Transferable lessons
Common gotchas

One foundation: declarative configuration

Ecotone now has a first-class integration for Tempest — a new package, ecotone/tempest (documentation). What makes this integration different from a typical framework adapter is that both sides already work the same way. In Tempest you write a controller, a model, a console command — discovery finds it, no registration. In Ecotone you write a class with #[CommandHandler] on a method — the framework finds it, builds the bus, routes the message, manages the transaction. Neither side asks you to describe your application to it; both derive the wiring from what you declared in code.

That shared foundation is why the composition looks like layers rather than glue:

A pedestal, built bottom-up: Tempest is the foundation layer, one composer require installs the Ecotone architecture layer on top of it, and everything above the two is yours — business logic, and only business logic.

The result is checkable as a size claim: an application with enterprise-level messaging architecture where the application code holds business logic and almost nothing else. There is no configuration layer to minimize; it simply isn't there.

The entire setup:

composer require ecotone/tempest

One command. No service provider, no bundle registration, no YAML.

A config file exists, but it is optional — the composer require alone gives you a fully working integration. Claims like that are cheap on a slide, which is why everything below comes from a browsable shop rather than snippets: product grid, cart, checkout, orders dashboard, shipment tracking, real emails landing in a local inbox. The whole application is public — ecotoneframework/tempest-ecotone-demo — so you can clone it, run docker compose up, play with it, and count the classes yourself.

ℹ️ Note: Prerequisites — PHP 8.5, Tempest, ecotone/tempest. The demo additionally uses ecotone/dbal, ecotone/pdo-event-sourcing and ecotone/jms-converter on Postgres.

Installing the architecture layer

The diagram's middle layer is what the composer require actually delivers. Ecotone brings its whole platform — durable channels, retries with backoff, dead-lettering, per-message delayed delivery, a query bus, event sourcing — and every piece of it is declared the same way the foundation is: attributes on plain classes, discovered, never registered.

namespace App\Order;

use Ecotone\Modelling\Attribute\CommandHandler;

final class PlaceOrderHandler
{
    #[CommandHandler('order.place')]
    public function place(string $orderId): void
    {
        // store the order in the database
    }
}

A handler is a plain class with one attribute — discovered, routed and wrapped in a transaction without any registration.

Here is the full path a request takes, from the browser down to the stored order — and who owns each step:

Tempest carries the request to your controller; Ecotone carries the command to your handler, inside a transaction; the only code you wrote is the controller call and the handler body.

Where does discovery get its scan paths? From what you already wrote. When no namespaces are configured, Ecotone derives them from Tempest's Composer object — the PSR-4 roots of your composer.json. The database connection comes from Tempest's own DatabaseConfig through TempestConnectionReference::defaultConnection(), so Ecotone's transactions wrap Tempest ORM writes on one shared PDO connection. You declared both things once; the integration reads them instead of asking again.

The buses arrive the same way. Every Ecotone gateway is injectable from Tempest's container with zero registration:

use Ecotone\Modelling\CommandBus;
use Tempest\Router\Post;

final class OrderController
{
    public function __construct(
        private CommandBus $commandBus,
    ) {}

    #[Post('/orders')]
    public function place(string $orderId): Redirect
    {
        $this->commandBus->sendWithRouting('order.place', $orderId);

        return new Redirect('/orders');
    }
}

Tempest does the dependency injection; Ecotone provides the gateways. QueryBus and EventBus inject the same way.

The split is clean. Tempest solves HTTP, DI, forms, database models, console. Ecotone adds, on top of the same models and the same container, the messaging layer an application needs when it grows.

The shop, concept by concept

What we are building: a shop where a customer browses products, fills a cart and checks out. The checkout records an order; stock drops immediately; a notification appears on the dashboard; a confirmation email arrives in the inbox; the warehouse prepares a shipment whose history is an event stream feeding the read model on screen; and thirty seconds after the shipment is dispatched, the customer gets a review request.

It is an ordinary-looking application, which is the point — here is the shop a user actually sees:

Every panel on that page comes from a different mechanism explained below: the tiles are a query, the shipments are a projection over an event stream, the notifications were written by a background worker. None of that is visible to the person clicking. One business flow, end to end:

The whole flow. Each section below delivers one highlighted piece of it.

Installation

Rolling out Tempest was one command: composer create-project tempest/app app — a working skeleton with routing, views, console. Adding Ecotone was one more: composer require ecotone/tempest.

The aggregate is the Tempest model

Focus: checkout → the Order aggregate.

Checkout needs somewhere to send PlaceOrder — and this is the strongest single moment in the integration, so look closely:

use Ecotone\Modelling\Attribute\Aggregate;
use Ecotone\Modelling\Attribute\CommandHandler;
use Ecotone\Modelling\Attribute\IdentifierMethod;
use Ecotone\Modelling\Attribute\QueryHandler;
use Tempest\Database\IsDatabaseModel;
use Tempest\Database\PrimaryKey;

#[Aggregate]
final class Order
{
    use IsDatabaseModel;

    public PrimaryKey $id;
    public string $user_id;
    public int $total_price;
    public bool $is_cancelled;

    #[CommandHandler]
    public static function place(PlaceOrder $command): self
    {
        $order = new self();
        $order->user_id = $command->userId;
        $order->total_price = $command->totalPrice;
        $order->is_cancelled = false;
        $order->save();

        return $order;
    }

    #[IdentifierMethod('id')]
    public function getId(): int
    {
        return $this->id->value;
    }

    #[CommandHandler(routingKey: 'cancel_order')]
    public function cancel(): void
    {
        $this->is_cancelled = true;
    }

    #[QueryHandler('is_cancelled')]
    public function isCancelled(): bool
    {
        return $this->is_cancelled;
    }
}

One final class where both frameworks meet: #[Aggregate] from Ecotone, IsDatabaseModel from Tempest. The static place() factory is the creation handler — a command creates the aggregate, and save() goes through Tempest's own persistence.

Look at cancel(). It mutates state. That is all it does. No fetch, no save, no repository injection. Sending a command to it looks like this:

$orderId = $commandBus->send(new PlaceOrder(userId: 'user-1', totalPrice: 100));

$commandBus->sendWithRouting('cancel_order', metadata: ['aggregate.id' => $orderId]);

$queryBus->sendWithRouting('is_cancelled', metadata: ['aggregate.id' => $orderId]); // true

Ecotone loads the model by id, calls the handler, saves it back — through Tempest's own persistence.

There is no repository class to write. TempestRepository — Ecotone's built-in repository, shipped with the integration — makes any model using IsDatabaseModel usable as an aggregate directly. Checkout in the controller is three lines: build PlaceOrder from the cart, send it, redirect with the returned order id.

Event handler: subscribing to what happened

Focus: the synchronous stock decrement.

The aggregate records OrderWasPlaced. Subscribing to it is one attribute on a plain class — this synchronous handler decrements stock in the same transaction as the order:

final class StockLevelUpdater
{
    #[EventHandler]
    public function whenOrderWasPlaced(OrderWasPlaced $event): void
    {
        foreach ($event->items as $line) {
            $product = Product::findById($line->productId);

            if ($product === null) {
                continue;
            }

            $product->stock = max(0, $product->stock - $line->quantity);
            $product->save();
        }
    }
}

No subscription config, no event map — the parameter type is the subscription.

Asynchronous event handler

Focus: the notifications channel and its async read model.

The same event also drives handlers that should not block checkout. Adding #[Asynchronous('notifications')] moves a handler to a background worker consuming a database-backed channel — the consistency model is chosen per handler:

final class NotificationRecorder
{
    #[Asynchronous('notifications')]
    #[EventHandler(endpointId: 'notification.order_placed')]
    public function whenOrderWasPlaced(OrderWasPlaced $event): void
    {
        Notification::create(
            message: sprintf('Order #%d placed by %s', $event->orderId, $event->customerName),
            type: 'order_placed',
        );
    }
}

One attribute picks the consistency model per handler.

And this is the moment the integration gets registered. The notifications channel the attribute refers to is declared in the application's only Ecotone configuration — one small class, two one-line methods: bridge Tempest's Postgres config into Ecotone, and declare the durable channel:

use Ecotone\Dbal\DbalBackedMessageChannelBuilder;
use Ecotone\Messaging\Attribute\ServiceContext;
use Ecotone\Tempest\Config\TempestConnectionReference;

final class MessagingConfiguration
{
    #[ServiceContext]
    public function connection(): TempestConnectionReference
    {
        return TempestConnectionReference::defaultConnection();
    }

    #[ServiceContext]
    public function notificationsChannel(): DbalBackedMessageChannelBuilder
    {
        return DbalBackedMessageChannelBuilder::create('notifications');
    }
}

#[ServiceContext] methods are discovered like everything else. The channel runs on the same Postgres connection Tempest's models use.

Three async handlers hang off the same event: this one writes the notifications read model, one starts the confirmation-email workflow, one starts shipment preparation. The worker is Ecotone's own CLI entrypoint — ./tempest ecotone:run notifications — with no app code behind it.

Event sourcing and a projection

Focus: the shipment event stream and its projection.

Shipment is an #[EventSourcingAggregate]: its state is not a table row but the stream of events in the Postgres event store. Command handlers return events; #[EventSourcingHandler] methods rebuild the state from them:

#[EventSourcingAggregate]
final class Shipment
{
    use WithAggregateVersioning;

    #[Identifier]
    private string $orderId;

    private string $customerName = '';

    private string $customerEmail = '';

    private bool $dispatched = false;

    #[CommandHandler]
    public static function prepare(PrepareShipment $command): array
    {
        return [new ShipmentWasPrepared(
            orderId: $command->orderId,
            customerName: $command->customerName,
            packageCount: $command->packageCount,
            customerEmail: $command->customerEmail,
        )];
    }

    #[CommandHandler(routingKey: 'shipment.dispatch')]
    public function dispatch(): array
    {
        if ($this->dispatched) {
            return [];
        }

        return [new ShipmentWasDispatched(
            orderId: $this->orderId,
            customerName: $this->customerName,
            customerEmail: $this->customerEmail,
        )];
    }

    #[EventSourcingHandler]
    public function applyPrepared(ShipmentWasPrepared $event): void
    {
        $this->orderId = $event->orderId;
        $this->customerName = $event->customerName;
        $this->customerEmail = $event->customerEmail;
    }

    #[EventSourcingHandler]
    public function applyDispatched(ShipmentWasDispatched $event): void
    {
        $this->dispatched = true;
    }
}

Handlers return events; state is rebuilt from the stream. The dispatched guard makes the Dispatch button idempotent — clicking twice records nothing twice.

The UI never reads the stream directly. A #[Projection] derives the read model — and the read model is a plain Tempest model:

#[Projection('shipment_list', Shipment::class)]
final class ShipmentListProjection
{
    #[EventHandler]
    public function whenShipmentWasPrepared(ShipmentWasPrepared $event): void
    {
        ShipmentView::create(
            order_id: $event->orderId,
            customer_name: $event->customerName,
            package_count: $event->packageCount,
            status: 'prepared',
        );
    }

    #[EventHandler]
    public function whenShipmentWasDispatched(ShipmentWasDispatched $event): void
    {
        $view = ShipmentView::find(order_id: $event->orderId)->first();
        $view->status = 'dispatched';
        $view->save();
    }
}

The projection writes ShipmentView — a Tempest IsDatabaseModel — so the dashboard queries it like any other table.

Workflow: async emails end to end

Focus: the email workflow, ending in the inbox.

The email pipeline is three small steps connected by channel names, and each step owns exactly one concern. The event handler composes the CONTENT — and only the content. It does not know the recipient; it passes the notification forward with the id needed to find out:

#[Asynchronous('notifications')]
#[EventHandler(endpointId: 'order_confirmation.start', outputChannelName: 'notification.enrich')]
public function start(OrderWasPlaced $event): EmailNotification
{
    return new EmailNotification(
        orderId: (string) $event->orderId,
        subject: sprintf('Order #%d confirmed', $event->orderId),
        html: /* ...items and total rendered to HTML */,
    );
}

Content and an id. No recipient, no mailer, no bus.

The next step enriches the message HEADERS with the account details. With changingHeaders: true, the returned array is merged into the headers while the payload passes through untouched:

final readonly class AccountDetailsEnricher
{
    #[InternalHandler(
        inputChannelName: 'notification.enrich',
        outputChannelName: 'email.send',
        changingHeaders: true,
    )]
    public function enrich(EmailNotification $notification): array
    {
        $order = Order::findById((int) $notification->orderId);

        return [
            'customerEmail' => $order->customer_email ?? '',
            'customerName' => $order->customer_name ?? '',
        ];
    }
}

A pipeline step that only adds knowledge. The payload flows on unchanged.

And the last step is a prepared building block: it reads the payload plus the enriched headers, builds the GenericEmail, and sends through Tempest's own Mailer:

#[InternalHandler(inputChannelName: 'email.send')]
public function send(
    EmailNotification $notification,
    #[Header('customerEmail')] ?string $customerEmail,
    #[Header('customerName')] ?string $customerName,
    Mailer $mailer,
): void {
    if ($customerEmail === null || $customerEmail === '') {
        return;
    }

    $mailer->send(new GenericEmail(
        subject: $notification->subject,
        to: $customerEmail,
        html: sprintf('<p>Hi %s!</p>', $customerName) . $notification->html,
    ));
}

The send block never changes — any notification in the application can flow through it. The delayed review request in the next section reuses this exact chain.

And the end of the chain is a real email, sent by the background worker through Tempest's Mailer — here caught by Mailpit, next to the delayed review request from the section below:

Delayed messages

Focus: the delayed review request.

Thirty seconds after a shipment is dispatched, the customer gets a review request. This is not a recurring job for a scheduler: it is one specific message, due once, thirty seconds after its own trigger. It waits inside the durable channel — surviving worker restarts — and is released when due:

#[Delayed(new TimeSpan(seconds: 30))]
#[Asynchronous('notifications')]
#[EventHandler(endpointId: 'review_request.on_shipment_dispatched', outputChannelName: 'notification.enrich')]
public function requestReview(ShipmentWasDispatched $event): EmailNotification
{
    return new EmailNotification(
        orderId: $event->orderId,
        subject: sprintf('How was order #%s?', $event->orderId),
        html: '<p>Your package is on its way. When it arrives, tell us how it went.</p>',
    );
}

One attribute replaces the scheduler — and the whole delayed email is eight lines of content, because enrichment and sending come from the pipeline it flows through.

When the mail step fails: retries, dead letter, alerts page

Focus: the mail send — the one step in this flow that talks to the outside world, and therefore the one that fails.

The checkout form has a "simulate an email delivery failure" checkbox:

It is sent as metadata on the command, and that metadata propagates: to the event the aggregate records, into the durable channel, out to the background worker, and finally to the send step, which reads it as a #[Header] parameter. Nothing between checkout and the mailer mentions it.

Tick it and the send throws. The message is retried after one second, retried again after three, and then parked in a database-backed dead letter with its stacktrace. The order placed right behind it, without the box ticked, gets its email immediately — same channel, no blockage, and the worker keeps running. That behavior is a third #[ServiceContext] method on the same config class from earlier:

#[ServiceContext]
public function errorHandling(): ErrorHandlerConfiguration
{
    return ErrorHandlerConfiguration::createWithDeadLetterChannel(
        'errorChannel',
        RetryTemplateBuilder::exponentialBackoff(initialDelay: 1000, multiplier: 3)
            ->maxRetryAttempts(2),
        'dbal_dead_letter',
    );
}

No retry loops in handlers, no dead-letter migration, no supervisor watching the worker.

Recovery is a console command, because Ecotone's commands are discovered by Tempest like any other:

./tempest ecotone:deadletter:list       # what is parked, when it failed, why
./tempest ecotone:deadletter:show <id>  # full payload and stacktrace
./tempest ecotone:deadletter:replay <id>

But operations work is not always CLI work, and this is where the layering pays off again: the dead letter is not a private mechanism, it is a service. DeadLetterGateway injects into any Tempest controller, so the demo turns it into a page:

final readonly class AlertsController
{
    public function __construct(private DeadLetterGateway $deadLetter) {}

    #[Get('/alerts')]
    public function index(): View
    {
        return view('./alerts.view.php', errors: $this->deadLetter->list(limit: 50, offset: 0));
    }

    #[Post('/alerts/{messageId}/replay')]
    public function replay(string $messageId): Redirect
    {
        $this->deadLetter->reply($messageId);

        return new Redirect('/alerts');
    }
}

Two routes and a view. Each entry is an ErrorContext — message id, failure time, exception class and message, file, line, stacktrace — so the template has everything an operations screen needs.

One detail worth stealing even if you never use this page: a replayed message carries the header ecotone.dlq.message_replied, readable as a normal #[Header] parameter. Recovery can therefore behave differently from the first attempt — skip a step that already succeeded, relax a guard, tag the result. A handler gets to see how a message reached it, not only what it carries.

Outbox and deduplication

Focus: the order transaction and the channel — one commit carries both.

Stop the worker and place an order. The order row and its event messages are committed in the same Postgres transaction, because the channel is database-backed — select count(*) from enqueue where queue='notifications' shows them waiting. Start the worker; the table drains and the emails go out. The dual-write problem ("order saved, event lost") cannot happen here, and nothing was configured to make that true. Redelivered messages are skipped through the ecotone_deduplication table — also zero code.

Multi-tenancy

Beyond this flow, the package also covers tenant separation. When you need it, a single message header routes commands, queries, transactions and business-interface SQL to the right tenant database:

$commandBus->send(new RegisterCustomer(1, 'John Doe'), metadata: ['tenant' => 'tenant_a']);
$commandBus->send(new RegisterCustomer(2, 'John Doe'), metadata: ['tenant' => 'tenant_b']);

$queryBus->sendWithRouting('customer.getAllRegistered', metadata: ['tenant' => 'tenant_a']); // [1]

Tenant routing decided by one metadata header.

Everything shown in this article, this header-based multi-tenancy included, runs on Ecotone's free Apache-2.0 tier; only custom tenant resolvers sit behind the paid Enterprise licence.

The whole flow — browse, checkout, stock −1, async notification, shipment prepared from the event stream, dispatch, email in the inbox — was exercised through the running web UI. The messaging logic is additionally covered without any framework boot by EcotoneLite tests, including async-tested-synchronously and the email workflow with a stubbed mailer.

The count

The application's entire messaging layer:

one state-stored aggregate (Order)
one event-sourced aggregate (Shipment)
commands and events as plain readonly objects
four event handlers
one projection
one query service
one workflow, plus the enrichment step it flows through
one config class: connection, channel, error handling

That is about a dozen small classes. Everything else in the codebase is Tempest UI: controllers, views, a session cart — including the alerts page, which is two routes on top of DeadLetterGateway. There is no custom worker command, no repository, no serializer configuration, no queue wiring. The architecture list reads like a system that needs a platform team; the diff reads like a weekend project.

The count also survived the resiliency additions. Retries with dead-lettering came in as one #[ServiceContext] method on the existing config class; the delayed review email is one method on the existing workflow class; the outbox and deduplication needed no code at all. The feature list grew, the class list did not.

What this does not solve

Honest edges, so the claim stays checkable.

A production-grade messaging layer reveals its complexity one production incident at a time — retry storms, poison messages, dual writes, replay against changed code. Hardening one takes years of absorbing other people's failures, and that is the layer Ecotone contributes here with the incident bill already paid. Tempest contributes HTTP, DI and models, which it does well. That is exactly why composition works: each side brings the layer it has spent its years on.

Multi-tenant messaging also has open edge cases in Ecotone's own tracker. The header-based routing shown above is solid for the command/query/transaction path, but I would not claim every corner is covered yet.

And the integration is young. Building the demo surfaced four integration bugs in ecotone 1.321 — each got a red-first test and a fix released in 1.322, and every workaround the demo carried was then deleted: the concrete OrderMailer wrapper, the custom shop:consume command, persistent: true in the database config, the APP_ENV override in phpunit.xml. The demo today runs workaround-free. That is what week one of a new integration honestly looks like.

Transferable lessons

Declarative + declarative composes; imperative + declarative fights. The integration is thin (about 20 source files) because neither side adapts to the other's philosophy. When picking tools to combine, alignment of principles matters more than feature lists.
Zero config means reading what the app already declares. PSR-4 roots, database config — the developer wrote them once; the integration derives from them instead of asking twice.
A framework choice does not have to mean an ecosystem ceiling. The "good fit, once more mature" objection assumes every capability must come from the framework's own ecosystem. A portable architecture layer breaks that assumption: the same Ecotone code runs on Laravel, Symfony, and now Tempest.
Enterprise-grade is a property of the architecture, not the amount of code. Transactions shared with the ORM connection, dead-letter support, tenant routing — none of it written by the application.

Common gotchas

Tempest persists every model property — including Ecotone's recorded events
Using Ecotone's WithEvents trait on a Tempest model maps the trait's private $recordedEvents property to a database column, and checkout fails with "no such column: recordedEvents". The fix is Tempest's own escape hatch: declare your own recorded-events property marked #[Virtual] with a recordThat() method and an #[AggregateEvents] release method. Two conventions colliding on one class, one-attribute fix.

JMS cannot serialize array-shape docblocks
array<array{product_id: int, ...}> fails with "Can't use unsupported type array." Define a proper readonly DTO (OrderLine) and use @param array<OrderLine> $items — JMS reads that natively. The serializer pushed the model toward the better shape.

In integration tests, clear Ecotone's static state BEFORE the kernel boots
Discovery may compile the messaging system during boot. Clearing statics afterwards leaves a container singleton without its gateway ids, and failures get confusing fast.

Wrapping up

Tempest gaining CQRS is the small news. The bigger news is what two discovery-based frameworks make possible when composed: an enterprise-level feature list carried by application code that holds only business logic. If you have been telling yourself that this architecture is for teams with a platform group, count the classes again.

How many classes does the messaging layer hold in your current project — and how many of them are business logic? Tell me in the comments.

Explore Ecotone for Tempest

About the author: Dariusz Gafka is a Software Architect and author of the Ecotone Framework. He writes about event sourcing, CQRS, and PHP architecture patterns.

Originally published at blog.ecotone.tech.

Your Legacy PHP Codebase Isn't Hopeless

Dariusz Gafka — Mon, 26 Jan 2026 22:05:16 +0000

You ship a small bug fix. Suddenly, two other features break. Every deployment feels like gambling. The business depends on this app — it brings in revenue, customers use it daily — but nobody feels confident working on it.

You open a file that should be a simple list of functions and find a 2,000‑line monolith of nested loops and if‑statements. Comments like // Temporary fix from years before. Presentation, database queries, and business logic all mixed together in what one developer described as a “glorious spaghetti mashup.”

You're not alone. And your codebase isn't hopeless.

The Industry’s Dirty Secret

~13% of Composer installs still run end‑of‑life PHP versions
~27% are on EOL or security‑only versions
Over 50% of popular PHP packages support unsupported PHP versions

Legacy systems are the norm, not the exception.

The Trap: Rewrite or Suffer

Rewrites have ~23% success rate
Incremental modernization has ~53% success rate
Small changes fail only ~4% of the time

Rewrites discard years of encoded business knowledge.

The Third Path: Incremental Transformation

Instead of rewriting everything:

Identify a painful area
Extract logic into a message handler
Test it in isolation
Make it async if needed
Repeat

This is exactly what Ecotone enables.

Example: The 800‑Line Controller

class OrderController
{
    public function placeOrder(Request $request)
    {
        // validation, persistence, payments, emails, analytics...
    }
}

Step 1: Extract an Event

class OrderWasPlaced
{
    public function __construct(
        public string $orderId,
        public string $customerId,
        public float $total
    ) {}
}

class OrderNotificationHandler
{
    #[EventHandler]
    public function sendConfirmation(OrderWasPlaced $event): void {}
}

Step 2: Publish From Legacy Code

$this->eventBus->publish(new OrderWasPlaced(
    $order->id,
    $customer->id,
    $order->total
));

Step 3: Test in Isolation

class OrderNotificationHandlerTest extends TestCase {}

Step 4: Make It Async

#[Asynchronous('notifications')]
#[EventHandler]
public function sendConfirmation(OrderWasPlaced $event): void {}

Step 5: Repeat

Analytics, loyalty points, reporting — each becomes isolated and testable.

Command Handlers

class PlaceOrder {}
class OrderHandler {}

$this->commandBus->send(new PlaceOrder(...));

Database Queries

interface OrderQueries
{
    #[DbalQuery(...)]
    public function getPendingOrders(string $customerId): array;
}

Resilience & Retries

Retries, DLQs, and error handling are declarative and consistent.

Idempotency

#[Deduplicated('orderId')]
#[CommandHandler]
public function placeOrder(PlaceOrder $command): string {}

Why This Works

System keeps running
Small PRs
Fast tests
Compounding improvements
Attracts senior engineers

Getting Started

composer require ecotone/ecotone

Laravel and Symfony integrations available.

Conclusion

Legacy codebases are not failures — they are assets.
Incremental modernization gives them a future.

Implementing Event-Driven Architecture in PHP

Dariusz Gafka — Fri, 26 Dec 2025 16:42:28 +0000

Traditional service integration moves routing logic outside the application’s code.
Message brokers, cloud messaging services, and stream-processing topologies become the place where business-critical flows are defined.

However, this comes at a cost of making our Endpoints - Dumb.

Dumb Endpoints

We often agree to move routing logic outside the application, because it promises simplicity or speed. It looks simpler because it looks like we no longer need to handle routing ourselves. From a developer’s perspective, we just receive and process a message, while routing happens “somewhere else” — outside the code.

When important logic is pushed outside the application, the code becomes unaware of the integrations it depends on. This makes changes harder to test and verify. It also lowers confidence when making changes, because modifying something outside the application is always riskier than changing code we fully own and can easily cover with tests.

When we follow the dumb endpoints approach, where the application is unaware of routing logic, we eventually end up in a situation where:

Knowledge becomes fragmented — Only a few people truly understand the full setup and configuration that lives outside the applications being integrated.
Testing becomes painful — It is no longer easy to test behavior using automated application-level tests. Changes often require modifying external configurations, where testing and verifying correctness is much harder.
Changes become risky — When changes cannot be easily verified, confidence drops. This slows development and often leads to more bugs and production issues.

The state of the architecture is often accepted as it is, and the problems created by dumb endpoints are pushed onto developers. This often leads to situations where more “control” is introduced to prevent further issues — for example, by adding gatekeepers who must review and approve every change.
Ironically, this all starts with the promise of speed and simplicity, offered as a trade-off for moving integration logic outside the application.

However, we can achieve both speed and simplicity while keeping integrations under the control of the application itself. There is no trade-off required. To do this, we need to follow a different approach — one where endpoints are no longer dumb, but become smart.

Smart Endpoints - Dumb Pipes

This leads us to the Smart Endpoints, Dumb Pipes approach.
It reverses the direction of responsibility — instead of moving logic outward, we move it back inward. Applications are no longer dumb. They become smart and decide where messages should go and where they should be consumed from. In this model, the application itself fully controls the integration.

To achieve smart endpoints we need to build the logic of routing inside our Applications. This means using clear abstractions that allow us to orchestrate message flow within the code, rather than external configurations.

To make this possible, messaging needs to be a first-class citizen in our applications.
The messaging abstraction should provide routing capabilities that we can configure as needed and fully test from within the application. Ideally, this abstraction should be decoupled, meaning we are not forced to implement or extend any framework-specific classes.

Enterprise Integration Patterns is a great book that defines a set of abstractions for building messaging systems at the programming-language level. I brought these patterns to life in the Ecotone Framework for PHP.
In the next section, we will explore how to build integrations between applications using a higher-level abstraction built on top of these patterns — the Service Map.

Service Map

Now that we’ve established that smart endpoints keep routing logic inside the application and provide messaging capabilities directly within the programming language, let’s explore how applications can actually be integrated.
To do this, we will look at one of Ecotone’s features — the Service Map.

Service Map is exactly what it sounds like—a map of integrated applications (services) and the pipes (channels) which they communicate through. Here's how to set it up:

#[ServiceContext]
public function serviceMap(): DistributedServiceMap
{
    return DistributedServiceMap::initialize()
        ->withCommandMapping(
            targetServiceName: "ticketService",
            channelName: "ticket_commands"
        );
}

This configuration says: "When sending Commands to Ticket Service, use ticket_commands channel (pipe)"

The routing is done at the Application level, not the Message Broker level. This means that we control the process from within the codebase we own, and can easily cover that with tests.

This configuration is for sending Commands, for Event we will be using Event Mapping:

#[ServiceContext]
public function serviceMap(): DistributedServiceMap
{
    return DistributedServiceMap::initialize()
        ->withEventMapping(
            channelName: "ticket_events",
            subscriptionKeys: ["user.*"],
        );
}

This configuration says: "When publishing Events, when routing key start with user then ticket_events channel (pipe)"

Event Mapping allows us to publish Events to specific Channel (Pipe) based on subscription keys.

We can of course have multiple subscription to broadcast events to different Services.

Application Code

With the map configured, publishing is straightforward.

Sending side

For Commands, we target a specific service:

public function onUserRegistered(
    string $userId, 
    DistributedBus $distributedBus
): void {
    $distributedBus->convertAndSendCommand(
        targetServiceName: "ticketService",
        routingKey: "ticket.create",
        command: new CreateTicket($userId, "Welcome!")
    );
}

For Events that multiple services might care about, we publish without a target:

$distributedBus->convertAndPublishEvent(
    routingKey: "user.registered",
    event: new UserRegistered($userId)
);

Ecotone makes this part of the API: Commands are sent to a single service, while Events can be delivered to many services.
The Service Map automatically handles routing based on subscription keys.

Receiving side

On the receiving side, we mark handlers as distributed to accept external messages:

#[Distributed]
#[CommandHandler("ticket.create")]
public function createTicket(CreateTicket $command): void
{
    // Create the ticket
}

#[Distributed]
#[EventHandler("user.registered")]
public function onUserRegistered(UserRegistered $event): void
{
    // React to user registration
}

The #[Distributed] attribute makes it explicit that these handlers can receive messages from other services. This clarity prevents accidental breaking changes.

I mentioned earlier that this approach does not require sacrificing speed.
We are not building our own integration infrastructure from scratch — instead, we reuse existing systems.

The key idea is to keep the logic inside the application and treat pipes (channels) as simple transport.
The channel’s only responsibility is to move messages, not to act as the “mastermind” of orchestration.

We have two message channels (pipes): ticket_commands and event_commands.
With the Service Map approach, we can define their implementations in a way that fits our needs, without being tightly coupled to a specific message broker.

This means we can choose — and later switch — the underlying technology if needed.
For example, we might decide to use RabbitMQ or Redis-based channels:

#[ServiceContext]
public function channels()
{
    return [
        // Amazon SQS Message Channel
        SqsBackedMessageChannelBuilder::create("ticket_events"),
        // RabbitMQ Message Channel
        AmqpBackedMessageChannelBuilder::create("ticket_commands"),
    ];
}

Defining Channel is enough for Ecotone to automatically register Message Consumer for us. From that point on, we can start consuming messages right away:

bin/console ecotone:run {ticket_commands/ticket_events}

Streaming Channels

The Service Map works regardless of whether we use queue-based brokers or streaming platforms under the hood.
When using streaming platforms, we gain additional capabilities thanks to their non-destructive nature, which I described in a previous blog post.

In the case of queue-based solutions, we can push messages to each channel as part of the publishing process:

#[ServiceContext]
public function serviceMap(): DistributedServiceMap
{
    return DistributedServiceMap::initialize()
        ->withEventMapping(
            channelName: "ticket_events",
            subscriptionKeys: ["user.*"],
        )
        ->withEventMapping(
            channelName: "order_events",
            subscriptionKeys: ["user.*"],
        );
}

When using Kafka or RabbitMQ streaming channels, we can push messages to a single channel, from which multiple services can consume:

#[ServiceContext]
public function serviceMap(): DistributedServiceMap
{
    return DistributedServiceMap::initialize()
        ->withEventMapping(
            channelName: "user_events",
            subscriptionKeys: ["user.*"],
        );
}

Ecotone provides different Message Channels integrations:

Streaming Channels: Kafka and RabbitMQ
Queue Channels: RabbitMQ, Amazon SQS, Redis, Database Channels, Symfony Messenger, Laravel Queues

Decoupled Data Models

All communication happens through defined routing keys, whether the message is a Command or an Event. This is intentional and helps keep applications decoupled from each other.

As a result, each application can use models that fit its own needs and include only the data that is truly meaningful from an integration perspective.

// Publisher sends this
$distributedBus->convertAndPublishEvent(
    routingKey: "user.billing.changed",
    event: new BillingDetailsChanged($userId, $newAddress)
);

// Consumer can use different model
#[Distributed]
#[EventHandler("user.billing.changed")]
public function handle(UserAddressUpdated $event): void
{
    // Different class, same routing key
}

Whether models are shared or not should be a project-level decision.
Ecotone does not force either approach, allowing teams to choose what works best for their specific context.

Testing Integrations

One of the core ideas I mentioned earlier is making integrations testable at the application level. With Ecotone’s Service Map, we can test integrations using in-memory channels or real integrations, all directly from the application code:

$messaging = EcotoneLite::bootstrapFlowTesting(
    [ServiceMapConfig::class],
    enableAsynchronousProcessing: [
        // Define using which Channel you want to test
        SimpleMessageChannelBuilder::createQueueChannel("ticket_commands"),
    ]
);

$messaging->convertAndSendCommand(
    targetServiceName: "ticketService",
    routingKey: "ticket.create",
    command: new CreateTicket($userId, "Welcome!")
);

// Verify command landed in channel
$message = $messaging->getMessageChannel('ticket_commands')->receive();
$this->assertNotNull($message);

The same way we could test out consumption side of things. It's really easy to test any kind of Service Map and cover that with automated tests to ensure that delivery happens as we expect.

Other Supporting Features

We did cover the core part of integration, however together with that Ecotone provides much more features, that ensures that integrations works as expected. For this you may consider exploring:

Outbox pattern: For transactional consistency
Dead letter queues: For failed message handling
Message priorities: For urgent processing
Scheduled messages: For delayed delivery

For this you may take a look on Ecotone's documentation page.

Summary

Choosing the Smart Endpoints, Dumb Pipes architecture allows us to take full control of the integration process and keep things simple, testable, and easy to verify for everyone.
The goal is to keep integration logic close to where it is actually used. This helps maintain shared knowledge and a clear understanding of how the system behaves as it evolves.

You can read more about about Service Map under this link.

Whatever you choose to use Ecotone to deliver this approach or build it yourself, feel free to join Ecotone's community channel to discuss different approaches and share the experiences.