README

Valkyrja OpenSwoole

OpenSwoole persistent worker entry point for the Valkyrja PHP framework.

This integration bootstraps the Valkyrja application once at worker startup, then dispatches every incoming request to an isolated child container so request state never bleeds between concurrent requests. The result is the performance benefit of a persistent process without the state-contamination risks of naive long-running PHP.

Requirements

• PHP 8.4+
• The OpenSwoole PHP extension (openswoole/core ^26.2.0)
• An existing Valkyrja application

Installation

composer require valkyrja/openswoole

Usage

Wire the OpenSwoole entry point into your application's front controller:

// app/public/index.php
use Valkyrja\Application\Data\HttpConfig;
use Valkyrja\OpenSwoole\OpenSwooleHttp;

OpenSwooleHttp::run(new HttpConfig(
    dir: __DIR__ . '/..',
));

run() bootstraps the application once when the worker process starts, then starts the OpenSwoole HTTP server. Each request is handled in an isolated child container so state never bleeds between requests.

Customizing the Server

Override getSwooleServer() to configure the server address, port, or options:

use OpenSwoole\HTTP\Server;
use Valkyrja\OpenSwoole\OpenSwooleHttp;

class App extends OpenSwooleHttp
{
    public static function getSwooleServer(): Server
    {
        $server = new Server('0.0.0.0', 8080);
        $server->set([
            'worker_num'  => 4,
            'max_request' => 10000,
        ]);

        return $server;
    }
}

Customizing Bootstrap

Override bootstrapParentServices() to force-resolve services that are expensive to create and safe to share across requests:

use Valkyrja\Application\Kernel\Contract\ApplicationContract;
use Valkyrja\Http\Routing\Collection\Contract\CollectionContract;
use Valkyrja\OpenSwoole\OpenSwooleHttp;

class App extends OpenSwooleHttp
{
    protected static function bootstrapParentServices(ApplicationContract $app): void
    {
        $container = $app->getContainer();
        $container->getSingleton(CollectionContract::class);
        $container->getSingleton(MyExpensiveSharedService::class);
    }
}

Worker Lifecycle

See the Valkyrja framework repository for a full explanation of the persistent worker lifecycle, the child container isolation model, and configuration options.

Related Integrations

Other persistent-worker runtime integrations for Valkyrja PHP:

• FrankenPHP — persistent worker via the FrankenPHP embedded runtime
• RoadRunner — persistent worker via the Go-based RoadRunner manager

Contributing

See CONTRIBUTING.md for the submission process and VOCABULARY.md for the terminology used across Valkyrja.

Security Issues

If you discover a security vulnerability, please follow our disclosure procedure.

License

Licensed under the MIT license. See LICENSE.md.