> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shivammathur/setup-php/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```yaml theme={null}
- 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

<CardGroup cols={3}>
  <Card title="Ubuntu" icon="linux">
    Extensions available as OS packages, on PECL, or in a git repository can be installed.
  </Card>

  <Card title="Windows" icon="windows">
    Extensions available on PECL that have a prebuilt DLL binary can be installed.
  </Card>

  <Card title="macOS" icon="apple">
    Extensions available on PECL or in a git repository can be installed.
  </Card>
</CardGroup>

<Tip>
  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](https://github.com/shivammathur/setup-php/wiki) for guides.
</Tip>

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:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

```yaml theme={null}
- name: Setup PHP with only mbstring
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: none, mbstring
```

<Warning>
  `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.
</Warning>

## 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:

```yaml theme={null}
- 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](https://github.com/shivammathur/icu-intl#icu4c-builds) for the exact versions available.

## Platform-specific examples

<CodeGroup>
  ```yaml Ubuntu theme={null}
  - 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
  ```

  ```yaml Windows theme={null}
  - name: Setup PHP on Windows
    uses: shivammathur/setup-php@v2
    with:
      php-version: '8.5'
      # Only PECL extensions with prebuilt DLLs
      extensions: redis, xdebug
  ```

  ```yaml macOS theme={null}
  - name: Setup PHP on macOS
    uses: shivammathur/setup-php@v2
    with:
      php-version: '8.5'
      # PECL extensions and git-sourced extensions
      extensions: imagick, redis
  ```
</CodeGroup>

## Extensions with custom support

The following extensions have dedicated support beyond standard PECL installation:

<AccordionGroup>
  <Accordion title="Ubuntu-only">
    * `cubrid` — CUBRID database extension
    * `pdo_cubrid` — PDO driver for CUBRID
  </Accordion>

  <Accordion title="Ubuntu and macOS">
    * `event` — libevent bindings
    * `gearman` — Gearman job server client
    * `geos` — GEOS geometry library
    * `relay` — Redis client with local in-process cache
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## 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:

```yaml theme={null}
- name: Setup PHP with fail-fast
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: oci8
  env:
    fail-fast: true
```

<Note>
  Extensions loaded by default after setup-php runs are listed on the [setup-php wiki](https://github.com/shivammathur/setup-php/wiki).
</Note>