PHP functions runtime for AWS Lambda

Bref's "Event-driven function" runtime lets you run PHP functions on AWS Lambda.

Unlike the PHP-FPM runtime, the function runtime does not use PHP-FPM. Instead, it invokes your PHP code directly with the AWS Lambda event.

Here is an example of a PHP Lambda function written as an anonymous function:

<?php
 
require __DIR__ . '/vendor/autoload.php';
 
return function ($event) {
    return 'Hello ' . ($event['name'] ?? 'world');
};

This form is very similar to lambdas written in other languages, for example JavaScript (opens in a new tab):

exports.myHandler = async function (event, context) {
   return "Hello " + event.name;
}

Writing functions is very useful to process events and data from other AWS services. For example, this is perfect to implement asynchronous workers, event handling, file processing, etc. Plenty of examples are available in the "Use cases" section in the menu.

Usage

To deploy a PHP function on AWS Lambda, use the php-xx runtime:

service: app
provider:
    name: aws
plugins:
    - ./vendor/bref/bref
functions:
    hello:
        handler: my-function.php
        runtime: php-81

PHP functions

Functions that can run on Lambda can be an anonymous function or any kind of callable supported by PHP (opens in a new tab).

<?php
 
require __DIR__ . '/vendor/autoload.php';
 
return function ($event) {
    return /* result */;
};

The function:

• takes an $event parameter which contains data from the event that triggered the function (list of examples here (opens in a new tab))
• can optionally return a result: the result must be serializable to JSON

There can only be one function returned per PHP file.

Context

The function is invoked with the $event parameter as well as a $context parameter. This parameter can be optionally declared if you want to use it:

<?php
 
use Bref\Context\Context;
 
require __DIR__ . '/vendor/autoload.php';
 
return function ($event, Context $context) {
    return /* result */;
};

The Context object is inspired from the context parameter in other languages (opens in a new tab) and provides information about the current lambda invocation (the request ID, the X-Ray trace ID, etc.).

PHP classes

As mentioned above, Lambda handlers can be functions or any kind of callable supported by PHP. That means you can write them as PHP classes.

The simplest option is to implement the Bref\Event\Handler interface. This is a generic interface to handle any kind of event.

<?php
 
use Bref\Context\Context;
 
require __DIR__ . '/vendor/autoload.php';
 
class Handler implements \Bref\Event\Handler
{
    public function handle($event, Context $context)
    {
        return 'Hello ' . $event['name'];
    }
}
 
return new Handler();

Bref also provides more specific abstract classes that you can extend. These let you get type-hinted events with autocompletion and type safety.

Explore the "Use cases" section in the left menu to learn more.

Autoloading

As you can see in the example above, we define the class in the "handler" file, i.e. the same file where we return new Handler().

But we can perfectly move that class to another directory, Composer will autoload it as usual:

<?php
 
require __DIR__ . '/vendor/autoload.php';
 
// The class is stored in `src/` or `app/` and autoloaded by Composer
return new \MyApp\Handler();

What is important is to configure serverless.yml to use the file that returns the handler:

# ...
 
functions:
    hello:
        handler: my-function.php # the file that returns the handler

DI container integration

It is also possible to directly define PHP classes as AWS Lambda handlers.

functions:
    hello:
        handler: MyApp\Handler

Invocation

A PHP function must be invoked via the AWS Lambda API, either manually or by integrating with other AWS services.

CLI

A PHP function can be triggered manually from the CLI using the serverless invoke command (opens in a new tab):

$ serverless invoke -f <function-name>
# The function name is the one in serverless.yml, in our example that would be `hello`:
$ serverless invoke -f hello
"Hello world"

To pass event data to the lambda use the --data option. For example:

serverless invoke -f <function-name> --data='{"name": "John" }'

Run serverless invoke --help to learn more about the invoke command.

From PHP applications

A PHP function can be triggered from another PHP application using the AWS PHP SDK:

You first need to install the AWS PHP SDK by running

$ composer require aws/aws-sdk-php

$lambda = new \Aws\Lambda\LambdaClient([
    'version' => 'latest',
    'region' => '<region>',
]);
 
$result = $lambda->invoke([
    'FunctionName' => '<function-name>',
    'InvocationType' => 'RequestResponse',
    'LogType' => 'None',
    'Payload' => json_encode(/* event data */),
]);
 
$result = json_decode($result->get('Payload')->getContents(), true);

From other AWS services

Functions are perfect to react to events emitted by other AWS services.

For example, you can write code that processes new SQS events, SNS messages, new uploaded files on S3, DynamoDb insert and update events, etc.

Plenty of examples are available in the "Use cases" section in the menu, get started there!