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

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.

basic.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'
          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.