Tools

Install PHP development tools globally in your GitHub Actions workflow using the tools input.

The tools input accepts a comma-separated list of tools to install globally. This is useful for CI-only tools that you do not want to commit to your composer.json.

Basic usage

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

Supported tools

The following tools can be installed by name:

Tool	Description
backward-compatibility-check	Roave backward compatibility checker
behat	BDD test framework
blackfire	Blackfire profiler CLI
blackfire-player	Blackfire scenario player
box	PHAR builder
castor	Task runner
churn	Complexity/churn analysis
codeception	Full-stack testing framework
composer	PHP dependency manager
composer-dependency-analyser	Dependency analyser
composer-normalize	Normalize composer.json
composer-prefetcher	Prefetch Composer packages (v1 only)
composer-require-checker	Check undeclared dependencies
composer-unused	Find unused Composer packages
cs2pr	Annotate pull requests from checkstyle
deployer	Deployment tool
ecs	Easy Coding Standard
flex	Symfony Flex Composer plugin
grpc_php_plugin	gRPC PHP plugin
infection	Mutation testing
mago	PHP toolchain
name-collision-detector	Detect class name collisions
parallel-lint	Parallel PHP syntax linter
pecl	PEAR Extension Community Library
phan	Static analyzer
phing	Build tool
phinx	Database migrations
phive	PHAR installation and verification
php-config	PHP build configuration helper
php-cs-fixer	PHP Coding Standards Fixer
php-scoper	Prefix PHP namespaces
phpcbf	PHP Code Beautifier and Fixer
phpcpd	Copy-paste detector
phpcs	PHP CodeSniffer
phpdoc / phpDocumentor	Documentation generator
phpize	PHP extension build helper
phplint	PHP linter
phpmd	PHP Mess Detector
phpspec	BDD spec testing
phpstan	Static analysis tool
phpunit	Unit testing framework
phpunit-bridge	Symfony PHPUnit Bridge
phpunit-polyfills	PHPUnit polyfills
pie	PHP extension installer
pint	Laravel Pint code style fixer
prestissimo	Parallel Composer downloads (v1 only)
protoc	Protocol Buffers compiler
psalm	Static analysis tool
rector	Automated refactoring
symfony / symfony-cli	Symfony CLI
vapor / vapor-cli	Laravel Vapor CLI
wp / wp-cli	WP-CLI

Tool version specification

Specify a version by appending :version to the tool name:

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

The version format accepts:

• Semver — tool:1.2.3 or tool:1.2.3-beta1
• Major only — tool:1 or tool:1.x (installs latest patch in that major)
• Major.minor — tool:1.2 or tool:1.2.x (installs latest patch in that minor)

Composer version options

The latest stable Composer is installed by default. You can pin a specific version:

Composer v1

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

Composer v2

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

Snapshot / preview

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

Also accepts composer:preview to install the preview release.

prestissimo and composer-prefetcher are skipped unless composer:v1 is also specified. It is recommended to drop prestissimo and use Composer v2 instead.

Installing arbitrary Composer packages

Any package on Packagist can be installed globally by specifying it as vendor/package. This format accepts the same version constraints as Composer:

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

Skipping Composer installation

If you do not use Composer in your workflow, specify tools: none to skip its installation:

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

Default tools on Linux and macOS

pear, pecl, phpize, and php-config are installed by default for all supported PHP versions on Linux and macOS. You do not need to list them in the tools input.

Composer environment variables

Setup-php sets the following Composer environment variables automatically:

Variable	Default	Description
COMPOSER_NO_INTERACTION	1	Disables interactive prompts. You do not need to pass --no-interaction to Composer commands.
COMPOSER_PROCESS_TIMEOUT	0	Removes the process timeout (unlimited).
COMPOSER_NO_AUDIT	1	Disables the automatic security audit on install. Add a separate composer audit step if you want vulnerability checks.

Override any of these in your workflow’s env block:

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

Allowing Composer plugins

Composer blocks all plugins by default. Tools installed via the tools input are automatically added to the allow list. If your dependencies include Composer plugins, allow them with COMPOSER_ALLOW_PLUGINS:

- 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

Fail-fast behavior

By default (except for composer itself), tools that cannot be set up leave an error message in the logs without interrupting the workflow. Set fail-fast to make the workflow fail instead:

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

Use the tools input for tools that are only needed in CI. This keeps your composer.json tidy and avoids pulling dev-dependencies into production builds. You can run composer install --no-dev and still have all the tools you need via the tools input.