Skip to content

SYSTEM Cited by 1 source

Bref

Bref is an open-source project by Matthieu Napoli that provides PHP runtime support on AWS Lambda, including pre-built Lambda runtime layers, a Serverless Framework integration, framework bridges for Laravel and Symfony, and handlers for both classic per-request PHP invocation and Laravel Octane persistent-process mode.

What Bref actually ships

  • PHP runtime layers for Lambda (php-81, php-82, etc.) — Lambda layer packages with a working PHP interpreter, OpenSSL trust store at /opt/bref/ssl/cert.pem, and the Bref runtime bootstrap.
  • bref/bref Composer package — the core runtime library.
  • bref/laravel-bridge — Laravel integration: publishes a sensible serverless.yml template, provides HttpHandler and OctaneHandler classes, and wires Laravel Artisan into the Lambda runtime so CLI commands run on Lambda.
  • serverless bref:cli --args="..." — a Serverless Framework subcommand that invokes the Lambda function in management- command mode, letting you run e.g. php artisan migrate --force against the production database.

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

Two request-handling modes

Classic mode (shares-nothing per invocation)

web:
  handler: Bref\LaravelBridge\Http\HttpHandler
  runtime: php-81
  events:
    - httpApi: '*'

Every Lambda invocation spins up a fresh PHP process image, boots Laravel, handles one HTTP request, tears down. Matches PHP's traditional shares- nothing request model verbatim. Against PlanetScale this yields p50 75 ms / p95 130 ms on a trivial read endpoint because every invocation pays the full Laravel bootstrap + TLS handshake + DB auth cost.

Octane mode (persistent process across invocations)

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

Each Lambda execution environment keeps the PHP process + DB connection warm across up to BREF_LOOP_MAX invocations (default shown: 250). Recovers 5× latency at p50 (75 ms → 14 ms) and 3.7× at p95 (130 ms → 35 ms) against PlanetScale — the delta is almost entirely amortised TLS handshake + Laravel bootstrap cost. See patterns/persistent-process-for-serverless-php-db-connections.

Operational gotchas

  • SSL trust store path differs between Lambda and local dev. On Lambda: /opt/bref/ssl/cert.pem (ships in the Bref runtime layer). On the developer's machine: typically /etc/ssl/cert.pem (Linux) or platform-specific. Any PDO MYSQL_ATTR_SSL_CA-style config needs to toggle.
  • Cold-start tail is ~1 s for a typical Laravel app via Bref; amortised across ~50 cold starts per freshly deployed burst, so <1% of requests in the first minute under 50-concurrent fan-out hit the cold path. See concepts/cold-start.
  • Bref respects the serverless TCP-socket restriction only via full Lambda. Lambda functions can open arbitrary outbound TCP (unlike Cloudflare Workers or Vercel Edge Functions), so PHP's native mysqli / PDO works against PlanetScale's binary protocol. See concepts/serverless-tcp-socket-restriction for the runtimes where this doesn't hold.

Why Bref matters for the wiki

Bref is the canonical PHP-on-Lambda runtime and the vehicle that makes non-Node, non-Python languages first-class on Lambda without writing a Custom Runtime from scratch. The Octane-in-Lambda trick it enables is architecturally interesting independent of PHP: it shows that "persistent process inside a serverless invocation environment" is a viable cross-language pattern for recovering per-request amortisation without giving up autoscale. Same shape applies to Python ASGI workers, Node cluster workers, and Ruby Puma — any language where a persistent request-handling loop exists and the runtime permits multiple request dispatch within one Lambda execution context.

Seen in

Last updated · 470 distilled / 1,213 read