feat: FrankenPHP Worker Mode

[michalsn]

Description
This PR adds experimental support for FrankenPHP Worker Mode, allowing to handle multiple HTTP requests within the same PHP process. Instead of bootstrapping the framework for every request (traditional PHP-FPM model), the worker boots once and reuses resources across requests, resulting in 2-3x performance improvements for typical database-driven applications.

How it works

1. One-time bootstrap: Framework loads autoloader, configuration, services, and routes once at worker startup
2. Request loop: Each incoming request reuses existing resources, resets only request-specific state, processes the request, and cleans up
3. Connection persistence: Database and cache connections are validated and reused across requests
4. State isolation: Services, factories, and superglobals are properly reset between requests to prevent data leakage

New features

• app/Config/WorkerMode.php - Configuration for persistent services and garbage collection
• php spark worker:install - Generates Caddyfile and worker entry point
• php spark worker:uninstall - Removes worker mode files

Optimizations

Database:

• Added BaseConnection::ping() method for connection health checks
• Postgre uses native pg_ping(), other drivers use SELECT 1
• DatabaseConfig::validateForWorkerMode() - validates connections at request start
• DatabaseConfig::cleanupForWorkerMode() - detects uncommitted transactions and rolls back

Session handlers:

• Added PersistsConnection trait for Redis and Memcached handlers
• Connections are pooled by configuration hash and reused across requests
• Connections are validated before reuse, automatically re-established if unhealthy

Services and state management:

• Boot::bootWorker() - one-time initialization for worker mode
• CodeIgniter::resetForWorkerMode() - resets request-specific state
• Services::resetForWorkerMode() - resets non-persistent services between requests
• Services::validateForWorkerMode() - validates cache connections
• Events::cleanupForWorkerMode() - clears event performance data

Debug Toolbar:

• Toolbar::reset() - resets collectors between requests (development only)

No impact on traditional PHP-FPM
All worker mode methods are only called from the worker entry point (public/frankenphp-worker.php). When running in traditional PHP-FPM mode via public/index.php, none of this code is executed. The changes introduce zero performance overhead for applications not using worker mode.

Benchmarks
I also prepared a set of simple benchmarks to evaluate worker mode performance: https://github.com/michalsn/benchmark-codeigniter-frankenphp

Based on existing benchmarks, nginx with PHP-FPM should perform similarly to FrankenPHP running in classic mode. When I attempted to verify this, the results showed roughly 60% of classic mode performance. However, these tests were run in a local development environment that is not properly tuned, which likely skewed the results.

For this reason, I decided not to include the benchmark numbers for nginx with PHP-FPM. In a real-world, properly configured environment, nginx is expected to perform similarly to FrankenPHP in classic mode.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[paulbalandan]

Need to read up on this, but sharing initial comments.

[paulbalandan]

does this config need to extend BaseConfig?

[neznaika0]

Keep in mind that these values will change in Registrars and env.

[michalsn]

No, I don't think so. Although overrides from the .env file might be acceptable in theory, allowing Registrars would be misleading, as the values are only used once and not on a per-request basis. I would rather leave it as it is.

[paulbalandan]

At first glance, the name is not descriptive of what it does actually. From its name, I am expecting that this validates something when using worker mode but is actually reconnecting the cache if needed. Can you rename this along that behavior?

[michalsn]

The method name comes from previous iterations (I had a few), where more things were happening.

I will use "reconnect" in the method name, although I'm not sure if that won't be misleading, as we first check if the connection is still valid and reconnect only if it's not.

[paulbalandan]

how about "reconnectIfNeededForWorkerMode". verbose but it gets the idea through

[michalsn]

That's pretty long, and we still don't know what it's about... The current one is reconnectCacheForWorkerMode.

[michalsn]

It would be simpler without ForWorkerMode part, but I would like to keep it.

[paulbalandan]

Same commentary as above but for database connections.

[michalsn]

Done.

[github-actions]

👋 Hi, @michalsn!

We detected conflicts in your PR against the base branch 🙊
You may want to sync 🔄 your branch with upstream!

Ref: Syncing Your Branch