5b4d4f2672
Add support for zephir_parser |
||
---|---|---|
.github | ||
data | ||
scripts | ||
.dockerignore | ||
.editorconfig | ||
.gitattributes | ||
.gitignore | ||
.php_cs | ||
Dockerfile | ||
LICENSE | ||
MAINTAINERS.md | ||
README.md | ||
composer.json | ||
install-php-extensions |
README.md
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 Dockerfile
s: 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 Dockerfile
s 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 supports 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
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:
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:
install-php-extensions mongodb-stable
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 | PHP 8.1 |
---|---|---|---|---|---|---|---|---|---|
amqp | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
apcu | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
apcu_bc | ✓ | ✓ | ✓ | ✓ | ✓ | ||||
ast | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
bcmath | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
blackfire | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
bz2 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
calendar | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
cmark | ✓ | ✓ | ✓ | ✓ | ✓ | ||||
csv | ✓ | ✓ | ✓ | ||||||
dba | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
decimal | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
ds | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||
enchant | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
ev | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
event | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
excimer | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||
exif | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
ffi | ✓ | ✓ | ✓ | ||||||
gd | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
gearman | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
geoip | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
geospatial | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
gettext | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
gmagick | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
gmp | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
gnupg | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
grpc | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
http | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
igbinary | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
imagick | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
imap | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
inotify | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
interbase | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||
intl | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
ioncube_loader | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
jsmin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
json_post | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
ldap | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
lzf | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
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 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
spx | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
sqlsrv* | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
ssh2 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
stomp | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
swoole | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
sybase_ct | ✓ | ✓ | |||||||
sysvmsg | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
sysvsem | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
sysvshm | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
tensor | ✓ | ✓ | ✓ | ✓ | |||||
tidy | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
timezonedb | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
uopz | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
uploadprogress | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
uuid | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
vips* | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
wddx | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||
xdebug | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
xhprof | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
xlswriter | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
xmldiff | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
xmlrpc | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
xsl | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
yac | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||
yaml | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
yar | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
zip | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
zookeeper | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
zstd | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Number of supported extensions: 113
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]
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:
IPE_LZF_BETTERCOMPRESSION=1 install-php-extensions lzf
Here's the list of all the supported environment variables:
Extension | Environment variable | Description |
---|---|---|
IPE_KEEP_SYSPKG_CACHE=1 |
By default the script will clear the apt/apk/pear cache in order to save disk space. You can disable it by setting this environment variable | |
lzf | IPE_LZF_BETTERCOMPRESSION=1 |
By default install-php-extensions compiles the lzf extension to prefer speed over size; you can use this environment variable to compile it preferring size over speed |
event | IPE_EVENT_NAMESPACE= ... |
By default the event classes are defined in the root namespace. You can use this environment variable to specify a custom namespace |
Special requirements
Some extensions have special requirements:
How do I know which Linux distribution I am using?
You can run this command:
cat /etc/os-release
For example:
- for Debian 11 (Bullseye) you'll see:
PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"
- for Alpine Linux 3.14 you'll see:
PRETTY_NAME="Alpine Linux v3.14"
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, you should execute the lint
script in the scripts
directory (or lint.bat
on Windows).
If you don't do that, and if there's a coding style error, you'll see that the Check shell coding style
and/or the Check PHP coding style
GitHub Actions will fail.
The error will be something like this:
--- filename.orig
+++ filename
@@ -line number,7 +line number,7 @@
good line of code #1
good line of code #2
good line of code #3
- the original line with a wrong coding style
+ the line wrong coding style that has been corrected
good line of code #4
good line of code #5
good line of code #6
So, you should fix highlighted line (the one(s) at line number
) by replacing what you see after the -
with what you see after the +
Adding support to a new PHP extension?
- change the
install-php-extensions
script - update the
data/supported-extensions
file, adding a new line with the handle of the extension and the list of supported PHP versions - if the extension requires ZTS images:
add a new line to thedata/special-requirements
file, with the extension handle followed by a space andzts
See this pull request for an example.
Changing the supported PHP versions for an already supported PHP extension?
- change the
install-php-extensions
script - 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 task, 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 😉