Skip to content

SYSTEM Cited by 1 source

Laravel Octane

Laravel Octane is Laravel's official persistent-process request handler. It runs on Swoole, RoadRunner, FrankenPHP, or (under Bref) an AWS Lambda-resident Octane handler, and flips PHP's shares- nothing request model into an Erlang/Node-like persistent worker model: the Laravel application boots once per worker process and serves many requests before the process recycles.

What persists across requests

  • The Laravel application bootstrap (service container, config, route tree, middleware pipeline, compiled views).
  • Database connections when OCTANE_PERSIST_DATABASE_SESSIONS=1.
  • Redis connections when OCTANE_PERSIST_REDIS_CONNECTIONS=1.
  • Any singleton bound to the service container.

What doesn't persist

  • Request-scoped state — the request object, session, authentication guard, view renderer. Octane resets these per request via Illuminate\Foundation\Http\Middleware\ResetContext.
  • Static and global state — Octane has a known footgun here: mutable state in static properties or global variables leaks across requests. Application code has to be defensive in a way it didn't in classic shares-nothing mode.

The serverless use case

Under Bref on AWS Lambda, Octane solves the per-invocation TLS handshake + Laravel bootstrap tax that shares-nothing PHP incurs on every request. See concepts/ssl-handshake-as-per-request-tax.

Canonical config shape:

web:
  handler: Bref\LaravelBridge\Http\OctaneHandler
  runtime: php-81
  environment:
    BREF_LOOP_MAX: 250
    OCTANE_PERSIST_DATABASE_SESSIONS: 1
  events:
    - httpApi: '*'

BREF_LOOP_MAX bounds how many invocations a single Lambda execution environment serves before Lambda recycles it. Trades amortisation depth against state-staleness bounds — higher BREF_LOOP_MAX means more reuse per process but also more exposure to memory leaks, connection-side effects, and per-worker drift.

Measured delta (against PlanetScale)

Metric Classic Octane Delta
p50 75 ms 14 ms 5.4×
p95 130 ms 35 ms 3.7×

(Source: sources/2026-04-21-planetscale-serverless-laravel-applications-with-aws-lambda-and-planetscale.)

The 61 ms saved at p50 decomposes approximately as: - Laravel application bootstrap (service container, config loading, route compilation) — largest single chunk, dozens of milliseconds on a cold boot. - TLS handshake to PlanetScale (2-3 RTT over encrypted TLS 1.2 / TLS 1.3 to the PlanetScale endpoint) — see concepts/ssl-handshake-as-per-request-tax. With PlanetScale's 0.3 ms query time, the handshake dwarfed the query cost. - DB auth handshake (caching_sha2_password auth roundtrip).

Octane amortises all of these across up to BREF_LOOP_MAX = 250 requests per worker.

Why this is interesting beyond PHP

Laravel Octane is the canonical persistent-process-inside-a- serverless-invocation-environment example. The same pattern applies to:

  • Node.js — a persistent event-loop handler that keeps DB connection + app state warm across Lambda invocations.
  • Python ASGI (FastAPI / Starlette) — a persistent ASGI loop inside Lambda with Mangum-style request adaptation.
  • Ruby Puma in Lambda — similar shape.

See patterns/persistent-process-for-serverless-php-db-connections for the generalised pattern.

Seen in

Last updated · 470 distilled / 1,213 read