Update index.php to display errors

GromNaN · GromNaN · commit 883e951c0f30 · 2024-04-11T15:18:48.000+02:00
Review tutorial
diff --git a/docs/examples/aws-lambda/index.php b/docs/examples/aws-lambda/index.php
@@ -4,11 +4,16 @@
 
 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
-    ->selectCollection('sample_guides', 'planets')
-    ->find([], ['sort' => ['orderFromSun' => 1]]);
+$uri = getenv('MONGODB_URI');
+
+try {
+    $client = new Client($uri);
+    $planets = $client
+        ->selectCollection('sample_guides', 'planets')
+        ->find([], ['sort' => ['orderFromSun' => 1]]);
+} catch (Throwable $exception) {
+    exit($exception->getMessage());
+}
 
 ?>
 <!DOCTYPE html>
diff --git a/docs/tutorial/aws-lambda.txt b/docs/tutorial/aws-lambda.txt
@@ -2,8 +2,6 @@
 Deploy to AWS Lambda with Bref
 ==============================
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -13,72 +11,86 @@ Deploy to AWS Lambda with Bref
 Overview
 --------
 
-`Bref <https://bref.sh>`__ allows to deploy serverless PHP applications on AWS Lambda.
+`Bref <https://bref.sh>`__ 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.
 
 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>`__.
+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<https://bref.sh/docs/setup>`__
+in the Bref official documentation.
 
 Install the MongoDB extension
 -----------------------------
 
-By default, the bref layer is compiled with PHP and a few extensions. Additional extensions
-are provided in additional layers.
+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. This project will be a bare minimum PHP web application that
-connects to a MongoDB cluster.
+and Bref dependencies.
+
+.. code-block:: none
 
-.. code-block:: bash
+   $ mkdir bref-mongodb-app && cd bref-mongodb-app
+   $ composer init
+   $ composer require bref/bref bref/extra-php-extensions mongodb/mongodb
 
-    mkdir bref-mongodb-app && cd bref-mongodb-app
-    composer init
-    composer require bref/bref bref/extra-php-extensions mongodb/mongodb
-    vendor/bin/bref init
+Then initialize the serverless configuration using the ``bref`` command.
 
+.. code-block:: none
 
-The file ``index.php`` has been created. To validate the deployment, you can start
-by deploying this default application.
+   $ vendor/bin/bref init
 
-.. code-block:: bash
 
-    serverless deploy
+This series of commands creates a file named ``index.php``. To validate your
+setup, try deploying this default application. This will output an
+URL that renders a webpage with the Bref logo.
 
+.. code-block:: none
 
-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>`__.
+   $ 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 <https://github.com/brefphp/extra-php-extensions>`__.
+Add it to the ``layers`` of the function in ``serverless.yaml``, this file
+will look like this:
 
 .. code-block:: yaml
 
-    plugins:
-        - ./vendor/bref/bref
-        - ./vendor/bref/extra-php-extensions
+   plugins:
+       - ./vendor/bref/bref
+       - ./vendor/bref/extra-php-extensions
 
-    functions:
-        api:
-            handler: index.php
-            runtime: php-83-fpm
-            layers:
-                - ${bref-extra:mongodb-php-83}
+   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 `sample dataset <https://www.mongodb.com/docs/atlas/sample-data/>`__.
+Let's use the MongoDB driver with a web page that list planets from Atlas'
+`sample dataset <https://www.mongodb.com/docs/atlas/sample-data/>`__.
 Replace the contents of ``index.php`` with the following:
 
 .. literalinclude:: /examples/aws-lambda/index.php
    :language: php
 
 
-Deploy the application
+Redeploy the application with the new ``index.php``:
 
-.. code-block:: bash
+.. code-block:: none
 
-    serverless deploy
+   $ serverless deploy
 
 
 The application will not work unless you define the ``MONGODB_URI`` environment variable.
@@ -90,33 +102,41 @@ Atlas supports passwordless authentication with AWS credentials. In any Lambda f
 AWS sets environment variables that contains the access token and secret token with
 the role assigned to deployed function.
 
-Set up `unified AWS Access <https://www.mongodb.com/docs/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.
+3. Add this role to your Atlas cluster with the built-in Role: "Read and write any database"
 
-Update the ``serverless.yml`` file to pass the environment variable ``MONGODB_URI``
+To learn how to set up unified AWS access, see `Set Up Unified AWS Access
+<https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access/>`__ in the
+MongoDB Atlas documentation.
 
-.. code-block:: yaml
+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.
 
-    provider:
-        environment:
-            MONGODB_URI: "mongodb+srv://cluster0.example.mongodb.net/"
+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 <https://www.mongodb.com/docs/atlas/security/ip-access-list/>`__.
 
+.. note::
 
-The value can be found in "Atlas > Deployment > Database > Connect". Select "3. AWS IAM".
+   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 :guilabel:`Atlas > Deployment > Database > Connect`.
+Select :guilabel:`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
+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/?authSource=%24external&authMechanism=MONGODB-AWS&retryWrites=true&w=majority"
+
+Finally, deploy with the new configuration. Once done you can access the function URL
+and see the list of planets from your Atlas cluster.
+
+.. code-block:: none
 
-    serverless deploy
+   $ serverless deploy
