Laravel Bridge Laravel Package

Technical Evaluation

Architecture fit. brefphp/laravel-bridge remains the glue layer making a stock Laravel app viable on AWS Lambda under Bref: SQS queue connector, S3 filesystem adapter, a writable-storage strategy respecting Lambda's read-only filesystem (redirecting to /tmp), and the CloudWatch logging bridge. Release 3.1.4 is the first substantive patch since 3.1.3's constraint-only bump, and it touches real runtime behavior in three places:

1. Uploaded-file cleanup. Under Octane and Bref\LaravelBridge\Http\HttpHandler, files uploaded with a request were never deleted — they accumulated in the instance's /tmp until it filled, after which everything writing to /tmp failed, Laravel's storage included. This is a self-inflicted collision with the bridge's own writable-storage design. Files are now deleted at the start of the next request.
2. Failed-job error preservation. When a failed job could not be persisted (e.g. the default database-uuids driver in an app with no database), the storage error overwrote the job's own exception, which was then never logged or reported. Both errors are now reported.
3. Deprecation of bref.request_context. The option injected an X-Request-ID header into shared log context, but API Gateway does not send that header, so it was inert under PHP-FPM. On Lambda, Bref's log formatter now prefixes every line with the request ID. Removal is slated for the next major.

There is also a new hard floor: Bref core >= 3.0.13, because earlier Bref releases missed every upload during cleanup on PHP 8.4+.

Integration feasibility. Still a routine composer update, but no longer a free one. Two things change the calculus. First, the transitive floor on Bref core means a bridge upgrade can now drag the core runtime forward; teams lagging on Bref 3.0.x must upgrade both together. Second, the file-lifecycle change is a genuine behavioral break for any code that treated an uploaded file's /tmp path as durable — most commonly by capturing $file->getRealPath() and handing it to a queued job or deferred process that runs after the response. That pattern was always unsafe on Lambda; this release makes it fail fast instead of fail slowly.

Technical risk. Moderate-low. The /tmp exhaustion fix is a clear net win and likely eliminates a class of production incidents that were previously very hard to attribute. But it converts a slow-burn leak into an immediate break for the deferred-file-processing pattern, and it is a lifecycle change shipped in a patch release — the kind of thing that arrives without a migration note in most teams' upgrade rituals. The failed-job change has a subtler consequence: previously-swallowed exceptions will start appearing in CloudWatch and in error alerting, which will read as a regression to anyone unfamiliar with the release. The bref.request_context deprecation is inert — removing it changes nothing about log output on Lambda — but it is deprecation debt with a known expiry at the next major.

Key questions.

• Is cleanup scoped to files Symfony tracks as UploadedFile, or does it sweep all of /tmp? The answer determines blast radius for any app writing scratch files there.
• Deletion happens at the start of the next request — under Octane, does that interact safely with concurrent in-flight requests on the same worker, or is there a window where a still-running request loses its uploads?
• Is there a config flag to opt out of cleanup, for teams that deliberately stage files in /tmp within a single request?
• Does the Bref 3.0.13 floor interact with the bref/monolog-bridge 1.x/2.x split introduced in 3.1.3, or are the two dependency trees orthogonal?
• What replaces bref.request_context for teams that were setting X-Request-ID themselves upstream of API Gateway?
• Is there a migration note for the deferred-file-processing pattern, or is the breaking change documented only in the release notes?

Integration Approach

Stack fit. Excellent for Laravel 10/11/12 on Bref 3.0.13+ with PHP 8.1–8.4. The PHP 8.4 path is specifically better after this release: prior to Bref 3.0.13, cleanup was skipped entirely on 8.4+, so PHP 8.4 teams were accumulating uploads with no remediation available at the bridge level. Teams on Bref 3.0.12 or earlier must upgrade core first — the bridge will not resolve otherwise.

