Cli Laravel Package

Technical Evaluation

Architecture fit

• bref/cli is the command surface for Bref, the PHP-on-AWS-Lambda runtime. It lives in the build/deploy plane, not the request path: it scaffolds projects (bref init), packages and uploads artifacts (bref deploy), invokes functions locally via Docker (bref local), and reads logs. It is a Symfony Console application that shells out to Serverless Framework or AWS SAM and the AWS SDK.
• Fit is therefore binary: high if the target architecture is PHP on Lambda, near-zero otherwise. It does not improve a container, ECS, or EC2-based PHP deployment.
• Because it operates on CloudFormation stacks and S3 artifacts, it becomes a privileged part of the delivery pipeline rather than a library dependency. Budget governance attention accordingly.
• Release 1.3.4 adds bref deploy --param for serverless.yml applications — a pass-through for Serverless Framework --param values at deploy time. It is purely additive: no breaking changes, no deprecations, no runtime-layer or PHP-version coupling introduced. The architectural evaluation is unchanged.

Integration feasibility

• Straightforward to install (Composer dev dependency pulled in by bref/bref, or a standalone PHAR), but it presumes a fair amount of surrounding infrastructure: AWS credentials with deploy-role permissions, a PHP 8.x toolchain, plus Node/Serverless Framework or the SAM CLI and Docker for local invocation.
• The real integration cost is not the CLI — it is IAM role design, stack naming, artifact retention, and CI identity federation (OIDC). Expect the CLI work to be a day and the platform work to be a sprint.
• 1.3.4 makes parameter injection possible without templating serverless.yml or maintaining per-environment config files. Marginal convenience, not a capability we lacked — serverless deploy --param was already reachable by shelling out. It reduces the temptation to bypass the CLI in the pipeline, which is a mild plus for standardization.

Technical risk

• Low blast radius, high privilege. It can't crash production traffic directly, but it mutates stacks and holds credentials that can. Treat it as a privileged CI component with least-privilege roles and manual prod approval.
• Version coupling is the dominant risk. bref/cli, bref/bref, the Lambda runtime layers (provided.al2/provided.al2023), PHP minor versions, and the Serverless/SAM CLI must move together. Unpinned versions produce failures that surface at deploy time, not build time.
• Feature surface is driver-specific. --param applies only to the Serverless Framework path. Teams on SAM or raw CloudFormation get nothing from this release, which sharpens the "pick one driver" decision rather than resolving it — every feature the CLI adds deepens the Serverless-first assumption.
• Weak external validation. 4 stars, 0 dependents, score ~19.5 and opportunity ~36 signal a package with essentially no independent community footprint. This is almost certainly a measurement artifact — most consumers install bref/bref, which pulls the CLI, so bref/cli is undercounted as a direct dependency. Still, the practical conclusion holds: treat it as first-party-coupled tooling with no community backstop, not as a broadly battle-tested open-source component.
• The future-dated release (2026-10-06) should be reconciled against the actual tag history before pinning; if the registry metadata is unreliable, pin by commit SHA. 1.3.4 does not alter this — the sequencing anomaly persists across releases, so it is a registry-metadata issue to resolve, not a one-off.

Key questions

1. Is PHP-on-Lambda an actual requirement, or is this being evaluated as a generic deployment tool?
2. Is bref/bref already in composer.json, and which deploy driver is in use — Serverless Framework, SAM, or raw CloudFormation? (1.3.4 is only useful on the first.)
3. Who owns the IAM deploy role, and can CI assume it via OIDC rather than long-lived keys?
4. Which Lambda runtime and PHP minor are targeted, and what is the runtime deprecation horizon?
5. Do we need bref local Docker parity with production, or is staging sufficient?
6. If Laravel Vapor is in play, which one wins? Running both creates two divergent deploy paths.
7. What is the maintainer's release cadence and bus factor, and do we need a commercial support arrangement?
8. If we adopt --param, what is the source of truth for parameter values — pipeline config, checked-in files, or ad-hoc CLI invocation?

Integration Approach

Stack fit

• Composer-installed dev dependency for local use; a pinned PHAR is preferable in CI to avoid dragging dev dependencies into the build image.
• CI requirements: PHP 8.x, AWS credentials (OIDC-assumed role strongly preferred), and either Node + Serverless Framework or SAM CLI. GitHub Actions and GitLab CI both work cleanly with this shape.
• 1.3.4 slots in as a patch bump on an existing 1.3.x pin. No pipeline changes required to stay current; adopting --param is opt-in.

Migration path

