Deploying Laravel API on AWS Lambda

AWS Lambda PHP sounds as a good combination since it 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 my hands-on experience on how to deploy a Laravel API service on AWS Lambda with other Laravel developers who are interested in learning.


To follow along the entire AWS Lambda Laravel combination, you'll need a few ingredients:

- AWS Account

- IAM Access Key / Secret Key


- [Composer](

- [NPM](

- [Serverless](

- [Bref](

- [Laravel](

- [Optional] Docker

If you have an AWS Account already, everything else for the Laravel Lambda function is manageable.

Let's get started!

IAM Access

Let's first start the Laravel AWS Lambda process 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 Laravel Lambda 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 Laravel 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
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.


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.


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


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 Laravel:

service: app

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

  - ./vendor/bref/bref

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

# Exclude files from deployment
    - '!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.


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:
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:
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:
  ANY -
  api: app-dev-api

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

This is pretty much it! Your source code is now available behind Laravel AWS 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, we'll get a fatal error because Lambda 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 Laravel AWS API-based projects, we can also add a nice little middleware to enforce that every HTTP Response will be JSON.


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.


This introduction to Serverless 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 PHP Laravel makes them highly scalable and cheap if you have little to no usage at night or on weekends, for instance.

Now you know how to deploy Laravel API, and if you're interested in expanding your Laravel knowledge, consider reading the following resources:


Q: How to manage database connections in Laravel APIs on AWS Lambda for optimal performance?
To manage database connections in Laravel APIs on AWS Lambda for optimal performance, use AWS's RDS Proxy to pool and share connections efficiently across Lambda instances. This approach reduces the overhead of creating new connections for each request, enhancing performance and scalability.
Q: Can existing Laravel applications be migrated to AWS Lambda without major modifications?
Yes, existing Laravel applications can be migrated to AWS Lambda with minimal modifications, primarily related to handling stateless computing and optimizing for the serverless environment.
Q: How to monitor and debug Laravel applications running on AWS Lambda?
Use AWS CloudWatch for monitoring and AWS X-Ray for detailed tracing and debugging. These tools provide insights into performance and help identify issues in your Laravel application on AWS Lambda.
Marco Aurélio Deleu
Marco Aurélio Deleu
Serverless PHP Artisan

Marco is a Senior Software Engineer with over 11 years of experience in the industry. He is passionate about Open Source, Laravel and AWS.

  • Laravel
  • PHP
  • AWS
  • Serverless
  • AWS Lambda
  • Open Source
  • +1

Ready to start?

Get in touch or schedule a call.