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.xof thebref/extra-php-extensionspackage.If you are using Bref v1, you need to use version
0.xof thebref/extra-php-extensionspackage.
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 layerAvailable layers
| Name | Serverless config (php 8.1) |
|---|---|
| AMQP | ${bref-extra:amqp-php-81} |
| Blackfire | ${bref-extra:blackfire-php-81} |
| Bsdiff | ${bref-extra:bsdiff-php-81} |
| Calendar | ${bref-extra:calendar-php-81} |
| Cassandra | ${bref-extra:cassandra-php-81} |
| Datadog | ${bref-extra:datadog-php-81} |
| Decimal | ${bref-extra:decimal-php-81} |
| DS | ${bref-extra:ds-php-81} |
| Elastic APM | ${bref-extra:elastic-apm-php-81} |
| GD | ${bref-extra:gd-php-81} |
| gnupg | ${bref-extra:gnupg-php-81} |
| GMP | ${bref-extra:gmp-php-81} |
| gRPC | ${bref-extra:grpc-php-81} |
| Igbinary | ${bref-extra:igbinary-php-81} |
| Imagick | ${bref-extra:imagick-php-81} |
| IMAP | ${bref-extra:imap-php-81} |
| LDAP | ${bref-extra:ldap-php-81} |
| Mailparse | ${bref-extra:mailparse-php-81} |
| MaxMind DB | ${bref-extra:maxminddb-php-81} |
| Memcache | ${bref-extra:memcache-php-81} |
| Memcached | ${bref-extra:memcached-php-81} |
| MongoDB | ${bref-extra:mongodb-php-81} |
| MsgPack | ${bref-extra:msgpack-php-81} |
| Newrelic | ${bref-extra:newrelic-php-81} |
| ODBC Snowflake | ${bref-extra:odbc-snowflake-php-81} |
| OpenSwoole | ${bref-extra:openswoole-php-81} |
| Oracle | ${bref-extra:oci8-php-80} |
| Pcov | ${bref-extra:pcov-php-81} |
| PostgreSQL | ${bref-extra:pgsql-php-81} |
| RdKafka | ${bref-extra:rdkafka-php-81} |
| Redis (phpredis) | ${bref-extra:redis-php-81} |
| Redis-Igbinary | ${bref-extra:redis-igbinary-php-81} |
| Relay | ${bref-extra:relay-php-81} |
| Scout APM | ${bref-extra:scoutapm-php-81} |
| Scrypt | ${bref-extra:scrypt-php-81} |
| SPX | ${bref-extra:spx-php-81} |
| SSH2 | ${bref-extra:ssh2-php-81} |
| Swoole | ${bref-extra:swoole-php-81} |
| Symfony Runtime | ${bref-extra:symfony-runtime-php-81} |
| Microsoft SQLSRV | ${bref-extra:sqlsrv-php-81} |
| Tideways | ${bref-extra:tideways-php-81} |
| Tidy | ${bref-extra:tidy-php-81} |
| UUID | ${bref-extra:uuid-php-81} |
| Xdebug | ${bref-extra:xdebug-php-81} |
| Xlswriter | ${bref-extra:xlswriter-php-81} |
| Yaml | ${bref-extra:yaml-php-81} |
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.25You 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.
- Create a new folder in
layersand name it to your extension name. - Add your Dockerfile
- Create a config.json file at root of your layer directory specifying php versions it is built for
- Create a test.php file with a small test that makes sure the extension is loaded
- 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 makeLambda 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.