Sidecar Laravel Package

Technical Evaluation

Architecture fit

Sidecar is a thin Laravel-native orchestration layer over AWS Lambda. Its architecture mirrors Laravel conventions closely, which is the primary reason a TPM can defend it in a design review:

• Configuration-as-code in PHP. Every function is a LambdaFunction subclass (handler(), package(), plus overridable memory/timeout/runtime/env/layers). This keeps serverless function definitions inside the same review, lint, and test pipeline as the application, rather than in Terraform, SAM, or a separate Node repo. For a TPM this collapses a cross-team dependency into a single-repo change.
• Bounded scope by design. The README is explicit: Sidecar does not provision API Gateway, databases, caches, or HTTP endpoints. Execution is only from the Laravel app. That is a feature for governance — it means the package cannot silently expand your AWS blast radius beyond Lambda + S3 + IAM + CloudWatch Logs, and it cannot become an externally reachable attack surface.
• Deploy and invoke are the same abstraction. php artisan sidecar:deploy --activate and Function::execute([...]) mean the TPM can scope an initiative as "one PR adds one function" — a small, estimable unit of work with a predictable rollout.
• Polyglot escape hatch. Node 20/18, Python 3.9–3.12, Java 8–21, .NET 6/8, Ruby 3.2/3.3, and OS-only runtimes are supported, plus container images and custom architectures. It solves the "we need exactly one headless-Chrome / image-resize / SSR / PDF / Python-ML script" problem without standing up a second deployable service and a second on-call rotation.

Integration feasibility

Low ceremony, moderate governance. composer require hammerstone/sidecar plus a sidecar:configure flow that provisions the IAM role and S3 artifact bucket is a genuine one-sitting setup. The real TPM work is not the install — it is the entitlement and boundary work:

• AWS account/sub-account access, cross-account deploy role, and S3 bucket ownership must be negotiated with whoever owns cloud infrastructure. Sidecar assumes a deployment user with Lambda + S3 + IAM + ECR permissions (ECR added in 0.3.10); that is a non-trivial privilege ask and should be scoped to a dedicated CI role, not a developer's personal credentials.
• Environment separation is handled via sidecar.env (0.2.0), which decouples the Sidecar environment name from APP_ENV. This is the single most important config decision for multi-developer teams — without it, every developer on local overwrites the same set of Lambda functions. A TPM should make this a hard convention from day one.
• Version management is real: aliases, --activate, --pre-warm, and automatic sweeping of old unused versions all exist, so the lifecycle story is credible rather than hand-rolled.

Technical risk

The changelog also shows steady, responsive stewardship: Windows path fixes, Guzzle v6 support, Arrayable payload casting, macroable package, Laravel 9/12/13 compatibility PRs, and runtime deprecations tracked against AWS's own deprecation calendar. For a pre-1.0 package, the hygiene signals are strong.

Key questions to resolve before committing

1. Is there an existing Vapor footprint? If yes, Sidecar is a natural complement (Vapor handles the app, Sidecar handles the auxiliary functions). If no, are we prepared to own AWS Lambda operations directly?
2. Which team owns the IAM role and S3 artifacts bucket — application engineering or platform/cloud?
3. What is our upgrade policy for a pre-1.0 dependency, and who is on the hook if upstream goes quiet for six months?
4. Are the target use cases all sub-6 MB, sub-15-minute, PHP-orchestrated? If any consumer is external, Sidecar is the wrong tool.

Integration Approach

Stack fit

Sidecar targets the Laravel ecosystem directly and has kept pace with it — Laravel 9 support arrives in 0.3.8, 12.x in 0.7.0, 13.x in 0.8.0. It requires Composer, an AWS account, and a Laravel app that already treats Artisan as the operational interface (which any Laravel team does). The two-file mental model — a PHP class plus a payload directory — is comprehensible to a mid-level Laravel developer in under an hour.

The natural fit is: a Laravel app that needs one to three non-PHP capabilities and already deploys to AWS. The poor fit is: a polyglot platform team that already runs Terraform/CDK, or a team needing externally callable functions.

Migration path

The realistic migration is not "replace our serverless platform" — it is "repatriate the ad-hoc serverless functions we bolted on."

1. Inventory. List every Vercel/Netlify function, standalone Node script, or external microservice currently invoked over HTTP from Laravel for a narrow purpose (OG image generation, PDF rendering, headless-Chrome screenshots, JS SSR, a Python data transform).
2. Select one. Pick the lowest-traffic, lowest-blast-radius candidate — typically OG image generation, which is idempotent, cacheable, and non-critical.
3. Port in place. Move the handler under resources/lambda/, create the LambdaFunction subclass declaring handler(), package(), and an explicit runtime(), then sidecar:deploy --activate.
4. Cut over behind a flag. Replace the HTTP call with Function::execute(). Because both return a string or structured payload, the call-site diff is small.
5. Retire. Delete the old function and its secrets once traffic has moved.

Repeat per function. There is no big-bang requirement, and each step is independently revertible — which is the property that makes this approvable.

Compatibility considerations

