Configuring PHP


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 override the path by setting it in the PHP_INI_SCAN_DIR environment variable.

PHP_INI_SCAN_DIR must contain an absolute path. Since your code is placed in /var/task on AWS Lambda, the environment variable should contain something like /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.


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

Extensions installed and enabled

Extensions installed but disabled by default

  • intl - Internationalization extension (referred 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.
  • PostgreSQL PDO Driver - PDO_PGSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to PostgreSQL databases.

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


Extra extensions

Due to space limitations in AWS Lambda, Bref cannot provide every possible extension. There are a list of additional PHP extensions that can be installed as a separate layer. They are less common extensions or extensions that for some reasons should not be in the normal Bref layer.

All extra PHP extensions are found in brefphp/extra-php-extensions.

Contributions to add more PHP extensions are welcomed.

Custom extensions

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

This guide is really raw, feel free to contribute to improve it.

To create your custom layer, you will need to:

  • compile the extension (and any required libraries) in the same environment as AWS Lambda and Bref
  • include the compiled extension (and required libraries) in a layer
  • upload the layer to AWS Lambda
  • include it in your project after the Bref layer
  • enable the extension in a custom php.ini

To compile the extension, Bref provides the bref/build-php-* Docker images. Here is an example with Blackfire:

FROM bref/build-php-74

RUN curl -A "Docker" -o /tmp/ -L -s ""

# Build the final image from the amazon image that is close to the production environment

# Copy things we installed to the final image
COPY --from=0 /tmp/ /opt/bref-extra/

The .so extension file can then be retrieved in /opt/bref-extra/ If you installed system libraries, you may also need to copy them to the image.

See brefphp/extra-php-extensions for more examples.

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.

    # ...
        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.

Separate vendor folder

Bref has the ability to shrink the Lambda deployment archive by separating the vendor folder from the applications code and injecting it later on into the Lambda function. This allows Bref to circumvent Lambda file size limitations.

By setting the option separateVendor in the custom.bref block to true, you can enable this feature.

        separateVendor: true

Using this option changes the path of the vendor directory to /tmp/vendor. References in your code to the composer autoloader therefore must be adjusted to /tmp/vendor/autoload.php.