Skip to content

Conversation

@michalsn
Copy link
Member

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

@michalsn michalsn added new feature PRs for new features 4.7 labels Jan 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

4.7 new feature PRs for new features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant