Go to file
Michele Locati 6bb9fe9e5a
Use official ssh2 release on PHP 8.0
Test: ssh2
2021-03-02 14:11:30 +01:00
.github Push all tagged docker images 2021-02-25 11:09:05 +01:00
data Add support for CSV 2021-02-23 18:28:37 +01:00
scripts Support installing generic versions of extensions 2021-01-26 16:58:14 +01:00
.dockerignore Only send install-php-extensions to Docker context when building the Docker image 2021-01-14 16:05:17 +01:00
.editorconfig Add lint script 2019-12-20 18:30:32 +01:00
.gitattributes fix EOL 2021-01-20 13:24:36 +01:00
.gitignore Remove inspect-pecl-package service script 2021-01-13 13:14:57 +01:00
.php_cs Check the PHP Coding Style of files in the scripts dir 2020-12-11 18:24:34 +01:00
Dockerfile create base image from scratch instead of bash 2019-10-09 21:21:06 +02:00
LICENSE Update license year 2020-11-06 18:22:38 +01:00
MAINTAINERS.md Add instructions for the maintainers 2021-01-14 15:49:25 +01:00
README.md [skip ci] Automatically update README.md 2021-02-23 18:26:49 +00:00
composer.json Lint PHP files 2019-12-27 15:00:45 +01:00
install-php-extensions Use official ssh2 release on PHP 8.0 2021-03-02 14:11:30 +01:00

README.md

Downloaded GitHub Releases Docker Hub pulls Test recent

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.

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 all the Alpine/Debian versions, except for PHP 5.5 where we only support Debian 8 (jessie) (that is, php:5.5, php:5.5-apache, php:5.5-cli, php:5.5-fpm, php:5.5-zts). See also the notes in the Special requirements section.

Usage

You have two ways to use this script within your Dockerfiles: you can download the script on the fly, or you can grab it from the mlocati/php-extension-installer Docker Hub image. With the first method you are sure you'll always get the very latest version of the script, with the second method the process is faster since you'll use a local image.

For example, here are two Dockerfiles that install the GD and xdebug PHP extensions:

Downloading the script on the fly

FROM php:7.2-cli

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

RUN chmod +x /usr/local/bin/install-php-extensions && sync && \
    install-php-extensions gd xdebug

Copying the script from a Docker image

FROM php:7.2-cli

COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

Beware

When building locally, be sure you have the latest version of the mlocati/php-extension-installer image by running :

docker pull mlocati/php-extension-installer

otherwise the COPY instruction could use a previously downloaded, outdated version of the image stored in the local docker cache.

Installing specific versions of an extension

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

install-php-extensions xdebug-2.9.7

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

# 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

Installing composer

You can also install composer, and you also can specify a major version of it, or a full version.

Examples:

# 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

Supported PHP extensions

Extension PHP 5.5 PHP 5.6 PHP 7.0 PHP 7.1 PHP 7.2 PHP 7.3 PHP 7.4 PHP 8.0
amqp
apcu
apcu_bc
bcmath
bz2
calendar
cmark
csv
dba
decimal
ds
enchant*
ev
exif
ffi
gd
gearman
geoip
geospatial
gettext
gmagick
gmp
gnupg
grpc
http
igbinary
imagick
imap
interbase
intl
ioncube_loader
json_post
ldap
mailparse
maxminddb
mcrypt
memcache
memcached
mongo
mongodb
mosquitto
msgpack
mssql
mysql
mysqli
oauth
oci8
odbc
opcache
opencensus
parallel*
pcntl
pcov
pdo_dblib
pdo_firebird
pdo_mysql
pdo_oci
pdo_odbc
pdo_pgsql
pdo_sqlsrv*
pgsql
propro
protobuf
pspell
pthreads*
raphf
rdkafka
recode
redis
seaslog
shmop
smbclient
snmp
snuffleupagus
soap
sockets
solr
sqlsrv*
ssh2
swoole
sybase_ct
sysvmsg
sysvsem
sysvshm
tidy
timezonedb
uopz
uuid
wddx
xdebug
xhprof
xlswriter
xmlrpc
xsl
yaml
yar
zip
zookeeper
zstd

