Setup PHP

GitHub-Hosted Runners

Virtual environment	YAML workflow label	Pre-installed PHP
Ubuntu 24.04	`ubuntu-24.04`	`PHP 8.3`
Ubuntu 22.04	`ubuntu-latest` or `ubuntu-22.04`	`PHP 8.1`
Ubuntu 20.04	`ubuntu-20.04`	`PHP 7.4` to `PHP 8.3`
Windows Server 2022	`windows-latest` or `windows-2022`	`PHP 8.3`
Windows Server 2019	`windows-2019`	`PHP 8.3`
macOS Sonoma 14.x	`macos-14`	-
macOS Ventura 13.x	`macos-13`	`PHP 8.3`
macOS Monterey 12.x	`macos-latest` or `macos-12`	`PHP 8.3`

Disable Coverage

Specify coverage: none to disable both Xdebug and PCOV.

Disable coverage for these reasons:

You are not generating coverage reports while testing.
You are using phpdbg for running your tests.
You are profiling your code using blackfire.
You are using PHP in JIT mode. Please refer to JIT configuration section for more details.

- name: Setup PHP with no coverage driver
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    coverage: none

Inputs

Specify using with keyword

`ini-file` (optional)

Specify the base php.ini file.
Accepts production, development or none.
By default, production php.ini file is used.

`ini-values` (optional)

Specify the values you want to add to php.ini.
Accepts a string in csv-format. For example post_max_size=256M, max_execution_time=180.
Accepts ini values with commas if wrapped in quotes. For example xdebug.mode="develop,coverage".

Outputs

`php-version`

On GitHub Actions you can assign the setup-php step an id, you can use the same to get the outputs in a later step.

Provides the PHP version in semver format.

- name: Setup PHP
  id: setup-php
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'

- name: Print PHP version
  run: echo ${{ steps.setup-php.outputs.php-version }}

Flags

Specify using env keyword

`fail-fast` (optional)

Specify to mark the workflow as failed if an extension or tool fails to set up.
This changes the default mode from graceful warnings to fail-fast.
By default, it is set to false.
Accepts true and false.

`phpts` (optional)

Specify to set up a thread-safe build of PHP.
Accepts nts for non-thread-safe and zts or ts for thread-safe.
By default, it is set to nts.
See thread safe setup for more info.

`update` (optional)

Specify to update PHP on the runner to the latest patch version.
Accepts true and false.
By default, it is set to false.
See force update setup for more info.

See below for more info.

Basic Setup

Set up a particular PHP version.

steps:
- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    extensions: mbstring, intl
    ini-values: post_max_size=256M, max_execution_time=180
    coverage: xdebug
    tools: php-cs-fixer, phpunit

Matrix Setup

Set up multiple PHP versions on multiple operating systems.

jobs:
  run:
    runs-on: ${{ matrix.operating-system }}
    strategy:
      matrix:
        operating-system: ['ubuntu-latest', 'windows-latest', 'macos-latest']
        php-versions: ['8.1', '8.2', '8.3']
        phpunit-versions: ['latest']
        include:
          - operating-system: 'ubuntu-latest'
            php-versions: '8.0'
            phpunit-versions: 9
    steps:
    - 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 }}
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Thread Safe Setup

Set up TS or NTS PHP.

NTS versions are set up by default.

jobs:
  run:
    runs-on: [ubuntu-latest, windows-latest, macos-latest]
    name: Setup PHP TS
    steps:
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.3'
      env:
        phpts: ts # specify ts or nts

Force Update Setup

Update to the latest patch of PHP versions.

Pre-installed PHP versions are not updated to their latest patch release by default.
If ppa:ondrej/php is missing on the Ubuntu GitHub environment, the PHP version is updated to the latest patch release.
You can specify the update environment variable to true for updating to the latest release.

- name: Setup PHP with latest versions
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
  env:
    update: true # specify true or false

Verbose Setup

Debug your workflow

To debug any issues, you can use the verbose tag instead of v2.

- name: Setup PHP with logs
  uses: shivammathur/setup-php@verbose
  with:
    php-version: '8.3'

Local Testing Setup

Test your Ubuntu workflow locally using nektos/act.

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.3'

Run the workflow locally with act using shivammathur/node docker images.

Choose the image tag which matches the runs-on property in your workflow. For example, if you are using ubuntu-20.04 in your workflow, run act -P ubuntu-20.04=shivammathur/node:2004.

# For runs-on: ubuntu-latest
act -P ubuntu-latest=shivammathur/node:latest

# For runs-on: ubuntu-24.04
act -P ubuntu-24.04=shivammathur/node:2404

# For runs-on: ubuntu-22.04
act -P ubuntu-22.04=shivammathur/node:2204

# For runs-on: ubuntu-20.04
act -P ubuntu-20.04=shivammathur/node:2004

JIT Configuration

Enable Just-in-time (JIT) on PHP 8.0 and above.

To enable JIT, enable opcache in cli mode by setting opcache.enable_cli=1.
JIT conflicts with Xdebug, PCOV, and other extensions which override zend_execute_ex function, so set coverage: none and disable any such extension if added.
By default, opcache.jit=1235 and opcache.jit_buffer_size=256M are set which can be changed using ini-values input.
For detailed information about JIT related directives refer to the official PHP documentation.

For example to enable JIT in tracing mode with buffer size of 64 MB.

- name: Setup PHP with JIT in tracing mode
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    coverage: none
    ini-values: opcache.enable_cli=1, opcache.jit=tracing, opcache.jit_buffer_size=64M

Cache Extensions

You can cache PHP extensions using shivammathur/cache-extensions and action/cache GitHub Actions. Extensions which take very long to set up when cached are available in the next workflow run and are enabled directly. This reduces the workflow execution time.
Refer to shivammathur/cache-extensions for details.

