mongodb · GromNaN · Apr 12, 2024 · Apr 2, 2024 · Apr 4, 2024 · Apr 9, 2024
diff --git a/.gitignore b/.gitignore
@@ -19,4 +19,7 @@ psalm.xml
 .phpbench/
 phpbench.json
 
+# bref
+.serverless/
+
 mongocryptd.pid
diff --git a/docs/examples/aws-lambda/composer.json b/docs/examples/aws-lambda/composer.json
@@ -0,0 +1,19 @@
+{
+    "name": "mongodb/bref-tutorial",
+    "type": "project",
+    "license": "MIT",
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../../..",
+            "options": {
+                "symlink": false
+            }
+        }
+    ],
+    "require": {
+        "bref/bref": "^2.1",
+        "bref/extra-php-extensions": "^1.4",
+        "mongodb/mongodb": "@dev"
+    }
+}
diff --git a/docs/examples/aws-lambda/index.php b/docs/examples/aws-lambda/index.php
@@ -0,0 +1,28 @@
+<?php
+
+use MongoDB\Client;
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('The MONGODB_URI environment variable is not set');
+$client = new Client($uri);
+$planets = $client->sample_guides->planets
+    ->find(
+        [],
+        ['sort' => ['orderFromSun' => 1]],
+    );
+
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>MongoDB Planets</title>
+</head>
+<body>
+    <ul>
+        <?php foreach ($planets as $planet) : ?>
+            <li><?= $planet->name ?></li>
+        <?php endforeach ?>
+    </ul>
+</body>
+</html>
diff --git a/docs/examples/aws-lambda/serverless.yml b/docs/examples/aws-lambda/serverless.yml
@@ -0,0 +1,22 @@
+service: app
+
+provider:
+    name: aws
+    region: us-east-1
+    environment:
+        MONGODB_URI: ${env:MONGODB_URI}
+
+plugins:
+    - ./vendor/bref/bref
+    - ./vendor/bref/extra-php-extensions
+
+functions:
+    api:
+        handler: index.php
+        description: ''
+        runtime: php-83-fpm
+        timeout: 28 # in seconds (API Gateway has a timeout of 29 seconds)
+        events:
+            -   httpApi: '*'
+        layers:
+            - ${bref-extra:mongodb-php-83}
diff --git a/docs/tutorial.txt b/docs/tutorial.txt
@@ -18,5 +18,6 @@ Tutorials
    /tutorial/indexes
    /tutorial/tailable-cursor
    /tutorial/example-data
+   /tutorial/aws-lambda
    /tutorial/modeling-bson-data
    /tutorial/stable-api
diff --git a/docs/tutorial/aws-lambda.txt b/docs/tutorial/aws-lambda.txt
@@ -0,0 +1,124 @@
+==============================
+Deploy to AWS Lambda with Bref
+==============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. versionadded:: 1.17
+
+Overview
+--------
+
+`Bref <https://bref.sh>`_ allows to 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.
+
+Prerequisites
+--------------
+
+Before you begin, you must install Bref on your machine. You can follow the
+`official documentation to setup Bref <https://bref.sh/docs/setup>`_.
+
+Install the MongoDB extension
+-----------------------------
+
+By default, the bref layer is compiled with PHP and a few extensions. Additional extensions
+are provided in additional layers.
+
+Start by creating a new directory for your project and install the required MongoDB
+and Bref dependencies. This project will be a bare minimum PHP web application that
+connects to a MongoDB cluster.
-and Bref dependencies. This project will be a bare minimum PHP web application that
-connects to a MongoDB cluster.
+and Bref dependencies by running the following commands:
-and Bref dependencies. This project will be a bare minimum PHP web application that
-connects to a MongoDB cluster.
+and Bref dependencies by running the following commands:
+
+.. code-block:: bash
+
+    mkdir bref-mongodb-app && cd bref-mongodb-app
+    composer init
+    composer require bref/bref bref/extra-php-extensions mongodb/mongodb
+    vendor/bin/bref init
+
+
+The file ``index.php`` has been created. To validate the deployment, you can start
+by deploying this default application.
+
+.. code-block:: bash
+
+    serverless deploy
+
+
+Bref provides a Lambda layer with PHP and some very common extensions.
+Additional extensions are provided by the package `bref/extra-php-extension <https://github.com/brefphp/extra-php-extensions>`_.
+
+.. code-block:: yaml
+
+    plugins:
+        - ./vendor/bref/bref
+        - ./vendor/bref/extra-php-extensions
+
+    functions:
+        api:
+            handler: index.php
+            runtime: php-83-fpm
+            layers:
+                - ${bref-extra:mongodb-php-83}
+
+
+Let's try to use the MongoDB driver with this simple web page that list planets
+from the :manual:`sample dataset </atlas/sample-data/>`.
+Replace the contents of ``index.php`` with the following:
+
+.. literalinclude:: /examples/aws-lambda/index.php
+   :language: php
+
+
+Deploy the application
+
+.. code-block:: bash
+
+    serverless deploy
+
+
+The application will not work unless you define the ``MONGODB_URI`` environment variable.
+
+AWS Credentials
+---------------
+
+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.
+
+Set up :manual:`unified AWS Access </atlas/security/set-up-unified-aws-access/>`:
+
+1. Open the Lambda function in the AWS console
+2. In "Configuration > Permission", copy the "Role name"
+3. Open the MongoDB Atlas project
+4. Go to "Security > Database Access"
+5. Click "Add a new Database User"
+6. Select Authentication Method: "AWS IAM", type "IAM Role" and paste the role name in "AWS Role ARN".
+7. Add "Built-in Role": "Read and write any database"
+8. Validate by clicking on "Add user".
+
+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.
+
+Update the ``serverless.yml`` file to pass the environment variable ``MONGODB_URI``
+
+.. code-block:: yaml
+
+    provider:
+        environment:
+            MONGODB_URI: "mongodb+srv://cluster0.example.mongodb.net/"
+
+
+The value can be found in "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.
+
+.. code-block:: bash
+
+    serverless deploy
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
@@ -75,6 +75,17 @@
 
         <!-- Disable forbidden annotation sniff as excluding @api from the list doesn't work -->
         <exclude name="SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden" />
+
+        <!-- Example file using HTML templating -->
+        <exclude name="Generic.Files.InlineHTML.Found">
+            <exclude-pattern>docs/examples/*/index.php</exclude-pattern>
+        </exclude>
+        <exclude name="SlevomatCodingStandard.ControlStructures.BlockControlStructureSpacing.IncorrectLinesCountAfterControlStructure">
+            <exclude-pattern>docs/examples/*/index.php</exclude-pattern>
+        </exclude>
+        <exclude name="Squiz.NamingConventions.ValidVariableName.MemberNotCamelCaps">
+            <exclude-pattern>docs/examples/*/index.php</exclude-pattern>
+        </exclude>
     </rule>