Laravel Octane

When testing applications designed for Octane, follow these patterns to ensure state isolation and driver compatibility:

• Simulate Request Lifecycle: Call $this->refreshApplication() between assertions to simulate the flushing of scoped bindings and verify that state does not leak.
• Concurrency Testing: When exercising concurrently(), tables, or ticks, test for functional correctness rather than parallelism, as closures may run sequentially in a test environment.
• Driver Guards: Guard Swoole-specific tests by checking for the extension: extension_loaded('swoole') || extension_loaded('openswoole').

Before using driver-specific features like concurrency or Swoole Tables, determine which server is running by checking the octane.server configuration key. This prevents errors when running on drivers like RoadRunner or FrankenPHP that do not support Swoole-specific APIs.

Supported drivers are: swoole, roadrunner, or frankenphp.

config('octane.server')

Since workers are long-lived, unreferenced objects will accumulate and eventually crash the worker. Follow these practices to manage memory:

• Set Recycle Limits: Configure max-requests or max-jobs as a safety mechanism to recycle workers periodically.
• Avoid Request-Level Registration: Register event listeners in Service Providers, never inside request handlers, as the dispatcher will retain them indefinitely.
• Clear Static Collections: Never append to static arrays inside request handlers. Instead, clear them in a lifecycle listener or by adding the service to the flush list.
• Watch Closures: Be cautious of singletons that capture large objects (like Eloquent models) within closures, as these will be held in memory forever.

To upgrade to Laravel Octane 2.0, ensure your environment meets the new minimum version requirements and update your application dependencies.

Minimum Requirements:

• PHP: v8.1.0 or higher
• Laravel: v10.10.1 or higher

Production Deployment Note: Before updating dependencies in a production environment, you must "stop" your Octane workers. You can restart the workers once the update is complete.

Because Octane reuses the application container across requests, storing request-specific data in singletons or static properties will cause state to leak between users.

To prevent this:

• Use $this->app->scoped() instead of $this->app->singleton() for services that hold data derived from the current request (e.g., Auth::user()).
• Inject the Request object via method parameters or the request() helper rather than capturing it in a constructor.
• Add services that hold per-request state to the flush list in config/octane.php.
• Listen for the RequestTerminated event to manually reset any necessary static state.

// Avoid: holds request 1's user for every later request
$this->app->singleton(UserContext::class);

// Prefer: flushed and re-resolved per request
$this->app->scoped(UserContext::class);

Update your composer.json file to require the new versions of laravel/octane. If you are using the RoadRunner server, you must also update the spiral/roadrunner dependencies to the compatible versions.

// Update Octane
"laravel/octane": "^2.0"

// If using RoadRunner, update these:
"spiral/roadrunner-http": "^3.0.1",
"spiral/roadrunner-cli": "^2.5.0"

When using the swoole driver, you can utilize Swoole Tables and the octane cache store for high-performance, shared in-memory data.

Swoole Tables:

• Pre-sizing: You must pre-size tables at boot using the 'name:maxRows' syntax. Tables cannot be resized once created.
• Volatility: Data in Swoole Tables is lost when workers restart; do not use them as a permanent database or Redis replacement.
• Atomicity: Use incr() and decr() for atomic counters, as there are no transactions.

Octane Cache:

• Use the octane cache store only for ephemeral, high-frequency data. It shares memory with the workers and is not durable.

If using the swoole driver, you can execute closures in parallel using Octane::concurrently().

Important Constraints:

• Serialization: Closures are serialized for task workers. Do not capture $this or non-serializable objects (like PDO connections or Eloquent models). Instead, pass scalar IDs and re-fetch the models inside the closure.
• Order: Results are returned in the same order as the input array.
• Error Handling: Catch exceptions inside the closures if you need to transform or log them before Octane rethrows them.

[$users, $orders] = Octane::concurrently([
    fn () => User::all(),
    fn () => Order::pending()->get(),
]);

When using the Swoole driver, Octane can serve static files directly from your public directory. To enable or configure this, use the serve_static_files and static_file_headers keys within your Octane configuration.

• serve_static_files: A boolean to enable/disable static file serving.
• static_file_headers: An associative array where keys are URL patterns (e.g., *.css) and values are arrays of headers to apply to those files.

Note: Files with extensions like php, htaccess, or config are excluded from static serving for security.

Laravel Octane supports the following high-performance application servers:

• FrankenPHP
• Open Swoole
• Swoole
• RoadRunner