[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?

The code has -1 === $this->loopMax so this check is not correct.
BTW, I'd suggest turning this into 0 >= $this->loopMax

You can check the value of $workerLoopMax before calling filter_var. If $workerLoopMax !== null and filter_var($workerLoopMax) === null, then you know it is invalid.

Indeed, I misunderstood the meaning of using -1/0. I updated accordingly and added a comment about negative values in the options array shape

src/Symfony/Component/Runtime/SymfonyRuntime.php

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: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.

nicolas-grekas · 2025-05-23T07:29:16Z

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

+                $this->kernel->terminate($sfRequest, $sfResponse);
+            }
+
+            gc_collect_cycles();


I'm wondering about this: could it become a perf hog?

Maybe could we make this configurable (ex: run it after N requests), but this prevents the GC to be triggered in the middle of the handling of a request.

Worker mode is relatively new to PHP so maybe there's something to improve on this topic in php-src itself?
Some new conditional trigger that'd be light to check when running the GC would be really useful?
Or maybe we can build something on gc_status?

If we want to give more control over this to end users, we could move the call into a kernel-terminate listener, that'd do it only in worker mode.

It would be nice to move this logic to a listener and make it configurable, but maybe it could be done in a follow-up PR?

… 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

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

nicolas-grekas reviewed May 23, 2025

View reviewed changes

alexandre-daubois force-pushed the frankenphp-runner branch from fbf64c4 to 5eac909 Compare May 23, 2025 07:50

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

5ce19ae

… detected

alexandre-daubois force-pushed the frankenphp-runner branch from 5eac909 to 5ce19ae Compare May 23, 2025 07:57

		@@ -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;

Uh oh!

[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 Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexandre-daubois May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicolas-grekas May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexandre-daubois May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexandre-daubois commented May 21, 2025 •

edited

Loading

alexandre-daubois May 22, 2025 •

edited

Loading

nicolas-grekas May 23, 2025 •

edited

Loading

alexandre-daubois May 23, 2025 •

edited

Loading