octane-development

name	octane-development
description	Use this skill when working with Laravel Octane, a long-running PHP worker server (Swoole, FrankenPHP, RoadRunner) where the application boots once and serves many requests instead of rebooting for each request like PHP-FPM. Trigger when installing Octane or starting its server; configuring or detecting the active driver for driver-specific code; using Octane::concurrently(), Octane::table(), the Octane cache, or shared in-memory state across workers; controlling worker memory growth; or testing Octane behavior. Skip plain PHP-FPM applications with no persistent worker.
license	MIT
metadata	{"author":"laravel"}

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.

Common Pitfalls

These issues recur when developing applications on Octane. Guard against each one as you write code.

• Avoid resolving config(), app('config'), or other container services in low-level worker boot code before the application is fully bootstrapped, especially when configuration is not cached. Resolve configuration after the application is booted, and never assume php artisan config:cache has run.
• Never capture Auth::user() in a singleton, static property, or custom guard binding. It can leave one user logged in for later requests on the same worker, even after their cookie is cleared. Resolve authentication state per request and add stateful services to the flush list. See State Isolation.
• Close per-request Redis, database, and HTTP client connections you open outside the framework's managed pools. Octane does not close them, so they can accumulate until the worker recycles. Reset them in a RequestTerminated listener.
• Do not read PHP superglobals. $_GET, $_POST, and $_SERVER are not reliably populated under workers. Use the Request object instead.
• Do not capture non-serializable values in a concurrently() closure. A PDO connection, Eloquent model, or $this can trigger a serialization error. Pass scalar IDs and re-fetch models inside the closure.
• Fix PHP warnings emitted during request startup. On FrankenPHP, they can shut down the worker. Resolve the underlying warning rather than suppressing it.
• Reload workers after changing code, providers, environment variables, or configuration. Workers hold the booted application in memory and pick up changes only after octane:reload, a restart, or running with --watch in local development.

References

Verify driver-specific details against the official docs, because versions and configuration keys change:

• Laravel Octane: https://laravel.com/docs/octane
• FrankenPHP: https://frankenphp.dev/docs/ (worker mode: /docs/worker/, Laravel: /docs/laravel/, config/Caddyfile: /docs/config/, known issues: /docs/known-issues/)
• OpenSwoole: https://openswoole.com/docs
• RoadRunner: https://docs.roadrunner.dev/docs (PHP workers: /docs/php-worker/worker.md, intro: /docs/general/about.md)

Verification

1. Confirm config('octane.server') matches the driver assumed by any Swoole-only code.
2. Confirm no request-derived state lives in a singleton or static without scoped, flush, or a reset.
3. Confirm a worker recycle limit (max_requests or max_jobs) is configured.