Download the PHP package chubbyphp/chubbyphp-swoole-request-handler without Composer

chubbyphp-swoole-request-handler

Description

A request handler adapter for swoole, using PSR-7, PSR-15 and PSR-17.

It turns a swoole HTTP Server into a runtime for any PSR-15 request handler: each incoming swoole request is converted into a PSR-7 server request through PSR-17 factories, handed to your application, and the returned PSR-7 response is sent back through the swoole response.

Because swoole is a long-running process, your application is bootstrapped once per worker process and then serves many requests. This removes the per-request bootstrap cost of a classic PHP-FPM setup.

Requirements

• php: ^8.3

Suggest

Any PSR-7 / PSR-17 implementation can be used, for example:

• guzzlehttp/psr7 (with http-interop/http-factory-guzzle)
• laminas/laminas-diactoros
• nyholm/psr7
• slim/psr7
• sunrise/http-message

Installation

Through Composer as chubbyphp/chubbyphp-swoole-request-handler.

The examples below use slim/psr7 as the PSR-7 / PSR-17 implementation:

Usage

Basic server

Create a server.php and start it with php server.php:

Components

The package consists of three small, replaceable parts. Each one has an interface, so you can swap in your own implementation where the defaults don't fit.

PsrRequestFactory maps the following data:

• method, URI and all headers
• cookies, query params and the parsed body (form data)
• uploaded files, including nested ones (as UploadedFileInterface instances)
• the raw body, written to the request body stream
• server params from swoole's server array, with upper-cased keys (REQUEST_METHOD, REMOTE_ADDR, ...)

SwooleResponseEmitter maps the following data:

• status code and reason phrase
• all headers, with Set-Cookie headers translated to swoole cookies (including SameSite)
• the body, streamed in chunks of 128 KiB by default; pass another chunk size to the constructor to change it

Long-running process caveats

Swoole keeps the PHP process alive between requests, which differs from PHP-FPM:

• Superglobals like $_GET, $_POST, $_SERVER or $_COOKIE are not populated. Read everything from the PSR-7 request instead.
• Anything you keep in static properties or in long-lived services persists across requests. Avoid request specific state in shared objects, or reset it per request.
• REMOTE_ADDR is the address of the direct peer. If you run behind a reverse proxy, use a middleware such as chubbyphp/chubbyphp-trusted-proxy to resolve the client IP from headers.

With Blackfire

BlackfireOnRequestAdapter wraps an OnRequestInterface and profiles a request whenever the X-Blackfire-Query header is present, for example when triggered by the Blackfire browser extension or the blackfire curl command. Requests without that header pass through untouched. The probe is always ended, even if the wrapped handler throws.

Requires the blackfire extension and the blackfire/php-sdk package.

With New Relic

NewRelicOnRequestAdapter wraps an OnRequestInterface and starts a New Relic transaction for every request. The transaction is always ended, even if the wrapped handler throws, so each request is reported separately instead of as one endless transaction per worker process.

Requires the newrelic extension.

Both adapters implement OnRequestInterface, so they can be combined by nesting them.

Copyright

2026 Dominik Zogg