Inputs

Configure setup-php behavior using the with: keyword in your GitHub Actions workflow.

Configure setup-php by passing inputs via the with: keyword in your workflow step. All inputs are optional — you can use as few or as many as your project requires.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: mbstring, intl
    ini-values: post_max_size=256M, max_execution_time=180
    coverage: xdebug
    tools: php-cs-fixer, phpunit

---

php-version · string

The PHP version to set up. Accepts a version string like '8.5', or one of the following special values:

Value	Behavior
lowest	Sets up the lowest supported PHP version
highest or latest	Sets up the latest stable PHP version
nightly	Sets up a nightly build from the PHP master branch
pre-installed	Uses the highest pre-installed PHP version on the runner
d.x	Sets up the latest release for a given major, e.g. 8.x

If omitted, setup-php reads the version from php-version-file, then composer.lock, then composer.json. If none are found, the latest stable version is used.

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

- name: Setup latest stable PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: 'latest'

- name: Setup PHP in a matrix
  uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php-versions }}

Specifying 8.6 installs a nightly build of PHP 8.6.0-dev from the master branch. These builds are in active development and may contain bugs or breaking changes.

php-version-file · string

Path to a file containing the PHP version to set up. Useful for version-pinning via a checked-in file.

Accepts any file that either contains a bare PHP version string or follows the asdf .tool-versions format.

Defaults to .php-version in the repository root. If php-version is also set, it takes precedence over this input. If the default .php-version file is not found and this input is not set, the latest stable PHP version is used.

- name: Setup PHP from version file
  uses: shivammathur/setup-php@v2
  with:
    php-version-file: '.phpenv-version'

extensions · string

A comma-separated list of PHP extensions to install or disable.

• Prefix an extension with : to disable it.
• Specify none to disable all shared extensions. When combined with other extensions, none is processed first — all shared extensions are disabled, then the remaining entries are installed.
• Suffix an extension name with a version to install a specific PECL release, e.g. swoole-1.9.3.
• Suffix with a stability flag (alpha, beta, devel, snapshot) to install a pre-release version, e.g. xdebug-beta.

- name: Setup PHP with extensions
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: imagick, redis

- name: Disable opcache
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: :opcache

- name: Disable all shared extensions except mbstring
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    extensions: none, mbstring

- name: Install specific PECL extension version
  uses: shivammathur/setup-php@v2
  with:
    php-version: '5.4'
    extensions: swoole-1.9.3

Using none disables all core and third-party shared extensions. This can break tools that depend on them. Add required extensions explicitly after none to avoid issues.

ini-file · string · default: "production"

The base php.ini file to use. Accepts production, development, or none.

Value	Behavior
production	Uses the production php.ini template (default)
development	Uses the development php.ini template
none	Starts with an empty php.ini

- name: Setup PHP with development ini
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    ini-file: development

ini-values · string

A comma-separated list of key=value pairs to add to php.ini.

Values that contain commas must be wrapped in quotes, e.g. xdebug.mode="develop,coverage".

- name: Setup PHP with custom ini values
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    ini-values: post_max_size=256M, max_execution_time=180

- name: Configure PCOV directory
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    ini-values: pcov.directory=api
    coverage: pcov

- name: Enable JIT in tracing mode
  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

coverage · string

The code coverage driver to set up. Accepts xdebug, xdebug2, pcov, or none.

Value	Behavior
xdebug	Installs the latest Xdebug compatible with the PHP version and disables PCOV
xdebug2	Installs Xdebug 2.x — use for PHP 7.2, 7.3, and 7.4
pcov	Installs PCOV and disables Xdebug — requires PHP 7.1+
none	Disables both Xdebug and PCOV

- name: Setup PHP with Xdebug
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: xdebug

- name: Setup PHP with PCOV
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: pcov

- name: Setup PHP with no coverage driver
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: none

Xdebug is enabled by default on Ubuntu GitHub Actions runners. If you are not generating coverage reports, set coverage: none to improve PHP performance.

tools · string

A comma-separated list of tools to install globally. Accepts tool names, vendor/package Packagist references, versioned entries like tool:1.2.3, or none to skip all tools including composer.

Supported tools include: composer, phpunit, phpstan, psalm, php-cs-fixer, phpcs, phpmd, rector, infection, deployer, symfony, wp-cli, and many more.

- name: Setup PHP with tools
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    tools: php-cs-fixer, phpunit

- name: Setup specific tool versions
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    tools: composer:v2, phpunit:10

- name: Setup Packagist tool
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    tools: vimeo/psalm

- name: Setup PHP without composer
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    tools: none

The tools input is useful for CI-only tools, keeping your composer.json tidy. Use --no-dev with composer and install required tools via tools to speed up your workflow.

github-token · string · default: "${{ github.token }}"

A GitHub token used for authentication when installing tools and extensions. Defaults to the GITHUB_TOKEN secret automatically provided by GitHub Actions.

Set this to a Personal Access Token (PAT) if you need elevated permissions or if you are on GitHub Enterprise, where GITHUB_TOKEN is not used as the default.

- name: Setup PHP with a PAT
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    github-token: ${{ secrets.YOUR_PAT_TOKEN }}

The COMPOSER_TOKEN and GITHUB_TOKEN environment variables are deprecated in favor of this input and will be removed in the next major version.