README

Yii FrankenPHP worker runner

The package contains a bootstrap for running Yii3 application using FrankenPHP worker mode.

Note

If you do not want to run Yii3 in worker mode, please use yiisoft/yii-runner-http which is default for yiisoft/app and yiisoft/app-api.

Requirements

• PHP 8.1 - 8.5.

Installation

The package could be installed with Composer:

composer require yiisoft/yii-runner-frankenphp

General usage

In your application root create worker.php:

<?php

declare(strict_types=1);

use App\Environment;
use Psr\Log\LogLevel;
use Yiisoft\ErrorHandler\ErrorHandler;
use Yiisoft\ErrorHandler\Renderer\PlainTextRenderer;
use Yiisoft\Log\Logger;
use Yiisoft\Log\StreamTarget;
use Yiisoft\Yii\Runner\FrankenPHP\FrankenPHPApplicationRunner;

$root = __DIR__;

require_once $root . '/src/bootstrap.php';

if (Environment::appC3()) {
    $c3 = $root . '/c3.php';
    if (file_exists($c3)) {
        require_once $c3;
    }
}

$runner = new FrankenPHPApplicationRunner(
    rootPath: $root,
    debug: Environment::appDebug(),
    checkEvents: Environment::appDebug(),
    environment: Environment::appEnv(),
    temporaryErrorHandler: new ErrorHandler(
        new Logger(
            [
                (new StreamTarget())->setLevels([
                    LogLevel::EMERGENCY,
                    LogLevel::ERROR,
                    LogLevel::WARNING,
                ]),
            ],
        ),
        new PlainTextRenderer(),
    ),
);
$runner->run();

Then edit Caddyfiles. For production it would be docker/Caddyfile:

# Production mode config
# https://frankenphp.dev/docs/config
# https://caddyserver.com/docs/caddyfile

{
    skip_install_trust

    frankenphp {

    }
}

{$SERVER_NAME::80} {
    encode zstd br gzip
    php_server {
        root /app/public
        worker {
            match *
            file /app/worker.php
        }
    }
}

For development it would be docker/dev/Caddyfile:

# Development mode config
# https://frankenphp.dev/docs/config
# https://caddyserver.com/docs/caddyfile

{
    skip_install_trust

    frankenphp {

    }
}

{$SERVER_NAME::80} {
    encode zstd br gzip
    php_server {
        root /app/public
        worker {
            match *
            file /app/worker.php
            watch /app/**/*.php
        }
    }
}

Development configuration has watch directive that makes FrankenPHP to reload changes when .php files are edited so you don't have to restart it manually.

Feel free to delete public/index.php and remove yiisoft/yii-runner-http from your composer.json. These are used for classic non-worker mode only.

Don't forget to rebuild images with new configuration files using make build.

Worker mode notes

You can configure the maximum number of requests to handle by setting the MAX_REQUESTS environment variable.

When using worker mode, make sure stateful services are reset after each request. For resetters configuration, see Yii DI StateResetter documentation.

Additional configuration

By default, the FrankenPHPApplicationRunner is configured to work with Yii application templates and follows the config groups convention.

You can override the default configuration using constructor parameters and immutable setters.

Constructor parameters

$rootPath — the absolute path to the project root.

$debug — whether the debug mode is enabled.

$checkEvents — whether check events' configuration.

$environment — the environment name.

$bootstrapGroup — the bootstrap configuration group name.

$eventsGroup — the events' configuration group name.

$diGroup — the container definitions' configuration group name.

$diProvidersGroup — the container providers' configuration group name.

$diDelegatesGroup — the container delegates' configuration group name.

$diTagsGroup — the container tags' configuration group name.

$paramsGroup — the config parameters group name.

$nestedParamsGroups — configuration group names that are included in a config parameters group. This is needed for recursive merge parameters.

$nestedEventsGroups — configuration group names that are included in events' configuration group. This is needed for reverse and recursive merge events' configurations.

$configModifiers — configuration modifiers.

$configDirectory — the relative path from $rootPath to the configuration storage location.

$vendorDirectory — the relative path from $rootPath to the vendor directory.

$configMergePlanFile — the relative path from $configDirectory to merge plan.

$temporaryErrorHandler — A temporary error handler is needed to handle the creation of configuration and container instances, then the error handler configured in your application configuration will be used.

$emitter — an emitter to send the response.

Immutable setters

If the configuration instance settings differ from the default, you can specify a customized configuration instance:

/**
 * @var Yiisoft\Config\ConfigInterface $config
 * @var Yiisoft\Yii\Runner\FrankenPHP\FrankenPHPApplicationRunner $runner
 */

$runner = $runner->withConfig($config);

The default container is Yiisoft\Di\Container. But you can specify any implementation of the Psr\Container\ContainerInterface:

/**
 * @var Psr\Container\ContainerInterface $container
 * @var Yiisoft\Yii\Runner\FrankenPHP\FrankenPHPApplicationRunner $runner
 */

$runner = $runner->withContainer($container);

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii FrankenPHP worker Runner is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates