freyr / message-broker
Standalone messaging library: transactional outbox, deduplication, per-transport producers and consumers (AMQP) with retries, DLQ and replay
Requires
- php: >=8.4
- ext-mbstring: *
- ext-pdo: *
- ext-pdo_pgsql: *
- psr/log: ^3.0
- symfony/clock: ^8.1
- symfony/console: ^7.4|^8.1
- symfony/uid: ^7.4|^8.1
Requires (Dev)
- deptrac/deptrac: ^4.7
- infection/infection: ^0.35.11
- php-amqplib/php-amqplib: ^3.7.2
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^13.4
- symplify/easy-coding-standard: ^13.3
Suggests
- php-amqplib/php-amqplib: Required for the AMQP transport
- phpunit/phpunit: Required for Freyr\MessageBroker\Testing\*, the test kit of contract test cases and fakes
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.7.1
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.0
- dev-docs/split-by-package
- dev-build/split-rehearsal
- dev-test/test-kit
- dev-ci/deptrac
- dev-ci/packagist-release
- dev-refactor/package-folders
- dev-refactor/consumer-split
- dev-refactor/relay-port
- dev-refactor/storage-ports
- dev-feat/retention-keeps-unpublished
- dev-ci/php-8.5
- dev-ci/release-actions-v2
This package is auto-updated.
Last update: 2026-11-15 22:26:24 UTC
README
Standalone PHP messaging library: transactional outbox on a partitioned PostgreSQL table, consumer-side deduplication and dead-lettering with replay, and an AMQP producer and consumer. Messages are JSON. Plain PDO storage on PostgreSQL, no framework coupling.
What it is
True exactly-once processing is rare and genuinely hard to build in PHP — it normally means hand-rolling a transactional outbox, consumer-side deduplication, and dead-lettering for every project. Freyr Message Broker packages that machinery as a reusable library: produce inside your database transaction, and the message reaches its transport with at-least-once delivery + consumer-side deduplication — exactly-once processing — with poison messages dead-lettered and replayable.
It runs over AMQP (RabbitMQ) so you adopt it within your existing infrastructure instead of standing up a new broker: competing-consumer queues, routed by message name. It gives no ordering guarantee: rows publish in any order, and consumers must be order-insensitive.
Status: 0.x. No stable release yet; every API may change between minor versions. A minor release (0.x.0) holds a major change and can break code. A patch release (0.x.y) holds smaller improvements and fixes.
Packages
The library has three packages. Today, one Composer package
(freyr/message-broker) holds all three. Separate Composer packages and
separate repositories are planned. Each package has its own folder of
documents, so that the documents move with the code.
| Package | Folder in this repo | What it holds | Documents |
|---|---|---|---|
Core (freyr/message-broker) |
src/broker/ |
The ports, the relay loop, the delivery processor, retry and dead letters, the wire format, the console commands and the test kit. | docs/core/ |
PostgreSQL adapter (freyr/message-broker-postgresql) |
src/adapter/postgresql/ |
The outbox, deduplication and dead-letter stores, the transaction, the schema installer and the outbox retention. | docs/postgresql/ |
AMQP adapter (freyr/message-broker-amqp) |
src/adapter/amqp/ |
The AMQP publisher and consumer, the wait-queue retry and the config classes. | docs/amqp/ |
The manifest and the README of each future package are in packages/<name>/.
Install
composer require freyr/message-broker
This installs the code of all three packages. It replaces freyr/message-broker-postgresql and freyr/message-broker-amqp.
Requires PHP 8.4 or 8.5 (tested in CI on both), ext-pdo_pgsql, and PostgreSQL 14+. Install the pieces you use:
| Need | Add |
|---|---|
| AMQP transport | composer require php-amqplib/php-amqplib |
| Graceful shutdown | ext-pcntl (relay/consumer SIGTERM handling) |
Quickstart
Define a message, produce it inside your own database transaction, run the schema setup, relay it over AMQP, and consume it with deduplication and retry — five steps, one lane, end to end. See docs/QUICKSTART.md for a runnable produce → relay → consume example.
The lane concept
One outbox table holds every produced message; each row is tagged with a
lane, a named drain of that table. Lanes isolate workloads from each other.
Any number of identical relay workers drain one lane in parallel; scale by
adding workers to the lane. The relay marks rows published and never deletes
them. The command message-broker:outbox:maintain drops daily partitions
after the retention period (default 7 days). A partition with unpublished rows is kept, and the command exits non-zero, unless --drop-unpublished is set — see docs/core/RELAY.md and
docs/postgresql/RETENTION.md.
Documentation
- Quickstart — produce → relay → consume, end to end (uses all three packages)
Core (docs/core/):
- Relay and lanes — lanes, the relay loop, failure handling, backoff
- Delivery processor and retry — the exactly-once algorithm, the retry policy
- Ports — the ports and the classes that implement them
- CLI Reference — every shipped console command
- DLQ Operations — inspecting, replaying, and purging dead letters
- Production — deployment, graceful shutdown, observability, scaling
- Testing — contract test cases for adapter authors, in-memory fakes for applications
PostgreSQL adapter (docs/postgresql/):
- Storage — the tables, the schema setup, the classes and their wiring
- Retention — outbox partitions,
outbox:maintain, pg_partman - Connection pooling — pgbouncer
AMQP adapter (docs/amqp/):
- Transport — routing, config classes, the dedicated channel, the publisher, the topology
- Consumer — the consumer, the TTL wait queues, the dead-letter exchange
License
MIT