Skip to main content
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.
ValueBehavior
ntsNon-thread-safe build (default)
ts or ztsThread-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

Build docs developers (and LLMs) love

Get started for freeTalk to us