README

Valkyrja FrankenPHP

FrankenPHP 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 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+
• FrankenPHP running in worker mode
• An existing Valkyrja application

Installation

composer require valkyrja/frankenphp

Usage

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

use Valkyrja\Application\Data\HttpConfig;
use Valkyrja\FrankenPhp\FrankenPhpHttp;

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

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

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\FrankenPhp\FrankenPhpHttp;
use Valkyrja\Http\Routing\Collection\Contract\CollectionContract;

class App extends FrankenPhpHttp
{
    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:

• OpenSwoole — persistent worker via the OpenSwoole extension
• 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.