Docs Menu
Docs Home
/ / /
PHP Library Manual

Deploy to AWS Lambda with Bref

On this page

  • Overview
  • Prerequisites
  • Install the MongoDB extension
  • AWS Credentials

Bref lets you deploy serverless PHP applications on AWS Lambda. In this tutorial, you will deploy a simple PHP application with the MongoDB PHP extension, and connect to an Atlas cluster using AWS IAM authentication.

To deploy to AWS Lambda by using Bref, you must have the following components set up:

  • AWS account with access keys

  • Serverless Framework

To learn how to set these up, follow the Setup tutorial in the Bref official documentation.

Bref uses Lambda layers to provide the PHP runtime. The bref layer is compiled with PHP and a few extensions. Other extensions, like mongodb, are available in additional layers.

Start by creating a new directory for your project and install the required MongoDB and Bref dependencies.

$ mkdir bref-mongodb-app && cd bref-mongodb-app
$ composer init
$ composer require bref/bref bref/extra-php-extensions mongodb/mongodb

Then initialize the serverless configuration using the bref command.

$ vendor/bin/bref init

After this series of commands, you should have this files:

  • composer.json for PHP dependencies installed in the vendor directory

  • index.php a sample webpage

  • serverless.yml for the configuration of the deployment

To validate your setup, try deploying this default application. This outputs a URL that renders a webpage with the Bref logo:

$ serverless deploy

Now that you have initialized the project, you will add the mongodb extension. Locate the "Serverless config" name in the list of extensions provided by bref/extra-php-extension. Add it to the layers of the function in serverless.yaml, this file will look like this:

- ./vendor/bref/bref
- ./vendor/bref/extra-php-extensions
handler: index.php
runtime: php-83-fpm
- ${bref-extra:mongodb-php-83}

Let's use the MongoDB driver with a web page that list planets from the Atlas sample dataset. Replace the contents of index.php with the following:

use MongoDB\Client;
require_once __DIR__ . '/vendor/autoload.php';
$uri = getenv('MONGODB_URI');
try {
$client = new Client($uri);
$planets = $client
->selectCollection('sample_guides', 'planets')
->find([], ['sort' => ['orderFromSun' => 1]]);
} catch (Throwable $exception) {
<!DOCTYPE html>
<html lang="en">
<title>MongoDB Planets</title>
<?php foreach ($planets as $planet) : ?>
<li><?= $planet->name ?></li>
<?php endforeach ?>

Redeploy the application with the new index.php:

$ serverless deploy

The application will display an error message because the MONGODB_URI environment variable has not yet been set. We'll look at how to set this variable in the next section.

Atlas supports passwordless authentication with AWS credentials. In any Lambda function, AWS sets environment variables that contains the access token and secret token with the role assigned to deployed function.

  1. Open the Lambda function in the AWS console

  2. In Configuration > Permission, copy the Role name

  3. Add this role to your Atlas cluster with the built-in Role: "Read and write any database"

To learn how to set up unified AWS access, see Set Up Unified AWS Access in the MongoDB Atlas documentation.

Now that the permissions have been configured, the Lambda function is allowed to access your Atlas cluster. You can configure your application with the Atlas endpoint.

Access to Atlas clusters is also restricted by IP address. Since the range of IP that comes from AWS is very wide, you can allow access from everywhere.


Using VPC Peering is recommended in order to isolate your Atlas cluster from Internet. This requires the Lambda function to be deployed in this AWS VPC.

Find the connection URI in the Atlas UI Atlas > Deployment > Database > Connect. Select 3. AWS IAM. Remove the <AWS access key>:<AWS secret key> part from the URI, the credentials will be read from environment variables.

Update the serverless.yml file to pass the environment variable MONGODB_URI.

MONGODB_URI: "mongodb+srv://"

Finally, deploy with the new configuration. After deployment completes, you can access the function URL and see the list of planets from your Atlas cluster.

$ serverless deploy
← Example Data