Add extension from source

This guide is written for developers with basic knowledge of compiling packages, if you have any questions please feel free to ask here.

Add extension from GitHub

On Ubuntu and macOS extensions can be compiled and installed from a git repository by suffixing the extension's name with repository@version.

For example to compile and install mongodb from its GitHub repository mongodb/mongo-php-driver and tag 1.15.0:

- name: Setup PHP with mongodb from source
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.2'
    extensions: mongodb-mongodb/[email protected]

The version can be a branch name or tag as supported by git clone -b <name>. The clone is performed recursively, i.e. submodules if any, will be cloned as well.

The input format is <extension-name>-<repository>@<branch/tag>.

Add extension from other git providers

By default, the extension repository is cloned from GitHub. If the extension is hosted on any other git provider. You need to specify the complete repository URL.

For example to compile and install csv extension from its repository hosted on GitLab:

- name: Setup PHP with csv from source
  uses: shivammathur/setup-php@v2
  with:
    php-version: '7.4'  
    extensions: csv-https://gitlab.com/Girgias/[email protected]

Add extension from a sub-directory

If the extension is not in the root directory of the repository, you can specify the sub-directory using the environment variable <EXTENSION>_PATH. For example for protobuf, the environment variable will be PROTOBUF_PATH.

- name: Setup PHP with protobuf from source
  uses: shivammathur/setup-php@v2
  with:
    php-version: '7.4'  
    extensions: protobuf-protocolbuffers/[email protected]
  env:
    PROTOBUF_PATH: php/ext/google/protobuf

Add extension with different configurations

Extensions can require various configuration options. While compiling an extension the call to the configure script can look like this

PREFIX_OPTS ./configure SUFFIX_OPTS

The PREFIX_OPTS can be Makefile variables like CFLAGS, SUFFIX_OPTS can be m4 inputs like --enable-extension.

So setup-php supports the following environment variables.

• <EXTENSION>_CONFIGURE_PREFIX_OPTS
• <EXTENSION>_CONFIGURE_SUFFIX_OPTS or <EXTENSION>_CONFIGURE_OPTS (alias)

For example to compile http extension from source:

- name: Setup PHP with http from source
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.0'  
    extensions: raphf, http-m6w6/[email protected]
  env:
    HTTP_CONFIGURE_PREFIX_OPTS: "CFLAGS=-Wno-implicit-function-declaration"
    HTTP_CONFIGURE_OPTS: "--with-http"

Add required libraries for the extension

Some extensions require external libraries. To setup libraries along with compiling the extension the following environment variables are supported.

• <EXTENSION>_LIBS
• <EXTENSION>_LINUX_LIBS
• <EXTENSION>_DARWIN_LIBS.

If you are using a single operating system in a workflow, then you can use <EXTENSION>_LIBS. In a multi OS workflow, you can use <EXTENSION>_LINUX_LIBS for Ubuntu workflows and <EXTENSION>_DARWIN_LIBS for macOS workflows.

Libraries on Ubuntu are installed using apt. On MacOS libraries are installed using Homebrew.

For example to compile and install redis extension with lz4 support in a cross-platform workflow:

- name: Get liblz4 directory
  id: lz4
  run: |
    if [ "$(uname -s)" = "Linux" ]; then
      echo "lz4_dir=/usr" >> "$GITHUB_OUTPUT"
    else
      echo "lz4_dir=$(brew --prefix)/opt/lz4" >> "$GITHUB_OUTPUT"
    fi
- name: Setup PHP with redis from source with lz4 support
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.0'
    extensions: redis-phpredis/[email protected]
  env:
    REDIS_CONFIGURE_OPTS: --enable-redis  --enable-redis-lz4 --with-liblz4=${{ steps.lz4.outputs.lz4_dir }}
    REDIS_LINUX_LIBS: liblz4-dev
    REDIS_DARWIN_LIBS: lz4