Sidecar — Deploy and execute AWS Lambda functions from your Laravel application.

Customizing Functions

The only two things required for a Sidecar function are the package and the handler, but there are many more things you can customize about your functions to meet your specific needs.

Runtime

Lambda supports multiple languages through the use of runtimes. You can choose any of the following runtimes by returning its corresponding identifier:

  • Node.js 14: nodejs14.x
  • Node.js 12: nodejs12.x
  • Node.js 10: nodejs10.x
  • Python 3.8: python3.8
  • Python 3.7: python3.7
  • Python 3.6: python3.6
  • Python 2.7: python2.7
  • Ruby 2.7: ruby2.7
  • Ruby 2.5: ruby2.5
  • Java 11: java11
  • Java 8: java8
  • Go 1.x: go1.x
  • .NET Core 3.1: dotnetcore3.1
  • .NET Core 2.1: dotnetcore2.1

E.g. to use the Go runtime, you would return go1.x:

1class ExampleFunction extends LambdaFunction
2{
3 public function runtime()
4 {
5 return 'go1.x';
6 }
7}

Read more in the AWS Documentation.

Memory

The only compute-related configuration that AWS allows you to configure for your Lambda is memory. From their documentation:

Lambda allocates CPU power in proportion to the amount of memory configured. Memory is the amount of memory available to your Lambda function at runtime. You can increase or decrease the memory and CPU power allocated to your function using the Memory (MB) setting. To configure the memory for your function, set a value between 128 MB and 10,240 MB in 1-MB increments. At 1,769 MB, a function has the equivalent of one vCPU (one vCPU-second of credits per second).

By default, Sidecar uses the value in your sidecar.php configuration file, which itself defaults to 512mb.

To change the allocated memory of your function, return the number in megabytes.

1class ExampleFunction extends LambdaFunction
2{
3 public function memory()
4 {
5 // 2GB of memory
6 return 2048;
7 }
8}
Code highlighting powered by torchlight.dev, a Hammerstone product.

Because this has cost implications, you should consider what makes the most sense for your use case.

Timeout

Every Lambda function must specify a timeout value, at which point AWS will stop execution. There is a hard upper limit of 15 minutes.

Sidecar uses the value from you sidecar.php configuration file, which is defaulted to 300 seconds.

You are free to change that per function by returning a value from the timeout method.

1class ExampleFunction extends LambdaFunction
2{
3 public function timeout()
4 {
5 // Only 30 seconds
6 return 30;
7 }
8}

Layers

Some functions require extra code or data beyond what is in your code package. From Amazon's documentation:

A Lambda layer is a .zip file archive that can contain additional code or data. A layer can contain libraries, a custom runtime, data, or configuration files. Layers promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic.

If you want to include layers in your Lambda, you'll need to provide the full ARN for those layers.

In this example below, we're providing the ARN for a layer that has Node Canvas pre-built for the Lambda runtime.

1class ExampleFunction extends LambdaFunction
2{
3 public function handler()
4 {
5 //
6 }
7 
8 public function package()
9 {
10 //
11 }
12 
13 public function layers()
14 {
15 return [
16 // Node Canvas from https://github.com/jwerre/node-canvas-lambda
17 'arn:aws:lambda:us-east-2:XXXX:layer:node_canvas:1',
18 ];
19 }
20}

Note that your layers must be in the same AWS region as your Lambdas!

Environment Variables

Some functions or layers may require configuration via Lambda environment variables. The Lambda runtime will inject the environment variables so that they available to your handler code.

In this example below, we're providing a path to a font directory as an environment variable.

1class ExampleFunction extends LambdaFunction
2{
3 public function handler()
4 {
5 //
6 }
7 
8 public function package()
9 {
10 //
11 }
12 
13 public function variables()
14 {
15 return [
16 'FONTCONFIG_PATH' => '/opt/etc/fonts',
17 ];
18 }
19}

It is very important to note that if you allow Sidecar to manage your Lambda's environment variables, any changes made to environment variables in the AWS UI will be overwritten next time you deploy your function.

By default, Sidecar doesn't touch your Lambda's environment at all. Only when you return an array from variables will Sidecar take control of the env vars.

Another important thing to note is that Sidecar sets your environment variables as a part of the activation process, not the deploy process. This means that the environment variables will be pulled from the machine that calls sidecar:activate.

For example, if you are sharing secrets with your Lambda, then the values passed to your Lambda will be equal to the ones on the machine that called sidecar:activate, not the one that called sidecar:deploy

1class ExampleFunction extends LambdaFunction
2{
3 public function handler()
4 {
5 //
6 }
7 
8 public function package()
9 {
10 //
11 }
12 
13 public function variables()
14 {
15 // Values will come from the "activating" machine.
16 return [
17 'aws_key' => config('services.aws.key'),
18 'aws_secret' => config('services.aws.secret'),
19 ];
20 }
21}

This is obviously important when you are calling deploy and activate from different machines as a part of your Laravel application's deployment process. To read more about deployment strategies, check out the deploying section.

Name

Your function has a name method that determines how Sidecar names your Lambda functions. By default it is based on the name and path of your PHP class. You are free to change this if you want, but you're unlikely to need to.

1class ExampleFunction extends LambdaFunction
2{
3 public function name()
4 {
5 return 'Function Name';
6 }
7}

Name Prefix

Regardless of what you choose for your function names, Sidecar will prepend the name of your app and the current environment.

Lambda function names must be unique, so adding these variables to your function names prevents collisions between different apps and environments.

You likely won't need to change this, but if you do, you must include the environment. If you don't, your local and production functions will overwrite each other.

1class ExampleFunction extends LambdaFunction
2{
3 public function prefix()
4 {
5 // Don't forget the environment!
6 return 'My App ' . Sidecar::getEnvironment()
7 }
8}
Code highlighting powered by torchlight.dev, a Hammerstone product.

Description

The description is totally up to you, you'll likely not need to change it at all. We have provided a descriptive default. Sidecar doesn't do anything with it.