Skip to main content

​
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

​
Set up PHP in your workflow

1

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.
.github/workflows/ci.yml
name: CI

on: [push, pull_request]

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

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.
.github/workflows/ci.yml
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'
Use php-version: 'latest' or php-version: 'highest' to always use the newest stable PHP release without updating your workflow file.
3

Add extensions

Use the extensions input to install PHP extensions. It accepts a comma-separated list of extension names.
- 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.
4

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

Run your tests

After setting up PHP, add steps to install your dependencies and run your tests.
- name: Install dependencies
  run: composer install --prefer-dist --no-progress

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

​
Complete workflow examples

The following examples show complete, working workflow files you can use as a starting point. 
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
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.

​
Next steps

Configuration reference

See all available inputs, outputs, and environment flags for setup-php.

Extensions

Learn how to install, version-pin, and disable PHP extensions.

Tools

Browse the full list of 50+ supported PHP tools.

Coverage

Configure Xdebug, PCOV, or disable coverage drivers.

Build docs developers (and LLMs) love

Get started for freeTalk to us