README

If you were looking for a way to easily deploy your Laravel project to AWS Lambda, you are in the correct place!

Building on the excellent bref project, we provide a simple and painless entry to the world of Serverless Laravel in AWS.

Installation

Assuming your are in existing Laravel project, let's install the bridge via Composer:

$ composer require stechstudio/laravel-bref-bridge

There is a route, config file, and AWS SAM template that needs to be published.

$ artisan vendor:publish --tag=bref-routes --tag=bref-sam-template --tag=bref-configuration

Configuration

TL;DR

Edit .env

BREF_NAME="<my-lambdas-name>"
BREF_S3_BUCKET="<bucket-name>"

$ artisan vendor:publish --tag=bref-sam-template --tag=bref-configuration
$ artisan bref:config-sam
$ artisan vendor:publish --tag=bref-routes
$ mv routes/lambda.example.php routes/lambda.php
$ artisan bref:package
$ artisan bref:deploy

AWS

You will need an S3 bucket to send the Function Package to in order for Cloudformation to consume it. Either use an existing bucket, or create a new one. You can easily create a new one with the AWS CLI like this.

$ aws s3 mb s3://<bucket-name>

.env

New edit your .env file and add:

BREF_NAME="<my-lambdas-name>"
BREF_S3_BUCKET="<bucket-name>"

Region Layers

While there is a default us-east-1 layer configured for you, it is best to reference https://bref.sh/docs/runtimes/ and find the ARN for the latest bref layer in the region you intend to deploy your lambda function.

Note that when you select the base layer, we require one of the php-??-fpm layers. Neither the php-?? nor the console layer types are compatible with this bridge.

Ensure that the region and the layer match, like so:

BREF_DEFAULT_REGION=ap-southeast-1
BREF_FUNCTION_LAYER_1=arn:aws:lambda:ap-southeast-1:209497400698:layer:php-73-fpm:6

SQS Job Queue

We will report the created default Job Queue after deployment. The Function will be configured to receive events from it as well as write to it. This means that when you dispatch a job to the default queue, it will trigger the same lambda function to handle the job.

SAM Template

$ artisan vendor:publish --tag=bref-sam-template

You will now find template.yml in your base directory and you can open it up, review it, edit, or just ignore it for now. When you are done, lets run the configuration command. This will generate a final template based on your .env file. If you modify anything in the .env you should run this command again to update the template.

$ artisan bref:config-sam

Lambda Routes

What are lambda routes? Glad you asked! Many people only concern themselves with events from API Gateway and/or AWS SQS that trigger their Lambda Jobs. However, there are a whole slew of events that might be configured to trigger your lambda function.

We have a router implemented for Laravel that makes it trivial for your application to consume and react to events from multiple triggers, all in a single Lambda Function. We use the AWS Events Package to transform the incoming events into the appropriate PHP Object, and then determine what controller to send that event too.

API Gateway

All API Gateway Proxy Request Events are hardwired to be treated as any normal web request. The event will be transformed into an HTTP Request and passed off to PHP-FPM just like nginx or apache would. The result will then be transformed back into the appropriate API Gateway Proxy Response and sent back to the Gateway. All you have to do for this scenario is write your HTTP routes and controllers the same as you would for any traditional Laravel app and, if we did our job correctly, it should just work!

The Other Events

Apart from API Gateway, we currently support routing for all (sixteen) of the other possible events. If you are not using any other events, you can simply ignore this section. However, for those who venture beyond the API Gateway, lets publish the example routes file.

$ artisan vendor:publish --tag=bref-routes

This will result in a routes/lambda.example.php being placed in your project. You will need to manually rename it to routes/lambda.php before it will be used. When you look at it you will notice that it follows the same paradigm as the HTTP Routes. You may either map a callback or map a Lambda Controller.

The router will then ensure that when an event of the type you are routing shows up, it gets passed on to the appropriate callable to handle the event. You simply need to return an array when you are done. To help you with testing the routing of various events, here are some samples.

AWS CloudFormation Create Request Sample Event

