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

> Configure which PHP version setup-php installs, including stable releases, nightly builds, special builds, and JIT configuration.

The `php-version` input controls which PHP version is installed on your runner. setup-php supports PHP 5.3 through 8.6 across GitHub-hosted and self-hosted runners on Ubuntu, Windows, and macOS.

## Supported PHP versions

| PHP version | Stability | Release support     | Runner support             |
| ----------- | --------- | ------------------- | -------------------------- |
| `5.3`       | Stable    | End of life         | GitHub-hosted              |
| `5.4`       | Stable    | End of life         | GitHub-hosted              |
| `5.5`       | Stable    | End of life         | GitHub-hosted              |
| `5.6`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `7.0`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `7.1`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `7.2`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `7.3`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `7.4`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `8.0`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `8.1`       | Stable    | End of life         | GitHub-hosted, self-hosted |
| `8.2`       | Stable    | Security fixes only | GitHub-hosted, self-hosted |
| `8.3`       | Stable    | Security fixes only | GitHub-hosted, self-hosted |
| `8.4`       | Stable    | Active              | GitHub-hosted, self-hosted |
| `8.5`       | Stable    | Active              | GitHub-hosted, self-hosted |
| `8.6`       | Nightly   | In development      | GitHub-hosted, self-hosted |

<Note>
  Specifying `8.6` installs a nightly build of `PHP 8.6.0-dev` from the master branch of PHP. See the [nightly build](#nightly-build) section below for details.
</Note>

## Platform support

### GitHub-hosted runners

| Virtual environment | Architecture | YAML workflow label                | Pre-installed PHP |
| ------------------- | ------------ | ---------------------------------- | ----------------- |
| Ubuntu 24.04        | x86\_64      | `ubuntu-latest` or `ubuntu-24.04`  | PHP 8.3           |
| Ubuntu 22.04        | x86\_64      | `ubuntu-22.04`                     | PHP 8.1           |
| Ubuntu 24.04        | aarch64      | `ubuntu-24.04-arm`                 | PHP 8.3           |
| Ubuntu 22.04        | aarch64      | `ubuntu-22.04-arm`                 | PHP 8.1           |
| Windows Server 2025 | x64          | `windows-2025`                     | PHP 8.5           |
| Windows Server 2022 | x64          | `windows-latest` or `windows-2022` | PHP 8.5           |
| macOS Tahoe 26.x    | arm64        | `macos-26`                         | —                 |
| macOS Sequoia 15.x  | arm64        | `macos-latest` or `macos-15`       | —                 |
| macOS Sonoma 14.x   | arm64        | `macos-14`                         | —                 |
| macOS Tahoe 26.x    | x86\_64      | `macos-26-intel`                   | PHP 8.5           |
| macOS Sequoia 15.x  | x86\_64      | `macos-15-intel`                   | PHP 8.5           |

<Note>
  PHP 5.3–5.5 are only available on GitHub-hosted runners, not self-hosted runners. PHP 5.6–8.6 are supported on both. On GitHub-hosted macOS ARM64 runners (e.g. `macos-14`), only PHP 5.6 and above are supported.
</Note>

### Self-hosted runners

| Host OS / virtual environment    | YAML workflow label        |
| -------------------------------- | -------------------------- |
| Ubuntu 24.04                     | `self-hosted` or `Linux`   |
| Ubuntu 22.04                     | `self-hosted` or `Linux`   |
| Debian 13                        | `self-hosted` or `Linux`   |
| Debian 12                        | `self-hosted` or `Linux`   |
| Debian 11                        | `self-hosted` or `Linux`   |
| Windows 7 and newer              | `self-hosted` or `Windows` |
| Windows Server 2012 R2 and newer | `self-hosted` or `Windows` |
| macOS Tahoe 26.x x86\_64/arm64   | `self-hosted` or `macOS`   |
| macOS Sequoia 15.x x86\_64/arm64 | `self-hosted` or `macOS`   |
| macOS Sonoma 14.x x86\_64/arm64  | `self-hosted` or `macOS`   |

If the requested PHP version is pre-installed, setup-php switches to it; otherwise it installs the requested version. Operating systems based on the supported Ubuntu and Debian versions are also supported on a best-effort basis.

## `php-version` input options

The `php-version` input accepts several formats:

<Tabs>
  <Tab title="Specific version">
    Provide a version string such as `'8.5'` or `'8.4'`:

    ```yaml theme={null}
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
    ```
  </Tab>

  <Tab title="lowest / highest">
    Use `lowest` to install the lowest supported PHP version, or `highest` / `latest` to install the latest stable release:

    ```yaml theme={null}
    - name: Setup latest stable PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: 'latest'
    ```

    ```yaml theme={null}
    - name: Setup lowest supported PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: 'lowest'
    ```
  </Tab>

  <Tab title="nightly">
    Use `nightly` to install a nightly build from the master branch of PHP:

    ```yaml theme={null}
    - name: Setup nightly PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: 'nightly'
    ```
  </Tab>

  <Tab title="pre-installed">
    Use `pre-installed` to activate the highest PHP version already present on the runner without downloading a new one:

    ```yaml theme={null}
    - name: Use pre-installed PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: 'pre-installed'
    ```

    Combine with `update: true` to also update it to the latest patch:

    ```yaml theme={null}
    - name: Use pre-installed PHP (updated)
      uses: shivammathur/setup-php@v2
      with:
        php-version: 'pre-installed'
      env:
        update: true
    ```
  </Tab>

  <Tab title="d.x format">
    Specify a major version with a wildcard to install the latest patch within that major:

    ```yaml theme={null}
    - name: Setup latest PHP 8.x
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.x'
    ```

    Also supports `5.x`, `7.x`, and `8.x`.
  </Tab>

  <Tab title="Matrix">
    Use a matrix to test across multiple PHP versions:

    ```yaml theme={null}
    jobs:
      run:
        runs-on: ubuntu-latest
        strategy:
          matrix:
            php-versions: ['8.2', '8.3', '8.4', '8.5']
        steps:
        - name: Setup PHP
          uses: shivammathur/setup-php@v2
          with:
            php-version: ${{ matrix.php-versions }}
    ```
  </Tab>
</Tabs>

## Auto-detection from project files

When `php-version` is not specified, setup-php looks for the PHP version in the following order:

1. The `php-version-file` input (if provided)
2. A `composer.lock` file — reads `platform-overrides.php`
3. A `composer.json` file — reads `config.platform.php`

If none of these are present, the latest stable PHP version is installed.

<Tip>
  If your `composer.lock` or `composer.json` is in a subdirectory, set the `COMPOSER_PROJECT_DIR` environment variable to the subdirectory path.
</Tip>

## `php-version-file` input

Specify a file that contains the PHP version to use. By default, setup-php looks for a `.php-version` file:

```yaml theme={null}
- name: Setup PHP from version file
  uses: shivammathur/setup-php@v2
  with:
    php-version-file: '.phpenv-version'
```

The file must either contain just the PHP version string (e.g. `8.5`) or follow the asdf `.tool-versions` format. If the default `.php-version` file is not found and `php-version-file` is not set, the latest stable PHP version is installed.

## Special builds

### Nightly build

Specifying `8.6` (or `nightly`) installs a nightly build of `PHP 8.6.0-dev` compiled from the master branch:

```yaml theme={null}
- name: Setup nightly PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.6'
    extensions: mbstring
    coverage: xdebug
```

<Warning>
  Nightly PHP versions are in active development and may contain bugs or breaking changes. Some user-space extensions may not yet support these versions.
</Warning>

### Debug build

Production release builds without debugging symbols are installed by default. Set the `debug` environment variable to `true` to install a build with debugging symbols for PHP 5.6 and above:

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

Debug symbol locations by platform:

* **Linux** — debug info files in `/usr/lib/debug/.build-id`, matching the `build-id` in the ELF section of PHP binaries
* **Windows** — `.pdb` files in the PHP installation directory
* **macOS** — debug symbols compiled directly into the binaries

### Thread-safe build

Non-thread-safe (NTS) PHP is installed by default. Use the `phpts` environment variable to select a thread-safe (TS/ZTS) build:

```yaml theme={null}
- name: Setup thread-safe PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    phpts: ts   # ts or zts for thread-safe, nts for non-thread-safe
```

## JIT configuration

PHP 8.0 and above support Just-in-Time (JIT) compilation. To enable JIT:

* Enable opcache in CLI mode with `opcache.enable_cli=1`
* Set `coverage: none` — JIT conflicts with Xdebug, PCOV, and other extensions that override `zend_execute_ex`
* Optionally tune `opcache.jit` and `opcache.jit_buffer_size`

By default, when JIT is enabled, setup-php sets `opcache.jit=1235` and `opcache.jit_buffer_size=256M` (128M on ARM).

<Tabs>
  <Tab title="Tracing mode">
    Enable JIT in tracing mode with a 64 MB buffer:

    ```yaml theme={null}
    - name: Setup PHP with JIT (tracing)
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        coverage: none
        ini-values: opcache.enable_cli=1, opcache.jit=tracing, opcache.jit_buffer_size=64M
    ```
  </Tab>

  <Tab title="Function mode">
    Enable JIT in function mode with a 128 MB buffer:

    ```yaml theme={null}
    - name: Setup PHP with JIT (function)
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        coverage: none
        ini-values: opcache.enable_cli=1, opcache.jit=1235, opcache.jit_buffer_size=128M
    ```
  </Tab>
</Tabs>

<Note>
  Refer to the [official PHP opcache documentation](https://www.php.net/manual/en/opcache.configuration.php#ini.opcache.jit) for a full list of JIT directives and their values.
</Note>