> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shivammathur/setup-php/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

<Tabs>
  <Tab title="Composer v1">
    ```yaml theme={null}
    - name: Setup PHP with Composer v1
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        tools: composer:v1
    ```
  </Tab>

  <Tab title="Composer v2">
    ```yaml theme={null}
    - name: Setup PHP with Composer v2
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        tools: composer:v2
    ```
  </Tab>

  <Tab title="Snapshot / preview">
    ```yaml theme={null}
    - 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.
  </Tab>
</Tabs>

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

## 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](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints) as Composer:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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`:

```yaml theme={null}
- 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:

```yaml theme={null}
- name: Setup PHP with fail-fast
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    tools: deployer
  env:
    fail-fast: true
```

<Tip>
  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.
</Tip>