Symfony Bridge Laravel Package

Product Decisions This Supports

• Serverless migration of an existing Symfony app (build vs. buy). This package is the "buy" answer to roughly 1–3 days of engineering glue: instead of hand-rolling a Lambda bootstrap, a PSR-11-aware runtime, cache-directory handling, and log formatting, the team changes one line (class Kernel extends BrefKernel) and inherits the work. That makes the "move the monolith to Lambda" roadmap item cheap enough to schedule as an experiment rather than a quarter-long project.
• Cost/latency tiering on the roadmap. The advanced mode (kernel handled directly in a kept-alive process, no PHP-FPM, BREF_LOOP_MAX configurable) is the lever for deciding how to run: FPM layer for simplicity vs. function runtime for per-request efficiency. That's a pricing-tier decision for your hosting story, not a code decision.
• Event-driven and background-work use cases. Class-name handlers let SQS queues and Symfony Messenger consumers point at a service (handler: App\Service\MyService) instead of a bespoke bin/consumer.php. This unlocks roadmap items like async webhooks, email/report fan-out, image processing, scheduled jobs, and queue-drained integrations without standing up workers or ECS services.
• Spiky or low-traffic products get a viable hosting option. Marketing-burst traffic, internal/admin tools used a few hours a day, per-tenant deployments, and webhook receivers all fit the scale-to-zero model. This is a "should we keep paying for idle capacity?" decision the PM can now answer with data.
• File-upload features are supportable on Lambda — with a caveat now made concrete. 3.0.3 fixes a real leak: on the Bref runtime (not PHP-FPM), uploaded files were never removed from the instance's /tmp, so a warm container accepting uploads would eventually fill its disk and break every other writer to /tmp — logs, temp caches, generated PDFs. That was a latent production failure mode for any roadmap item involving uploads (avatars, CSVs, invoice attachments, bulk imports), and it is now a solved one. The lesson for the roadmap is not "uploads are safe" but "any /tmp usage is a shared, finite budget" — worth a line in the architecture notes.
• Observability as a differentiator, not an afterthought. The bundle registers Bref's CloudWatch log formatter and bref/monolog-bridge 2.0 support puts the Lambda invocation request ID on every log line. Correlating a customer complaint to a single request in CloudWatch Insights becomes a support-SLA input rather than a forensic exercise.
• Platform standardization. Committing to Bref + this bridge is a statement that AWS Lambda is your default PHP runtime. That shapes hiring, on-call runbooks, IaC templates, and CI/CD (cache warmup becomes a deploy-pipeline requirement, not a runtime one).
• Explicit non-decision: it is a thin adapter, not a platform. Adopting it does not buy you observability vendor, secrets management, or local dev parity — budget separately for those or the "serverless" story will underdeliver on the ops side.

When to Consider This Package

Adopt when most of the following hold:

• You already run (or have firmly chosen) Symfony on PHP and want AWS Lambda via Bref. This bridge is Symfony-specific; a Laravel codebase should use bref/laravel-bridge, and framework-agnostic PHP work only needs Bref itself.
• You want the minimum-diff path: existing Kernel, existing bundles, existing public/index.php. If your app already boots cleanly, this is close to a drop-in.
• Your workload is request/response or queue-triggered, tolerates cold starts, and does not need durable local state.
• You need queue consumers / Symfony Messenger on Lambda and prefer class handlers over maintaining consumer scripts — the SQS path here is genuinely attractive for reducing moving parts.
• You want CloudWatch-shaped logs with request correlation out of the box; the 3.x line turns this on for new installs via Flex and offers a documented one-line opt-in for existing apps.
• You are on, or can move to, Bref ≥ 3.0.13 — that is now the hard floor on the 3.0.3 bridge, and on PHP 8.4+ it is the difference between uploads being cleaned up and silently accumulating.
• You have, or will build, serverless competency: prewarmed caches in CI, no filesystem cache pools, discipline about var/cache, a plan for cold-start tuning and tracing, and awareness that /tmp is per-instance and small.
• You can accept community-supported OSS with a small surface area.

Look elsewhere, or defer, when:

