phpfilebroker

The problem

Most “small” PHP apps need a queue. Most “small” PHP apps don’t deserve RabbitMQ, Kafka, or NATS in their dependency graph. The shared host doesn’t even have them.

phpfilebroker turns the filesystem into a real broker — with everything you’d expect: exchanges, persistent streams, consumer groups, priority queues, dead letters, retries, and metrics.

Architecture

• Pure PHP 8.4. Zero external services.
• Streams are append-only directories. Messages are individual files. Atomic moves give you transactional semantics.
• POSIX file locks + inotify (where available) enable consumer-group fan-out without polling overhead.
• Per-stream priority lanes; visibility timeout configurable per consumer.

Implementation highlights

• DLQ + retries with exponential backoff as first-class primitives, not bolt-on.
• Consumer groups with at-least-once delivery; idempotency hooks sit in the consumer interface.
• Prometheus-compatible metrics endpoint built in — depth, age, retry counters, DLQ size.
• Crash-safe: every transition is a single rename(2), which is atomic on POSIX filesystems.

Results

Drop-in replacement for “we need RabbitMQ but we have shared hosting” kind of pain. Tested under load on a Hetzner VPS pushing thousands of msg/sec.

Lessons

• The filesystem is an underrated database. POSIX semantics give you more than people think.
• “Boring tools” win when the operational surface is small.