Deploy and execute non-PHP AWS Lambda functions from your Laravel application.

Overview

Sidecar for Laravel

Tests Latest Stable Version Total Downloads License

Deploy and execute non-PHP AWS Lambda functions from your Laravel application.

Read the full docs at hammerstone.dev/sidecar/docs.

Follow me on Twitter for more updates: twitter.com/aarondfrancis

To install, simply require the package from composer: composer require hammerstone/sidecar

This package is still under development, please open issues for anything you run into.

What Sidecar Does

Sidecar packages, creates, deploys, and executes Lambda functions from your Laravel application.

You can write functions in any of the following runtimes and execute them straight from PHP:

  • Node.js 14
  • Node.js 12
  • Node.js 10
  • Python 3.8
  • Python 3.7
  • Python 3.6
  • Python 2.7
  • Ruby 2.7
  • Ruby 2.5
  • Java 11
  • Java 8
  • Go 1.x
  • .NET Core 3.1
  • .NET Core 2.1

Any runtime that Lambda supports, you can use!

What It Looks Like

Every Sidecar Function requires two things:

  • A PHP Class
  • Files that you want deployed to Lambda

For example, if we were wanting to use Node on Lambda to generate an og:image for all of our blog posts, we would first set up a simple class in PHP called OgImage.

App\Sidecar\OgImage.php

namespace App\Sidecar;

use Hammerstone\Sidecar\LambdaFunction;

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

    public function package()
    {
        // All files and folders needed for the function.
        return [
            'lambda',
        ];
    }
}

That's it! There are a lot more options, but that's all that is required.

The second thing you'd need is your function's "handler", in this case a javascript file.

Here's a simple JS file that could serve as our handler:

resources/lambda/image.js

const {createCanvas} = require('canvas')

exports.handler = async function (event) {
    const canvas = createCanvas(1200, 630)
    const context = canvas.getContext('2d')

    context.font = 'bold 70pt Helvetica'
    context.textAlign = 'center'
    context.fillStyle = '#3574d4'

    // Read the text out of the event passed in from PHP.
    context.fillText(event.text, 600, 170);
    
    // Return an image.
    return canvas.toDataURL('image/jpeg');
}

With those files created, you can deploy this function to Lambda:

php artisan sidecar:deploy --activate

And then execute it straight from your Laravel app!

web.php

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

Sidecar passes the payload from execute over to your Javascript function. Your Javascript function generates an image and sends it back to PHP.

Sidecar reduces the complexity of deploying small bits of code to Lambda.

Why Sidecar Exists

AWS Lambda is a powerful service that allows you to run code without provisioning or thinking about servers.

Laravel Vapor brought that power to Laravel. Using Vapor, you can run your plain ol' Laravel apps on a serverless platform and get incredible speed, security, and reliability.

Using Lambda through Vapor is a wonderful developer experience, but there are times when building your applications that you need to run just one or two Node functions for some reason. Common use cases could be taking screenshots with headless Chrome, generating images, or doing server-side rendering of your Javascript frontend.

Or maybe you want to run a Python script without configuring a server? Or a single Ruby script. Or even Java!

When running on a serverless platform, it's not quite as easy as installing Node and running your functions. You don't have access to the server! So you end up deploying a single Vercel or Netlify function and calling it over HTTP or just forgetting the thing altogether.

Sidecar brings the ease of Vapor to those non-PHP functions.

What Sidecar Doesn't Do

Sidecar does not handle any API Gateway, Databases, Caches, etc. The only thing Sidecar concerns itself with is packaging, creating, deploying, and executing Lambda functions.

Sidecar does not provide a way to execute a function via HTTP. You must execute it from your Laravel app through the provided methods.

If you need those other services, you are encouraged to use the instances that Vapor has set up for you, or set them up yourself.

