Environment flags

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

In addition to 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.

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

---

Workflow flags

fail-fast · 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.

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

phpts · 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

- name: Setup PHP TS
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    phpts: ts

update · 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.

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

- name: Update pre-installed PHP to latest patch
  uses: shivammathur/setup-php@v2
  with:
    php-version: 'pre-installed'
  env:
    update: true

debug · 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 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.

- name: Setup PHP with debug symbols
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    debug: true

runner · 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.

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

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.

---

Composer flags

COMPOSER_ALLOW_PLUGINS · 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.

- 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

PACKAGIST_TOKEN · string

Authentication token for Private Packagist. Set this when your workflow installs private Composer dependencies hosted on Private Packagist.

- name: Setup PHP with Private Packagist auth
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    PACKAGIST_TOKEN: ${{ secrets.PACKAGIST_TOKEN }}

COMPOSER_AUTH_JSON · 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.

- 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 }}"
          }
        }
      }

COMPOSER_PROCESS_TIMEOUT · 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.

- name: Setup PHP with custom Composer timeout
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    COMPOSER_PROCESS_TIMEOUT: 300