• You're not on Lambda, or you're on Lambda but still want PHP-FPM end-to-end — plain Bref suffices; this bridge adds little. (Note the 3.0.3 upload fix only applies to the runtime path; under PHP-FPM you own that lifecycle as before.)
• You have hard filesystem, session, or long-running-process requirements. The README is explicit that writes to cache.system or filesystem pools are the wrong pattern; if you cannot remove them, a container runtime (ECS/Fargate) is the honest answer. Large or concurrent file uploads belong in the same conversation: stream to S3 rather than reasoning about /tmp headroom.
• You need vendor-backed support, an SLA, or a security-review paper trail. This is MIT community software with a very small footprint and a single primary maintainer; the dependency-risk conversation belongs in the decision record, not after launch.
• Your stack is pinned to an older Symfony major, or you cannot move in lockstep with Bref major versions — 2.0 and 3.0 both landed as breaking majors tied to Bref 3.0, and 3.0.3 now raises the Bref floor again. Plan upgrade windows and treat the bridge's patch releases as potentially carrying dependency bumps.
• You'd be adopting it for the 50-star popularity signal. Judge it on fit, maintenance recency, and the fact that it is glue code you could replace; also independently verify the release metadata before relying on the cadence.
• You are unwilling to read the source and own the fallback. With near-zero listed dependents, you are effectively on the leading edge of the usage curve.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, free, MIT-licensed adapter that lets our existing Symfony application run on AWS Lambda with a one-line code change. It converts a "should we re-platform?" question into a low-risk pilot: no rewrite, no licensing cost, and reversible — rip it out and the app runs as before. The commercial upside is on the cost line (pay-per-request instead of idle servers, especially for low-traffic and spiky products) and on the delivery line (queue and background-job work becomes configuration rather than a new service to operate). The most recent patch is a good illustration of the maintenance model working as intended: a latent disk-exhaustion bug affecting file uploads was found and fixed in days, at the cost of a version bump — community-supported, but actively watched. The risk remains concentrated and knowable: small code surface, maintained by Bref's own author, with a defined exit to containers if it disappoints.

For engineering leadership: The change is Kernel extends BrefKernel; the rest is convention. Three things become deploy-time responsibilities rather than runtime behavior: run cache:clear --env=prod and composer install --classmap-authoritative in the pipeline so the first request isn't paying 1–20 seconds of cache build, disable Dotenv with a generated .env.local.php, and stop writing to filesystem cache pools (return [] from getWritableCacheDirectories() to symlink pools). Optional upside: switch off PHP-FPM and let the kept-alive Symfony process handle requests with BREF_LOOP_MAX as a recycle cap, and register services as public if you want SQS/Messenger handlers addressed by class name. Logs come out CloudWatch-ready with the Lambda request ID, which materially shortens incident triage.

What changed in 3.0.3, and why it matters to the plan: on the Bref runtime, uploaded request files were never deleted from the instance's /tmp, so warm containers slowly filled their disk and then failed everywhere that touches /tmp. 3.0.3 deletes them at the start of the next request — which is the right fix, but it means peak /tmp usage is one request's worth of uploads plus whatever else the app writes there, not zero. It also requires Bref ≥ 3.0.13; on PHP 8.4+ earlier Bref versions missed the cleanup entirely. Concretely: pin Bref, check the resolved version in composer.lock rather than the constraint, and if you take large uploads, put a hard limit on request body size and consider streaming straight to S3.

Risks to name up front, and the mitigations:

• Single-maintainer / small-community risk → pin the version, keep an integration test that boots the kernel on the Lambda image and exercises an upload followed by a second request, and document the ~1-day fallback (custom kernel.php bootstrap returning the kernel; the README shows exactly how).
• Upgrade coupling to Bref majors and patch floors → schedule framework and Bref upgrades together; 3.0.3's raised Bref minimum shows patch releases on this package can carry upstream dependency requirements. Read the notes before bumping, and don't float the constraint.
• Cold starts and cost surprises → prewarm in CI, set a memory/loop-size budget, and instrument p95 latency plus invocation counts before promising a savings number.
• /tmp as a shared, invisible budget → it is per-instance, small, and shared between uploads, logs, and temp files. Any feature that writes there inherits the failure mode this release just fixed. Add a size cap on uploads and a smoke test, rather than trusting it stays quiet.
• Operational maturity gap → serverless shifts work from runtime to pipeline and observability. Fund that, or the pilot will be judged on the wrong metric.

Recommendation: Approve a bounded pilot on one low-risk, spiky or queue-heavy Symfony service. Success criteria: unchanged application code beyond the kernel base class, p95 latency within an agreed envelope of current hosting, no filesystem cache writes, /tmp stable across repeated upload requests, request-ID-correlated logs in CloudWatch, and a written exit plan to Fargate. Revisit the full portfolio migration only after those hold.