{
  "StackId": "arn:aws:cloudformation:us-west-2:EXAMPLE/stack-name/guid",
  "ResponseURL": "http://pre-signed-S3-url-for-response",
  "ResourceProperties": {
    "StackName": "stack-name",
    "List": [
      "1",
      "2",
      "3"
    ]
  },
  "RequestType": "Create",
  "ResourceType": "Custom::TestResource",
  "RequestId": "unique id for this create request",
  "LogicalResourceId": "MyTestResource"
}

Amazon SES Email Receiving Sample Event

{
  "Records": [
    {
      "eventVersion": "1.0",
      "ses": {
        "mail": {
          "commonHeaders": {
            "from": [
              "Jane Doe <janedoe@example.com>"
            ],
            "to": [
              "johndoe@example.com"
            ],
            "returnPath": "janedoe@example.com",
            "messageId": "<0123456789example.com>",
            "date": "Wed, 7 Oct 2015 12:34:56 -0700",
            "subject": "Test Subject"
          },
          "source": "janedoe@example.com",
          "timestamp": "1970-01-01T00:00:00.000Z",
          "destination": [
            "johndoe@example.com"
          ],
          "headers": [
            {
              "name": "Return-Path",
              "value": "<janedoe@example.com>"
            },
            {
              "name": "Received",
              "value": "from mailer.example.com (mailer.example.com [203.0.113.1]) by inbound-smtp.us-west-2.amazonaws.com with SMTP id o3vrnil0e2ic for johndoe@example.com; Wed, 07 Oct 2015 12:34:56 +0000 (UTC)"
            },
            {
              "name": "DKIM-Signature",
              "value": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com; s=example; h=mime-version:from:date:message-id:subject:to:content-type; bh=jX3F0bCAI7sIbkHyy3mLYO28ieDQz2R0P8HwQkklFj4=; b=sQwJ+LMe9RjkesGu+vqU56asvMhrLRRYrWCbV"
            },
            {
              "name": "MIME-Version",
              "value": "1.0"
            },
            {
              "name": "From",
              "value": "Jane Doe <janedoe@example.com>"
            },
            {
              "name": "Date",
              "value": "Wed, 7 Oct 2015 12:34:56 -0700"
            },
            {
              "name": "Message-ID",
              "value": "<0123456789example.com>"
            },
            {
              "name": "Subject",
              "value": "Test Subject"
            },
            {
              "name": "To",
              "value": "johndoe@example.com"
            },
            {
              "name": "Content-Type",
              "value": "text/plain; charset=UTF-8"
            }
          ],
          "headersTruncated": false,
          "messageId": "o3vrnil0e2ic28tr"
        },
        "receipt": {
          "recipients": [
            "johndoe@example.com"
          ],
          "timestamp": "1970-01-01T00:00:00.000Z",
          "spamVerdict": {
            "status": "PASS"
          },
          "dkimVerdict": {
            "status": "PASS"
          },
          "processingTimeMillis": 574,
          "action": {
            "type": "Lambda",
            "invocationType": "Event",
            "functionArn": "arn:aws:lambda:us-west-2:012345678912:function:Example"
          },
          "spfVerdict": {
            "status": "PASS"
          },
          "virusVerdict": {
            "status": "PASS"
          }
        }
      },
      "eventSource": "aws:ses"
    }
  ]
}

Scheduled Event Sample Event

{
  "account": "123456789012",
  "region": "us-east-1",
  "detail": {},
  "detail-type": "Scheduled Event",
  "source": "aws.events",
  "time": "1970-01-01T00:00:00Z",
  "id": "cdc73f9d-aea9-11e3-9d5a-835b769c0d9c",
  "resources": [
    "arn:aws:events:us-east-1:123456789012:rule/my-schedule"
  ]
}

Amazon CloudWatch Logs Sample Event

{
 "awslogs": {
 "data": "H4sIAAAAAAAAAHWPwQqCQBCGX0Xm7EFtK+smZBEUgXoLCdMhFtKV3akI8d0bLYmibvPPN3wz00CJxmQnTO41whwWQRIctmEcB6sQbFC3CjW3XW8kxpOpP+OC22d1Wml1qZkQGtoMsScxaczKN3plG8zlaHIta5KqWsozoTYw3/djzwhpLwivWFGHGpAFe7DL68JlBUk+l7KSN7tCOEJ4M3/qOI49vMHj+zCKdlFqLaU2ZHV2a4Ct/an0/ivdX8oYc1UVX860fQDQiMdxRQEAAA=="
 }
 }

