[Runtime] Automatically use FrankenPHP runner when its worker mode is detected #60503

alexandre-daubois · 2025-05-21T15:29:32Z

Q	A
Branch?	7.4
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues	-
License	MIT

Currently, to use FrankenPHP worker mode, you have to install the runtime/frankenphp-symfony package and set the APP_RUNTIME env var to the correct FQCN.

@dunglas and I would like to move the runtime and the runner classes to the Symfony core now that The PHP Foundation officially supports FrakenPHP.

This PR adds FrankenPHP worker mode detection and registers the correct runner to use it. This specific runner is only used when using the worker mode. When using FrankenPHP in classic mode, HttpKernelRunner is still used.

The DX would be greatly improved, given that it works out of the box with this PR.

Classes and tests are coming from this repo with a few tweaks to stick to Symfony CS.

src/Symfony/Component/Runtime/FrankenPhpRuntime.php

src/Symfony/Component/Runtime/Runner/FrankenPhpRunner.php

src/Symfony/Component/Runtime/SymfonyRuntime.php

dunglas · 2025-05-22T07:01:11Z

src/Symfony/Component/Runtime/Runner/FrankenPhpRunner.php

+            if (\extension_loaded('xdebug') && \function_exists('xdebug_connect_to_client')) {
+                xdebug_connect_to_client();
+            }


For the record, this feature is currently broken in Xdebug. We're investigating what's going on. It doesn't hurt to keep this code anyway.

src/Symfony/Component/Runtime/SymfonyRuntime.php

dunglas · 2025-05-22T07:06:07Z

src/Symfony/Component/Runtime/SymfonyRuntime.php

@@ -143,12 +147,23 @@ public function __construct(array $options = [])

        $options['error_handler'] ??= SymfonyErrorHandler::class;

+        $workerLoopMax = $options['worker_loop_max'] ?? $_SERVER['FRANKENPHP_LOOP_MAX'] ?? $_ENV['FRANKENPHP_LOOP_MAX'] ?? null;


Shouldn't the env var has the same name as the option?

I kept as is to keep the backward compatibility with the current runtime package, but maybe it's the occasion to have a better name indeed.

It'd say we can keep FRANKENPHP_LOOP_MAP to help transitioning.
We also have the $_SERVER['APP_RUNTIME_OPTIONS'] vars which allows configuring any options.

Wouldn't that require a modification in FrankenPHP itself?

If it requires an update, we could make FrankenPHP compatible with both FRANKENPHP_LOOP_MAX and (something like) WORKER_LOOP_MAX, then deprecated the first one day when we're ready

No need to modify FrankenPHP, this option is entirely handled by the runtime.

dunglas · 2025-05-22T07:07:06Z

src/Symfony/Component/Runtime/SymfonyRuntime.php

@@ -143,12 +147,23 @@ public function __construct(array $options = [])

        $options['error_handler'] ??= SymfonyErrorHandler::class;

