Serverless Laravel - Getting started

This guide helps you run Laravel applications on AWS Lambda using Bref. These instructions are kept up to date to target the latest Laravel version.

Setup

First, follow the Setup guide to create an AWS account and install the necessary tools.

Next, in an existing Laravel project, install Bref and the Laravel-Bref package (opens in a new tab).

composer require bref/bref bref/laravel-bridge --update-with-dependencies

Then let's create a serverless.yml configuration file:

php artisan vendor:publish --tag=serverless-config

How it works

By default, the Laravel-Bref package will automatically configure Laravel to work on AWS Lambda.

If you are curious, the package will automatically:

• enable the stderr log driver, to send logs to CloudWatch (read more about logs)
• enable the cookie session driver (opens in a new tab) (if you prefer, you can configure sessions to be stored in database, DynamoDB or Redis)
• move the storage directory to /tmp (because the default storage directory is read-only on Lambda)
• adjust a few more settings (have a look at the BrefServiceProvider for details (opens in a new tab))

Deployment

We do not want to deploy "dev" caches that were generated on our machine (because paths will be different on AWS Lambda). Let's clear them before deploying:

php artisan config:clear

When running in AWS Lambda, the Laravel application will automatically cache its configuration when booting. You don't need to run php artisan config:cache before deploying.

Let's deploy now:

serverless deploy

When finished, the deploy command will show the URL of the application.

Deploying for production

At the moment, we deployed our local codebase to Lambda. When deploying for production, we don't want to deploy:

• development dependencies,
• our local .env file,
• or any other dev artifact.

Follow the deployment guide for more details about deploying in general.

Specifically for Laravel, Bref will automatically cache the configuration on "cold starts". This means that you don't need to run php artisan config:cache before deploying.

php artisan config:clear && php artisan config:cache

Troubleshooting

In case your application is showing a blank page after being deployed, have a look at the logs.

Logs

Thanks to the Bref integration, Laravel will automatically log to CloudWatch via stderr. You don't have to do anything.

You can learn more about logs in the Logs guide.

It is recommended you enable Bref's logs formatter optimized for CloudWatch:

provider:
    environment:
        LOG_STDERR_FORMATTER: Bref\Monolog\CloudWatchFormatter

With this formatter, logs will contain structured data that can be filtered in CloudWatch Logs Insights. For example, you can filter by log level, exception class, or anything in the Laravel Context (opens in a new tab).

Website assets

Have a look at the Website guide to learn how to deploy a website with assets.

Laravel Artisan

As you may have noticed, we define a function named "artisan" in serverless.yml. That function is using the Console runtime, which lets us run Laravel Artisan on AWS Lambda.

For example, to execute an artisan command on Lambda, run the command below:

serverless bref:cli --args="{artisan command and options}"

serverless bref:cli --args="route:list"

For more details follow the "Console" guide.

Laravel Tinker

If you are using Bref Cloud, you can start an interactive Tinker shell on AWS Lambda from your machine by running:

bref tinker

The usual flags work, for example to run Tinker in the production environment:

bref tinker --env=production

If you are not using Bref Cloud, you can check out this community package: sls-tinker (opens in a new tab).

Inertia

Laravel with Inertia runs without issue, like any other website. Follow the Websites guide to learn how to deploy a Laravel with assets with Bref.