Amazon SNS Sample Event

{
  "Records": [
    {
      "EventVersion": "1.0",
      "EventSubscriptionArn": eventsubscriptionarn,
      "EventSource": "aws:sns",
      "Sns": {
        "SignatureVersion": "1",
        "Timestamp": "1970-01-01T00:00:00.000Z",
        "Signature": "EXAMPLE",
        "SigningCertUrl": "EXAMPLE",
        "MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
        "Message": "Hello from SNS!",
        "MessageAttributes": {
          "Test": {
            "Type": "String",
            "Value": "TestString"
          },
          "TestBinary": {
            "Type": "Binary",
            "Value": "TestBinary"
          }
        },
        "Type": "Notification",
        "UnsubscribeUrl": "EXAMPLE",
        "TopicArn": topicarn,
        "Subject": "TestInvoke"
      }
    }
  ]
}

Amazon DynamoDB Update Sample Event

{
  "Records": [
    {
      "eventID": "1",
      "eventVersion": "1.0",
      "dynamodb": {
        "Keys": {
          "Id": {
            "N": "101"
          }
        },
        "NewImage": {
          "Message": {
            "S": "New item!"
          },
          "Id": {
            "N": "101"
          }
        },
        "StreamViewType": "NEW_AND_OLD_IMAGES",
        "SequenceNumber": "111",
        "SizeBytes": 26
      },
      "awsRegion": "us-west-2",
      "eventName": "INSERT",
      "eventSourceARN": eventsourcearn,
      "eventSource": "aws:dynamodb"
    },
    {
      "eventID": "2",
      "eventVersion": "1.0",
      "dynamodb": {
        "OldImage": {
          "Message": {
            "S": "New item!"
          },
          "Id": {
            "N": "101"
          }
        },
        "SequenceNumber": "222",
        "Keys": {
          "Id": {
            "N": "101"
          }
        },
        "SizeBytes": 59,
        "NewImage": {
          "Message": {
            "S": "This item has changed"
          },
          "Id": {
            "N": "101"
          }
        },
        "StreamViewType": "NEW_AND_OLD_IMAGES"
      },
      "awsRegion": "us-west-2",
      "eventName": "MODIFY",
      "eventSourceARN": sourcearn,
      "eventSource": "aws:dynamodb"
    },
    {
      "eventID": "3",
      "eventVersion": "1.0",
      "dynamodb": {
        "Keys": {
          "Id": {
            "N": "101"
          }
        },
        "SizeBytes": 38,
        "SequenceNumber": "333",
        "OldImage": {
          "Message": {
            "S": "This item has changed"
          },
          "Id": {
            "N": "101"
          }
        },
        "StreamViewType": "NEW_AND_OLD_IMAGES"
      },
      "awsRegion": "us-west-2",
      "eventName": "REMOVE",
      "eventSourceARN": sourcearn,
      "eventSource": "aws:dynamodb"
    }
  ]
}

Amazon Cognito Sync Trigger Sample Event

   {
  "datasetName": "datasetName",
  "eventType": "SyncTrigger",
  "region": "us-east-1",
  "identityId": "identityId",
  "datasetRecords": {
    "SampleKey2": {
      "newValue": "newValue2",
      "oldValue": "oldValue2",
      "op": "replace"
    },
    "SampleKey1": {
      "newValue": "newValue1",
      "oldValue": "oldValue1",
      "op": "replace"
    }
  },
  "identityPoolId": "identityPoolId",
  "version": 2
}

Amazon Kinesis Data Streams Sample Event

{
  "Records": [
    {
      "eventID": "shardId-000000000000:49545115243490985018280067714973144582180062593244200961",
      "eventVersion": "1.0",
      "kinesis": {
        "partitionKey": "partitionKey-3",
        "data": "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0IDEyMy4=",
        "kinesisSchemaVersion": "1.0",
        "sequenceNumber": "49545115243490985018280067714973144582180062593244200961"
      },
      "invokeIdentityArn": identityarn,
      "eventName": "aws:kinesis:record",
      "eventSourceARN": eventsourcearn,
      "eventSource": "aws:kinesis",
      "awsRegion": "us-east-1"
    }
  ]
}

