Add support for PHP Runtimes

[jelen07]

Add Support for PHP Runtimes

Summary

This proposal suggests adding official support for long-running PHP runtimes (like Open Swoole, RoadRunner, and FrankenPHP) in Nette Framework through a runtime abstraction layer. This would bring significant performance improvements while maintaining backward compatibility and the elegant simplicity Nette is known for.

Table of Contents

1. Summary
2. Context: The Rise of PHP Runtimes
3. Current State in PHP Ecosystem
   • Symfony: Runtime Component
   • Laravel: Octane
   • Other Frameworks
4. Comparison of Primitive Application
   • Nginx Unit
   • Open Swoole
   • Test Summary
5. The Challenge for Nette
6. Proposed Solution: Nette Runtime Component
   • Core Architecture
   • Lifecycle Hook System
   • Configuration (NEON)
   • Entry Point Modification
   • State Reset Strategy
7. Implementation Phases
   • Phase 1: Core Abstraction
   • Phase 2: Additional Runtimes
   • Phase 3: Ecosystem Integration
8. Benefits for Nette Community
9. Real-World Performance Data
10. Example: Simple Nette App with Runtime
11. Open Questions for Discussion
12. Conclusion
13. References
14. Technical Diagrams
    • Request Flow Comparison
    • State Management Hierarchy

Context: The Rise of PHP Runtimes

In recent years, we have seen a significant shift in how PHP applications are deployed. Modern PHP runtimes that keep applications in memory between requests are becoming increasingly popular, offering 5-10x performance improvements over traditional PHP-FPM deployments.

Traditional PHP-FPM Model:

┌───────────────────────────────────────┐
│  Each Request (100-150ms total)       │
├───────────────────────────────────────┤
│  1. Bootstrap application    (~50ms)  │
│  2. Load dependencies       (~30ms)   │
│  3. Compile DI container    (~20ms)   │
│  4. Process request         (~40ms)   │
│  5. Generate response       (~10ms)   │
│  6. Destroy everything      (FREE)    │
└───────────────────────────────────────┘
                  ↓
            Process dies

Long-Running Runtime Model:

┌───────────────────────────────────────┐
│  Initialization (ONCE per worker)     │
├───────────────────────────────────────┤
│  1. Bootstrap application    (~50ms)  │
│  2. Load dependencies       (~30ms)   │
│  3. Compile DI container    (~20ms)   │
└───────────────────────────────────────┘
                  ↓
┌───────────────────────────────────────┐
│  Per Request (8-15ms total)           │
├───────────────────────────────────────┤
│  1. Process request         (~8ms)    │
│  2. Generate response       (~5ms)    │
│  3. Reset state            (~2ms)     │
└───────────────────────────────────────┘
                  ↓
         Worker continues →

Performance Improvement: Typically 5-10x faster response times, significantly lower resource usage.

Current State in PHP Ecosystem

Symfony: Runtime Component

Symfony introduced the Runtime Component in version 5.3, providing a vendor-agnostic abstraction for different runtimes.

Architecture:

// public/index.php
use App\Kernel;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function (array $context): Kernel {
    return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};

Key Design Principles:

• Returns a factory callable, not an instance
• Runtime decides how to execute the kernel (FPM, Swoole, RoadRunner, etc.)
• Framework-agnostic (can be used with any PSR application)
• Clear separation between bootstrapping logic and global state

Supported Runtimes:

• Generic runtime (PHP-FPM compatible)
• Open Swoole (via runtime/swoole)
• RoadRunner (via runtime/roadrunner-symfony-nyholm)
• FrankenPHP (via runtime/frankenphp)
• ReactPHP (via runtime/react-php)
• Custom implementations

Laravel: Octane

Laravel introduced Octane in version 8.x, providing first-class runtime support with automatic state management.

Key Features:

• Built-in support for Swoole, Open Swoole, RoadRunner, and FrankenPHP
• Automatic state reset for Laravel services
• Rich configuration and lifecycle hooks
• Development-friendly (hot reload, debugging)

State Management:
Octane automatically resets:

• Container bindings (request-scoped)
• Events
• Session
• Authentication
• Cookies

