Weave Code
Sidecar Laravel Package
hammerstone/sidecar
Sidecar lets your Laravel app package, deploy, and execute AWS Lambda functions in Node, Python, Java, .NET, Ruby, or custom runtimes. Define a PHP class and files, then invoke serverless functions directly from PHP.
Deploy and execute AWS Lambda functions from your Laravel application.
Frequently asked questions about Sidecar
- What is hammerstone/sidecar used for in a Laravel app?
- Sidecar packages, deploys, and invokes AWS Lambda functions from PHP, so you can offload a single non-PHP capability such as headless-Chrome screenshots, OG image generation, JS server-side rendering, or a Python/Ruby/Java/.NET script. Instead of standing up a separate microservice or shelling out to a local binary, you define a LambdaFunction class with handler() and package() methods and call it from Laravel. It is intentionally narrow: it does not run PHP on Lambda, provision API Gateway, or expose your function over HTTP.
- How do I install Sidecar and deploy my first Lambda function?
- Run composer require hammerstone/sidecar, then create a class that extends Hammerstone\Sidecar\LambdaFunction and implement handler() and package(). Use php artisan sidecar:configure to bootstrap the AWS-side prerequisites (deployment user and role, plus an S3 packaging bucket), and php artisan sidecar:deploy --activate to ship and activate the function. Most of the real integration work is on the AWS side: IAM permissions across Lambda, S3, ECR, and IAM, plus credentials for CI.
- Which AWS Lambda runtimes does Sidecar support?
- Sidecar supports the Lambda runtimes it tracks in the package, including Node.js 18 and 20, Python 3.9 through 3.12, Java 8 through 21, .NET 6 and 8, Ruby 3.2 and 3.3, and the OS-only Amazon Linux 2 and Amazon Linux 2023 runtimes. Container image support was added in v0.3.2, so any runtime Lambda supports is reachable. Note that the package has dropped deprecated runtimes over time (Node 16, Python 3.8, and .NET 7 were removed in v0.7.0), so you inherit AWS's runtime deprecation treadmill.
- Is Sidecar a replacement for Laravel Vapor?
- No. Vapor runs your PHP application itself on Lambda, while Sidecar deploys non-PHP Lambda functions that your Laravel app invokes synchronously from PHP. Sidecar explicitly does not provision API Gateway, databases, or caches, and it does not expose your function over HTTP. The two can coexist: a Vapor-hosted or traditional Laravel monolith can call a Sidecar function for a capability PHP does not handle well.
- How do I configure AWS credentials and IAM permissions for Sidecar?
- The sidecar:configure command bootstraps the AWS-side prerequisites, creating a deployment user and role plus an S3 bucket used for packaging. Deployments need meaningful permissions across Lambda, S3, ECR, and IAM in whichever environment runs sidecar:deploy, which is usually CI. That is a wider blast radius than most Laravel packages, so scope the credentials to a dedicated deployment identity rather than reusing broad admin keys.
- Which Laravel versions does Sidecar support?
- Sidecar is a standard Composer package built on Laravel conventions: Artisan commands, PHP config files, and container bindings. Because the package is pre-1.0 and has changed behavior in minor releases, verify the exact laravel/framework and PHP constraints in its composer.json on Packagist before upgrading either your app or the package. Pin the version in composer.json so a routine update cannot silently move you onto a new requirement set.
- Can I invoke a Sidecar Lambda synchronously in a user-facing request?
- Yes, Sidecar invokes the function synchronously from PHP, which means Lambda latency including cold starts becomes user-facing request latency. Synchronous invocation also has a 6 MB payload ceiling, and while Lambda itself allows up to 15 minutes, the enclosing web request almost never does. For latency-sensitive paths, use provisioned concurrency and the sidecar:warm command with --pre-warm, or push the invocation to a queue.
- How do I stop local deployments from overwriting other developers' functions?
- Sidecar supports a separate sidecar.env file so that multiple developers running with APP_ENV=local do not deploy over each other's functions. The package also offers version sweeping for stale deployments and alias-based activation, so old versions can be cleaned up rather than piling up. Use these alongside aliases to keep local, staging, and production targets clearly separated.
- Is Sidecar stable enough for production, or should I pin the version?
- Sidecar is pre-1.0 and has a history of breaking changes in minor releases: v0.4.0 changed the function-naming algorithm, which could re-create existing functions under new names, and v0.6.0 changed the default runtime from Node 14 to Node 20 for functions that did not declare one. It is also a single-maintainer project with a small dependent base, and the README still describes it as under development. Pin the version, read changelogs before upgrading, and budget for the bus-factor risk.
- How do I test Sidecar functions and inspect Lambda errors?
- You can unit test your LambdaFunction subclasses' handler() and package() methods like any other PHP class, while end-to-end deploys and invocations require real AWS credentials in a non-production account. Function failures come back as a SettledResult, so whether an error surfaces as an exception or is quietly inspected is a developer choice in your calling code. There is no built-in tracing or log correlation beyond CloudWatch, so plan your own observability around the invocation.
Weaver
How can I help you explore Laravel packages today?