Amazon S3 Put Sample Event

{
  "Records": [
    {
      "eventVersion": "2.0",
      "eventTime": "1970-01-01T00:00:00.000Z",
      "requestParameters": {
        "sourceIPAddress": "127.0.0.1"
      },
      "s3": {
        "configurationId": "testConfigRule",
        "object": {
          "eTag": "0123456789abcdef0123456789abcdef",
          "sequencer": "0A1B2C3D4E5F678901",
          "key": "HappyFace.jpg",
          "size": 1024
        },
        "bucket": {
          "arn": bucketarn,
          "name": "sourcebucket",
          "ownerIdentity": {
            "principalId": "EXAMPLE"
          }
        },
        "s3SchemaVersion": "1.0"
      },
      "responseElements": {
        "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH",
        "x-amz-request-id": "EXAMPLE123456789"
      },
      "awsRegion": "us-east-1",
      "eventName": "ObjectCreated:Put",
      "userIdentity": {
        "principalId": "EXAMPLE"
      },
      "eventSource": "aws:s3"
    }
  ]
}

Amazon S3 Delete Sample Event

  {
  "Records": [
    {
      "eventVersion": "2.0",
      "eventTime": "1970-01-01T00:00:00.000Z",
      "requestParameters": {
        "sourceIPAddress": "127.0.0.1"
      },
      "s3": {
        "configurationId": "testConfigRule",
        "object": {
          "sequencer": "0A1B2C3D4E5F678901",
          "key": "HappyFace.jpg"
        },
        "bucket": {
          "arn": bucketarn,
          "name": "sourcebucket",
          "ownerIdentity": {
            "principalId": "EXAMPLE"
          }
        },
        "s3SchemaVersion": "1.0"
      },
      "responseElements": {
        "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH",
        "x-amz-request-id": "EXAMPLE123456789"
      },
      "awsRegion": "us-east-1",
      "eventName": "ObjectRemoved:Delete",
      "userIdentity": {
        "principalId": "EXAMPLE"
      },
      "eventSource": "aws:s3"
    }
  ]
}

Amazon Lex Sample Event

{
  "messageVersion": "1.0",
  "invocationSource": "FulfillmentCodeHook or DialogCodeHook",
  "userId": "user-id specified in the POST request to Amazon Lex.",
  "sessionAttributes": { 
     "key1": "value1",
     "key2": "value2",
  },
  "bot": {
    "name": "bot-name",
    "alias": "bot-alias",
    "version": "bot-version"
  },
  "outputDialogMode": "Text or Voice, based on ContentType request header in runtime API request",
  "currentIntent": {
    "name": "intent-name",
    "slots": {
      "slot-name": "value",
      "slot-name": "value",
      "slot-name": "value"
    },
    "confirmationStatus": "None, Confirmed, or Denied
      (intent confirmation, if configured)"
  }
}

Amazon SQS Event

{
     "Records": [
        {
            "messageId": "c80e8021-a70a-42c7-a470-796e1186f753",
            "receiptHandle": "AQEBJQ+/u6NsnT5t8Q/VbVxgdUl4TMKZ5FqhksRdIQvLBhwNvADoBxYSOVeCBXdnS9P+erlTtwEALHsnBXynkfPLH3BOUqmgzP25U8kl8eHzq6RAlzrSOfTO8ox9dcp6GLmW33YjO3zkq5VRYyQlJgLCiAZUpY2D4UQcE5D1Vm8RoKfbE+xtVaOctYeINjaQJ1u3mWx9T7tork3uAlOe1uyFjCWU5aPX/1OHhWCGi2EPPZj6vchNqDOJC/Y2k1gkivqCjz1CZl6FlZ7UVPOx3AMoszPuOYZ+Nuqpx2uCE2MHTtMHD8PVjlsWirt56oUr6JPp9aRGo6bitPIOmi4dX0FmuMKD6u/JnuZCp+AXtJVTmSHS8IXt/twsKU7A+fiMK01NtD5msNgVPoe9JbFtlGwvTQ==",
            "body": "{\"foo\":\"bar\"}",
            "attributes": {
                "ApproximateReceiveCount": "3",
                "SentTimestamp": "1529104986221",
                "SenderId": "594035263019",
                "ApproximateFirstReceiveTimestamp": "1529104986230"
            },
            "messageAttributes": {},
            "md5OfBody": "9bb58f26192e4ba00f01e2e7b136bbd8",
            "eventSource": "aws:sqs",
            "eventSourceARN": "arn:aws:sqs:us-west-2:594035263019:NOTFIFOQUEUE",
            "awsRegion": "us-west-2"
        }
    ]
}

