Worker mode not working. What am I doing wrong?

[JAZ-013]

Hi all. I'm new to FrankenPHP but have my own PHP framework that I'm trying to get working with it. I have it working fine in non-worker mode and I'm finding it a lot faster than FPM or others. So now I'm trying to get it working in worker mode and not having much luck.

So what happens is, my worker script runs, starts up and bootstraps my application correctly and I can debug it up to when it executes frankenphp_handle_request($handler), but then that's it. None of my actual requests make it to the handler.

The confusing part is that everything "appears" to work because requests are being sent to my standard index.php entrypoint.

If I remove the root * / from the Caddyfile then nothing works and I get 404s.

What am I doing wrong here? I've been through the documentation a bunch of times and come up blank, but obviously I've missed a step. I'm hoping someone can shed some light on the issue for me. Thanks.

Caddy file:

{
	frankenphp {
		worker /app/public/worker.php
	}
}

localhost:80 {
	root * public/
	encode zstd br gzip
	php_server
}

Worker script:

<?php

declare(strict_types=1);

use Hazaar\Application;

if ((!($_SERVER['FRANKENPHP_WORKER'] ?? false)) || !function_exists('frankenphp_handle_request')) {
    echo 'FrankenPHP must be in worker mode to use this script.';

    exit(1);
}

// Prevent worker script termination when a client connection is interrupted
ignore_user_abort(true);

// Composer autoloading
include __DIR__.'/../vendor/autoload.php';

// Create a new application
$app = new Application(APPLICATION_ENV);
$app->bootstrap(true);

// Handler outside the loop for better performance (doing less work)
$handler = static function () use ($app) {
    $app->run();
};

$requestCount = 0;
$maxRequests = (int) ($_ENV['MAX_REQUESTS'] ?? $_SERVER['MAX_REQUESTS'] ?? 1000);

while ($requestCount < $maxRequests && frankenphp_handle_request($handler)) {
    ++$requestCount;
    gc_collect_cycles();
}

// Cleanup
$app->shutdown();

[JAZ-013]

Update. So this is interesting. If I rename the worker.php script file to index.php and update the worker config in the Caddyfile (see below), everything works.

???Why???

{
	frankenphp {
		worker /app/public/index.php
	}
}

localhost:80 {
	root * public/
	encode zstd br gzip
	php_server
}

This isn't mentioned in the documentation, which even has worker.php as the name of the script in the examples.

[dunglas]

By convention, the path of the worker script must be the path of your front controller. This is how FrankenPHP knows that this request must be handled by the worker script and not the traditional way.

[JAZ-013]

Thanks. Makes sense. It's just not really clear from the documentation that this is the way it works. The examples, for example, say this to start a worker using Docker:

docker run \
    -e FRANKENPHP_CONFIG="worker /app/path/to/your/worker/script.php" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

But nowhere does it state that /app/path/to/your/worker/script.php needs to be public/index.php. Which my understanding of the default Caddyfile is that it uses php_server, which only has index.php defined in the try_files directive. So I think that stating that the worker script is /app/path/to/your/worker/script.php is a bit misleading seeing as it can really only be public/index.php.

But again, I'm new, so let me know if I'm not totally understanding this.

[dunglas]

Indeed, we need to clarify the documentation.

[JAZ-013]

Indeed, we need to clarify the documentation.

Cool cool. On the plus side, once I figured this out, I was able to tweak a few things in my framework (Hazaar MVC) and it runs beautifully in worker mode now.

Way faster too. Some quick load time stats on my test page:

PHP-FPM: ~20ms
FrankenPHP: ~8ms
FrankenPHP Worker Mode: ~2ms

I'm pretty freakin' impressed. :)