• Pin the Sidecar version exactly ("hammerstone/sidecar": "0.8.0", not ^0.8) given the pre-1.0 status.
• Always declare runtime() explicitly. The 0.6.0 changelog demonstrates that an undeclared runtime silently changes under you on upgrade. This should be a written coding standard, not a suggestion.
• Verify Guzzle major version compatibility (v6 and v7 both supported since 0.3.9) against the rest of the app's dependency graph.
• Confirm PHP/Laravel version against the compatibility PRs (Laravel 13.x landed in 0.8.0).
• Set sidecar.env explicitly and map it to your environment tiers (production, staging, per-developer local-{name}).
• Verify architecture (arm64 vs x86_64) and ephemeral storage size are declared per function — both are configurable, and both materially affect cost and cold-start behavior.

Sequencing

Operational Impact

Maintenance

This is the dominant operational consideration and should be stated plainly to stakeholders: Sidecar is a pre-1.0 package maintained primarily by one individual, with zero Packagist dependents. The changelog is active and well-curated, releases ship with contributor credits, and the author publishes an accompanying Laracasts series and hosted docs — all good signals — but the bus-factor is one.

Practical consequence: treat the dependency as vendored in spirit. Pin exactly, review every upgrade, and maintain a documented "fork path" so that if upstream stops, a named engineer can own the fork with bounded effort. Given the package is a few thousand lines wrapping the AWS SDK, forking is genuinely viable — this is the risk mitigation that makes the risk acceptable.

Ongoing maintenance burden is low in steady state: runtime constants need periodic refreshing against AWS deprecation schedules (the project already tracks these — Node 16, Python 3.8, and .NET 7 were deprecated in 0.7.0), and Laravel major-version compatibility needs a bump roughly annually.

Support

Support is community-driven: GitHub issues (the README explicitly says "please open issues for anything you run into"), the hammerstone.dev docs site, and the Laracasts series for onboarding. There is no vendor SLA. Internal support therefore depends on at least two engineers on the team being comfortable with AWS Lambda primitives independently of Sidecar — the package is thin enough that debugging almost always lands in AWS, not in Sidecar.

Scaling

Scaling is AWS's problem, which is the honest appeal. Concurrency, memory, timeout, ephemeral storage, and architecture are all declarative per function. Warm-keeping is available via sidecar:warm and --pre-warm flags on deploy and activate, but is opt-in with zero instances by default — meaning a TPM should expect and plan for cold-start latency on low-traffic functions, and should make warm-keeping an explicit, cost-reviewed decision rather than an afterthought. Old version sweeping keeps the version count from growing unbounded.

The real scaling ceiling is the 6 MB synchronous payload/response limit and 15-minute invocation cap. Use cases should be scoped to bounded artifacts (an image, a PDF, a rendered HTML fragment, a JSON transform), not to data movement.

Failure modes

• Deploy-time races. The changelog shows a sustained history of fixes here: 409 handling moved into client middleware (0.3.6), wait-until-function-updated added (0.3.4), env-var updates waiting on function update (0.3.5). Mitigation: serialize deploys per function in CI; never allow two pipelines to target the same function concurrently.
• Naming drift on upgrade. A function-naming change (as in 0.4.0) can produce a new Lambda function rather than updating the existing one, silently leaving the old one live and the new one unaliased. Mitigation: post-deploy assertion that the expected function name and alias exist and point at the latest version.
• Runtime drift on upgrade. Undeclared runtimes change silently (0.6.0). Mitigation: explicit runtime() on every class, plus a lint rule.
• Cold-start latency spikes on spiky, low-volume endpoints.
• Credential/permission failure at deploy, most likely after an IAM policy change elsewhere — the 0.1.1–0.1.3 patch line was entirely sidecar:configure AWS error fixes. Mitigation: a smoke-test deploy in CI on a schedule, not just on release.
• Log/output parsing edge cases (0.3.10 "gracefully handle unexpected log output") — treat invocation failures as opaque unless logging is configured deliberately.
• Silent payload truncation if a response approaches the 6 MB cap.

Ramp-up

Onboarding cost is genuinely low for a Laravel team and is the strongest argument for the package from a people perspective:

• Day 1: a Laravel developer who has never touched Lambda can read the two-file example (an OgImage class plus image.js) and understand the entire model. php artisan sidecar:deploy --activate is the only new command required.
• Week 1: the developer can add memory, timeout, environment variables, and a second function by copying the pattern.
• The real gap is not Sidecar — it is Lambda literacy. Cold starts, concurrency limits, IAM execution roles, payload ceilings, and CloudWatch are AWS concepts the package deliberately hides. A team that never learns them will struggle the first time something fails in a way Sidecar cannot explain.

Recommended ramp plan: one engineer attends the Laracasts series and runs the Phase 0 spike, then writes a one-page internal runbook covering deploy, rollback, log inspection, and the explicit-runtime rule. That runbook — not the package documentation — is the artifact that actually de-risks adoption across the team.

Bottom line for a TPM: Sidecar is a narrow, well-scoped, well-maintained tool that converts a recurring "we need one Node/Python thing" architectural decision into a routine pull request. It is not a platform bet and should not be positioned as one. Approve it for bounded auxiliary functions behind an explicit runtime, an explicit sidecar.env, an exactly-pinned version, and a named fork owner — and it will pay for itself in avoided second-service overhead within a sprint or two.