• Phase 0 — spike: non-production AWS account, bref init scaffold, one trivial function deployed and invoked. Validates credentials, runtime layer, and packaging end to end.
• Phase 1 — pilot: migrate one low-risk, low-traffic service. Keep the existing deploy path intact and documented as the rollback.
• Phase 2 — standardize: codify the deploy as a reusable pipeline template, retire the legacy path per service.
• If Vapor is the incumbent, treat this as a replacement decision, not an addition — dual deploy tooling on the same app is a known source of drift and confused ownership.

Compatibility

• Pin bref/cli and bref/bref to matching versions; mismatches between CLI and runtime layer are the most common failure. bref/cli 1.3.4 is a safe in-range patch; it still needs to move in lockstep with bref/bref.
• Track the Lambda runtime lifecycle explicitly (AL2 deprecation forces periodic forced upgrades). Put a calendar reminder against the runtime EOL, not just the package release notes.
• Verify PHAR checksums if using the PHAR distribution; that adds a supply-chain verification step to CI that must be owned.
• If adopting --param, confirm the target Serverless Framework version supports the parameter being passed — the CLI will forward it, but the value only takes effect if the serverless.yml references it.

Sequencing

1. Confirm PHP-on-Lambda is a genuine requirement and that the operational model (cold starts, 15-minute ceiling, 250 MB unzipped artifact limit) is acceptable.
2. Pin versions; validate the scaffold in a sandbox account.
3. Wire OIDC-based CI credentials and a scoped deploy role.
4. Put deploy behind manual approval for production; automate non-prod fully.
5. Add local-invoke parity and a documented artifact rollback (retain prior S3 artifacts; CloudFormation rollback alone is not sufficient).
6. Decide the parameterization strategy before the second service onboards — --param, checked-in per-stage files, or both — and write it into the pipeline template.
7. Write the runbook before the second service onboards.

Operational Impact

Maintenance

• Minimal code footprint on our side, but a continuous upgrade treadmill: PHP minor upgrades, Lambda runtime deprecations, and Serverless/SAM version drift all force touch points at least annually.
• Maintainer concentration is a real concern — this is a small-team project with no visible commercial support tier. 1.3.4 is a single-contributor, single-commit patch, which is consistent with the project's operating shape but also evidence that throughput depends on one person. Plan for the possibility of upstream stall.

Support

• Expect GitHub issues, not SLAs. If the workload is business-critical, either budget for consulting or maintain a credible fallback (containerized PHP on ECS/Fargate) and rehearse it once.
• Internal ownership should sit with the platform team, not individual service teams, to avoid N divergent deploy configurations.

Scaling

• The CLI itself does not scale — it runs once per deploy. The scaling constraints are elsewhere: CloudFormation stack locks require serialized deploys per environment, and artifact size becomes binding for Laravel monoliths (vendor + app commonly lands in the 50–100 MB range against a 250 MB unzipped limit). Exclusion rules need tuning and verification per service.
• Lambda concurrency limits, cold-start behavior, and provisioned concurrency costs are architecture-level concerns the CLI surfaces but does not solve.
• --param is a per-invocation mechanism; it does not scale into a config-management system. Environments beyond a handful will want the parameter values checked in, not injected ad hoc.

Failure modes

• Credential/role assumption failure — usually a silent CI misconfiguration until deploy time.
• Stack stuck in ROLLBACK_COMPLETE, requiring manual deletion before redeploy.
• Artifact exceeding size limits after a dependency bump.
• Missing PHP extensions not compiled into the runtime layer — passes deploy, fails at invocation.
• Timeout/memory misconfiguration that only manifests under production load.
• Serverless Framework version drift breaking the CLI's plugin contract.
• Parameter drift (new in 1.3.4's blast radius): a --param value supplied by hand or by a divergent pipeline produces a stack whose effective config matches neither the repo nor staging. No record of passed params lands in version control by default.
• Concurrent deploys to the same stack colliding; mitigate with pipeline concurrency locks per environment.
• PHAR integrity/version mismatch between local and CI.

Ramp-up

• Engineers comfortable with PHP and Composer will learn the CLI in hours. The actual ramp is AWS-native: IAM, CloudFormation semantics, Lambda limits, and observability (CloudWatch). Estimate 1–2 weeks for one engineer to reach production-ready competency, plus runbook authoring and a second engineer cross-trained to avoid a single point of knowledge.
• Given the low adoption signals, front-load the spike and treat the first production deploy as a learning exercise rather than a routine cutover.
• 1.3.4 does not change the ramp. It adds one flag; if the team standardizes on --param, document the convention in the runbook or it will become tribal knowledge.