Migration path. Two distinct populations. Leak-affected: services that have hit /tmp exhaustion, or that run image/media upload endpoints through Octane — these should take the release promptly, as a fix, and the upgrade is mostly upside. Unaware: services that never noticed the leak because their upload volume is low relative to instance turnover. These carry the behavioral-change risk without the felt pain, and need the audit more than the fix. Both should grep for deferred handling of uploaded temp paths before promoting.

Compatibility. Confirm the triple of Bref core (>= 3.0.13), PHP runtime, and Laravel version against the support matrix. Audit config/logging.php and any service provider for bref.request_context — it can be deleted now with no output change, and leaving it in place guarantees a breakage at the next major. Verify any custom Monolog channels or processors are Monolog-3-compatible if you also took 3.1.3's bref/monolog-bridge ^2.0 widening. For apps using database-uuids as the failed-job driver without a backing database, expect new error volume immediately after deploy.

Sequencing.

1. Upgrade Bref core to >= 3.0.13, deploy and confirm stability on the current bridge.
2. Pin the bridge to 3.1.4 in the same reviewable change as any bref/monolog-bridge major decision carried over from 3.1.3.
3. Grep the codebase for getRealPath(), getPathname(), and any queue payloads carrying uploaded file paths; remediate before promoting.
4. Remove bref.request_context from configuration.
5. Stage a soak test with realistic upload volume and concurrency — including a multi-MB upload alongside a queued job — and watch /tmp utilization and error rates.
6. Diff CloudWatch error volume pre- and post-deploy; attribute any new entries to the failed-job reporting change rather than treating them as regressions.
7. Promote to production with the lockfile revert path intact.

Operational Impact

Maintenance. Low, but no longer a single-package bump. The upgrade is now a coordinated pair (Bref core floor + bridge), and the bref.request_context deprecation puts a dated item on the roadmap with a known expiry. Budget the removal into the next major-version cycle rather than discovering it at upgrade time.

Support. Two new support narratives are needed. First, the failed-job fix will surface previously invisible exceptions; on-call needs to know that new error volume in CloudWatch is the fix working, not a regression, or the first post-deploy incident review will chase a ghost. Second, the /tmp exhaustion class should be documented as historically resolved so engineers do not re-diagnose a known-fixed failure mode — with the caveat that it only holds on Bref >= 3.0.13. Documentation should state which monolog-bridge major each supported Laravel version resolves to, so on-call is not debugging Monolog 3 behavior against Monolog 2 guidance.

Scaling. No cold-start or memory impact. The per-request cleanup adds negligible I/O and improves behavior at scale, where high upload volume against long-lived warm instances was the worst case — /tmp filling on a warm instance takes down storage for every subsequent request until the instance is recycled, which under sustained load can look like a cascading outage rather than a leak.

Failure modes.

• Deferred file processing — the headline risk. Queued jobs or post-response handlers holding an uploaded file's /tmp path will now find it deleted. Fails loudly, but only after deploy.
• Silent /tmp exhaustion on Bref < 3.0.13 — the fix does not apply; PHP 8.4 apps on older Bref core remain fully exposed.
• Alert noise from failed-job reporting — new CloudWatch errors trip existing thresholds and page on-call for what is actually correct behavior.
• Deprecated config left in place — bref.request_context is inert today and removed in the next major; unaddressed, it becomes a hard break.
• Lockfile divergence on monolog-bridge — carried from 3.1.3; two services on identical composer.json can resolve different Monolog majors and produce inconsistent observability.
• Rollback friction — reverting in a serverless pipeline requires a full redeploy; there is no in-place rollback, and a rollback would reintroduce the /tmp leak.

Ramp-up. Modest. The mechanics are a Composer bump plus a config deletion, absorbable in an afternoon. The conceptual load is higher than 3.1.3's: engineers need a working model of Lambda's /tmp lifecycle, which files the bridge now owns and deletes, and where CloudWatch output originates. Budget a pairing session for whoever owns observability and a second short review for whoever owns file uploads — the two failure modes in this release sit in different domains, and treating the upgrade as purely a logging matter will miss the file-lifecycle change entirely.