Bref Laravel Bridge Laravel Package

Getting Started

• Install the bridge alongside Bref: composer require cachewerk/bref-laravel-bridge. You need bref/bref and a Laravel app already in place.
• Check the README for handler class names, then wire them into serverless.yml:
  • HTTP: handler: Bref\Laravel\Handler with a Bref PHP-FPM runtime.
  • Queue (SQS): the package's queue handler. In v0.3.0 this now delegates to Laravel's native queue worker, so your config/queue.php and job classes drive behavior.
• Set the minimum environment variables in serverless.yml / SSM: APP_ENV, APP_KEY, APP_DEBUG=false, LOG_CHANNEL=stderr, CACHE_DRIVER, SESSION_DRIVER, QUEUE_CONNECTION=sqs, AWS_REGION.
• Deploy and verify with serverless deploy, then hit the API Gateway URL. For queues, push a job and check CloudWatch logs plus SQS metrics.
• First use case: ship an HTTP Laravel route to Lambda. Once that works, add an SQS queue and Lambda event source mapping, then dispatch a job. The v0.3.0 queue change means standard Laravel queue semantics (events, retries, failed() methods) apply without custom handler code.

Implementation Patterns

• HTTP requests: API Gateway → Lambda → Bref\Laravel\Handler → Laravel kernel. Keep the handler thin; use middleware as usual.
• Queue workers: SQS → Lambda with the bridge's queue handler. Dispatch jobs normally (dispatch(new Job)). Because v0.3.0 uses Laravel's native queue handler, the worker honors $tries, $timeout, $backoff, retryUntil(), and queue events exactly as in a traditional worker.
• Scheduled tasks: EventBridge cron → Lambda running php artisan schedule:run (via the bridge's console handler or a dedicated function). Keep schedule definitions in app/Console/Kernel.php or routes/console.php.
• Artisan commands: use bref local:invoke or a dedicated Lambda function for one-off commands. This is handy for migrations (php artisan migrate --force) during deployment or via manual invocation.
• Local development: run php artisan serve for web and php artisan queue:work for queues. Use vendor/bin/bref local to invoke handlers with Lambda-shaped events. This catches handler wiring issues before deploy.
• Configuration caching: in your build step, run php artisan config:cache && php artisan route:cache && php artisan view:cache. Do it after env vars are set at deploy time; don't cache a local .env.
• Logging: set LOG_CHANNEL=stderr so Bref forwards logs to CloudWatch. Use LOG_STDERR_FORMATTER if you want JSON lines. Avoid the default single/stack file driver in Lambda.
• Storage: configure FILESYSTEM_DISK=s3 and use S3 for uploads; Lambda's /tmp is ephemeral and small.
• Batch processing: if you use SQS batch windows, tune batchSize and maximumBatchingWindow in serverless.yml. With the native handler, enable partial batch failure reporting (FunctionResponseTypes: [ReportBatchItemFailures]) so only failed messages are retried.

Gotchas and Tips

• v0.3.0 queue handler change: the queue integration now uses Laravel's native queue handler. If you previously extended or overrode the bridge's custom handler, migrate to standard Laravel queue configuration. Re-test job retries, failed() hooks, and queue events (JobProcessing, JobFailed) after upgrading. Also confirm the handler class in serverless.yml still matches the README.
• SQS visibility timeout must exceed Lambda timeout. If Lambda times out, SQS redelivers the message and you get duplicate processing. Set the queue's visibility timeout to at least the Lambda timeout plus a buffer.
• Partial batch failures: without ReportBatchItemFailures, a single failed message in a batch causes the entire batch to be retried. With the native handler, verify the response format and enable the feature in serverless.yml.
• No .env in Lambda: Bref does not load .env. Put secrets in SSM Parameter Store or Secrets Manager and reference them via serverless.yml or a small bootstrap. Never commit APP_KEY.
• Cold starts: keep the deployment package small (exclude node_modules, tests, docs). Run php artisan optimize in the build. Use provisioned concurrency only if latency is critical.
• Database connections: Lambda concurrency can exhaust MySQL/Postgres connections. Use RDS Proxy or a connection pooler; set DB_CONNECTION and pool sizes conservatively.
• Cache/session drivers: file-based cache and sessions don't persist across Lambda invocations. Use Redis, DynamoDB, or database-backed drivers.
• Debugging: serverless logs -f <function> -t tails CloudWatch. For local reproduction, bref local:invoke with a recorded event payload is more reliable than guessing the event shape.
• Timeouts: set timeout on the Lambda function to match the work; set QUEUE_* and job $timeout consistently. A job timeout longer than the Lambda timeout will be killed mid-run.
• Extension points: the bridge's service provider is the place to register custom handlers, macros, or queue connectors. In v0.3.0, because the queue handler is Laravel-native, you can plug in custom job middleware, queue events, and failure handling without patching the bridge.