Other Frameworks

• Spiral Framework: Built from ground up with RoadRunner integration
• Hyperf: PHP framework specifically designed for Swoole
• Mezzio: Swoole integration via mezzio/mezzio-swoole

Comparsion of primitive application

Comparison of individual solutions, without booting Nette.

Starting the test via: $ wrk -t10 -c1000 -d30s <host>

Both applications only output simple JSON:

{
  status: "ok",
  env: "<unit|swoole>"
}

Nginx Unit

$ wrk -t10 -c1000 -d30s http://omni.local:8888
Running 30s test @ http://omni.local:8888
10 threads and 1000 connections
Thread Stats   Avg      Stdev     Max   +/- Stdev
Latency   102.41ms   34.69ms 386.08ms   82.73%
Req/Sec   213.97     92.04   670.00     66.24%
63968 requests in 30.09s, 11.53MB read
Socket errors: connect 759, read 0, write 0, timeout 261
Requests/sec:   2125.81
Transfer/sec:    392.38KB

Open Swoole

$ wrk -t10 -c1000 -d30s http://omni.local:8889
Running 30s test @ http://omni.local:8889
10 threads and 1000 connections
Thread Stats   Avg      Stdev     Max   +/- Stdev
Latency    22.64ms   65.78ms   1.40s    89.16%
Req/Sec     5.55k     2.33k   15.09k    68.86%
1655281 requests in 30.02s, 260.47MB read
Socket errors: connect 759, read 0, write 0, timeout 0
Requests/sec:  55140.70
Transfer/sec:      8.68MB

Test Summary

Rough data (not a real application example) is 5.55k vs. 213 req/sec, so Open Swoole is ~25x faster.
For real UCs, the estimate is 8-12x faster depending on specific application.

The Challenge for Nette

While other major frameworks have embraced runtime support, Nette currently lacks official runtime integration. This creates several challenges:

1. Bootstrap Dependency on Global State

Current Nette bootstrapping in typical applications:

// public/index.php
$container = Bootstrap::boot($autoloader)->createContainer();
$app = $container->getByType(Application::class);
$app->run();
// Process dies here

This pattern assumes:

• Fresh process for each request
• Superglobals ($_SERVER, $_POST, etc.) available
• Process cleanup happens automatically
• No state persistence needed

2. Stateful Services in DI Container

Nette's DI container creates singleton services by default. In a long-running process, this can lead to state leakage:

class UserService
{
    private ?User $currentUser = null; // ⚠️ Persists between requests!

    public function setCurrentUser(User $user): void
    {
        $this->currentUser = $user;
    }
}

3. Session Handling

Standard session_start() relies on PHP's built-in session mechanism, which assumes process lifecycle. Runtime environments handle sessions differently (via cookies bridging).

4. Tracy Debugger

Tracy's global error handler and debug bar accumulate state that must be reset between requests.

5. Database Connections

Connection pooling vs. connection reset strategies need careful consideration in long-running processes.

Proposed Solution: Nette Runtime Component

I propose introducing a Nette Runtime Component inspired by Symfony's approach but tailored to Nette's philosophy and conventions.

Core Architecture

namespace Nette\Runtime;

/**
 * Runtime abstraction for long-running PHP processes.
 */
interface RuntimeInterface
{
    /**
     * Boot the runtime and prepare workers.
     */
    public function boot(callable $applicationFactory): void;

    /**
     * Run the runtime (blocking call).
     */
    public function run(): int;

    /**
     * Gracefully terminate the runtime.
     */
    public function terminate(): void;
}

Lifecycle Hook System

namespace Nette\Runtime;

interface LifecycleHookInterface
{
    /**
     * Called before each request is processed.
     */
    public function beforeRequest(Http\IRequest $request): void;

    /**
     * Called after request is processed successfully.
     */
    public function afterRequest(Http\IRequest $request, Http\IResponse $response): void;

    /**
     * Called when an error occurs during request processing.
     */
    public function onError(\Throwable $e): void;

    /**
     * Called when worker is stopping.
     */
    public function onWorkerStop(): void;

    /**
     * Hook priority (lower runs first).
     */
    public function getPriority(): int;
}

