Sidecar lets a Laravel app ship and run Lambda functions in other languages

A function is a PHP class plus a folder of files

Sidecar packages, creates, deploys and executes Lambda functions from your Laravel application, and the model it asks you to follow is unusually small. Every Sidecar function requires two things: a PHP class, and the files you want deployed to Lambda.

The class extends LambdaFunction and overrides two methods. The handler method says which entry point inside the package is the function, and the package method says which files and folders travel with it. The example in the README is an OgImage class that would generate a social preview image for blog posts using Node on Lambda:

class OgImage extends LambdaFunction
{
    public function handler()
    {
        return 'lambda/image.handler';
    }

    public function package()
    {
        return [
            'lambda',
        ];
    }
}

That is the whole contract. The handler string points at a file path and an exported function name inside the deployed package, and the package method returns the paths to ship. The README is blunt about the rest, that there are a lot more options but that is all that is required.

The companion file is the actual implementation, in the language of your choice, sitting in the project rather than in a separate repository. For the image example it is a JavaScript file in resources/lambda that pulls in the canvas package, draws text onto a 1200 by 630 canvas, and returns the result as a JPEG data URL. The comment in that handler is worth noting because it describes the contract precisely: it reads the text out of the event passed in from PHP.

So the payload goes from PHP to another language and the result comes back the same way. That is the shape of the whole package.

Deploy with an artisan command, call it from a route

Deployment is a single artisan command, and the README gives it with the activate flag:

php artisan sidecar:deploy --activate

The flag name is the useful part. It suggests that deployment and activation are separate steps, so a function can be created on AWS before it is wired up to serve traffic, and that the flag is what makes the new version the live one.

Execution is equally short, because the PHP class is callable directly. The README's example routes a URL to a static call on the class, passing an array:

Route::get('/ogimage', function () {
    return OgImage::execute([
        'text' => 'PHP to JS and Back Again!'
    ]);
});

No HTTP client, no API key management, no signed request building in the application code. The payload from execute is passed over to the JavaScript function, the function generates an image and sends it back to PHP.

What that buys is the thing the README says the package is for: reducing the complexity of deploying small bits of code to Lambda. A Laravel application stays the entry point for everything, and a language that does not fit the rest of the application is confined to a folder and a class.

The install is ordinary Composer, requiring the package by name, and the package is published under the hammerstone vendor name on Packagist even though the repository lives under the author's own account. The README points at the full documentation, at a Laracasts series for people who prefer to watch, and asks readers to follow the author on Twitter for updates.

Any runtime Lambda supports, including OS-only

The list of runtimes is the most concrete thing about the package, and it is long. You can write functions in Node.js 20 or 18, Python 3.12, 3.11, 3.10 or 3.9, Java 21, 17, 11 or 8,.NET 8 or 6, Ruby 3.3 or 3.2, and the OS-only runtime on Amazon Linux 2023 or Amazon Linux 2.

The README makes the point more generally than the list does, saying that any runtime that Lambda supports you can use. The list is therefore a snapshot rather than a boundary, and the practical implication is that the package is not tied to a language.

The OS-only entries are the ones worth pausing on. The other runtimes are managed by AWS, with a specific Node, Python or JVM version. The OS-only runtime gives you a full Linux environment, which means a native module or a system binary can be shipped the way you would ship it in a container.

That option comes with a cost, and the package does not hide it. An OS-only runtime means you are responsible for the environment, so your package method has to carry more than your function, and the size of the deployment grows. It is the right choice for a function that needs a browser binary, like the headless Chrome case the README names as a motivating use case, and the wrong choice for a small utility.

Because the runtime choice is a property of the function rather than of the application, a single Laravel project can carry functions in several languages at once, each with its own handler and its own packaged files.

What Sidecar refuses to do, and why that is a feature

The section on what Sidecar does not do is the most useful part of the README, and it is worth quoting in substance rather than paraphrasing, because the narrowness is deliberate.

Sidecar does not handle any API Gateway, Databases, Caches, and the only thing it concerns itself with is packaging, creating, deploying and executing Lambda functions. It does not provide a way to execute a function via HTTP; you must execute it from your Laravel app through the provided methods. And if you need those other services, you are encouraged to use the instances that the Laravel platform has set up for you, or to set them up yourself.

