Download the PHP package smwks/superprocess without Composer

SuperProcess

+--------------------------------+
|                                |
|  >> SuperProcess               |
|                                |
|  [master] --+--> [worker]      |
|             +--> [worker]      |
|             +--> [worker]      |
|                                |
|  fork · supervise · scale      |
+--------------------------------+

A fluent PHP library for supervised master-child process control using pcntl and pipes. Run one or more copies of a command or PHP closure, keep them alive automatically, communicate with them via stdin/stdout and a structured IPC channel, and scale the pool up or down at runtime.

Two features define SuperProcess:

• Closures fork. Pass closure() any PHP closure and it becomes an independent OS process — no serialisation boilerplate, no separate file. The closure runs in a pcntl_fork() copy of the master, with a socket wired back for structured IPC.

• The heartbeat drives the pool. Register a periodic callback that fires on the master process. Inside it you have full control: query a database, read a queue depth, inspect a config value — then call scaleUp() or scaleDown() to match worker supply to real-time demand.

Requires PHP 8.4+, ext-pcntl, ext-posix — Linux and macOS only.

Installation

Quick start

Supervise a pool of command workers:

Fork a closure as a worker process:

Drive pool size from an external source via heartbeat:

Concepts

Command children

command(string $cmd) runs an external process for each child slot. The command is started with proc_open(), so it inherits PATH and environment variables. Each child gets four file descriptors:

All pipes are non-blocking; reads happen inside the event loop via stream_select().

Closure children

closure(Closure $fn) forks the master with pcntl_fork() and runs the closure in the child. The closure receives a socket resource as its only argument — write JSON lines to it to send structured messages to the master via onChildMessage().

The closure captures its surrounding scope at the moment run() is called — that is when the fork actually happens. Any variable in scope at that point is available inside the child. Because the fork copies the master's entire memory image, expensive one-time work (bootstrapping a framework, parsing config, establishing a schema) is paid once in the master and shared copy-on-write across every worker.

Child lifecycle

On startup run() spawns min children. When a child exits:

1. onChildExit fires with an ExitReason.
2. If running count drops below min, a replacement is spawned with CreateReason::Replacement.

The master never exits the event loop on its own — send it SIGTERM or SIGINT (or call signal(posix_getpid(), ProcessSignal::Stop) from within a callback) to trigger a graceful shutdown.

Heartbeat

heartbeat(int $intervalSeconds, Closure $fn) registers a callback that fires on the master process at a regular interval throughout the event loop. The callback receives the live SuperProcess instance, giving it full runtime control.

This is the primary mechanism for externally-driven pool management. Instead of sizing the pool statically at startup, query whatever source of truth you have — a queue depth, a database flag, a config value — and nudge the pool toward the right size:

Because the heartbeat runs on the master — the process that owns the event loop — it is single-threaded and safe to call without locks. scaleUp() and scaleDown() each step by one and are no-ops when the pool is already at the configured limit.

Graceful shutdown

On SIGTERM or SIGINT (Ctrl+C) the master:

1. Runs the onShutdown callback, if registered, while all children are still alive.
2. Sends SIGTERM to every child.
3. Waits up to 5 seconds for each to exit.
4. Sends SIGKILL to any that remain.

The onShutdown callback is the right place to flush state, close connections, or send a final message to children before they are signalled:

API reference

Configuration

Callbacks

Runtime control

Enums and constants

Child properties

Sending structured messages from a command child

Write newline-delimited JSON to file descriptor 3. The master delivers each parsed line to onChildMessage.

Signals

Development

SuperProcess is open-sourced under the MIT license.