Weave Code
Bref Laravel Bridge Laravel Package
cachewerk/bref-laravel-bridge
Run Laravel on AWS Lambda with Bref. This bridge connects Laravel's HTTP kernel, queue workers, scheduler, and filesystem to Bref's serverless runtime, so you can deploy a familiar Laravel app without managing servers. Includes sensible defaults for serverless storage, logging, and configuration.
An advanced Laravel integration for Bref, including Octane support.
Frequently asked questions about Bref Laravel Bridge
- How do I install cachewerk/bref-laravel-bridge in a Laravel app?
- Install it with Composer alongside Bref, then publish the package configuration file so the serverless defaults for storage, logging, and queues are available to your app. From there you wire the bridge into your Bref function definitions in serverless.yml, mapping HTTP, queue, and console handlers to the Lambda runtime. Integration effort is mostly infrastructure configuration such as SQS, EventBridge, IAM, and DLQs rather than application code, so a team already running Bref can typically be productive in days.
- Does cachewerk/bref-laravel-bridge support Laravel Octane?
- Yes, Octane support is one of the package's advertised features and is part of why it positions itself as a more advanced Bref integration. Keep in mind that Lambda still runs a fresh invocation per request, so you do not get a long-lived Swoole or RoadRunner worker persisting across invocations the way you would on a traditional server. Treat Octane here as improving bootstrapping and lifecycle handling rather than eliminating cold starts entirely.
- How does the bridge run Laravel queue workers on AWS Lambda?
- Queue work is driven by SQS-triggered Lambda invocations, and the bridge connects those invocations to Laravel's queue worker. Since v0.3.0 it uses Laravel's native queue handler instead of a bespoke worker loop, so options like --max-time, --rest, backoff, tries, job middleware, and the JobProcessing, JobProcessed, and JobFailed events should behave as Laravel documents them. Verify your --max-time configuration explicitly rather than assuming the package imposes a clean exit at N seconds.
- Why are my jobs on Lambda being retried twice?
- You have two independent retry budgets. SQS event source mapping returns failed messages to the queue and redelivers them up to maxReceiveCount, while Laravel's worker also applies its own tries and backoff settings. Because SQS is at-least-once, a job can execute more than once even when nothing is misconfigured, so make your jobs idempotent and align the two retry configurations deliberately.
- How should I configure SQS visibility timeout and Lambda timeout?
- Chain the timeouts so the SQS visibility timeout is greater than the Lambda function timeout, which in turn must be greater than the worker's --max-time. If the visibility timeout is too short, a second invocation can pick up the same message while the first is still processing it, producing concurrent duplicate work. Also configure a dead-letter queue so poison messages stop cycling after maxReceiveCount.
- Is v0.3.0 of cachewerk/bref-laravel-bridge a breaking change?
- It is a minor bump under pre-1.0 semver, but it swaps the queue execution engine for Laravel's native handler, which is behaviorally significant even if not labeled breaking. Anything the old bespoke handler guaranteed, such as exiting cleanly at a fixed number of seconds, may now depend on explicit --max-time configuration. Pin the exact version and read the pull request diff, not just the changelog line, to catch config key renames or command signature changes.
- Which Laravel and PHP versions does this bridge support?
- Check the composer.json constraints for the specific release rather than assuming, because the v0.3.0 shift to Laravel's native queue handler likely raised the minimum Laravel version. The bridge has to track Laravel worker internals across major releases, so supported versions move with upstream. Pin the package and test upgrades against your target Laravel version before deploying.
- Can I run the Laravel scheduler on AWS Lambda with this package?
- Yes. The bridge connects Laravel's console kernel to Bref, so schedule:run can be triggered by an EventBridge rule, typically every minute. Keep scheduled tasks short and dispatch queued jobs for anything long-running, since the invocation is still bound by Lambda's execution limits. Remember that Lambda does not deliver a real SIGTERM before freezing or killing a sandbox, so graceful shutdown is best-effort.
- Is this package suitable for WebSockets, long-running jobs, or high-throughput Redis queues?
- It is a poor fit for those workloads. Lambda caps execution at roughly 15 minutes and does not support persistent connections or WebSockets, and high-throughput Redis queue drivers suffer from connection churn and VPC cold starts. The intended topology is HTTP on the php-fpm runtime, background work on SQS-triggered invocations, and the scheduler on EventBridge, with SQS as the sane queue path.
- What are the alternatives to cachewerk/bref-laravel-bridge and how is it maintained?
- The obvious alternative is using Bref directly and writing your own Laravel handlers, which gives you full control at the cost of more glue code; managed platforms such as Laravel Vapor are another route with a different architecture and cost model. This package is a small community project rather than first-party Laravel or AWS, so bus factor is the dominant supply-chain risk. Pin exact versions, review the source before adopting, and watch release activity before committing production workloads to it.
Weaver
How can I help you explore Laravel packages today?