Cli Laravel Package

Getting Started

bref/cli is the Symfony Console application behind vendor/bin/bref — the piece that scaffolds a Lambda project, validates serverless.yml, and invokes functions locally. It is not the Lambda runtime and not the Laravel adapter; think of it as the developer-facing control surface around serverless.

1. Install alongside the runtime, not instead of it:

   composer require bref/bref bref/laravel-bridge
   composer require --dev bref/cli
   

   If bref/bref already exposes a bref binary, keep only one provider of vendor/bin/bref to avoid a Composer bin conflict.
2. Run vendor/bin/bref list first — the command set is deliberately small, and reading --help on each is faster than guessing.
3. Scaffold with vendor/bin/bref init and pick the Laravel/HTTP template. Read the three generated files in this order: serverless.yml (the real source of truth for infra), the handler (usually public/index.php), and composer.json (extra-platform requirements for the Lambda PHP build).
4. First use case: deploy a trivial "hello world" function end-to-end before touching Laravel. You want to prove credentials, region, the serverless binary, and layer resolution in isolation. Only then swap in the Laravel handler.
5. Prerequisites to have in place: Node + a pinned Serverless Framework version, Docker (for local invocation), AWS credentials with deploy permissions, and PHP 8.x locally.

Where to look when stuck: the generated serverless.yml beats the docs for what your project actually does, and bref.sh/docs beats blog posts — this package has minimal community footprint (4 stars, no dependents), so third-party answers are scarce and often stale.

Implementation Patterns

Keep two local loops, deliberately. Use php artisan serve for fast iteration on application code, and bref local (which runs the handler inside a Lambda-emulating Docker container) only for parity checks: handler wiring, /tmp filesystem behaviour, missing extensions, environment variables. Don't burn a Docker round-trip on every save.

Deploy through the CLI, not raw serverless. vendor/bin/bref deploy wraps serverless deploy and pre-validates the PHP version against the runtime layer and the required extensions. That validation catches the single most common class of deployment failure before it reaches CloudFormation. Put it in CI as bref deploy --stage=$STAGE and treat --stage as your environment axis.

Use --param (1.3.4+) instead of forking serverless.yml per environment. bref deploy --param key=value forwards parameters into Serverless variable resolution, so you can express environment-specific settings in the one serverless.yml you ship:

provider:
  environment:
    APP_ENV: ${param:app_env, 'production'}
    APP_URL: ${param:app_url, 'https://example.com'}

vendor/bin/bref deploy --stage=staging --param app_url=https://staging.example.com

This is exactly the right axis for non-secret, per-deploy values that used to be duplicated files or hand-edited YAML. Keep defaults in the YAML (${param:key, 'fallback'}) so a bare bref deploy still works. Note this is a deploy-time feature: bref local, serverless invoke run directly, and anything else that doesn't go through bref deploy won't see the same params unless you pass them yourself — so prefer defaults over mandatory params to avoid drift between loops.

Treat serverless.yml as the deployment contract. Everything the CLI and Serverless do flows from it: provider.environment, provider.iam, package.patterns (exclusions), functions (HTTP handler, queue worker, scheduler), and the ${bref:layer.php-8x} layer references. Keep secrets out of it — reference SSM Parameter Store / Secrets Manager and resolve at boot. --param is for configuration, not credentials: params end up in CI logs and shell history.

Laravel-specific wiring is bref/laravel-bridge's job, driven by CLI deploys:

• Filesystem: point FILESYSTEM_DISK at S3; /tmp is the only writable local path.
• Sessions/cache: DynamoDB, Redis, or cookies — never the local file driver.
• Queues: an SQS-backed queue function running php artisan queue:work; enqueue from web functions as normal.
• Scheduler: EventBridge schedule events invoking php artisan schedule:run — not cron.
• Artisan one-offs: invoke a CLI function through Serverless (serverless invoke -f artisan --data '{"cli":"migrate --force"}' or the equivalent your template defines) rather than expecting shell access.

Build-time optimisation belongs in the deploy step. Run composer install --no-dev --optimize-autoloader plus php artisan config:cache route:cache view:cache event:cache as a Serverless hook or CI step, not at runtime. This is where most cold-start wins come from. If you cache config in the build, make sure the values you cache come from --param-driven provider.environment or SSM at boot — not from a locally-sourced .env.

Static assets off the function. Push public/ to S3 behind CloudFront via serverless-s3-sync-style plugins; leave only the front controller in the package. Pair with a custom-domain plugin so ASSET_URL and APP_URL line up per stage — both are natural --param values.

Extend at the Serverless layer, not the CLI layer. Custom commands live in serverless.yml plugins and lifecycle hooks, Composer scripts, and a custom Dockerfile for local parity. Don't fork the CLI to add behaviour.

Gotchas and Tips

• bref local requires Docker and pulls a large image on first run. Expect a slow first invocation; subsequent ones are cached. It is also not a perfect emulator — extension and php.ini differences bite rarely but memorably.
• bref deploy shells out to serverless. A missing/old Node, a global serverless that isn't the pinned one, or a Serverless Framework major-version/licensing change will make the CLI fail in confusing ways. Pin serverless in package.json and pin bref/cli in composer.json — with a low-adoption package, a minor bump is not a low-risk event.
• --param is deploy-scoped and not a secret store. It only applies to the bref deploy invocation you pass it on. Params are visible in CI logs, shell history, and CloudFormation/Serverless output; put credentials in SSM/Secrets Manager and read them in config/. If you rely on params without defaults, bref local and direct serverless calls will resolve ${param:...} differently or fail — always supply a ${param:key, 'default'} fallback.
• .env files are not deployed. Lambda env vars come from serverless.yml (including --param values) or SSM/Secrets Manager. If something works locally and 500s in Lambda, env() returning null is the first hypothesis.
• config:cache freezes env at build time. Any env() call outside config/ will silently return null once cached. Grep for env( in app/ before deploying.
• Read-only filesystem. Only /tmp (512 MB, per-invocation, not shared) is writable. storage/logs/laravel.log writes will fail — set LOG_CHANNEL=stderr so CloudWatch captures output.
• Package size is a hard wall. 250 MB unzipped. Use package.patterns to drop node_modules, tests, docs, and seeders; big vendor trees and unpruned public/ are the usual culprits.
• Timeouts aren't uniform. Lambda allows 15 minutes; API Gateway caps a synchronous HTTP response around 29 seconds. Long jobs belong on the queue function.
• Memory buys CPU. Raising memorySize is often the cheapest cold-start fix — test 512/1024/2048 before rewriting code.
• Debugging: --verbose on the CLI, then CloudWatch via serverless logs -f <fn> -t. Reproduce with bref local <fn> <event.json> using a captured real event payload (API Gateway proxy, SQS batch) — hand-written event shapes are the most common reason a "broken" function works fine when replayed.
• Layer references are region/version sensitive. Changing the AWS region or bumping the PHP layer without re-testing extensions (intl, gd, imagick) is a classic post-migration failure.
• Score context: a 4-star, zero-dependent package looks alarming, but adoption is transitive through Bref itself. Judge it by bref/bref releases, and budget time to read the Bref docs rather than search for answers.