Bref Sqs Laravel Laravel Package

Getting Started

christoph-kluge/bref-sqs-laravel bridges AWS SQS to Laravel's queue pipeline so a Bref/Lambda function can consume queued jobs without running a long-lived queue:work daemon. You still dispatch() jobs the Laravel way; the package handles turning an SQS batch from the Lambda invocation event into Laravel job executions.

Minimal path:

1. Pin compatible versions. 2.0.0 requires bref/bref 1.3.*. Install both together:

   composer require christoph-kluge/bref-sqs-laravel:^2.0 bref/bref:^1.3
   

   If you are on bref 1.2.x, stay on the 1.x line of this package.
2. Publish the config (php artisan vendor:publish and pick the package provider — the README lists the tag) and read config/bref-sqs.php first; that file and the package's job class are the two places that explain the whole integration.
3. Add an sqs connection in config/queue.php (driver sqs, region, prefix/queue URL) and keep your existing connection as the default so only explicitly-routed jobs go to SQS.
4. Define the Lambda function in serverless.yml using Bref's artisan handler plus the package's single-invocation consumer command, with an SQS event source:

   functions:
     worker:
       handler: artisan
       runtime: php-81
       timeout: 30
       layers: [ ${bref:layer.php-81} ]
       command: [ '<package SQS consumer command from README>' ]
       events:
         - sqs:
             arn: !GetAtt JobsQueue.Arn
             batchSize: 1
   

5. First use case: in a controller or command, ProcessOrder::dispatch($orderId) on the sqs connection; deploy; drop a message and confirm it appears in CloudWatch logs and lands in jobs/failed_jobs semantics you expect. Start with batchSize: 1 while you learn the retry behaviour.

Implementation Patterns

• Route by queue, one Lambda per queue. Use distinct queue names (orders, emails, exports) and a separate function/event source per queue so each can have its own timeout, memory, and concurrency. Don't multiplex unrelated workloads on one SQS queue.
• Dispatch small, serializable payloads. Queue IDs or scalars, not hydrated models with relations. Re-fetch inside handle(). SQS caps messages at 256 KB and Laravel's serialized model payload gets large fast.
• Per-job timeouts, not global ones. Because Lambda enforces the hard timeout, set the job's $timeout (and the connection's retryAfter) comfortably below the function timeout, and the function timeout below the queue's visibility timeout. This is the ordering that prevents duplicate processing.
• Design for at-least-once delivery. SQS redelivers, and a Lambda crash mid-batch returns the whole batch. Make handlers idempotent (unique constraints, upserts, "already processed" guards) from day one rather than retrofitting.
• Retries live in two places. Laravel-side: maxTries/backoff and the failed_jobs table. AWS-side: the queue's redrive policy (maxReceiveCount → DLQ) for invocations that never reach Laravel's failure handling. Align the numbers so a job doesn't bounce forever in one layer while the other looks healthy.
• Separate failure handling. failed() on the job covers application exceptions; a redrive DLQ covers cold-start crashes, OOM, and timeouts. Add alerting on both, and remember queue:retry/Horizon tooling does not apply to SQS.
• Local development: keep QUEUE_CONNECTION=database or sync locally and exercise jobs with dispatchSync() or queue:work --once. For end-to-end Lambda testing use serverless invoke local / SAM with a recorded SQS event fixture, or bref local against the consumer command.
• Config through serverless.yml. Put APP_KEY, queue URLs, and AWS region in provider.environment or SSM; build config/route caches at deploy time, not at invocation time. Grant the function sqs:ReceiveMessage, DeleteMessage, GetQueueAttributes, and ChangeMessageVisibility.
• Extension point: the job class is swappable/configurable in most setups — wrap it (or add queue middleware) if you need tenant context, correlation IDs, or tracing around every consumed record.

Gotchas and Tips

• 2.0.0 is a compatibility break, not a feature release. The only change is bref 1.3 support, and the major bump signals older bref versions are no longer supported. Check with composer why-not bref/bref 1.3 before upgrading; if bref is locked by another package, you are stuck on this package's 1.x.
• No long-running worker. Don't set the function command to queue:work. Lambda gives you one invocation per event; the package's consumer handles one batch and returns. Any pattern relying on a warm daemon (in-memory caching between jobs, --sleep, --daemon assumptions) doesn't apply.
• Whole-batch failure = duplicate work. Unless you configure partial batch failure reporting (and the package/event source supports it), one bad record fails every record in the batch. That is the strongest argument for batchSize: 1 on anything non-idempotent.
• Visibility timeout footgun. If the Lambda timeout or job timeout exceeds the queue's visibility timeout, SQS hands the same message to a second invocation while the first is still running. Set visibility ≥ 6× function timeout, and the job timeout below the function timeout.
• Cold starts dominate. Every invocation boots the framework. Cache config and routes in the deployment artifact, keep the service provider list lean, and prefer more memory (which buys CPU) over longer timeouts when latency matters.
• Logging goes to stderr. Set LOG_CHANNEL=stderr and read CloudWatch; local storage/logs writes are lost and slow on Lambda.
• Payload shape matters. If messages are produced by non-Laravel systems (or raw aws sqs send-message), they won't match Laravel's job envelope. Either publish through Laravel's queue API or confirm the package's handling of foreign payloads in the README before relying on it.
• Debugging checklist when a job "vanishes": (1) did the dispatch use the sqs connection, (2) is the message in the queue or already consumed, (3) CloudWatch for the invocation, (4) failed_jobs row, (5) DLQ message count. Those five cover almost every case.
• Upgrade hygiene: bump this package and bref together, redeploy the layer, and re-run one end-to-end job in staging — layer/runtime mismatches surface only at invocation time, not at composer update.