CloudFront Event

{
  "Records": [
    {
      "cf": {
        "config": {
          "distributionId": "EDFDVBD6EXAMPLE"
        },
        "request": {
          "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334",
          "method": "GET",
          "uri": "/picture.jpg",
          "headers": {
            "host": [
              {
                "key": "Host",
                "value": "d111111abcdef8.cloudfront.net"
              }
            ],
            "user-agent": [
              {
                "key": "User-Agent",
                "value": "curl/7.51.0"
              }
            ]
          }
        }
      }
    }
  ]
}

AWS Config Event

{ 
    "invokingEvent": "{\"configurationItem\":{\"configurationItemCaptureTime\":\"2016-02-17T01:36:34.043Z\",\"awsAccountId\":\"000000000000\",\"configurationItemStatus\":\"OK\",\"resourceId\":\"i-00000000\",\"ARN\":\"arn:aws:ec2:us-east-1:000000000000:instance/i-00000000\",\"awsRegion\":\"us-east-1\",\"availabilityZone\":\"us-east-1a\",\"resourceType\":\"AWS::EC2::Instance\",\"tags\":{\"Foo\":\"Bar\"},\"relationships\":[{\"resourceId\":\"eipalloc-00000000\",\"resourceType\":\"AWS::EC2::EIP\",\"name\":\"Is attached to ElasticIp\"}],\"configuration\":{\"foo\":\"bar\"}},\"messageType\":\"ConfigurationItemChangeNotification\"}",
    "ruleParameters": "{\"myParameterKey\":\"myParameterValue\"}",
    "resultToken": "myResultToken",
    "eventLeftScope": false,
    "executionRoleArn": "arn:aws:iam::012345678912:role/config-role",
    "configRuleArn": "arn:aws:config:us-east-1:012345678912:config-rule/config-rule-0123456",
    "configRuleName": "change-triggered-config-rule",
    "configRuleId": "config-rule-0123456",
    "accountId": "012345678912",
    "version": "1.0"
}

AWS IoT Button Event

{
  "serialNumber": "ABCDEFG12345",
  "clickType": "SINGLE",
  "batteryVoltage": "2000 mV"
}

Kinesis Data Firehose Event

{
  "invocationId": "invoked123",
  "deliveryStreamArn": "aws:lambda:events",
  "region": "us-west-2",
  "records": [
    {
      "data": "SGVsbG8gV29ybGQ=",
      "recordId": "record1",
      "approximateArrivalTimestamp": 1510772160000,
      "kinesisRecordMetadata": {
        "shardId": "shardId-000000000000",
        "partitionKey": "4d1ad2b9-24f8-4b9d-a088-76e9947c317a",
        "approximateArrivalTimestamp": "2012-04-23T18:25:43.511Z",
        "sequenceNumber": "49546986683135544286507457936321625675700192471156785154",
        "subsequenceNumber": ""
      }
    },
    {
      "data": "SGVsbG8gV29ybGQ=",
      "recordId": "record2",
      "approximateArrivalTimestamp": 151077216000,
      "kinesisRecordMetadata": {
        "shardId": "shardId-000000000001",
        "partitionKey": "4d1ad2b9-24f8-4b9d-a088-76e9947c318a",
        "approximateArrivalTimestamp": "2012-04-23T19:25:43.511Z",
        "sequenceNumber": "49546986683135544286507457936321625675700192471156785155",
        "subsequenceNumber": ""
      }
    }
  ]
}

After you publish your package to lambda, you can head over to the AWS console to copy/paste the various samples here into the tests and run them manually. You could also do that from the AWS CLI if want to test from there.

Packaging & Deploying

