Skip to main content
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

- 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:
  • cubrid — CUBRID database extension
  • pdo_cubrid — PDO driver for CUBRID
  • event — libevent bindings
  • gearman — Gearman job server client
  • geos — GEOS geometry library
  • relay — Redis client with local in-process cache
  • 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us