Deploying Laravel API on AWS Lambda

AWS Lambda brought the term “serverless” into reality and shook the world of software development.

It gained a lot of popularity in the last few years and is one of the fastest-growing technologies provided by Amazon. One of its strengths is the ability to pay only for the amount of time it takes to run the code and pay nothing while the code isn’t running.

To accomplish this business model, AWS made Lambda scalable by default. You only provide the amount of memory your process needs and the cloud provider will be responsible for provisioning as much hardware as necessary every time your source code needs to be executed.

I have been working with AWS for 4 years and AWS Lambda in particular for 2 years. In this post, I want to share hands-on experience on deploying a Laravel API service on AWS Lambda.

Requirements

To follow along, you’ll need a few ingredients:

– AWS Account

– IAM Access Key / Secret Key

– PHP

– [Composer](https://getcomposer.org/download/)

– [NPM](https://nodejs.org/en/download/)

– [Serverless](https://goserverless.com)

– [Bref](https://bref.sh)

– [Laravel](https://laravel.com)

– [Optional] Docker

If you have an AWS Account already, everything else is manageable.

Let’s get started!

IAM Access

Let’s first start by generating programmatic access to AWS. We’ll need it so that we can provide the Serverless Framework with the ability to provision/deploy AWS lambda into our AWS account.

Log into your AWS account and go to IAM → Users → Add User. Choose a username for your account, check the Programmatic Access checkbox, and hit Next: Permission.

Under Attach existing policies directly, select the AdministratorAccess policy. We can now proceed to Next: Tags and subsequently Next: Review (Tags are optional).

Take this opportunity to double-check the configuration. Once you click Create User, AWS will show you the Access Key and Secret Key. The Secret Key is unrecoverable, so make sure to save it.

PHP, Composer, NPM, and Severless

If you have these tools installed in your environment, you may skip this step. Otherwise, I’ll show you how I install these tools inside a docker container.

#!/usr/bin/env sh

docker run --rm -v $(pwd):/app -w /app -it alpine:3.14 sh

apk add php8 php8-phar php8-curl php8-openssl php8-dom php8-xml php8-xmlwriter php8-xmlreader php8-tokenizer php8-mbstring php8-fileinfo php8-simplexml

apk add composer npm

cp /usr/bin/php8 /usr/bin/php

npm install -g serverless

This sequence of commands will start an Alpine Linux container and install PHP 8, Composer, NPM, and Serverless. Keep this container open because we’ll continue using it for the next steps.

Laravel and Bref

Let’s start a new Laravel project and install Bref using Composer.

#!/usr/bin/env sh

composer create-project laravel/laravel my-api
cd my-api
composer require bref/bref
./vendor/bin/bref init
0
rm index.php

The 0 above is to automatically select the option [0] Web application. Bref will then create serverless.yml and index.php. Since we’re using Laravel, we can remove the index.php and just keep the serverless.yml.

Before we move on to Serverless, let’s add a sample routing for our API by editing the routes/api.php file.

<?php

Route::get('/hello', fn () => response(['data' => 'Hello from Laravel!']));

Remember that by default the api.php folder is configured with the /api prefix, so our route will actually be /api/hello.

Serverless

Before we dive into the serverless.yml template, let’s configure the Serverless Framework. We can do that in two ways:

export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_HERE
export AWS_SECRET_ACCESS_KEY=YUR_SECRET_KEY_HERE

The framework will automatically pick up the credentials from the environment variable and perform deployments into your account.

The 2nd approach is to use serverless config credentials:

serverless config credentials --provider aws --key YOUR_ACCESS_KEY_HERE --secret YOUR_SECRET_KEY_HERE

After configuring the credentials for your AWS account, let’s tweak the serverless.yml template generated by Bref:

service: app

provider:
  name: aws
  region: us-east-1
  runtime: provided.al2

plugins:
  - ./vendor/bref/bref

functions:
  api:
    handler: public/index.php
    environment:
        LOG_CHANNEL: stderr
        SESSION_DRIVER: array
        CACHE_DRIVER: array
    description: ''
    timeout: 28 # in seconds (API Gateway has a timeout of 29 seconds)
    layers:
      - ${bref:layer.php-80-fpm}
    events:
      - httpApi: '*'

# Exclude files from deployment
package:
  patterns:
    - '!node_modules/**'
    - '!tests/**'

We change the handler from index.php to public/index.php as that’s the entry point for a Laravel application. There are also 3 important environment variables: LOG_CHANNEL, SESSION_DRIVER, and CACHE_DRIVER. The stderr driver will automatically drive log messages into CloudWatch and the array driver will essentially disable Session and Cache.

Deployment

To deploy the project, let’s issue the following command:

sls deploy

The output should look like this:

/app/my-api # sls deploy
Serverless: Deprecation warning: Detected ".env" files. In the next major release variables from ".env" files will be automatically loaded into the serverless build process. Set "useDotenv: true" to adopt that behavior now.
            More Info: https://www.serverless.com/framework/docs/deprecations/#LOAD_VARIABLES_FROM_ENV_FILES
Serverless: Deprecation warning: Resolution of lambda version hashes was improved with better algorithm, which will be used in next major release.
            Switch to it now by setting "provider.lambdaHashingVersion" to "20201221"
            More Info: https://www.serverless.com/framework/docs/deprecations/#LAMBDA_HASHING_VERSION_V2
Serverless: Packaging service...
Serverless: Excluding development dependencies...
Serverless: Service files not changed. Skipping deployment...
Service Information
service: app
stage: dev
region: us-east-1
stack: app-dev
resources: 11
api keys:
  None
endpoints:
  ANY - https://0000000000.execute-api.us-east-1.amazonaws.com
functions:
  api: app-dev-api
layers:
  None

You can use your endpoint to test the API. It should look like this: 

https://your_api_gateway_id.execute-api.us-east-1.amazonaws.com/api/hello

This is pretty much it! Your source code is now available behind API Gateway and Lambda and you’ll only pay for the time it takes for your code to execute.

Enforcing JSON Response

If we try to load an invalid route, say https://your_api_gateway_id.execute-api.us-east-1.amazonaws.com/whatever, we’ll get a fatal error because Laravel will try to write the compiled php files for Blade. We can fix that by adjusting the VIEW_COMPILED_PATH environment variable. But since the focus is to deploy API-based projects, we can also add a nice little middleware to enforce that every HTTP Response will be JSON.

<?php

namespace App\Http\Middleware;

use Closure;

class EnforceJsonResponse
{
    public function handle($request, Closure $next)
    {
        $request->headers->set('Accept', 'application/json');

        return $next($request);
    }
}

Then we can register it inside Kernel.php.

Conclusion

This introduction to Serverless with Laravel gives an overview of the foundation behind treating AWS Lambda as a hosting provider that only charges for execution time.

Although it is important to consider the aspect of running code on a read-only environment (with limited disk space under /tmp) and how two requests may not share the same live “container”, this approach doesn’t have a strong impact on the development practices and day-to-day operation of developers.

Providing APIs behind AWS Lambda makes them highly scalable and cheap if you have little to no usage at night or weekends, for instance.