+        $workerLoopMax = $options['worker_loop_max'] ?? $_SERVER['FRANKENPHP_LOOP_MAX'] ?? $_ENV['FRANKENPHP_LOOP_MAX'] ?? null;
+        if (null !== $workerLoopMax && (!\is_numeric($workerLoopMax) || $workerLoopMax <= 0)) {


filter_var?

If we do this (for example filter_var($options['worker_loop_max'] ?? $_SERVER['FRANKENPHP_LOOP_MAX'] ?? $_ENV['FRANKENPHP_LOOP_MAX'] ?? null, FILTER_VALIDATE_INT, FILTER_NULL_ON_FAILURE);), we cannot detect if the option is a string like "foo", and it'll fallback on the default value. It works, but there will be no explicit error message to warn the user. Maybe I'm missing an argument to provide to filter_var?

dunglas · 2025-05-22T07:08:25Z

src/Symfony/Component/Runtime/SymfonyRuntime.php

        parent::__construct($options);
    }

    public function getRunner(?object $application): RunnerInterface
    {
        if ($application instanceof HttpKernelInterface) {
+            if (filter_var($_SERVER['FRANKENPHP_WORKER'] ?? $_ENV['FRANKENPHP_WORKER'] ?? null, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false) {


I don't think it's necessary to check for $_ENV or use filter_var(). IIRC $_SERVER is always populated by FrankenPHP in worker mode, and the other SAPIs don't have any reason to use the FRANKENPHP_ prefix.

oh, this is not an env var, but something the sapi exposes? then indeed let's revert to the previous code

src/Symfony/Component/Runtime/Internal/ComposerPlugin.php

src/Symfony/Component/Runtime/Runner/FrankenPhpRunner.php

src/Symfony/Component/Runtime/SymfonyRuntime.php

nicolas-grekas · 2025-05-22T07:13:23Z

src/Symfony/Component/Runtime/SymfonyRuntime.php

        parent::__construct($options);
    }

    public function getRunner(?object $application): RunnerInterface
    {
        if ($application instanceof HttpKernelInterface) {
+            if (filter_var($_SERVER['FRANKENPHP_WORKER'] ?? $_ENV['FRANKENPHP_WORKER'] ?? null, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false) {


oh, this is not an env var, but something the sapi exposes? then indeed let's revert to the previous code

nicolas-grekas · 2025-05-22T07:15:33Z

src/Symfony/Component/Runtime/SymfonyRuntime.php

@@ -143,12 +147,23 @@ public function __construct(array $options = [])

        $options['error_handler'] ??= SymfonyErrorHandler::class;

+        $workerLoopMax = $options['worker_loop_max'] ?? $_SERVER['FRANKENPHP_LOOP_MAX'] ?? $_ENV['FRANKENPHP_LOOP_MAX'] ?? null;


It'd say we can keep FRANKENPHP_LOOP_MAP to help transitioning.
We also have the $_SERVER['APP_RUNTIME_OPTIONS'] vars which allows configuring any options.

… detected

carsonbot added Status: Needs Review Feature Runtime labels May 21, 2025

carsonbot added this to the 7.3 milestone May 21, 2025

alexandre-daubois added the DX DX = Developer eXperience (anything that improves the experience of using Symfony) label May 21, 2025

alexandre-daubois force-pushed the frankenphp-runner branch from 41b4f54 to 5a1bd6e Compare May 21, 2025 15:30

nicolas-grekas reviewed May 21, 2025

View reviewed changes

src/Symfony/Component/Runtime/FrankenPhpRuntime.php Outdated Show resolved Hide resolved

stof reviewed May 21, 2025

View reviewed changes

src/Symfony/Component/Runtime/Runner/FrankenPhpRunner.php Outdated Show resolved Hide resolved

alexandre-daubois force-pushed the frankenphp-runner branch from 5a1bd6e to 1be5a66 Compare May 21, 2025 18:17

alexandre-daubois changed the title ~~[Runtime] Automatically enable FrankenPHP runtime when its worker mode is detected~~ [Runtime] Automatically use FrankenPHP runner when its worker mode is detected May 21, 2025

nicolas-grekas reviewed May 21, 2025

View reviewed changes

src/Symfony/Component/Runtime/SymfonyRuntime.php Outdated Show resolved Hide resolved

src/Symfony/Component/Runtime/SymfonyRuntime.php Show resolved Hide resolved

src/Symfony/Component/Runtime/SymfonyRuntime.php Outdated Show resolved Hide resolved

alexandre-daubois force-pushed the frankenphp-runner branch from 1be5a66 to f7b1310 Compare May 22, 2025 07:04

dunglas requested changes May 22, 2025

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels May 22, 2025

nicolas-grekas reviewed May 22, 2025

View reviewed changes

[Runtime] Automatically use FrankenPHP runner when its worker mode is…

fbf64c4

… detected

alexandre-daubois force-pushed the frankenphp-runner branch from f7b1310 to fbf64c4 Compare May 22, 2025 07:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Runtime] Automatically use FrankenPHP runner when its worker mode is detected #60503

[Runtime] Automatically use FrankenPHP runner when its worker mode is detected #60503

alexandre-daubois commented May 21, 2025 •

edited

Loading

dunglas May 22, 2025

dunglas May 22, 2025

alexandre-daubois May 22, 2025

nicolas-grekas May 22, 2025

GromNaN May 22, 2025

alexandre-daubois May 22, 2025 •

edited

Loading

dunglas May 22, 2025

dunglas May 22, 2025

alexandre-daubois May 22, 2025

dunglas May 22, 2025 •

edited

Loading

nicolas-grekas May 22, 2025 •

edited

Loading

dunglas May 22, 2025

nicolas-grekas May 22, 2025 •

edited

Loading

nicolas-grekas May 22, 2025

		@@ -143,12 +147,23 @@ public function __construct(array $options = [])

		$options['error_handler'] ??= SymfonyErrorHandler::class;

		$workerLoopMax = $options['worker_loop_max'] ?? $_SERVER['FRANKENPHP_LOOP_MAX'] ?? $_ENV['FRANKENPHP_LOOP_MAX'] ?? null;

[Runtime] Automatically use FrankenPHP runner when its worker mode is detected #60503

Are you sure you want to change the base?

[Runtime] Automatically use FrankenPHP runner when its worker mode is detected #60503

Conversation

alexandre-daubois commented May 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexandre-daubois May 22, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dunglas May 22, 2025 • edited Loading

Choose a reason for hiding this comment

nicolas-grekas May 22, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolas-grekas May 22, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexandre-daubois commented May 21, 2025 •

edited

Loading

alexandre-daubois May 22, 2025 •

edited

Loading

dunglas May 22, 2025 •

edited

Loading

nicolas-grekas May 22, 2025 •

edited

Loading

nicolas-grekas May 22, 2025 •

edited

Loading