PHPackages zoclee/flux - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. zoclee/flux ActiveProject zoclee/flux =========== Flux is a pure PHP implementation of a unified message broker with PostgreSQL persistence. v0.1.0-RC3(today)06↑2400%MITPHPPHP ^8.4 Since Aug 24Pushed todayCompare [ Source](https://github.com/Zoclee/flux)[ Packagist](https://packagist.org/packages/zoclee/flux)[ RSS](/packages/zoclee-flux/feed)WikiDiscussions main Synced today READMEChangelogDependencies (1)Versions (4)Used By (0) Flux ==== [](#flux) Flux is a pure PHP implementation of a unified message broker with PostgreSQL persistence. Flux is currently at an MVP release-candidate stopping point. The first supported protocol adapter is AMQP 0-9-1, backed by the protocol-neutral Broker core and PostgreSQL persistence. MVP Capabilities ---------------- [](#mvp-capabilities) - PostgreSQL-backed persistence - `flux` CLI migrations and administrative diagnostics - AMQP 0-9-1 connection/channel handshake - queue declare/delete/purge - default exchange - direct exchange declare/delete - fanout exchange declare/delete - topic exchange declare/delete - queue bind/unbind - `basic.publish` - `basic.consume` - `basic.get` - `basic.ack`, `basic.reject`, and `basic.nack` - `basic.qos` prefetch-count enforcement - minimal individual publisher confirms - heartbeats and disconnect cleanup - plaintext AMQP listener - TLS AMQP listener - username/password authentication - per-vhost `configure`, `write`, and `read` authorization - retry and dead-letter handling - resource limits and overload protection - graceful bounded draining/shutdown - local runtime diagnostics plus CLI health/readiness checks Known Limitations ----------------- [](#known-limitations) - no clustering or replication - no MQTT or Kafka adapters yet - no headers exchanges - no AMQP transactions - no mandatory returns or alternate exchanges - no management UI or HTTP health endpoints - no Prometheus/OpenTelemetry metrics subsystem - no systemd, Docker, or process-supervisor packaging - no mutual TLS or certificate-based user authentication - no rolling restart or zero-downtime upgrade workflow Requirements ------------ [](#requirements) - PHP 8.4 or newer - PHP extensions: `pdo`, `pdo_pgsql`, and `openssl` - Composer - PostgreSQL for integration tests and persistence work Installation ------------ [](#installation) From a source checkout: ``` composer install ``` After the first public package is published, install the Composer binary with: ``` composer global require zoclee/flux ``` CLI --- [](#cli) The repository command entry point is `flux` at the project root: ``` php flux php flux help php flux --version php flux db:status php flux migrate php flux health php flux readiness php flux server:start php flux connection:list php flux consumer:list php flux broker:stats php flux user:list-vhosts test_user php flux vhost:create /development php flux vhost:list php flux queue:list php flux queue:show orders php flux binding:list php flux subscription:list php flux message:peek orders ``` The intended Composer-installed command format is: ``` flux ``` Queue, binding, subscription, and message commands are administrative inspection commands over persisted state. `php flux health` checks whether the local runtime diagnostics endpoint is reachable and currently running. `php flux readiness` additionally checks that Flux is ready to accept broker traffic, including runtime state, listener status, database connectivity, and migration status. Broker API ---------- [](#broker-api) Flux now exposes publishing through the protocol-neutral `Flux\Broker\Broker` service. It also has a foreground, long-running protocol-neutral runtime that can host future protocol adapters: ``` Protocol adapters | Broker Runtime | Broker | Persistence orchestration | PostgreSQL ``` The Broker API accepts broker-facing concepts such as virtual-host name, routing source, routing key, payload bytes, headers, and message metadata. It now owns the protocol-neutral broker operation boundary for `publish`, `reserve`, `acknowledge`, `reject`, and `release`. Future protocol adapters and broker-operation commands should use this boundary rather than constructing PostgreSQL repositories directly. The runtime can be started with: ``` php flux server:start ``` It verifies PostgreSQL connectivity, starts the in-memory runtime registries, starts enabled AMQP listeners and local diagnostics, and remains in the foreground until shutdown. The plaintext AMQP listener defaults to `127.0.0.1:5672` and can be configured with: ``` FLUX_AMQP_ENABLED FLUX_AMQP_HOST FLUX_AMQP_PORT FLUX_AMQP_HEARTBEAT ``` The TLS AMQP listener is disabled by default and can be configured with: ``` FLUX_AMQP_TLS_ENABLED FLUX_AMQP_TLS_HOST FLUX_AMQP_TLS_PORT FLUX_AMQP_TLS_CERT FLUX_AMQP_TLS_KEY FLUX_AMQP_TLS_CA ``` `FLUX_AMQP_HEARTBEAT` defaults to `60` seconds. Set it to `0` to disable heartbeat negotiation and timeout cleanup. Runtime diagnostics are exposed through a small read-only local socket used by `health`, `readiness`, `connection:list`, `consumer:list`, and `broker:stats`. It defaults to `127.0.0.1:5673` and does not expose credentials, message payloads, or mutation commands. Authentication uses persisted username/password credentials. Users must be granted access to virtual hosts with `php flux user:grant-vhost `; inspect those grants with `php flux user:list-vhosts `. Authorization uses separate persisted per-vhost `configure`, `write`, and `read` regex permissions. Resource limits and graceful shutdown can be configured with: ``` FLUX_MAX_CONNECTIONS FLUX_MAX_CHANNELS_PER_CONNECTION FLUX_MAX_CONSUMERS_PER_CONNECTION FLUX_MAX_CONSUMERS_PER_CHANNEL FLUX_AMQP_MAX_FRAME_SIZE FLUX_MAX_MESSAGE_SIZE FLUX_MAX_QUEUES_PER_VHOST FLUX_MAX_QUEUE_DEPTH FLUX_SHUTDOWN_DRAIN_TIMEOUT ``` ### Database Migrations [](#database-migrations) Flux verifies PostgreSQL connectivity and reports migration status without applying migrations with: ``` php flux db:status ``` Flux applies PostgreSQL migrations with: ``` php flux migrate ``` After Composer installation, the equivalent command is `flux migrate`. Database configuration is read from normal environment variables: ``` FLUX_DB_HOST FLUX_DB_PORT FLUX_DB_NAME FLUX_DB_USER FLUX_DB_PASSWORD ``` The current defaults are defined in `config/flux.php`. For local development, Flux also loads a `.env` file from the project root before reading configuration: ``` FLUX_DB_HOST=127.0.0.1 FLUX_DB_PORT=5432 FLUX_DB_NAME=flux FLUX_DB_USER=flux FLUX_DB_PASSWORD= ``` Values already present in the process environment take precedence over `.env`. MVP Smoke Test -------------- [](#mvp-smoke-test) See `docs/mvp-smoke-test.md` for a short manual smoke-test path that covers installation, migrations, user/vhost permissions, runtime startup, health/readiness, and a minimal AMQP publish/consume flow. Tests ----- [](#tests) ``` composer test ``` Unit tests live in `tests/Unit/`. Integration tests live in `tests/Integration/` and use a real PostgreSQL test database when `FLUX_TEST_DATABASE_URL` is set. Example: ``` FLUX_TEST_DATABASE_URL="pgsql:host=127.0.0.1;port=5432;dbname=flux_test;user=flux;password=secret" composer test ``` PostgreSQL Persistence Model ---------------------------- [](#postgresql-persistence-model) The initial schema lives in plain SQL migrations under `database/migrations/`. It establishes the Phase 1 persistence foundation only: Migration filenames use `yyyymmdd_hhmmss_description.sql` so lexical order is execution order. If multiple migrations are created at the same time, increment the timestamp by one second for each subsequent file. Migrations must be idempotent and safe to apply more than once. ``` virtual_hosts | +-- destinations | | | +-- bindings | | | +-- message_routes | | | +-- deliveries | +-- subscriptions messages | +-- message_routes ``` Flux uses `destinations` instead of making queues the fundamental abstraction so the core schema stays protocol-neutral. A queue is the first supported destination type, but future protocol adapters should not force MQTT topics, Kafka topics, or AMQP exchanges into queue-specific tables. `messages` store payload bytes and message metadata once. `message_routes` associate one stored payload with one or more destinations, allowing fan-out without duplicating binary payload data. `deliveries` are separate because reservation, acknowledgement, rejection, retries, and attempts have their own lifecycle independent of message storage. Live consumers, TCP connections, channels, sockets, and runtime statistics are not persisted. Durable consumption relationships are represented by `subscriptions`; active consumers remain runtime concepts for later broker phases. Directory Structure ------------------- [](#directory-structure) - `flux` - project-root CLI entry point - `config/` - Flux configuration - `database/migrations/` - PostgreSQL schema migrations - `src/Broker/` - protocol-neutral broker core - `src/Console/` - CLI application commands - `src/Persistence/` - persistence abstractions and implementations - `src/Persistence/Postgres/` - PostgreSQL persistence implementation - `src/Protocol/` - protocol adapters - `src/Protocol/Amqp/` - AMQP 0-9-1 adapter - `src/Support/` - small shared infrastructure - `tests/` - unit, integration, and fixture files - `var/` - runtime logs and process files ### Health Score 39 — LowBetter than 84% of packages Maintenance100 Actively maintained with recent releases Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 0d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/a6e41f37b5618ebeafa7bec8a6afea5a20c6048ab016edcd09172934c68fcee3?d=identicon)[info@zoclee.com](/maintainers/info@zoclee.com) --- Top Contributors [![alwyn1024](https://avatars.githubusercontent.com/u/2869280?v=4)](https://github.com/alwyn1024 "alwyn1024 (64 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/zoclee-flux/health.svg) ``` [![Health](https://phpackages.com/badges/zoclee-flux/health.svg)](https://phpackages.com/packages/zoclee-flux) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)