Add extension from PECL with libraries and custom configuration

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

On Ubuntu and macOS extensions can be compiled using PECL with required libraries and custom configure options.

Add extension with custom configurations

Extensions can require various configuration options. While compiling an extension the call to the configure script in PECL 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)

Note: <EXTENSION>_CONFIGURE_SUFFIX_OPTS or <EXTENSION>_CONFIGURE_OPTS is supported on PHP 5.4 and above.

For example to install pecl_http extension with configure options:

- name: Setup PHP with http from source
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.0'  
    extensions: pecl_http-4.2.0
  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 set up 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 install redis extension with lz4 support using PECL 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-5.3.7
  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