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

composer require byfareska/swoole-server-bundle

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

return [
    // ...
    Byfareska\SwooleServer\SwooleServerBundle::class => ['all' => true],
];

Configuration

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

# .env
SWOOLE_SERVER_DSN=swoole://0.0.0.0:8000?workers=4&package_max_length=67108864

# config/packages/byfareska_swoole_server.yaml
byfareska_swoole_server:
    dsn: '%env(SWOOLE_SERVER_DSN)%'

    # optional:
    # kernel_class: App\Kernel   # null = the application kernel class (detected automatically)
    # health_check_path: /healthz # plain-text 200 "ok" answered before the kernel; null = disabled
    hot_reload:
        # enabled: null          # null = enabled only when kernel.debug
        watch_dirs:
            - '%kernel.project_dir%/src'
            - '%kernel.project_dir%/config'
            - '%kernel.project_dir%/templates'
        interval: 1000           # ms between scans
        extensions: [php, twig, yaml]

DSN format

swoole://HOST:PORT?workers=N&<any_swoole_options>

• 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

bin/console byfareska:swoole:server:start
# or with a DSN override:
bin/console byfareska:swoole:server:start --dsn='swoole://127.0.0.1:9501?workers=2'

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:

healthcheck:
    test: ["CMD", "curl", "-fs", "http://localhost:8000/healthz"]

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:

# config/packages/framework.yaml
framework:
    trusted_proxies: '%env(TRUSTED_PROXIES)%'
    trusted_headers: ['x-forwarded-for', 'x-forwarded-proto', 'x-forwarded-host', 'x-forwarded-port']

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:

services:
    app:
        command: bin/console byfareska:swoole:server:start
        restart: unless-stopped

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):

use Byfareska\SwooleServer\Http\ChunkYieldingStreamedResponse;

return new ChunkYieldingStreamedResponse(
    function (): iterable {
        foreach ($events as $event) {
            yield "data: {$event}\n\n";
        }
    },
    headers: ['Content-Type' => 'text/event-stream'],
);

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

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse

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).

use Byfareska\SwooleServer\Reset\WorkerResetterInterface;
use Symfony\Component\HttpKernel\KernelInterface;

final class InMemoryCacheResetter implements WorkerResetterInterface
{
    public function reset(KernelInterface $kernel): void
    {
        // release any per-request state your app accumulates
    }
}

# only needed without autoconfigure or to set a priority explicitly:
services:
    App\Swoole\InMemoryCacheResetter:
        tags:
            - { name: byfareska_swoole_server.worker_resetter, priority: -10 }

Structure

License

Released under the MIT License.

Made with ❤️ in Bydgoszcz 🇵🇱