Skip to main content
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:
ValueBehavior
lowestSets up the lowest supported PHP version
highest or latestSets up the latest stable PHP version
nightlySets up a nightly build from the PHP master branch
pre-installedUses the highest pre-installed PHP version on the runner
d.xSets 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.
ValueBehavior
productionUses the production php.ini template (default)
developmentUses the development php.ini template
noneStarts 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.
ValueBehavior
xdebugInstalls the latest Xdebug compatible with the PHP version and disables PCOV
xdebug2Installs Xdebug 2.x — use for PHP 7.2, 7.3, and 7.4
pcovInstalls PCOV and disables Xdebug — requires PHP 7.1+
noneDisables 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us