chubbyphp-workerman-request-handler

Description

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

It turns a workerman HTTP Worker into a runtime for any PSR-15 request handler: each incoming workerman 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 over the workerman connection.

Because workerman 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
• psr/http-factory: ^1.1
• psr/http-message: ^1.1|^2.0
• psr/http-server-handler: ^1.0.2
• psr/log: ^2.0|^3.0.2
• workerman/workerman: ^5.2.2

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-workerman-request-handler.

composer require chubbyphp/chubbyphp-workerman-request-handler "^2.3"

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

composer require slim/psr7 "^1.8"

Usage

Basic server

Create a server.php and start it with php server.php start (add -d to daemonize):

<?php

declare(strict_types=1);

namespace App;

use Chubbyphp\WorkermanRequestHandler\OnMessage;
use Chubbyphp\WorkermanRequestHandler\PsrRequestFactory;
use Chubbyphp\WorkermanRequestHandler\WorkermanResponseEmitter;
use Psr\Http\Server\RequestHandlerInterface;
use Slim\Psr7\Factory\ServerRequestFactory;
use Slim\Psr7\Factory\StreamFactory;
use Slim\Psr7\Factory\UploadedFileFactory;
use Workerman\Worker;

require __DIR__.'/vendor/autoload.php';

/** @var RequestHandlerInterface $app */
$app = ...; // your PSR-15 application, bootstrapped once per worker process

$http = new Worker('http://0.0.0.0:8080');

// number of worker processes, typically the number of CPU cores
$http->count = 4;

$http->onWorkerStart = static function (): void {
    echo 'Workerman http server is started at http://0.0.0.0:8080'.PHP_EOL;
};

$http->onMessage = new OnMessage(
    new PsrRequestFactory(
        new ServerRequestFactory(),
        new StreamFactory(),
        new UploadedFileFactory()
    ),
    new WorkermanResponseEmitter(),
    $app
);

Worker::runAll();

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.

Class	Interface	Responsibility
OnMessage	OnMessageInterface	Workerman onMessage callback: builds the PSR-7 request, calls the PSR-15 handler and emits the response.
PsrRequestFactory	PsrRequestFactoryInterface	Converts a workerman request into a PSR-7 server request via the given PSR-17 factories.
WorkermanResponseEmitter	WorkermanResponseEmitterInterface	Converts a PSR-7 response into a workerman response and sends it over the connection.

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 REMOTE_ADDR and REMOTE_PORT from the TCP connection

Long-running process caveats

Workerman 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.
• Only REMOTE_ADDR and REMOTE_PORT are available as server params. 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

BlackfireOnMessageAdapter wraps an OnMessageInterface 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.

<?php

declare(strict_types=1);

namespace App;

use Blackfire\Client;
use Blackfire\Profile\Configuration;
use Chubbyphp\WorkermanRequestHandler\Adapter\BlackfireOnMessageAdapter;
use Chubbyphp\WorkermanRequestHandler\OnMessageInterface;
use Psr\Log\LoggerInterface;

/** @var OnMessageInterface $onMessage */
$onMessage = ...;

/** @var LoggerInterface $logger */
$logger = ...;

if (extension_loaded('blackfire')) {
    $onMessage = new BlackfireOnMessageAdapter(
        $onMessage,
        new Client(),
        new Configuration(), // optional, defaults to new Configuration()
        $logger              // optional, defaults to a NullLogger; receives Blackfire client errors
    );
}

$http->onMessage = $onMessage;

With New Relic

NewRelicOnMessageAdapter wraps an OnMessageInterface 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.

<?php

declare(strict_types=1);

namespace App;

use Chubbyphp\WorkermanRequestHandler\Adapter\NewRelicOnMessageAdapter;
use Chubbyphp\WorkermanRequestHandler\OnMessageInterface;

/** @var OnMessageInterface $onMessage */
$onMessage = ...;

if (extension_loaded('newrelic') && false !== $appname = ini_get('newrelic.appname')) {
    $onMessage = new NewRelicOnMessageAdapter($onMessage, $appname);
}

$http->onMessage = $onMessage;

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

Copyright

2026 Dominik Zogg