Issues
  • Error executing

    Error executing "HeadBucket" on "https://s3.ca-central-1.amazonaws.com/sidecar-";

    The configure commands requires me to have SIDECAR_ARTIFACT_BUCKET_NAME defined in my .env, otherwise it won't work.

    image

    opened by antergos98 3
  • Undefined array key 0 on sidecar:configure

    Undefined array key 0 on sidecar:configure

    Here is the error message:

    image

    opened by antergos98 3
  • Error executing

    Error executing "ListVersionsByFunction": Environment name repeated twice in lambda name

    Hi - I'm sure I'm doing something wrong, but not quite sure what. I've been writing/testing lambdas locally successfully, and I'm now attempting to push to my staging env.

    The CI flow is a github action (PHP based) that runs the vapor deploy staging command, then the deploy/activate divided between build & deploy stages as suggested in the docs.

    The error I get at the 'activate' stage is:

    Error executing "ListVersionsByFunction" on "https://lambda.***.  
      amazonaws.com/2015-03-31/functions/SC-Variant-Staging-staging-Sidecar-Sharp  
      ResizeImageLambda/versions?MaxItems=100"; AWS HTTP error: Client error: `GE  
      T https://lambda.***.amazonaws.com/2015-03-31/functions/SC-Varia  
      nt-Staging-staging-Sidecar-SharpResizeImageLambda/versions?MaxItems=100` re  
      sulted in a `404 Not Found
    

    Looking at the lambdas deployed, I can see why the 404 occurs, as the only deployed staging version is 'SC-Variant-staging-Sidecar-SharpResizeImageLambda' (note the single, lowercase 'staging').

    opened by 60days 3
  • Call to undefined method Hammerstone\Sidecar\Commands\Actions\DetermineRegion::choice()

    Call to undefined method Hammerstone\Sidecar\Commands\Actions\DetermineRegion::choice()

    I have this error when I use the sidecar:configure command:

    image

    Looks like the choice methods doesn't exist in neither DetermineRegion or BaseAction class.

    opened by antergos98 1
  • Error executing

    Error executing "GetRole" on "https://iam.amazonaws.com";

    When I run sidecar:configure, creating an execution role is not working:

    image

    opened by antergos98 1
  • Clean up old functions

    Clean up old functions

    Lambda has a 75gb limit on function storage, which includes all aliases. We need to be responsible for cleaning up old versions of our functions so that we don't cause problems for people.

    enhancement 
    opened by aarondfrancis 1
  • Better Error Messages for Env Mismatches

    Better Error Messages for Env Mismatches

    When a function is deployed in staging and then executed in prod, we should catch the 404 error and look to see if there is a similarly named function with the env swapped out. If there is, we should throw a better error.

    enhancement 
    opened by aarondfrancis 1
  • Clean Old Functions

    Clean Old Functions

    opened by aarondfrancis 1
  • Support spaces in app name when creating function name

    Support spaces in app name when creating function name

    Adds support for APP_NAME variables that contain spaces.

    opened by owenconti 1
  • Fix method name for the layers example [ci skip]

    Fix method name for the layers example [ci skip]

    Updates the layer example to use the proper layers method.

    opened by jelleroorda 1
  • Support for testing/mocking

    Support for testing/mocking

    It would be awesome if the package supported the ability to fake/mock a Sidecar execution, ie:

    /** @test */
    public function it_calls_sidecar_function()
    {
        // Given
        $mockedResponse = [
            'hello' => 'world'
        ];
        SomeFunction::fake($mockedResponse);
    
        // When
        $this->get('/call-function')->assertSuccessful();
    
        // Then
        $expectedParams = [
            'foo' => 'bar'
        ];
        SomeFunction::assertExecuted($expectedParams);
    }
    

    The idea here would be to keep the faking pattern similar to the Laravel first-party fakes (Http, Queue, etc):

    • You call fake() with a mocked response for the lambda
    • You call your controller/command/job, etc that will execute the lambda
    • You call an assertion method to assert that the lambda was invoked with the given set of parameters
    enhancement 
    opened by owenconti 6
  • Pre-warm

    Pre-warm

    Once warming is in, there should be an option to warm functions between deploying and activating, so that most requests hit a warm container.

    enhancement 
    opened by aarondfrancis 1
  • Caching

    Caching

    If a function is invoked and

    1. the package hasn't changed and
    2. the payload hasn't changed

    then the developer should be given the option to not hit Lambda and just return the cached result.

    enhancement 
    opened by aarondfrancis 0
  • Support Layer Creation

    Support Layer Creation

    Right now we support referencing layers that already exist, but it might be nice to support creating layers, in the same way we create packages for functions.

    enhancement 
    opened by aarondfrancis 0
  • Add Zip Sweeping

    Add Zip Sweeping

    Right now ZIP archives will just pile up on S3. They are totally unnecessary after they are deployed to Lamba, so we need to add a sweep to clear old artifacts.

    enhancement 
    opened by aarondfrancis 0
  • Add Logs Command

    Add Logs Command

    We need to add a sidecar:logs command to pull logs from CloudWatch Logs. I've already added the CloudWatchLogs client, just need to write the command.

    enhancement 
    opened by aarondfrancis 0