Configuration (NEON)

runtime:
    # Runtime driver: openswoole, roadrunner, frankenphp
    driver: openswoole

    http:
        host: 0.0.0.0
        port: 8080
        workers: 4
        maxRequests: 1000  # Auto-restart worker after N requests

    hooks:
        # System hooks (provided by Nette)
        - Nette\Runtime\Hook\ResetHttpObjectsHook
        - Nette\Runtime\Hook\DatabaseConnectionHook
        - Nette\Runtime\Hook\SessionBridgeHook
        - Nette\Runtime\Hook\TracyBarResetHook

        # Application hooks (user-defined)
        - App\Runtime\Hook\CustomStateResetHook

Entry Point Modification

// public/index.php (traditional - still works!)
$container = Bootstrap::boot($autoloader)->createContainer();
$app = $container->getByType(Application::class);
$app->run();

// bin/runtime.php (runtime mode)
use Nette\Runtime\RuntimeFactory;

$container = Bootstrap::boot($autoloader)->createContainer();

$runtime = RuntimeFactory::create('openswoole', $container);
$runtime->boot(fn() => $container->getByType(Application::class));

exit($runtime->run());

State Reset Strategy

The component would provide built-in hooks for common scenarios:

1. HTTP Objects (Fresh Per Request):

class ResetHttpObjectsHook implements LifecycleHookInterface
{
    public function beforeRequest(Http\IRequest $request): void
    {
        // Container receives fresh Request/Response from runtime bridge
    }
}

2. Database Connection (Validate & Reset):

class DatabaseConnectionHook implements LifecycleHookInterface
{
    public function beforeRequest(Http\IRequest $request): void
    {
        // Ping connection, reconnect if needed
        // Rollback any active transaction (bug detection)
    }

    public function onError(\Throwable $e): void
    {
        // Always rollback on error
    }
}

3. Session (Cookie Bridge):

class SessionBridgeHook implements LifecycleHookInterface
{
    public function beforeRequest(Http\IRequest $request): void
    {
        // Extract session ID from request cookies
        // Start session with proper storage backend
    }

    public function afterRequest(...): void
    {
        // Write session, update cookies
    }
}

Implementation Phases

Phase 1: Core Abstraction (Foundation)

Deliverables:

• Nette\Runtime namespace with core interfaces
• Open Swoole runtime implementation (most performant)
• Basic lifecycle hook system
• Documentation and migration guide

Time Estimate: 6-8 weeks

Phase 2: Additional Runtimes (Expansion)

Deliverables:

• RoadRunner runtime implementation
• FrankenPHP runtime implementation
• Runtime selection via configuration

Time Estimate: 4-6 weeks

Phase 3: Ecosystem Integration (Polish)

Deliverables:

• Contrib package integration examples
• Testing utilities for runtime compatibility
• Performance monitoring helpers
• Production deployment guides

Time Estimate: 2-4 weeks

Benefits for Nette Community

1. Performance: 5-10x faster response times, lower hosting costs
2. Modern Stack: Keeps Nette competitive with Symfony and Laravel
3. Backward Compatibility: Existing applications continue to work unchanged
4. Flexibility: Runtime selection based on needs (ease of use vs. performance)
5. Learning Opportunity: Community exploration of async PHP patterns
6. Optional Adoption: Not forced, purely opt-in enhancement

Real-World Performance Data

Based on community benchmarks (February 2024-2025):

Metric	PHP-FPM	Open Swoole	RoadRunner	FrankenPHP
Requests/sec	150	1,500 (10x)	1,300 (8.6x)	1,200 (8x)
Avg Latency	120ms	8ms	12ms	11ms
Memory/request	~8MB	~1MB	~1MB	~1.5MB

These are average numbers for typical web applications. Results vary by application complexity.

Example: Simple Nette App with Runtime

// app/Bootstrap.php
class Bootstrap
{
    public static function boot(ClassLoader $loader): Configurator
    {
        $configurator = new Configurator();
        $configurator->enableTracy(__DIR__ . '/../log');
        $configurator->setTempDirectory(__DIR__ . '/../temp');
        $configurator->addConfig(__DIR__ . '/config/config.neon');

        return $configurator;
    }
}