GitHub Composer Authentication

If you have a number of workflows which set up multiple tools or have many composer dependencies, you might hit the GitHub’s rate limit for composer. Also, if you specify only the major version or the version in major.minor format, you can hit the rate limit. To avoid this you can specify an OAuth token by setting GITHUB_TOKEN environment variable. You can use GITHUB_TOKEN secret for this purpose.

The COMPOSER_TOKEN environment variable has been deprecated in favor of GITHUB_TOKEN and will be removed in the next major version.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Private Packagist Authentication

If you use Private Packagist for your private composer dependencies, you can set the PACKAGIST_TOKEN environment variable to authenticate.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
  env:
    PACKAGIST_TOKEN: ${{ secrets.PACKAGIST_TOKEN }}

Manual Composer Authentication

In addition to GitHub or Private Packagist, if you want to authenticate private repositories hosted elsewhere, you can set the COMPOSER_AUTH_JSON environment variable with the authentication methods and the credentials in json format. Please refer to the authentication section in composer documentation for more details.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
  env:
    COMPOSER_AUTH_JSON: |
      {
        "http-basic": {
          "example.org": {
            "username": "${{ secrets.EXAMPLE_ORG_USERNAME }}",
            "password": "${{ secrets.EXAMPLE_ORG_PASSWORD }}"
          }
        }
      }

Inline PHP Scripts

If you have to run multiple lines of PHP code in your workflow, you can do that easily without saving it to a file.

Put the code in the run property of a step and specify the shell as php {0}.

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

- name: Run PHP code
  shell: php {0}
  run: |
    <?php
    $welcome = "Hello, world";
    echo $welcome;

Problem Matchers

Problem matchers are json configurations which identify errors and warnings in your logs and surface them prominently in the GitHub Actions UI by highlighting them and creating code annotations.

PHP

Setup problem matchers for your PHP output by adding this step after the setup-php step.

- name: Setup problem matchers for PHP
  run: echo "::add-matcher::${{ runner.tool_cache }}/php.json"

PHPUnit

Setup problem matchers for your PHPUnit output by adding this step after the setup-php step.

- name: Setup problem matchers for PHPUnit
  run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"

Examples

Examples of using setup-php with various PHP frameworks and packages.

Framework/Package	Runs on	Workflow
Blackfire	`macOS`, `ubuntu` and `windows`	blackfire.yml
Blackfire Player	`macOS`, `ubuntu` and `windows`	blackfire-player.yml
CakePHP with `MySQL` and `Redis`	`ubuntu`	cakephp-mysql.yml
CakePHP with `PostgreSQL` and `Redis`	`ubuntu`	cakephp-postgres.yml
CakePHP without services	`macOS`, `ubuntu` and `windows`	cakephp.yml
CodeIgniter	`macOS`, `ubuntu` and `windows`	codeigniter.yml
Laminas MVC	`macOS`, `ubuntu` and `windows`	laminas-mvc.yml
Laravel with `MySQL` and `Redis`	`ubuntu`	laravel-mysql.yml
Laravel with `PostgreSQL` and `Redis`	`ubuntu`	laravel-postgres.yml
Laravel without services	`macOS`, `ubuntu` and `windows`	laravel.yml
Lumen with `MySQL` and `Redis`	`ubuntu`	lumen-mysql.yml
Lumen with `PostgreSQL` and `Redis`	`ubuntu`	lumen-postgres.yml
Lumen without services	`macOS`, `ubuntu` and `windows`	lumen.yml
Phalcon with `MySQL`	`ubuntu`	phalcon-mysql.yml
Phalcon with `PostgreSQL`	`ubuntu`	phalcon-postgres.yml
Roots/bedrock	`ubuntu`	bedrock.yml
Roots/sage	`ubuntu`	sage.yml
Slim Framework	`macOS`, `ubuntu` and `windows`	slim-framework.yml
Symfony with `MySQL`	`ubuntu`	symfony-mysql.yml
Symfony with `PostgreSQL`	`ubuntu`	symfony-postgres.yml
Symfony without services	`macOS`, `ubuntu` and `windows`	symfony.yml
Yii2 Starter Kit with `MySQL`	`ubuntu`	yii2-mysql.yml
Yii2 Starter Kit with `PostgreSQL`	`ubuntu`	yii2-postgres.yml

GitHub-Hosted Runners

Disable Coverage

Inputs

`ini-file` (optional)

`ini-values` (optional)

Outputs

`php-version`

Flags

`fail-fast` (optional)

`phpts` (optional)

`update` (optional)

Basic Setup

Matrix Setup

Thread Safe Setup

Force Update Setup

Verbose Setup

Local Testing Setup

JIT Configuration

Cache Extensions

GitHub Composer Authentication

Private Packagist Authentication

Manual Composer Authentication

Inline PHP Scripts

Problem Matchers

PHP

PHPUnit

Examples

:package: Dependencies

:bookmark_tabs: Further Reading

Articles

Setup PHP

GitHub-Hosted Runners

Disable Coverage

Inputs

ini-file (optional)

ini-values (optional)

Outputs

php-version

Flags

fail-fast (optional)

phpts (optional)

update (optional)

Basic Setup

Matrix Setup

Thread Safe Setup

Force Update Setup

Verbose Setup

Local Testing Setup

JIT Configuration

Cache Extensions

GitHub Composer Authentication

Private Packagist Authentication

Manual Composer Authentication

Inline PHP Scripts

Problem Matchers

PHP

PHPUnit

Examples

:package: Dependencies

:bookmark_tabs: Further Reading

Articles

`ini-file` (optional)

`ini-values` (optional)

`php-version`

`fail-fast` (optional)

`phpts` (optional)

`update` (optional)