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

# Environment flags

> Control setup-php behavior using environment variables set via the env: keyword in your workflow step.

In addition to [inputs](/configuration/inputs), `setup-php` supports a set of environment flags that control how the action behaves. Set them using the `env:` keyword on the `setup-php` step.

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

***

## Workflow flags

<ParamField path="fail-fast" type="boolean" default="false">
  When set to `true`, the workflow fails immediately if an extension or tool cannot be set up, instead of continuing with a warning in the logs.

  By default, failures to add or disable extensions and failures to install tools (other than `composer`) produce a log warning without interrupting the workflow.

  ```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
  ```
</ParamField>

<ParamField path="phpts" type="string" default="nts">
  Controls whether to set up a thread-safe (TS/ZTS) or non-thread-safe (NTS) build of PHP.

  | Value         | Behavior                        |
  | ------------- | ------------------------------- |
  | `nts`         | Non-thread-safe build (default) |
  | `ts` or `zts` | Thread-safe build               |

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

<ParamField path="update" type="boolean" default="false">
  When set to `true`, updates the pre-installed PHP version on the runner to the latest patch release before setting up.

  By default, pre-installed PHP versions are not updated to their latest patch. Set this flag when you need the latest bug fixes and security patches for a given minor version.

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

  You can combine this with `php-version: pre-installed` to update whichever PHP version is already installed on the runner:

  ```yaml theme={null}
  - name: Update pre-installed PHP to latest patch
    uses: shivammathur/setup-php@v2
    with:
      php-version: 'pre-installed'
    env:
      update: true
  ```
</ParamField>

<ParamField path="debug" type="boolean">
  When set to `true`, sets up a PHP build that includes debugging symbols. Supported for PHP 5.6 and above.

  Platform-specific behavior:

  * **Linux** — Debug symbols are added as [separate debug info files](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Separate-Debug-Files.html) under `/usr/lib/debug/.build-id`. Tools like `gdb` resolve them automatically.
  * **Windows** — Debug symbols are added as `.pdb` files in the PHP installation directory.
  * **macOS** — Debug symbols are compiled into the binaries.

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

<ParamField path="runner" type="string">
  Set to `self-hosted` when running on a self-hosted runner. This tells `setup-php` to adjust its behavior for non-GitHub-hosted environments.

  ```yaml theme={null}
  jobs:
    run:
      runs-on: self-hosted
      strategy:
        matrix:
          php-versions: ['8.3', '8.4', '8.5']
      steps:
        - name: Setup PHP
          uses: shivammathur/setup-php@v2
          with:
            php-version: ${{ matrix.php-versions }}
          env:
            runner: self-hosted
  ```

  <Warning>
    Do not run multiple self-hosted runners on the same server instance — parallel workflows will conflict. Avoid using the same labels as GitHub-hosted runners.
  </Warning>
</ParamField>

***

## Composer flags

<ParamField path="COMPOSER_ALLOW_PLUGINS" type="string">
  A comma-separated list of Composer plugin package names to add to the allow list.

  By default, Composer blocks all plugins. Plugins installed via the `tools` input are automatically allowed. Use this flag to allow plugins that are required by your dependencies rather than installed directly.

  ```yaml theme={null}
  - name: Setup PHP and allow Composer plugins
    uses: shivammathur/setup-php@v2
    with:
      php-version: '8.5'
    env:
      COMPOSER_ALLOW_PLUGINS: composer/installers, composer/satis
  ```
</ParamField>

<ParamField path="PACKAGIST_TOKEN" type="string">
  Authentication token for [Private Packagist](https://packagist.com/). Set this when your workflow installs private Composer dependencies hosted on Private Packagist.

  ```yaml theme={null}
  - name: Setup PHP with Private Packagist auth
    uses: shivammathur/setup-php@v2
    with:
      php-version: '8.5'
    env:
      PACKAGIST_TOKEN: ${{ secrets.PACKAGIST_TOKEN }}
  ```
</ParamField>

<ParamField path="COMPOSER_AUTH_JSON" type="string">
  A JSON string containing Composer authentication credentials for private repositories not hosted on GitHub or Private Packagist. Follows the same format as [Composer's `auth.json`](https://getcomposer.org/doc/articles/authentication-for-private-packages.md).

  ```yaml theme={null}
  - name: Setup PHP with manual Composer auth
    uses: shivammathur/setup-php@v2
    with:
      php-version: '8.5'
    env:
      COMPOSER_AUTH_JSON: |
        {
          "http-basic": {
            "example.org": {
              "username": "${{ secrets.EXAMPLE_ORG_USERNAME }}",
              "password": "${{ secrets.EXAMPLE_ORG_PASSWORD }}"
            }
          }
        }
  ```
</ParamField>

<ParamField path="COMPOSER_PROCESS_TIMEOUT" type="number">
  Overrides the Composer process timeout (in seconds). By default, `setup-php` sets this to `0` (no timeout), so Composer commands in your scripts do not time out.

  Set this to a positive integer if you want to enforce a timeout limit on Composer operations.

  ```yaml theme={null}
  - name: Setup PHP with custom Composer timeout
    uses: shivammathur/setup-php@v2
    with:
      php-version: '8.5'
    env:
      COMPOSER_PROCESS_TIMEOUT: 300
  ```
</ParamField>