Download the PHP package byfareska/swoole-server-bundle without Composer

byfareska/swoole-server-bundle

A long-running Swoole HTTP server for Symfony 8+ applications (PHP 8.5+).

Works like PHP-FPM: each worker is a separate process with its own Symfony kernel and handles one request at a time (enable_coroutine=false). Concurrency comes from the number of workers. Coroutines are disabled on purpose — a worker has a single kernel, i.e. one Doctrine connection and one identity map, so overlapping requests would share state (e.g. the PDO error "Cannot execute queries while other unbuffered queries are active").

Requirements

• PHP >= 8.5 with the swoole extension
• Symfony >= 8.0

Installation

Registration in config/bundles.php (without Flex):

Configuration

The whole server is configured with a single DSN — preferably from an env var:

DSN format

• workers — number of workers; 0 or absent = swoole_cpu_num() (worker_num is rejected with a hint — use workers)
• every other query parameter goes 1:1 to $server->set() — e.g. package_max_length=134217728, log_level=warning (level names are mapped to the SWOOLE_LOG_* constants), http_compression=true
• true/false/on/off values are cast to bool, numbers to int

Default server settings (overridable via the DSN):

Usage

Health check

Set health_check_path (e.g. /healthz) to get a plain-text 200 ok answered directly by the server, before the kernel — it reports liveness of the server process and responds even while workers are still booting. Handy for docker/k8s health checks:

Metrics (Prometheus)

Long-running workers never get recycled (max_request=0), so a slow leak grows silently until the OOM killer restarts the process — and with N workers you cannot tell "one worker leaks" from "all of them grow" without per-process numbers. Enable metrics to get a Prometheus text endpoint answered directly by the server, before the kernel (like the health check):

How it works: every worker samples itself every sample_interval ms into a Swoole\Table (shared memory allocated by the master before the fork — no IPC), and whichever worker receives the scrape renders the whole table plus the server-wide counters. A worker that stops updating its row is stuck or dead — its last_sample_timestamp goes stale. The table outlives worker processes, which is what makes worker_restarts_total possible: a worker id whose row already exists on workerStart was re-forked (OOM kill, fatal error, recycling).

Label cardinality is fixed (worker_id ∈ 0..N-1), so the series count does not grow with traffic. The endpoint has no authentication: expose the server port to your monitoring network only and do not route the path through the public reverse proxy. Scrape example:

Useful alerts: worker_memory_rss_bytes / php_memory_limit_bytes > 0.7, increase(worker_restarts_total[15m]) > 0, predict_linear(worker_memory_rss_bytes[2h], 6*3600) > php_memory_limit_bytes.

Behind a reverse proxy (trusted proxies)

The bridge builds the Request from raw Swoole data, so behind nginx/traefik the standard Symfony rules apply: without configured trusted proxies, Request::getClientIp() returns the proxy's IP and isSecure() is false even for TLS-terminated traffic. Configure it as usual:

Hot-reload (dev)

In debug mode a watcher (mtime polling — works also on Docker Desktop/macOS volumes, where inotify does not receive events from the host) scans watch_dirs and on any change stops the whole server ($server->stop()) — docker's/supervisor's restart policy brings up a fresh process, so the code is guaranteed to come up new. A graceful $server->reload() is deliberately not used: with 1 worker it does not work at all (ERRNO 507), and in debug a re-forked worker serves the old code anyway (class definitions sit in the master's memory after the DI container compilation).

Example for docker-compose:

Streaming (SSE / chunks)

A regular StreamedResponse with a callback returning a generator is supported. For full control over the chunks use ChunkYieldingStreamedResponse (or implement ChunkYieldingResponseInterface in your own response class):

The emitter reads chunks straight from the response (not through the callback), because HttpKernel wraps the callback with a wrapper that loses the returned generator.

A callback that echoes its output instead of returning an iterable (the classic FPM style) also works — the emitter captures the echo with an output buffer and rewrites it onto $res->write(). This is a fallback path: it costs an extra memory copy per chunk, loses logical chunk boundaries and logs a warning — prefer returning an iterable or ChunkYieldingResponseInterface.

File downloads

BinaryFileResponse is sent with Swoole's zero-copy sendfile() — the file never passes through PHP memory, so output_buffer_size does not apply to downloads. Range requests (206 Partial Content), X-Sendfile/ X-Accel-Redirect delegation, HEAD requests and deleteFileAfterSend() keep their standard Symfony semantics; responses backed by an in-memory SplTempFileObject fall back to a streamed copy.

What the bundle does for you

• State reset after every request — the manual Swoole bridge does not go through symfony/runtime, so the bundle calls services_resetter itself (the equivalent of $kernel->reset()); without it Doctrine accumulates entities in the identity map (memory leak + "MySQL gone away"), and the token storage / profiler leak state between requests. In debug it additionally wipes the FormDataCollector buffers that its reset() does not clean up.
• Exceptions outside the kernel — a failure of the bridge itself gets a 500 page (HtmlErrorRenderer), a log entry on stderr and a manually collected profile, so the request is visible in the profiler. The response format is replaceable: alias Byfareska\SwooleServer\ErrorHandler\ExceptionResponseFactoryInterface to your own service (or decorate the default one), e.g. to return JSON for an API.
• Response::prepare() before emission — the same fixups the FPM front controller does (HEAD responses without a body, Content-Length/charset, protocol version).
• APP_RUNTIME_MODE=web=1&worker=1 — the kernel does not wrongly detect console mode despite the "cli" SAPI.
• Clean worker teardown — on worker stop/recycling the kernel is shut down ($kernel->shutdown()), flushing logs and closing connections.
• Unhandled-exception logging — through the PSR-3 logger (monolog channel swoole_server) when available, with a raw-stderr fallback otherwise.

Extension points

Flex recipe

The repository ships a recipe under recipe/ (bundle registration, the config/packages/byfareska_swoole_server.yaml file and the SWOOLE_SERVER_DSN env entry). To have composer require apply it automatically, publish it on a private recipes endpoint (e.g. symfony/recipes-checker fork or a private Flex server) under byfareska/swoole-server-bundle/<version>/. Without Flex, follow the manual installation steps above.

Tests

The suite runs without ext-swoole — tests/Stub/ ships minimal stand-ins for Swoole\Http\Request/Response and the SWOOLE_LOG_* constants; with the extension loaded the real classes win. Static analysis runs at PHPStan level: max (Swoole symbols come from swoole/ide-helper).

Custom worker resetters

Prefer Symfony's standard mechanism first: implement Symfony\Contracts\Service\ResetInterface on the service that holds per-request state (autoconfiguration tags it with kernel.reset). The bundle runs services_resetter after every request, so such services are reset automatically — and the same code keeps working under FPM, in tests and with any other runtime.

Byfareska\SwooleServer\Reset\WorkerResetterInterface is an escape hatch for the cases ResetInterface cannot cover — e.g. state living outside the container (globals, static caches) or a reset that needs the kernel itself. Implement it and register the class as a regular service — autoconfiguration tags it with byfareska_swoole_server.worker_resetter and the bundle calls it after every request. Use the tag's priority to control ordering (higher runs first; the built-in services_resetter bridge runs at priority 100).

Structure

License

Released under the MIT License.

Made with ❤️ in Bydgoszcz 🇵🇱