That last point is the design decision that makes the package usable. A package that also provisioned an API Gateway and a database would be competing with the platform. By refusing, Sidecar stays small enough that a team can reason about what it does, and it defers the infrastructure questions to the serverless platform the application already runs on.

The trade is that the caller has to be in the application. There is no public URL for a function, which means no webhook can target it directly and no external system can call it. If your requirement is a small HTTP endpoint, this is the wrong shape and the README says so outright.

The boundary also appears in the repository layout. There is a config directory and a src directory, a tests directory alongside a test directory, a phpunit.xml.dist for the test configuration, a pint.json for code style, a CHANGELOG.md, a docs directory and a contents.zip at the root. There is no infrastructure-as-code in the tree, which is consistent with a package that does not deploy anything except the function itself.

Why it exists, and where Vapor already does the job

The Why Sidecar Exists section gives the clearest account of the problem, and it is a problem of deployment friction rather than of language.

AWS Lambda lets you run code without provisioning servers, and the Laravel platform brought that power to Laravel, letting plain Laravel apps run on a serverless platform with speed, security and reliability. The README calls using Lambda through that platform a wonderful developer experience, and then makes the concession that matters: there are times when building your application you need to run just one or two Node functions for some reason.

The named cases are taking screenshots with headless Chrome, generating images, and doing server-side rendering of a JavaScript front end. Then the same argument extends to Python, Ruby and Java.

The specific obstacle is named too. When running on a serverless platform, it is not quite as easy as installing Node and running your functions, because you do not have access to the server. The outcome is that you end up deploying a single Vercel or Netlify function and calling it over HTTP, or just forgetting the thing altogether.

That last phrase is the sharpest description of the problem in the README, and it explains the shape of the solution. Sidecar brings the ease of that platform to the non-PHP functions, so a Node or Python job is packaged and deployed from the same repository and called synchronously from PHP, with no second service, no second deployment pipeline and no forgotten TODO.

A young package with an explicit invitation to report problems

The project says plainly that it is still under development and asks you to open issues for anything you run into. That is a useful signal from a maintainer, and it is worth pairing with the version history.

The releases are v0.8.0 on 2026-05-31, v0.7.1 on 2025-08-22 and v0.7.0 on 2025-05-07, and the last push to the repository was on 2026-05-31, the same day as the newest release. The repository is not archived.

So the 0.8.0 release is the current line and the branch has not moved much beyond it. The default branch is main, and the documentation lives at hammerstone.dev/sidecar/docs/main, so the docs are versioned alongside the package.

A version below 1.0 with an explicit request for issue reports is a package to adopt with your eyes open. The API surface is small enough to read in an afternoon, since the core of it is one base class and two overridden methods, so the risk is not that the abstraction is wrong but that details will change. A team that pins the version and reads the changelog before each upgrade will not notice; a team that lets it float on a schedule might.

The licence is MIT, which for a package that runs inside the request path of a production application removes the usual commercial question. The repository carries a LICENSE file and a CHANGELOG.md.

One more detail in the layout is worth a note: there is both a test directory and a tests directory, alongside a phpunit.xml.dist. That is the kind of small inconsistency that suggests an active refactor in progress, and it is another reason to pin a version.

Editorial conclusion

Sidecar suits a Laravel team that has one or two small jobs to run in another language, a screenshot, an image generator, a Python script, and wants them packaged and deployed from the same repository rather than as a separate service. It is the wrong tool for anything that needs an HTTP endpoint, a database or a cache attached, because the package explicitly refuses those concerns and points you at the platform's own instances instead, and it is the wrong tool for a team unwilling to manage AWS credentials and Lambda function lifecycle themselves. Before you adopt it, read the overview documentation at hammerstone.dev/sidecar/docs, note that the project states it is still under development and asks for issues, and plan for a version 0.x package whose 0.8.0 release landed on 2026-05-31 with the last push on the same day.

Frequently asked questions

Official sources

1. aarondfrancis/sidecar on GitHub
2. License: MIT
3. Project website
4. README
5. Releases