Advanced HTTP use-cases

Alternative AWS architectures

By default, Bref uses API Gateway v2 HTTP APIs to run HTTP applications.

However, there are other ways to run HTTP applications on AWS Lambda: using API Gateway (opens in a new tab), Lambda Function URLs (opens in a new tab), or AWS Application Load Balancer (ALB) (opens in a new tab):

• API Gateway v1 "REST" + Lambda
• API Gateway v2 "HTTP" + Lambda
• Lambda Function URL
• AWS ALB (Application Load Balancer) + Lambda

Bref supports all 4, but API Gateway v2 "HTTP" is the default because it is the simplest option that supports both HTTP APIs and websites with custom domains.

Here is a summary of the differences between the 4 options:

You can read more details in the "Choosing between REST APIs and HTTP APIs" AWS documentation (opens in a new tab).

API Gateway v2 HTTP API

The simplest way to set up API Gateway is to have all incoming requests sent to our application in one Lambda function:

functions:
    hello:
        handler: index.php
        # ...
        events:
            - httpApi: '*'

That works well with frameworks like Symfony or Laravel that have a single entrypoint (e.g. public/index.php) combined with the PHP-FPM runtime.

You can look at more advanced API Gateway routing options in the serverless documentation (opens in a new tab).

Lambda Function URLs

Since 2022, AWS Lambda can respond to HTTP requests via Lambda Function URLs (opens in a new tab). This is a new way to invoke Lambda functions via HTTP without using API Gateway.

You can deploy a Lambda Function URL via the following configuration (opens in a new tab):

functions:
    hello:
        handler: index.php
        # ...
        url: true

API Gateway v1 REST API

The syntax is slightly different from API Gateway v2 HTTP APIs as we must use a different events configuration. Here is an example that sends all requests to a single Lambda function:

functions:
    hello:
        handler: index.php
        # ...
        events:
            - http: 'ANY /'
            - http: 'ANY /{proxy+}'

Learn more in the Serverless Framework documentation (opens in a new tab).

Application Load Balancer

Application Load Balancer (ALB) is a managed load balancer that can be used to route HTTP requests to Lambda functions. It is a more advanced option that is interesting at high scale as ALB can be much cheaper than API Gateway.

functions:
    hello:
        handler: index.php
        # ...
        events:
            -   alb:
                    listenerArn: arn:aws:elasticloadbalancing:us-east-1:12345:listener/app/my-load-balancer/50dc6c495c0c9188/
                    priority: 1
                    conditions:
                        path: '/*'

Learn more in the Serverless Framework documentation (opens in a new tab).

PHP handlers

There are two ways to handle HTTP events with PHP:

• via the PHP-FPM runtime (simplest, this is Bref's default)
• via the Event-Driven Function runtime (more advanced)

Here is a full comparison between both approaches:

With the PHP-FPM runtime

This is perfect for most use-cases: PHP works like on any server with PHP-FPM. HTTP routing based on the URL is done by the application/the framework.

This approach is already covered by most of the Bref documentation, so we won't go into details here.

You can read more about the PHP-FPM runtime here.

With the Event-Driven Function runtime

This is more advanced, as PHP does not run in a traditional PHP-FPM environment. It can be used with or without a PHP framework.

When used with a framework, understand that the whole HTTP stack (like HTTP middlewares) of the framework does not run. You are responsible for invoking the PHP code that should run.

The handler must be a PHP function, or a PSR-15 implementation. Indeed, Bref natively supports the PSR-15 (opens in a new tab) and PSR-7 (opens in a new tab) standards. Here is an example:

<?php
 
namespace App;
 
use Nyholm\Psr7\Response;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
 
class MyHttpHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $name = $request->getQueryParams()['name'] ?? 'world';
 
        return new Response(200, [], "Hello $name");
    }
}

Then, create a Lambda function that listens to HTTP events with the handler you created:

functions:
    # ...
    handler: App\MyHttpHandler
    runtime: php-81
    # Lambda Function URL
    url: true
    # Or API Gateway
    events:
        # API Gateway v2
        - httpApi: 'GET /hello'
        # API Gateway v1
        - http: 'GET hello'

Since a handler is a controller for a specific route, we can use the API Gateway routing to deploy multiple functions:

functions:
    create-article:
        handler: App\CreateArticleController
        runtime: php-81
        events:
            - httpApi: 'POST /articles'
    get-article:
        handler: App\GetArticleController
        runtime: php-81
        events:
            - httpApi: 'GET /articles/{id}'

Path parameters (e.g. {id} in the example above) are available as request attributes in the PSR-7 request:

$id = $request->getAttribute('id');

Full reference of HTTP events in serverless.yml (opens in a new tab).

Lambda event and context

The API Gateway event and Lambda context are available as attributes on the PSR-7 request:

/** @var $event Bref\Event\Http\HttpRequestEvent */
$event = $request->getAttribute('lambda-event');
 
/** @var $context Bref\Context\Context */
$context = $request->getAttribute('lambda-context');

If you're looking for the request context array, for example when using a Lambda authorizer (opens in a new tab):

$requestContext = $request->getAttribute('lambda-event')->getRequestContext();

Cold starts

AWS Lambda automatically destroys Lambda containers that have been unused for 10 minutes. Warming up a new container can take 250ms or more, especially if your application is large. This delay is called cold start (opens in a new tab).

To mitigate cold starts for HTTP applications, you can periodically send an event to your Lambda including a {warmer: true} payload. This will trigger the Lambda function. Bref recognizes this event and immediately responds with a Status: 100 without executing your code.

You can set up such events using a schedule (read this article for more details (opens in a new tab)):

        events:
            - httpApi: '*'
            - schedule:
                rate: rate(5 minutes)
                input:
                    warmer: true

You can learn more how AWS Lambda scales and runs in the Serverless Visually Explained (opens in a new tab) course.