Releases(v0.1.4)
Owner
Hammerstone
Making tools to make your life easier.
Hammerstone
Please see the Diglactic fork.

Update: 18 October 2020 There is now an official fork of Laravel Breadcrumbs: https://github.com/diglactic/laravel-breadcrumbs Blog post: https://news

Dave James Miller 2.4k Jun 17, 2021
Laravel Stats Tracker

Laravel Stats Tracker Tracker gathers a lot of information from your requests to identify and store: Sessions Page Views (hits on routes) Users (logge

Antonio Carlos Ribeiro 2.6k Jun 13, 2021
Inertia.js Events for Laravel Dusk

Inertia.js Events for Laravel Dusk Requirements PHP 7.4+ Vue Laravel 8.0 and higher Support We proudly support the community by developing Laravel pac

Protone Media 9 Jun 14, 2021
Laravel blade directives and php helpers for serverside rendered content, based on browser window size WITHOUT css

Laravel Window Size and Breakpoints Laravel blade directives and php helpers for server side rendered content, based on browser window size WITHOUT cs

Tina Hammar 5 May 24, 2021
A web installer for Laravel

Laravel Web Installer | A Web Installer Package About Requirements Installation Routes Usage Contributing Help Screenshots License About Do you want y

Rachid Laasri 1.7k Jun 13, 2021
Awes.io // boilerplate based on Vue, Nuxt, TailwindCSS plus Laravel as a backend. 🤟

Platform for Interactive Business Applications 10x faster to create than the traditional way • 3x increase application experiences • 60% decrease in d

Awes.io 640 Jun 15, 2021
Laravel Proxy Package for handling sessions when behind load balancers or other intermediaries.

Laravel Trusted Proxies Setting a trusted proxy allows for correct URL generation, redirecting, session handling and logging in Laravel when behind a

Chris Fidao 7.1k Jun 12, 2021
jQuery DataTables API for Laravel 4|5|6|7|8

jQuery DataTables API for Laravel 4|5|6|7|8 This package is created to handle server-side works of DataTables jQuery Plugin via AJAX option by using E

Arjay Angeles 3.9k Jun 14, 2021
A sample application with a multistep form built with Livewire.

About Laravel Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experie

David Grzyb 5 Jun 2, 2021
Laravel Backend for Learnbot app

About Laravel Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experie

Mobile & Backend developer 4 May 18, 2021
Simple user messaging package for Laravel

Laravel Messenger This package will allow you to add a full user messaging system into your Laravel application. Leave some feedback How are you using

Chris Gmyr 2k Jun 14, 2021
Laravel Ban simplify blocking and banning Eloquent models.

Laravel Ban Introduction Laravel Ban simplify management of Eloquent model's ban. Make any model bannable in a minutes! Use case is not limited to Use

cybercog 614 Jun 4, 2021
A set of useful Laravel collection macros

A set of useful Laravel collection macros This repository contains some useful collection macros. Spatie is a webdesign agency based in Antwerp, Belgi

Spatie 1.1k Jun 12, 2021
PHP Secure Headers

Secure Headers Add security related headers to HTTP response. The package includes Service Providers for easy Laravel integration. Version Installatio

null 384 May 31, 2021