Applications might require native PHP extensions which are usually written in C. Consequently, they need to be compiled as shared libraries (.so files) to be used by PHP.

Some of them are pre-installed and shipped by default with the deployed version of PHP. Others are dynamically installed if specified in the project’s composer.json file.

Pre-Installed Extensions

The following extensions are available and enabled by default with the installed version of PHP. You don’t need to add them in your composer.json file (but you can).

• Databases: mysql, mysqli, pgsql, pdo-mysql, pdo-pgsql,
• Compression: bz2, zlib, zip
• Web services: soap
• XML manipulation: xmlreader
• String encoding: mbstring
• Process control: pcntl
• Socket management: sockets
• Math functions: bcmath
• Images manipulation: gd
• Intl (Internationalization): intl

Working With PECL Extensions

All PECL extensions are available. If the extension you need is not in the above list of pre-installed extensions, it will be compiled during the build phase of your deployment.

To enable a native PHP extension, add it in the require block of your composer.json, like so (notice the ext- prefix):

{
  "require": {
    "ext-mongodb": "*",
    "ext-imagick": "*",
    ...
  }
}

Working With PECL Extensions That Have Dependencies

While some PECL extensions compile and install just fine out of the box, some others have precise requirements. In most cases, these requirements consist in libraries and libraries headers, which are generally available and distributed as OS packages.

The documentation of the extension should normally specify the name(s) (and sometimes the versions) of these required package(s).

To install these packages in your container, and when possible, we strongly recommend to use the APT buildpack along with the multi-buildpack.

Specifying Compilation Flags

Some extensions also require specific compilation flags to be set. To specify these flags, create a new environment variable named after the extension and prefixed with PHP_PECL_EXTENSION_CONFIGURE_ARGS_ (see Full Example, below). Then, put the compilation flags you want to use in this variable.

Each extension requiring specific compilation flags must have its own environment variable.

Full Example

In this example, we are going to install the PECL extension named yaml. This is a good example as it requires thelibyaml and libyaml-dev packages to be installed, and it also needs some specific compilation flags.

First, let’s tell the platform we need this extension. To do so, we will have to create a file named composer.json at the root of our project, like this:

{
  "require": {
    "ext-yaml": "*"
  }
}

As recommended, we will use the multi-buildpack to tell the platform to:

1. first, call the APT buildpack to install the required packages;
2. and then, use the PHP buildpack to install PHP, Composer and the required extensions.

Let’s create a file named .buildpacks at the root of the project with the following content:

https://github.com/Scalingo/apt-buildpack
https://github.com/Scalingo/php-buildpack

libyaml is already available in our containers so we don’t have to worry about it. But we still have to install libyaml-dev. To do so, create another file, named Aptfile, at the root of the project:

libyaml-dev

We then need to create a dedicated environment variable, named PHP_PECL_EXTENSION_CONFIGURE_ARGS_yaml and set its value to --with-yaml=$BUILD_DIR/.apt/usr. This instructs the platform to compile the extension with this flag, which tells the compile script where to find the libyaml headers.

The last step consists in committing your work and pushing it to Scalingo.