Number of supported extensions: 99

PS: the pre-installed PHP extensions are excluded from this list. You can list them with the following command (change php:7.2-cli to reflect the PHP version you are interested in):

$ docker run --rm php:7.2-cli php -m
[PHP Modules]
Core
ctype
curl
date
dom
fileinfo
filter
ftp
hash
iconv
json
libxml
mbstring
mysqlnd
openssl
pcre
PDO
pdo_sqlite
Phar
posix
readline
Reflection
session
SimpleXML
sodium
SPL
sqlite3
standard
tokenizer
xml
xmlreader
xmlwriter
zlib

[Zend Modules]

Special requirements

Some extension has special requirements:

Extension Requirements
enchant • Not available in 7.2-alpine3.12 docker images
• Not available in 7.3-alpine3.12 docker images
• Not available in 7.3-alpine3.13 docker images
• Not available in 7.4-alpine3.12 docker images
• Not available in 7.4-alpine3.13 docker images
parallel Requires images with PHP compiled with thread-safety enabled (zts).
pdo_sqlsrv • Not available in 7.0-alpine3.7 docker images
• Not available in 7.1-alpine3.7 docker images
• Not available in 7.1-alpine3.8 docker images
• Not available in 7.2-alpine3.7 docker images
• Not available in 7.2-alpine3.8 docker images
• Not available in 7.3-alpine3.8 docker images
pthreads Requires images with PHP compiled with thread-safety enabled (zts).
sqlsrv • Not available in 7.0-alpine3.7 docker images
• Not available in 7.1-alpine3.7 docker images
• Not available in 7.1-alpine3.8 docker images
• Not available in 7.1-alpine3.9 docker images
• Not available in 7.1-alpine3.10 docker images
• Not available in 7.2-alpine3.7 docker images
• Not available in 7.2-alpine3.8 docker images
• Not available in 7.3-alpine3.8 docker images

Tests

When submitting a pull request, a GitHub Action is executed to check if affected PHP extensions actually work (see below).

Furthermore, we also check that new versions of extensions in the PECL repository will still work. This is done on a scheduled basis with another GitHub Action.
In case of failure, a message is sent to a Telegram Channel.
Feel free to subscribe to it to receive failure notifications.

How to contribute

Formatting code

Before submitting any pull request, be sure to execute the lint script in the scripts directory (or lint.bat on Windows).

Adding support to a new PHP extension?

  1. change the install-php-extensions script
  2. update the data/supported-extensions file, adding a new line with the handle of the extension and the list of supported PHP versions
  3. if the extension requires ZTS images:
    add a new line to the data/special-requirements file, with the extension handle followed by a space and zts

See this pull request for an example.

Changing the supported PHP versions for an already supported PHP extension?

  1. change the install-php-extensions script
  2. update the data/supported-extensions file, adding the new PHP version to the existing line corresponding to the updated extension

See this pull request for an example.

Improving code for an already supported extension?

If you change some code that affects one or more extensions, please add a line with Test: extension1, extension2 to the message of one of the pull request commits. That way, the test jobs will check the extension even if you don't touch the data/supported-extensions file.

Here's an example of a commit message:

Improve the GD and ZIP extensions

Test: gd, zip

Tests only check the installation of a single PHP extension at a time. If you want to test installing more PHP extensions at the same time, use a commit message like this:

Improve the GD and ZIP extensions

Test: gd+zip

If your pull request contains multiple commits, we'll check the "Test:" message of every commit. If you want to stop parsing next commits, add -STOP- in the "Test:" line, for example:

Improve the GD and ZIP extensions

Test: gd, zip, -STOP-

See this pull request for an example.

PHP requirements and configure options

PHP extensions published on the PECL archive contain a package.xml (or package2.xml) file describing the supported PHP versions and the options that can be used to compile it. When we add support for a new PHP extension, and when a new version of a PHP extension is released, we have to check those constraints.

It's a rather tedious taks, so I developed a project that lets you easily check those constraints: you can find it at https://mlocati.github.io/pecl-info (here you can find its source code).

For the maintainers

See the MAINTAINERS.md file.

Do you want to really say thank you?

You can offer me a monthly coffee or a one-time coffee 😉