Multi-node Broker
By default php-via keeps all state in a single worker process. That's correct for most deployments:
OpenSwoole handles thousands of concurrent SSE connections comfortably in one worker.
When you need multiple workers on the same machine (CPU parallelism) or multiple servers,
a broker fans out broadcast() calls so every worker can react
to changes that happened on any other worker.
The broker carries broadcasts only. Passing an action or a download to the worker that holds the tab goes through OpenSwoole's worker pipe, whichever broker is set, and it stays within one server.
When do you need a broker?
| Scenario | Broker | External dep? |
|---|---|---|
| Single worker (default) | InMemoryBroker, without a withBroker() call | None |
| Multiple workers, same machine | SwooleBroker, without a withBroker() call | None |
| Multiple servers / containers | RedisBroker or NatsBroker | Redis / NATS |
TAB scope is always fully isolated per-connection: no broker ever carries TAB broadcasts.
A worker publishes a scope at most once per broadcast flush, however often it was broadcast in between, and the messages a worker receives between two of its flushes share one re-render. See Broadcasting → When the update is sent.
InMemoryBroker (default with one worker)
No configuration needed. It is the broker of a single worker: it publishes nothing and costs nothing.
Passing it to withBroker() together with withWorkerNum() above 1 makes
start() throw a \RuntimeException, since the other workers would never hear
a broadcast.
// These are equivalent with one worker
$config = new Config();
$config = (new Config())->withBroker(new InMemoryBroker());SwooleBroker (default with several workers)
Uses OpenSwoole's built-in inter-worker pipe (Server::sendMessage /
onPipeMessage) to fan out scope invalidations across all worker processes on
the same machine. No external infrastructure required. With
withWorkerNum() above 1 and no withBroker() call, php-via uses it by itself.
GlobalState is backed by OpenSwoole\Table, shared memory that is
allocated in the master process and mmap'd into every worker on fork.
use Mbolli\PhpVia\Broker\SwooleBroker;
$config = (new Config())
->withWorkerNum(\OpenSwoole\Util::getCPUNum()); // SwooleBroker by default
// The same, spelled out:
$config = (new Config())
->withWorkerNum(\OpenSwoole\Util::getCPUNum())
->withBroker(new SwooleBroker());No sticky routing needed. Every worker sits behind the same port, so a load balancer cannot pick one anyway. A tab lives on the worker that holds its stream, and an action or a download that lands on another worker is passed there. Scoped signal values, GlobalState, session data and the client list are shared; PHP statics stay per worker, and server-owned TAB signals start over when a tab's stream reconnects after the worker that held it stopped. See Deployment → Same machine for the details and for the atomic update methods.
Limits (configurable). GlobalState is backed by an
OpenSwoole\Table with a fixed capacity allocated at startup:
1 024 keys × 32 KB per value by default, keys up to 63 characters. Increase with
Config::withGlobalStateTableSize(int $maxRows, int $maxValueBytes). The row count is a
floor, not a ceiling. An \OverflowException is thrown when a value exceeds the configured
size or the table is full.
RedisBroker
Uses Redis pub/sub to relay scope invalidations across nodes. Requires the
ext-redis PHP extension and the coroutine hook for its connection:
SWOOLE_HOOK_TCP, SWOOLE_HOOK_TLS with tls: true, or
SWOOLE_HOOK_UNIX for a socket path. php-via's default hook_flags include
all three, and start() throws if flags set with withSwooleSettings()
leave out the one the broker needs, since every Redis call would then block the worker. See
Coroutine hooks. The broker opens two coroutine connections
per worker: one for publish, one for the subscribe loop.
Basic setup
use Mbolli\PhpVia\Broker\RedisBroker;
$config->withBroker(new RedisBroker('127.0.0.1', 6379));Authentication
Pass $password for requirepass setups, or both
$password and $username for Redis 6+ ACL users. Keep credentials
out of source code: use environment variables or a secrets manager.
// requirepass (Redis default auth)
$config->withBroker(new RedisBroker(
host: 'redis.internal',
password: $_ENV['REDIS_PASSWORD'],
));
// ACL user (Redis 6+)
$config->withBroker(new RedisBroker(
host: 'redis.internal',
password: $_ENV['REDIS_PASSWORD'],
username: 'php-via',
));
The minimal ACL permissions required are +subscribe +publish +ping &via:broadcast
(or whichever channel name you configure).
TLS
// TLS: verify against system CA bundle
$config->withBroker(new RedisBroker(
host: 'redis.internal',
port: 6380,
password: $_ENV['REDIS_PASSWORD'],
tls: true,
));
// TLS with a custom CA (self-signed or internal PKI)
$config->withBroker(new RedisBroker(
host: 'redis.internal',
port: 6380,
password: $_ENV['REDIS_PASSWORD'],
tls: true,
tlsCaFile: '/etc/ssl/my-ca.pem',
));Custom channel
If multiple apps share the same Redis instance, give each app a distinct channel so their broadcast traffic doesn't cross-contaminate:
$config->withBroker(new RedisBroker(channel: 'myapp:broadcast'));Full constructor signature
new RedisBroker(
string $host = '127.0.0.1',
int $port = 6379,
?string $password = null, // #[SensitiveParameter]
?string $username = null,
string $channel = 'via:broadcast',
bool $tls = false,
?string $tlsCaFile = null,
)NatsBroker
Uses a raw OpenSwoole coroutine TCP socket with the minimal NATS protocol: no extra PHP extension required beyond OpenSwoole itself. Good choice for containerised deployments where NATS already runs for other services.
Basic setup
use Mbolli\PhpVia\Broker\NatsBroker;
$config->withBroker(new NatsBroker('127.0.0.1', 4222));Token authentication
$config->withBroker(new NatsBroker(
host: 'nats.internal',
authToken: $_ENV['NATS_TOKEN'],
));TLS
// TLS: verify against system CA bundle (port 4243 is the TLS convention)
$config->withBroker(new NatsBroker(host: 'nats.internal', port: 4243, tls: true));
// TLS + custom CA + token
$config->withBroker(new NatsBroker(
host: 'nats.internal',
port: 4243,
authToken: $_ENV['NATS_TOKEN'],
tls: true,
tlsCaFile: '/etc/ssl/my-ca.pem',
));Custom subject
$config->withBroker(new NatsBroker(subject: 'myapp.broadcast'));Full constructor signature
new NatsBroker(
string $host = '127.0.0.1',
int $port = 4222,
?string $authToken = null, // #[SensitiveParameter]
string $subject = 'via.broadcast',
bool $tls = false,
?string $tlsCaFile = null,
)Error observability
Both Redis and NATS brokers reconnect automatically with exponential backoff (1 s → 30 s cap).
Register an error handler to receive a \Throwable on every connection drop:
$config->onBrokerError(function (\Throwable $e): void {
// Safe summary only: do NOT log $e->getMessage() verbatim if it may
// contain connection strings or credentials (OWASP: sensitive data exposure).
error_log('[broker] connection lost: ' . get_class($e));
$metrics->increment('broker.error');
});
The handler fires for every reconnect attempt. When the broker is in the backoff window,
isConnected() returns false and the /_health endpoint
reports "status":"degraded".
Health endpoint
Every php-via server exposes GET /_health, no configuration needed, no devMode
gate. Use it with your load balancer, Kubernetes liveness probes, or uptime monitors:
curl https://myapp.example.com/_health{
"status": "ok",
"version": "0.14.2",
"broker": {
"driver": "RedisBroker",
"connected": true
},
"connections": {
"contexts": 42,
"sse": 38
}
}
HTTP 200 when the broker is connected. HTTP 503 when the
broker is in the reconnect window ("status":"degraded"). The response contains
no IP addresses, credentials, or per-user data. connections counts the contexts and
open streams of the worker that answered, not of the whole server. version is
Via::VERSION.
Example Caddy health check to remove a degraded node from rotation:
reverse_proxy node1:3000 node2:3000 {
health_uri /_health
health_interval 5s
health_timeout 2s
health_status 200
}Upgrading nodes that share a broker
A broker message names a scope, and the form of some scopes can change between releases: in 0.14 a session's scope became a hash of its id. Upgrade every node that shares a broker together, so all of them name a scope the same way.
Connection count
Each php-via worker process opens its own connection(s) to the broker backend.
| Broker | Connections per worker |
|---|---|
InMemoryBroker | 0 |
SwooleBroker | 0 (in-process pipes) |
RedisBroker | 2 (publish + subscribe) |
NatsBroker | 1 |
Plan your Redis/NATS maxclients / connection limits accordingly.
With withWorkerNum(N), multiply the per-worker count by N.
Next steps
- Broadcasting: the broadcast() API and scope targets
- Scopes: which scopes cross node boundaries
- Deployment: systemd, Caddy, TLS setup