PHP Extensions

Install, configure, and disable PHP extensions in your GitHub Actions workflows using the extensions input.

The extensions input accepts a comma-separated list of PHP extensions to install or disable. setup-php handles package resolution, PECL installation, and compilation automatically depending on the platform.

Basic usage

- name: Setup PHP with extensions
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: mbstring, intl, redis, imagick

How extensions are installed per platform

Ubuntu

Extensions available as OS packages, on PECL, or in a git repository can be installed.

Windows

Extensions available on PECL that have a prebuilt DLL binary can be installed.

macOS

Extensions available on PECL or in a git repository can be installed.

On Ubuntu and macOS you can compile and install an extension from a git repository or from PECL with custom libraries and configuration. See the setup-php wiki for guides.

Extensions that are installed alongside PHP are automatically enabled when specified in the extensions input.

Installing extensions from PECL

PECL extensions are referenced by name:

- name: Setup PHP with PECL extension
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: imagick, redis

Specific extension versions

Suffix an extension name with the version number to install a specific release from PECL. This is useful for running end-of-life PHP versions that require older extension releases:

- name: Setup PHP with specific PECL extension version
  uses: shivammathur/setup-php@v2
  with:
    php-version: '5.4'
    extensions: swoole-1.9.3

Pre-release versions

Suffix an extension name with its stability state to install a pre-release build from PECL:

- name: Setup PHP with pre-release PECL extension
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: xdebug-beta

Accepted stability suffixes: alpha, beta, devel, snapshot.

Disabling extensions

Disable a specific extension

Prefix an extension name with : to disable it. All extensions that depend on the disabled extension are also disabled:

- name: Setup PHP and disable opcache
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: :opcache

Disable all shared extensions

Specify none to disable every shared extension. When none appears alongside other extension names, it is hoisted to run first — disabling everything — then the remaining extensions are processed:

- name: Setup PHP with only mbstring
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: none, mbstring

none disables all core and third-party shared extensions, which can break tools that depend on them. When tools are set up, required extensions are re-enabled on a best-effort basis. Always list any extensions your tools need after none to avoid issues.

Special ICU/intl versioning on Ubuntu

The intl extension can be paired with a specific ICU version on Ubuntu for PHP 5.6 and above. Suffix intl with the ICU version:

- name: Setup PHP with specific ICU version
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: intl-77.1

Supported ICU version ranges:

• PHP 8.4 and lower — ICU 50.2 and newer
• PHP 8.5 and above — ICU 57.2 and newer

Refer to the icu-intl builds list for the exact versions available.

Platform-specific examples

Ubuntu

- name: Setup PHP on Ubuntu
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    # Packages, PECL extensions, and git-sourced extensions
    extensions: imagick, redis, swoole, intl-77.1

Extensions with custom support

The following extensions have dedicated support beyond standard PECL installation:

Ubuntu-only

• cubrid — CUBRID database extension
• pdo_cubrid — PDO driver for CUBRID

Ubuntu and macOS

• event — libevent bindings
• gearman — Gearman job server client
• geos — GEOS geometry library
• relay — Redis client with local in-process cache

All platforms

• blackfire — Blackfire profiler
• couchbase — Couchbase SDK
• ibm_db2 — IBM Db2 driver
• ioncube — ionCube Loader
• oci8 — Oracle Database extension
• pdo_firebird — PDO driver for Firebird
• pdo_ibm — PDO driver for IBM Db2
• pdo_oci — PDO driver for Oracle
• pecl_http — HTTP extension
• phalcon3 — Phalcon 3 framework
• phalcon4 — Phalcon 4 framework
• phalcon5 — Phalcon 5 framework
• zephir_parser — Zephir parser

Fail-fast behavior

By default, if an extension cannot be added or disabled, setup-php logs an error but continues without interrupting the workflow. To make the workflow fail instead, set the fail-fast flag:

- name: Setup PHP with fail-fast
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: oci8
  env:
    fail-fast: true

Extensions loaded by default after setup-php runs are listed on the setup-php wiki.