Sidecar Local Laravel Package

Product Decisions This Supports

• Build vs. buy on local serverless emulation. This package lets a Laravel app invoke Lambda-style handlers (Node.js, Python) on the developer's machine using real AWS Lambda runtime images, which removes the "build our own Docker orchestration for local function testing" line item from the roadmap.
• Architecture choice: Laravel-as-orchestrator vs. full serverless. If the team wants Laravel to own the request path while offloading discrete workloads (image processing, PDF generation, ML inference, third-party webhooks) to isolated functions, this package makes that hybrid architecture cheap to prototype and demo before committing.
• Developer experience investment. sidecar:local --run now defaults to a Docker-in-Docker topology with managed daemons and orphan cleanup — this is the kind of change that trades setup friction for "one command and it works," a direct lever on onboarding time and CI reliability.
• Sail and container-first workflows. --sail support signals alignment with teams already standardized on Laravel Sail; adopting this does not force a second local dev paradigm on the team.
• CI strategy. The package now ships its own Docker integration tests and a 2.0 compatibility matrix — evidence the maintainers treat local runtime fidelity as a supported contract, which de-risks using it as a test dependency in our pipelines.
• Upgrade sequencing decision. Dropping Laravel 11 and PHP 8.1 forces a coordinated platform upgrade. That is a roadmap input, not a footnote: either we schedule the PHP/Laravel bump first, or we pin to the 1.x line and accept divergence.

When to Consider This Package

Consider it when:

• The product runs (or plans to run) Node.js or Python AWS Lambda handlers that a Laravel application needs to invoke, and local fidelity matters — the resolver now pins to real public ECR Lambda runtime images rather than hand-rolled containers.
• The team is on Laravel 12+ and PHP 8.2+; 2.0.0 explicitly removes Laravel 11 and PHP 8.1, so older stacks must stay on 1.x.
• You want reproducible local invocation and clean teardown — scoped Compose projects with --remove-orphans and --stop semantics reduce the "stale container ate my afternoon" class of support tickets.
• Developers already use Docker or Sail; the DinD requirement is a real prerequisite, and hosts that block nested virtualization (some CI runners, hardened laptops, certain managed VDI setups) will not get value here.
• You need configurable networking across environments — SIDECAR_LOCAL_HOST lets the Lambda client endpoint adapt to Docker networking layouts instead of hardcoding localhost.

Look elsewhere when:

• The stack is PHP-only with no Lambda or containerized function workloads — the operational overhead buys nothing.
• You are committed to Laravel 11 or PHP 8.1 in the near term and cannot absorb a platform upgrade.
• The team cannot run Docker-in-Docker (restricted CI, no privileged containers) and will not invest in workarounds.
• You need production Lambda deployment, provisioning, or IAM management — this is a local development and testing tool, not an infrastructure-as-code or deployment solution.
• Windows-native or non-Docker development is a hard requirement for a meaningful share of the team.

How to Pitch It (Stakeholders)

For executives: This is a developer-productivity package, not a customer-facing feature. It lets our Laravel application call serverless functions locally the same way it will in production, using genuine AWS Lambda runtime images inside Docker. The payoff is shorter onboarding, fewer "works on my machine" defects, and the ability to validate a hybrid Laravel-plus-serverless architecture without standing up cloud infrastructure. Cost is low — an open-source dependency plus a platform upgrade we likely need anyway.

For engineering leadership: Version 2.0.0 is a meaningful maturity step. Local invocation now defaults to a Docker-in-Docker topology with a managed daemon, isolated runtime containers, scoped Compose projects, and orphan removal — the operational sharp edges around stale containers and manual cleanup are largely gone. A runtime image resolver tracks supported Node.js and Python Lambda versions, and Docker integration tests now run in CI against a defined compatibility matrix, so the package is testable and its support surface is explicit.

For engineering teams: Two things to plan for. First, 2.0.0 is breaking on platform support: Laravel 11 and PHP 8.1 are removed, so the upgrade is gated on our framework and PHP versions. Second, the default local runtime is now DinD, which requires Docker with nested-container capability; the --sail option covers teams on Sail, and SIDECAR_LOCAL_HOST handles endpoint differences across Docker network setups. Teams needing a lighter footprint or unable to run DinD should stay on 1.x deliberately rather than drift into it.

Recommendation: Adopt on new or actively upgraded Laravel 12 / PHP 8.2+ services with Node or Python Lambda workloads. For the existing Laravel 11 estate, pin 1.x and treat the platform upgrade as the gate — do not let the version drift be discovered during a routine composer update.