Bref Extra PHP Extension

This repository provides PHP extensions for Bref applications via AWS Lambda layers.

This is useful when you want something "off the shelf". If you ever need more than 2-3 layer you should consider creating your own layer. That is because AWS has a limit of 5 layers per Lambda. You can also utilise the provided docker images for local development.

Note

If you are using Bref v2, you need to use version 1.x of the bref/extra-php-extensions package.

If you are using Bref v1, you need to use version 0.x of the bref/extra-php-extensions package.

Warning

ARM64 is not supported yet with Bref v2.

We are happy to get contributions for other extensions. Sky is the limit! (And also your knowledge with Docker...)

Install and configure

composer require bref/extra-php-extensions

# serverless.yml
service: app

provider:
    name: aws
    region: us-east-1

plugins:
    - ./vendor/bref/bref
    - ./vendor/bref/extra-php-extensions # <----- Add the extra Serverless plugin

functions:
    console:
        handler: bin/console
        runtime: php-81
        layers:
            - ${bref-extra:amqp-php-81} # <----- Example for AMQP layer

Available layers

Blackfire installation

The Blackfire layer only have the probe installed.

You still need to install the agent. The agent is installed on a separate server (not a lambda function). The micro EC2 instance is sufficient to run the Blackfire agent.

Create a blackfire.ini file in php/conf.d/ for your lambda function where you load the extension and modify the agent_socket in order to point it to the Blackfire Agent.

;php/conf.d/blackfire.ini
blackfire.agent_socket = tcp://ip-172-40-40-40.eu-central-1.compute.internal:8307
blackfire.agent_timeout = 0.25

You may tweak other Blackfire parameters. See Blackfire documentation about them.

Then modify your agent config to make sure you are listening to tcp://0.0.0.0:8307.

This blog post could be helpful as it describes how to install the Blackfire Agent.

ODBC Snowflake setup

You need to set the environment variable ODBCSYSINI: /opt/snowflake_odbc/conf/ in your serverless.yaml in order to tell unixODBC to load the ini file of the snowflake client.

You can then use snowflake like this: odbc_connect('DRIVER=SnowflakeDSIIDriver;Server=[name].snowflakecomputing.com;Account=;Schema=;Warehouse=;Database=;Role=', 'username', 'password').

There is more information about the driver ini configuration in the snowflake client documentation but the default configuration is enough in most cases. The easiest way review those is to download the snowflake_odbc directory.

Symfony Runtime

Read docs at runtime/bref.

SQL Server setup

The SQL Server layer includes both the SQLSRV extension and the PDO_SQLSRV extension (source). If you are unsure of which extension to use, this stackoverflow post may be helpful. You need to set the environment variable ODBCSYSINI: /opt/microsoft/conf/ in your serverless.yaml in order to tell unixODBC to load the required ini files.

New Relic

Read the New Relic tutorial.

Datadog

Read the Datadog tutorial.

Docker images

There are Docker images for every layer. They are updated on every push to master and on every tag. The name of the image is bref/extra-[name]-php-[version]. Find all images on Docker hub.

These are the same docker images that creates the layers. All layer files lives inside the /opt directory in the image.

Local Development

When developing locally you can build your own images with the required extensions. Example with PHP 8.2 and MongoDB Extension:

docker-compose.yml

  php:
    build:
      context: .
      dockerfile: Dockerfile-phpFpm
    volumes:
      - .:/var/task:ro

Dockerfile-phpFpm

FROM bref/php-82-fpm-dev:2
COPY --from=bref/extra-mongodb-php-82:1 /opt /opt

For contributors and maintainers

Creating a new layer

The idea is to start from bref/build-php-XX, install all libraries and extensions you want, then move all related files to /opt. Those files will be available in the same location on the Lambda.

Note that one can't just move files/libraries around. Most of them are expected to be in their "standard" location.

1. Create a new folder in layers and name it to your extension name.
2. Add your Dockerfile
3. Create a config.json file at root of your layer directory specifying php versions it is built for
4. Create a test.php file with a small test that makes sure the extension is loaded
5. Update the table in the readme

Please refer here for more details.

Testing the layer

# Test all layers and PHP versions
make test

# Test only a single layer
layer=imagick make test

# Test a single layer on a single PHP version
layer=imagick php_versions=81 make test

You can publish the layer in your AWS account to test it in AWS Lambda as well:

# Publish a single layer on a single PHP version in a single region
layer=imagick php_versions=81 only_region=us-east-1 make publish

Deploy new versions

Use Github actions

Prepare the changelog with some release notes. Then push your changes to prepare-release branch. The Github Action will build an publish layers and then commit the layers.json to your PR.

Now you will just merge and create a tag.

The manual way

export AWS_PROFILE=my_profile
make publish
git add layers.json
git commit -m "New version of layers"
git push

Config

You can also build only one specific layer by providing layer=blackfire to make. Same thing for some specific version(s) of php by providing php_versions="80 81" to make. You can invoke both ways:

# First way: make with named arguments
make layer=gd php_versions=81
# Second way: environment variables passed to make
layer=blackfire php_versions=81 make

Lambda layers in details

Notice: this section is only useful if you want to learn more.

The lambda layers follow this pattern:

arn:aws:lambda:<region>:403367587399:layer:<layer-name>:<layer-version>

See the latest layer versions.