We have made this as trivial as possible.

$ artisan bref:package

This will generate a storage/latest.zip package of your current code. There will be no dev packages from composer, so if you want those packages you will need to move them into the required stanza.

$ artisan bref:deploy

After a few moments, the job will finish and you can head over to the AWS Console to check out your new Lambda Job.

That was it, Congratulations!

Configuration Options

The config/bref.php file holds our configuration options for us. This is a high level overview of the available settings. Please see comments in the file itself for more detail and defaults.

name - This value is the name of your Lambda. This value is used when the framework needs to generate the lambda function names.
description - This value is the description of your Lambda. This value is used when the framework needs to generate the lambda function descriptions.
region - This value is the region of your Lambda. This value is used when the framework needs to generate the lambda function regions.
timeout - This value is the timeout, in seconds, to configure the lambda function for. The API Gateway timeout is 30 seconds, so that is our default. The maximum timeout is 900 seconds (15 minutes).
memory_size - The amount of memory that your function has access to. Increasing the function's memory also increases it's CPU allocation. The default value is 128 MB and the maximum value is 3,008 MB. The value must be an integer multiple of 64 MB.
layers - A list of function layers to add to the function's execution environment. Specify each layer by ARN, including the version, in the order they should be layered, with a maximum of five layers.
keep - The number of latest (zip) packages to keep on the filesystem.
sqs - Lambda consumption of job queues gets configured here. Publishing jobs to queues still works as normal, So no changes there. Just update the .env
packaging - This array configures the files that should be ignored when packaging your application, as well as identifying executable files.
env - This array configures environment variables that are passed in for function code, as well as listing those that are ignored.

.env Variables

The following .env variables are available to be used. Reference the config/bref.php for more details.

BREF_NAME - This value is the name of your Lambda. This value is used when the framework needs to generate the lambda function names.
BREF_DESCRIPTION - This value is the description of your Lambda. This value is used when the framework needs to generate the lambda function descriptions.
BREF_DEFAULT_REGION - This value is the region of your Lambda. This value is used when the framework needs to generate the lambda function regions.
BREF_FUNCTION_TIMEOUT - This value is the timeout, in seconds, to configure the lambda function for. The API Gateway timeout is 30 seconds, so that is our default. The maximum timeout is 900 seconds (15 minutes).
BREF_FUNCTION_MEMORY_SIZE -The amount of memory that your function has access to. Increasing the function's memory also increases it's CPU allocation. The default value is 128 MB and the maximum value is 3,008 MB. The value must be an integer multiple of 64 MB.
BREF_FUNCTION_LAYER_1 - The ARN, including version, of the first layer. This will override the default layer.
BREF_FUNCTION_LAYER_2 - The ARN, including version, of the second layer, if used.
BREF_FUNCTION_LAYER_3 - The ARN, including version, of the third layer, if used.
BREF_FUNCTION_LAYER_4 - The ARN, including version, of the fourth layer, if used.
BREF_FUNCTION_LAYER_5 - The ARN, including version, of the fifth layer, if used.
BREF_PACKAGE_KEEP - The number of latest (zip) packages to keep on the filesystem.
BREF_APP_STORAGE - Where the laravel app storage should be. Defaults to /tmp/storage.
BREF_LOG_CHANNEL - How to handle logging in lambda. Defaults to stderr.
BREF_CACHE_DRIVER - The cache driver to use in Lambda. Defaults to file.
BREF_SESSION_DRIVER - The Session driver to use in Lambda. Defaults to array.
BREF_QUEUE_CONNECTION - The queue connection to use in Lambda. Defaults to sqs.

Enable an Extension

If you would like to enable an extension, of simply modify the php.ini directives, you can do so by creating a ./storage/php/conf.d directory. Anything you place in that directory will get packaged to end up in /var/task/php/config.d which is the default for bref.

For example, to enable pdo_mysql, which comes in the base bref layer, just create a ./storage/php/conf.d/mysql.ini file like so:

extension=pdo_mysql

See: https://bref.sh/docs/environment/php.html#customizing-phpini https://bref.sh/docs/environment/php.html#extensions-installed-but-disabled-by-default

stechstudio / laravel-bref-bridge

Maintainers

Details