Configuring PHP

php.ini

PHP will read its configuration from:

• /opt/bref/etc/php/php.ini (PHP’s official production configuration)
• /opt/bref/etc/php/conf.d/bref.ini (Bref’s optimizations for Lambda)

These files cannot be customized.

Customizing php.ini

You can create your own php.ini to customize PHP’s configuration:

1. create a php/conf.d/ subdirectory in your project
2. create a php.ini file inside that directory (the name of the file does not matter, it must have an .ini extension)

PHP will automatically include any *.ini file found in php/conf.d/ in your project.

Customizing php.ini using a custom path

If you want PHP to scan a different directory than php/conf.d/ in your project, you can add it with the PHP_INI_SCAN_DIR environment variable:

provider:
    environment:
        PHP_INI_SCAN_DIR: '/opt/bref/etc/php/conf.d:/var/task/my/different/dir'

Learn how to declare environment variables by reading the Environment Variables guide.

Customizing php.ini in extra layers

If you are using Lambda layers, for example to use custom PHP extensions, you can override the default php.ini by placing your own configuration file in /opt/bref/etc/php/conf.d/.

Make sure to give a unique name to your .ini file to avoid any collision with other layers.

OPcache

OPcache is enabled by default. PHP checks whether each PHP file has changed before using its cached version (opcache.validate_timestamps). The code of a Lambda function does not change once deployed, so you can disable that check in your php/conf.d/php.ini to save a little time on each request:

opcache.validate_timestamps=0

Keep the check enabled if your application modifies PHP files at runtime (for example a cache written to /tmp): OPcache would keep using the old version of those files.

Extensions

Bref strives to include the most common PHP extensions. If a major PHP extension is missing please open an issue to discuss it.

Built-in extensions

The following extensions are installed and enabled by default in Bref runtimes:

• Core
• bcmath
• ctype
• curl
• date
• dom
• exif
• FFI
• fileinfo
• filter
• ftp
• gettext
• hash
• iconv
• json
• libxml
• mbstring
• mysqli
• mysqlnd
• opcache
• openssl
• pcntl
• pcre
• PDO
• pdo_sqlite
• pdo_mysql
• pdo_pgsql
• Phar
• posix
• readline
• Reflection
• session
• SimpleXML
• sodium
• sockets
• SPL
• sqlite3
• tokenizer
• xml
• xmlreader
• xmlwriter
• xsl
• zip
• zlib

FFI follows PHP’s default ffi.enable=preload: it can be used from the CLI and from preloaded files. Set ffi.enable=true in your php.ini to use it everywhere.

Extensions installed but disabled by default

The following extensions are installed in Bref runtimes, but disabled by default:

• intl  - Internationalization extension (referred to as Intl) is a wrapper for ICU library, enabling PHP programmers to perform various locale-aware operations.
• APCu  - APCu is APC stripped of opcode caching.
• Redis  - A PHP extension for interfacing with Redis.
• soap  - SOAP client and server for PHP

You can enable these extensions by loading them in php/conf.d/php.ini (as mentioned in the section above), for example:

extension=intl
extension=apcu
extension=redis
extension=soap

Extra extensions

Due to space limitations in AWS Lambda, Bref runtimes cannot include every possible PHP extension. These additional PHP extensions are provided by the brefphp/extra-php-extensions  project, as separate AWS Lambda layers and Docker images.

The most popular extra extensions are:

• gd  - image processing with the GD library
• imagick  - image manipulation with ImageMagick
• gmp  - GNU Multiple Precision arithmetic
• mongodb  - MongoDB driver
• sqlsrv  - Microsoft SQL Server driver (pdo_sqlsrv)
• memcached  - Memcached client
• rdkafka  - Apache Kafka client (librdkafka)
• amqp  - RabbitMQ and AMQP client
• grpc  and protobuf  - gRPC and Protocol Buffers
• ldap  - LDAP directory access
• xdebug  - debugging and profiling
• pcov  - code coverage
• blackfire , tideways , datadog , newrelic  - APM and profiling agents

And many more: see the full list of extra extensions . Contributions to add more PHP extensions are welcome.

Not every extension is available for every PHP version (some are not published for PHP 8.5 yet). Check the available layers  for your PHP version.

Using extra extensions with Lambda layers

Install the bref/extra-php-extensions package, add its plugin to serverless.yml and reference the layer of each extension you need:

composer require bref/extra-php-extensions

plugins:
    - ./vendor/bref/bref
    - ./vendor/bref/extra-php-extensions
 
functions:
    api:
        handler: public/index.php
        runtime: php-84-fpm
        layers:
            - ${bref-extra:gd-php-84}
            - ${bref-extra:imagick-php-84}

Use these ${bref-extra:…} variables rather than copying layer ARNs: the ARNs follow updates of the bref/extra-php-extensions package.

Keep in mind that AWS Lambda allows at most 5 layers per function, and that extra extensions are not available for ARM (arm64) yet.

Layers also count toward the 250MB size limit of Lambda functions. Some extensions are large: for example, imagick takes about 70MB unzipped (it includes Ghostscript). Deploy without development dependencies (composer install --no-dev) to leave room for them.

Using extra extensions with Docker

If you deploy using container images, each extra extension is also available as a Docker image (bref/extra-gd-php-84, bref/extra-imagick-php-84, etc.) that you can copy into your own image. Read the “Extra PHP extensions” section of the Docker guide.

Custom extensions

It is also possible to provide your own extensions via custom AWS Lambda layers .

A layer is unzipped in /opt on Lambda. A layer for a PHP extension contains:

• the compiled extension in /opt/bref/extensions/
• an .ini file that enables it in /opt/bref/etc/php/conf.d/ (give it a unique name, for example ext-<name>.ini)
• the system libraries it needs, if any, in /opt/lib/

Compile the extension in the bref/build-php-* Docker images: they use the same environment as AWS Lambda and Bref. Here is an example with the xhprof extension from PECL:

FROM bref/build-php-84:3 AS ext
 
RUN pecl install xhprof
RUN cp `php-config --extension-dir`/xhprof.so /tmp/xhprof.so
RUN echo 'extension=xhprof.so' > /tmp/ext.ini
 
# Keep only the files of the layer
FROM scratch
 
COPY --from=ext /tmp/xhprof.so /opt/bref/extensions/xhprof.so
COPY --from=ext /tmp/ext.ini /opt/bref/etc/php/conf.d/ext-xhprof.ini

Build the image, zip the content of /opt and publish it as a layer:

docker build --platform linux/amd64 --output type=local,dest=layer .
(cd layer/opt && zip -r ../../layer.zip .)
aws lambda publish-layer-version --layer-name php-84-xhprof --zip-file fileb://layer.zip --compatible-architectures x86_64

Then add the layer ARN returned by that command to the layers of your functions. The layer must be built for the same PHP version and architecture as your functions.

If you deploy using container images, you don’t need a layer: add the build stage to your Dockerfile and copy the files into your image (COPY --from=ext /tmp/xhprof.so /opt/bref/extensions/xhprof.so, and the same for the .ini file).

See brefphp/extra-php-extensions  for more examples, including extensions that need system libraries.

Custom vendor path

Bref automatically requires vendor dependencies from the default vendor/autoload.php path.

If your Composer dependencies are installed elsewhere, you can customize that path via the BREF_AUTOLOAD_PATH environment variable.

provider:
    # ...
    environment:
        BREF_AUTOLOAD_PATH: '/var/task/foo-bar/vendor/autoload.php'

The path must start with /var/task, which is the directory where projects are installed on AWS Lambda.