> ## 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.

# Quickstart

> Add setup-php to your GitHub Actions workflow and get PHP configured in minutes.

## Prerequisites

Before you begin, you need:

* A GitHub repository with GitHub Actions enabled
* A `.github/workflows/` directory (or the ability to create one)
* Basic familiarity with [GitHub Actions workflow syntax](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions)

## Set up PHP in your workflow

<Steps>
  <Step title="Create a workflow file">
    Create a file at `.github/workflows/ci.yml` in your repository. This file defines the workflow that GitHub Actions will run.

    ```yaml .github/workflows/ci.yml theme={null}
    name: CI

    on: [push, pull_request]

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
    ```
  </Step>

  <Step title="Add the setup-php step">
    Add `shivammathur/setup-php@v2` as a step in your job. Specify the PHP version you need with the `php-version` input.

    ```yaml .github/workflows/ci.yml theme={null}
    name: CI

    on: [push, pull_request]

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4

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

    <Tip>
      Use `php-version: 'latest'` or `php-version: 'highest'` to always use the newest stable PHP release without updating your workflow file.
    </Tip>
  </Step>

  <Step title="Add extensions">
    Use the `extensions` input to install PHP extensions. It accepts a comma-separated list of extension names.

    ```yaml theme={null}
    - name: Setup PHP with extensions
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        extensions: mbstring, intl
    ```

    Extensions are sourced from packages (on Ubuntu), PECL, or git repositories depending on your platform. Prefix an extension with `:` to disable it instead of installing it.
  </Step>

  <Step title="Add tools">
    Use the `tools` input to install PHP tools globally. It accepts a comma-separated list of tool names. The latest stable version of `composer` is always set up by default.

    ```yaml theme={null}
    - name: Setup PHP with tools
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        tools: php-cs-fixer, phpunit
    ```

    You can also install a specific version of any tool by appending `:version`, for example `phpunit:11`.
  </Step>

  <Step title="Run your tests">
    After setting up PHP, add steps to install your dependencies and run your tests.

    ```yaml theme={null}
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress

    - name: Run tests
      run: vendor/bin/phpunit
    ```
  </Step>
</Steps>

## Complete workflow examples

The following examples show complete, working workflow files you can use as a starting point.

<CodeGroup>
  ```yaml basic.yml theme={null}
  name: CI

  on: [push, pull_request]

  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4

        - 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

        - name: Install dependencies
          run: composer install --prefer-dist --no-progress

        - name: Run tests
          run: vendor/bin/phpunit
  ```

  ```yaml with-coverage.yml theme={null}
  name: CI with coverage

  on: [push, pull_request]

  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4

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

        - name: Install dependencies
          run: composer install --prefer-dist --no-progress

        - name: Run tests with coverage
          run: vendor/bin/phpunit --coverage-text
  ```

  ```yaml matrix.yml theme={null}
  name: CI matrix

  on: [push, pull_request]

  jobs:
    run:
      runs-on: ${{ matrix.operating-system }}
      strategy:
        matrix:
          operating-system: ['ubuntu-latest', 'windows-latest', 'macos-latest']
          php-versions: ['8.2', '8.3', '8.4', '8.5']
          phpunit-versions: ['latest']
          include:
            - operating-system: 'ubuntu-latest'
              php-versions: '8.1'
              phpunit-versions: 10
      steps:
        - uses: actions/checkout@v4

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

        - name: Install dependencies
          run: composer install --prefer-dist --no-progress

        - name: Run tests
          run: vendor/bin/phpunit
  ```
</CodeGroup>

<Note>
  The `basic.yml` example uses `coverage: xdebug`. If you are not generating coverage reports, use `coverage: none` instead — this improves PHP performance because Xdebug is disabled.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration reference" icon="sliders" href="/configuration/inputs">
    See all available inputs, outputs, and environment flags for setup-php.
  </Card>

  <Card title="Extensions" icon="puzzle-piece" href="/features/extensions">
    Learn how to install, version-pin, and disable PHP extensions.
  </Card>

  <Card title="Tools" icon="wrench" href="/features/tools">
    Browse the full list of 50+ supported PHP tools.
  </Card>

  <Card title="Coverage" icon="chart-bar" href="/features/coverage">
    Configure Xdebug, PCOV, or disable coverage drivers.
  </Card>
</CardGroup>