Octane Development

Laravel Octane

Octane boots the application container once and reuses it across requests in a long-running worker. Follow these rules to avoid Octane-specific bugs caused by PHP-FPM assumptions.

Always verify against the docs. Octane's APIs, configuration keys, and driver options change between versions. Before giving setup steps, configuration examples, or exact API syntax, call the Laravel Boost search-docs tool scoped to the installed laravel/octane version. Treat the rules below as durable patterns, and treat search-docs as the source of truth for specifics such as installation commands, Caddyfile and .rr.yaml configuration, server flags, and method signatures.

Detect the Driver First

Read config('octane.server') to determine the driver: swoole, roadrunner, or frankenphp. Guard Octane::concurrently(), Octane::table(), the octane cache store, and ticks or intervals behind this check, because they run on Swoole only.

State Isolation (all drivers)

Avoid storing request-specific state in singletons or static properties. State set during one request can survive into the next, which is the most common source of Octane bugs.

// 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);

• Scope, lazily resolve, or add to the flush list (config/octane.php) any service that holds data derived from $request, Auth::user(), or another per-request value.
• Inject Request through method parameters or the request() helper inside methods. Do not capture it at construction, where it goes stale.
• Reset any static state you must keep by listening for the RequestTerminated event, or list the service in flush. Octane already flushes core framework state such as authentication, sessions, and cookies. Your application code is your responsibility.

Memory (all drivers)

Free what you allocate. Workers are long-lived, so anything left referenced can accumulate until the worker crashes.

• Set a max-requests or max-jobs recycle limit as the last line of defense against leaks.
• Register event listeners in service providers, never inside request handlers, since the dispatcher keeps every one.
• Clear static arrays in a lifecycle listener or flush the service. Never append to them in request handlers.
• Watch for singletons that capture large objects (Eloquent models) in closures, since they are held forever.

Concurrency (Swoole only)

Guard the driver, then run closures in parallel:

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

• Pass scalar IDs and re-fetch models inside the closure. Do not capture $this or non-serializable state, because closures are serialized for task workers.
• Expect results in input order. Catch exceptions inside closures when you need to transform or log the error before Octane rethrows it.

Swoole Tables and octane Cache (Swoole only)

• Pre-size tables at boot ('name:maxRows'). You cannot resize them, and exceeding the maximum may fail silently. Treat them as volatile because data is lost on worker restart; do not use them as a Redis or database replacement.
• Use incr() and decr() for atomic counters, since there are no transactions.
• Use the octane cache store only for ephemeral, high-frequency data. It uses the same shared memory and is not durable caching.

Testing (all drivers)

• Test correctness rather than parallelism when exercising concurrently(), tables, and ticks without a real server, since closures may run sequentially in tests.
• Call $this->refreshApplication() between assertions to simulate the per-request scoped-binding flush and prove state does not leak.
• Guard Swoole-specific tests with extension_loaded('swoole') || extension_loaded('openswoole') and skip them when neither extension is available.