// bin/runtime.php
use Nette\Runtime\RuntimeFactory;

$autoloader = require __DIR__ . '/../vendor/autoload.php';
$container = Bootstrap::boot($autoloader)->createContainer();

$runtime = RuntimeFactory::createFromConfig(
    $container->getParameters()['runtime']
);

$runtime->boot(fn() => $container->getByType(Application\Application::class));

exit($runtime->run());

# Start runtime server
php bin/runtime.php

# Server running on http://0.0.0.0:8080
# Workers: 4
# Runtime: Open Swoole 22.1.0

Open Questions for Discussion

1. Package Location: Core Nette package or separate nette/runtime package?
2. Default Runtime: Should we recommend one runtime as default for beginners?
3. Testing Strategy: How to test runtime compatibility in user applications?
4. Tracy Integration: Full Tracy support in runtime or production-only deployment?
5. Async Support: Should we expose async capabilities (coroutines) or keep it sync-only initially?

Conclusion

Long-running PHP runtimes are becoming the industry standard for high-performance applications. Adding official runtime support to Nette would:

• Keep the framework modern and competitive
• Provide significant value to existing users (performance, cost savings)
• Attract new developers looking for performant PHP frameworks
• Maintain Nette's philosophy of simplicity and elegance
• Support for Lambda / serverless environments

I believe this is a natural evolution for Nette, similar to how the framework adapted to dependency injection, Composer, and other standards in the past. The key is implementing it in a way that feels "Nette-like" - simple, elegant, and opt-in.

I am happy to contribute to this effort and have already done extensive research on runtime integration patterns, state management strategies, and compatibility challenges specific to Nette's architecture.

Would the Nette team and community be interested in exploring this further?

---

References

1. Symfony Runtime Component
2. Laravel Octane Documentation
3. Open Swoole Documentation
4. RoadRunner Documentation
5. FrankenPHP Documentation
6. PHP Runtime Performance Comparison (2024)
7. Middleware Support in Nette (not implemented yet)
8. 3rd party Middlewares for Nette – Contributte/Midleware
9. Talk about RoadRunner integation with Nette by Radovan Kepák and David Štrop (czech)
10. Integration of RoadRunner with Nette
11. Worker mode compatibility in Nette (czech)
12. ResetInterface for Nette DI

Technical Diagrams

Request Flow Comparison

Traditional PHP-FPM:

HTTP Request
    ↓
PHP-FPM spawns process
    ↓
Bootstrap application (expensive)
    ↓
Create DI Container (expensive)
    ↓
Process request
    ↓
Send response
    ↓
Process dies (cleanup automatic)

Long-Running Runtime:

[One-time: Worker Initialization]
    Bootstrap application
    Create DI Container
    ↓
[Per Request Loop]
    Receive HTTP request
    ↓
    Lifecycle: beforeRequest hooks
    ↓
    Process request (fast - everything cached)
    ↓
    Send response
    ↓
    Lifecycle: afterRequest hooks (reset state)
    ↓
    Continue to next request

State Management Hierarchy

┌─────────────────────────────────────────────┐
│  Persistent State (Keep Alive)              │
│  - DI Container                             │
│  - Application instance                     │
│  - Service configurations                   │
│  - Compiled templates (Latte)               │
│  - Class definitions                        │
└─────────────────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────┐
│  Connection-Like State (Validate & Reset)   │
│  - Database connections (ping & reconnect)  │
│  - Redis connections                        │
│  - External API clients                     │
└─────────────────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────┐
│  Request-Specific State (Fresh Per Request) │
│  - HTTP Request/Response                    │
│  - Session data                             │
│  - User authentication                      │
│  - Presenter instances                      │
│  - Form instances                           │
│  - Tracy debug bar                          │
└─────────────────────────────────────────────┘

---

Type: Feature Proposal / RFC

[bckp]

This is nice addition to nette, we are currently reworking our Nette RoadRunner extension, we have some MR to make our life less miserable about implementing...

This proposal will make our life even less miserable, yet it is big shift and im not sure if it is backward compatible on Nette side :(