# Technical Documentation: mlocati/docker-php-extension-installer

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/mlocati/docker-php-extension-installer)

### Overview (README.md)

[](https://github.com/mlocati/docker-php-extension-installer/releases)
[](https://hub.docker.com/r/mlocati/php-extension-installer)
[](https://github.com/mlocati/docker-php-extension-installer/pkgs/container/php-extension-installer)
[](https://github.com/mlocati/docker-php-extension-installer/actions/workflows/check-updates.yml)

# Easy installation of PHP extensions in official PHP Docker images

This repository contains a script that can be used to easily install a PHP extension inside the [official PHP Docker images](https://hub.docker.com/_/php/).

The script will install all the required APT/APK packages; at the end of the script execution, the no-more needed packages will be removed so that the image will be much smaller.

Supported docker images are:

- Debian-based docker images: since jessie (Debian 8) (minimum PHP version: 5.5)
- Alpine-based docker images: since Alpine 3.9 (minimum PHP version: 7.1)

See also the notes in the [Special requirements](#special-requirements) section.

## Usage

You have many ways to use this script within your `Dockerfile`s.

Here's a list of sample `Dockerfile`s that install the GD and xdebug PHP extensions:

### Downloading the script on the fly with `ADD`

```Dockerfile
FROM php:7.2-cli

ADD --chmod=0755 https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug
```

### Downloading the script on the fly with `curl`

```Dockerfile
FROM php:7.2-cli

RUN curl -sSLf \
        -o /usr/local/bin/install-php-extensions \
        https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions && \
    chmod +x /usr/local/bin/install-php-extensions && \
    install-php-extensions gd xdebug
```

### Direct execution with `curl`

```Dockerfile
FROM php:8.2-cli

RUN ( curl -sSLf https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions -o - || echo 'return 1' ) | sh -s \
      gd xdebug
```

### Copying the script from a Docker image

- using GitHub Container Registry
  
  ```Dockerfile
  FROM php:8.4-cli
  
  COPY --from=ghcr.io/mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/
  
  RUN install-php-extensions gd xdebug
  ```
- using Docker Hub
  
  ```Dockerfile
  FROM php:8.4-cli
  
  COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/
  
  RUN install-php-extensions gd xdebug
  ```

**Warning**: by using this method you may use an outdated version of the Docker image.
You may want to run `docker pull ghcr.io/mlocati/php-extension-installer` or `docker pull mlocati/php-extension-installer` in order to use an up-to-date version.

### Using the script of a Docker image

- using GitHub Container Registry
  
  ```Dockerfile
  RUN  --mount=type=bind,from=ghcr.io/mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
      install-php-extensions gd xdebug
  ```
- using Docker Hub
  
  ```Dockerfile
  RUN  --mount=type=bind,from=mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
      install-php-extensions gd xdebug
  ```

**Warning**: by using this method you may use an outdated version of the Docker image image.
You may want to run `docker pull ghcr.io/mlocati/php-extension-installer` or `docker pull mlocati/php-extension-installer` in order to use an up-to-date version.


## Installing specific versions of an extension

Simply append `-<version>` to the module name.
For example:

```sh
install-php-extensions xdebug-2.9.7
```

The script also supports resolving *compatible* versions by prefixing the version with a caret (`^`).
For example:

```sh
# Install the most recent xdebug 2.x version (for example 2.9.8)
install-php-extensions xdebug-^2
# Install the most recent xdebug 2.8.x version (for example 2.8.1)
install-php-extensions xdebug-^2.8
```

Please remark that with the syntax above you'll get the very latest compatible version, which may be unstable. In order to install the most recent *stable* version, you can append `@stable`:

```sh
# Install the most recent STABLE xdebug 3.x version (for example 3.2.2)
install-php-extensions xdebug-^3@stable
```

(valid suffixes are: `@snapshot`, `@devel`, `@alpha`, `@beta`, and `@stable`)

Pre-release versions extensions available on `PECL` can be setup by suffixing the extension's name with its state i.e. `alpha`, `beta`, `rc`, `preview`, `devel` or `snapshot`.
For example:

```sh
install-php-extensions xdebug-beta
```

TIP: When the latest version available on `PECL` is not stable, and you want to keep the last stable version, 
force it by suffixing the extension's name with the `stable` state.
For example:

```sh
install-php-extensions mongodb-stable
```

## Installing an extension from its source code

You can also install PHP extensions from source code (provided that it comes with a `package.xml` or a `package2.xml` file).

Accepted formats are:

- A short version for repositories hosted on GitHub.  
  For example, for the [php-memcached-dev/php-memcached](https://github.com/php-memcached-dev/php-memcached) GitHub repository,
  you can simply write:
  ```sh
  # Install from a specific commit (full commit SHA-1)
  install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb005ca6100b12ccc89000daafa9d8
  # Install from a specific commit (short commit SHA-1)
  install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb
  # Install from tag v3.2.0RC2
  install-php-extensions php-memcached-dev/php-memcached@v3.2.0RC2
  install-php-extensions php-memcached-dev/php-memcached@refs/tags/v3.2.0RC2
  # Install from branch master
  install-php-extensions php-memcached-dev/php-memcached@master
  install-php-extensions php-memcached-dev/php-memcached@refs/heads/master
  ```
- An URL providing an archive containing the source code.  
  Examples:
  ```sh
  # tgz archive for commit 8f106564e6bb005ca6100b12ccc89000daafa9d8
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/8f106564e6bb005ca6100b12ccc89000daafa9d8
  # tgz archive for tag v3.1.5
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
  # tgz archive for branch master
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/heads/master
  ```
- The absolute path of a local directory.  
  Examples:
  ```sh
  # Download the source code
  curl -o /tmp/source.tgz https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
  tar xzf /tmp/source.tgz -C /tmp
  install-php-extensions /tmp/php-memcached-3.1.5

## Bundled extensions or not?

There are some extensions that are bundled in the PHP source code (for example, `gd` and `zip`).

Some of these extensions are also available on PECL and/or a source code repository.

By default, `install-php-extensions` installs the bundled version.

If instead you want to use a remote version:

- for using PECL: just append the stability to the package name. For example:
  ```
  install-php-extensions zip-stable
  ```
- for installing from source code: use the syntax [specified above](#installing-an-extension-from-its-source-code). For example:
  ```
  install-php-extensions php/pecl-database-oci8@7aa1061
  ```

`install-php-extensions` supports installing remote versions instead of bundled ones for these extensions:

- pdo_oci
- oci8
- zip

## Installing composer

You can also install [composer](https://getcomposer.org/), and you also can specify a major version of it, or a full version.

Examples:

```sh
# Install the latest version
install-php-extensions @composer
# Install the latest 1.x version
install-php-extensions @composer-1
# Install a specific version
install-php-extensions @composer-2.0.2
```

## Issue with Let's Encrypt certificates

The root CA certificate of Let's Encrypt changes ([more details here](https://letsencrypt.org/docs/dst-root-ca-x3-expiration-september-2021/)).  
That breaks old linux distributions, namely:

- Debian Jessie (8)
- Debian Stretch (9)
- Alpine Linux 3.7
- Alpine Linux 3.8

This script can fix this issue: simply pass `@fix_letsencrypt` as an argument:

```sh
install-php-extensions @fix_letsencrypt
```
/* Detailed source-code truncated for AI context efficiency. */
```
$ docker run --rm php:8.5-cli php -m
[PHP Modules]
Core
ctype
curl
date
dom
fileinfo
filter
hash
iconv
json
lexbor
libxml
mbstring
mysqlnd
openssl
pcre
PDO
pdo_sqlite
Phar
posix
random
readline
Reflection
session
SimpleXML
sodium
SPL
sqlite3
standard
tokenizer
uri
xml
xmlreader
xmlwriter
Zend OPcache
zlib

[Zend Modules]
Zend OPcache
```

## Configuration

You can configure the behavior of the script, as well as fine-tune some extensions in order fit your needs, by using environment variables.

Here's an example:

```sh
IPE_LZF_BETTERCOMPRESSION=1 install-php-extensions lzf
```
/* Detailed source-code truncated for AI context efficiency. */
```sh
cat /etc/os-release
```

For example:
- for Debian 11 (Bullseye) you'll see:
  ```sh
  PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"
  ```
- for Alpine Linux 3.14 you'll see:
  ```sh
  PRETTY_NAME="Alpine Linux v3.14"
  ```

## Library versions

Some PHP extensions require libraries that `install-php-extensions` compiles or downloads when they aren't provided by the system.
You can use a version different from the default one by setting the corresponding environment variable.
For example:

```sh
IPE_LIBVERSION_XCRYPT=4.4.36 install-php-extensions xpass
```

**Beware**: other versions may not work, so use this feature at your own risk.

Here's the list of these libraries (the default versions are the ones used by the latest release of `install-php-extensions`):









| Library | Environment variable | Default version | Used by | Notes |
|---|---|---|---|---|
| [libaom](https://aomedia.googlesource.com/aom/+refs) | `IPE_LIBVERSION_AOM` | `3.12.0` | gd | Only with PHP 8.1+ on Alpine < 3.15 and Debian < 12 (unless `IPE_GD_WITHOUTAVIF` is set) |
| [libavif](https://github.com/AOMediaCodec/libavif/releases) | `IPE_LIBVERSION_AVIF` | `1.3.0` | gd | Only with PHP 8.1+ on Alpine < 3.15 and Debian < 12 (unless `IPE_GD_WITHOUTAVIF` is set) |
| [Cassandra C++ driver](https://github.com/apache/cassandra-cpp-driver/tags) | `IPE_LIBVERSION_CASSANDRACPPDRIVER` | `2.17.1` | cassandra |  |
| [libcmark](https://github.com/commonmark/cmark/releases) | `IPE_LIBVERSION_CMARK` | `0.31.2` | cmark | Only with cmake 3.15+ (with older cmake versions we use older libcmark versions) |
| [libdatrie](https://github.com/tlwg/libdatrie/releases) | `IPE_LIBVERSION_DATRIE` | `0.2.14` | wikidiff2 | Only on Alpine |
| [libdav1d](https://code.videolan.org/videolan/dav1d/-/tags) | `IPE_LIBVERSION_DAV1D` | `1.5.3` | gd | Only with PHP 8.1+ on Alpine < 3.15 and Debian < 12 (unless `IPE_GD_WITHOUTAVIF` is set) |
| [libenchant1](https://github.com/rrthomas/enchant/releases) | `IPE_LIBVERSION_ENCHANT1` | `1.6.1` | enchant | Only with PHP < 8.0 on Alpine 3.12+ and Debian 11+ |
| [Firebird](https://github.com/FirebirdSQL/firebird/releases) | `IPE_LIBVERSION_FIREBIRD` | `5.0.4.1812-0` | interbase, pdo_firebird, swoole | Only on Alpine, with PHP 8.4+ (with older PHP versions we use Firebird 2.5). Format: `<version>.<build>-<revision>` (as in the name of the source archive) |
| [libgearman](https://github.com/gearman/gearmand/releases) | `IPE_LIBVERSION_GEARMAN` | `2.1.0` | gearman | Only on Alpine |
| [HAT-trie](https://github.com/Tessil/hat-trie/releases) | `IPE_LIBVERSION_HATTRIE` | `0.7.1` | php_trie |  |
| [libidnkit](https://jprs.co.jp/idn/) | `IPE_LIBVERSION_IDNKIT` | `2.3` | http | Only with PHP 7.0+ |
| [ion-c](https://github.com/amzn/ion-c/releases) | `IPE_LIBVERSION_IONC` | `1.1.6` | ion |  |
| [IP2Location C library](https://github.com/chrislim2888/IP2Location-C-Library/tags) | `IPE_LIBVERSION_IP2LOCATION` | `8.7.0` | ip2location |  |
| [libmpdec](https://www.bytereef.org/mpdecimal/changelog.html) | `IPE_LIBVERSION_MPDEC` | `4.0.1` | decimal | Only on Alpine and Debian 12+ |
| [Microsoft ODBC Driver for SQL Server (Alpine)](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server) | `IPE_LIBVERSION_MSODBC` | `18.7.1.1-1@ade174b7-8cea-4543-91a6-c33ae320c2f0` | pdo_sqlsrv, sqlsrv | Only on Alpine, with PHP 7.4+. Format: `<version>@<download path>` (see the download URLs on the [Microsoft website](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server)) |
| [Microsoft ODBC Driver 17 for SQL Server (Alpine)](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server#alpine17) | `IPE_LIBVERSION_MSODBC17` | `17.11.1.1-1@607ebe2c-e17c-4c34-b367-10a75b83bef9` | pdo_sqlsrv, sqlsrv | Only on Alpine, with PHP up to 7.3. Format: `<version>@<download path>` (see the download URLs on the [Microsoft website](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server)) |
| [libthai](https://github.com/tlwg/libthai/releases) | `IPE_LIBVERSION_THAI` | `0.1.30` | wikidiff2 | Only on Alpine |
| [libtomcrypt](https://github.com/libtom/libtomcrypt/releases) | `IPE_LIBVERSION_TOMCRYPT` | `1.18.2` | pdo_firebird, swoole | Only on Alpine, with PHP 8.4+ |
| [libtommath](https://github.com/libtom/libtommath/releases) | `IPE_LIBVERSION_TOMMATH` | `1.3.0` | pdo_firebird, swoole | Only on Alpine, with PHP 8.4+ |
| [libxcrypt](https://github.com/besser82/libxcrypt/releases) | `IPE_LIBVERSION_XCRYPT` | `4.5.2` | xpass | Only on Alpine |
| [LibXDiff](http://www.xmailserver.org/xdiff-lib.html) | `IPE_LIBVERSION_XDIFF` | `0.23` | xdiff |  |
| [libyuv](https://chromium.googlesource.com/libyuv/libyuv/+log) | `IPE_LIBVERSION_YUV` | `d359a9f922af840b043535d43cf9d38b220d102e` | gd | Only with PHP 8.1+ on Alpine < 3.15 and Debian < 12 (unless `IPE_GD_WITHOUTAVIF` is set). Format: git commit hash |
| [zstd](https://github.com/facebook/zstd/releases) | `IPE_LIBVERSION_ZSTD` | `1.5.7` | redis | Only with redis 5+ |


## Tests

When submitting a pull request, a [GitHub Action](https://github.com/mlocati/docker-php-extension-installer/blob/master/.github/workflows/test-extensions.yml) is executed to check if affected PHP extensions actually work (see below).

Furthermore, we also check that new versions of the PHP extensions and of the libraries they use will still work.
This is done on a scheduled basis with another [GitHub Action](https://github.com/mlocati/docker-php-extension-installer/blob/master/.github/workflows/check-updates.yml).  
In case of failure, a message is sent to a [Telegram Channel](https://t.me/docker_php_extension_installer).  
Feel free to subscribe to it to receive failure notifications.

## How to contribute

See the [`CONTRIBUTING.md`](https://github.com/mlocati/docker-php-extension-installer/blob/master/CONTRIBUTING.md) file.


## For the maintainers

See the [`MAINTAINERS.md`](https://github.com/mlocati/docker-php-extension-installer/blob/master/MAINTAINERS.md) file.

## Do you want to really say thank you?

You can offer me a [monthly coffee](https://github.com/sponsors/mlocati) or a [one-time coffee](https://paypal.me/mlocati) :wink:

---

--- METRICS ---
- Files Extracted: 1
- Estimated Token Budget: ~3875 tokens
- Canonical Reference: https://codewiki.google/github.com/mlocati/docker-php-extension-installer