This is a tool to develop, build and test PHP extensions in Docker containers.

Clone this repository and add the bin/ directory of this repository to your $PATH.

Call the build-php-extension from the root directory of your extension source. The directory must contain your config.m4 file.

The build-php-extension command has multiple subcommands.

To configure and build your extension, run:

build-php-extension configure

To trigger a build, you can run:

build-php-extension build

And to run the tests, you need to execute:

build-php-extension test

You can specify the tests which should be executed as parameters to the test command. If you omit the list of tests, all tests are run.

build-php-extension test tests/my_test_*.phpt

You can specify the minor PHP version which should be used, whether to enable thread-safety (--zts) and the build mode (--release or --debug) as arguments to all commands:

build-php-extension --php-version 7.4 --release --zts build

The default is to disable thread safety and to build in debug mode.

Instead of a released version (--php-version) you can also specify a git branch or tag like master, PHP-8.2 or php-8.1.11:

build-php-extension --php-git-branch PHP-8.2 build

To open an interactive shell inside a Docker container, you can execute:

build-php-extension shell

The dist-clean subcommand can be used to clean all generated files from the build directory:

build-php-extension dist-clean

Status information is stored by the tool in the file .build-php-extension.state.ini inside the source code of your extension. You should add this file to your .gitignore.

When you first execute a command in one specific configuration, the Docker image for that configuration will automatically be built. When you call commands with the same configuration later on, that Docker image will be reused. You can manually rebuild the Docker image with the following command:

build-php-extension --php-version 8.0 --debug build-image

You can customize the behavior of the build using various hooks. These are scripts that are sourced at the respective steps of the build process. These are the available extension points:

• build-hooks/pre-configure.sh
• build-hooks/post-configure.sh
• build-hooks/pre-build.sh
• build-hooks/post-build.sh
• build-hooks/pre-test.sh
• build-hooks/post-test.sh
• build-hooks/pre-clean-build-directory.sh
• build-hooks/post-clean-build-directory.sh
• build-hooks/pre-shell.sh

If the file build-hooks/configure exists and is executable, it is executed instead of calling ./configure directly. This can be used to pass additional flags to ./configure. All command-line-arguments that script receives, should be forwarded to ./configure:

#!/bin/sh

set -eu
./configure --my-special-configure-flag "${@}"