search

shivammathur / setup-php

GitHub action to set up PHP with extensions, php.ini configuration, coverage drivers, and various tools.
https://setup-php.com
MIT License
2.93k stars 348 forks source link
code-coverage composer continuous-integration github-actions php php-extensions static-analysis tools

readme

Setup PHP in GitHub Actions

Setup PHP in GitHub Actions

GitHub Actions status Codecov Code Coverage LICENSE PHP Versions Supported

setup-php reddit setup-php twitter setup-php status

Setup PHP with required extensions, php.ini configuration, code-coverage support and various tools like composer in GitHub Actions. This action gives you a cross-platform interface to set up the PHP environment you need to test your application. Refer to Usage section and examples to see how to use this.

Contents

:cloud: OS/Platform Support

Both GitHub-hosted and self-hosted runners are supported by setup-php on the following OS/Platforms.

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 Sequoia 15.x macos-15 -
macOS Sonoma 14.x macos-latest or macos-14 -
macOS Ventura 13.x macos-13 PHP 8.3

Self-Hosted Runners

Host OS/Virtual environment YAML workflow label
Ubuntu 24.04 self-hosted or Linux
Ubuntu 22.04 self-hosted or Linux
Ubuntu 20.04 self-hosted or Linux
Debian 12 self-hosted or Linux
Debian 11 self-hosted or Linux
Windows 7 and newer self-hosted or Windows
Windows Server 2012 R2 and newer self-hosted or Windows
macOS Sequoia 15.x x86_64/arm64 self-hosted or macOS
macOS Sonoma 14.x x86_64/arm64 self-hosted or macOS
macOS Ventura 13.x x86_64/arm64 self-hosted or macOS

:tada: PHP Support

On all supported OS/Platforms the following PHP versions can be set up as per the runner.

PHP Version Stability Release Support Runner Support
5.3 Stable End of life GitHub-hosted
5.4 Stable End of life GitHub-hosted
5.5 Stable End of life GitHub-hosted
5.6 Stable End of life GitHub-hosted, self-hosted
7.0 Stable End of life GitHub-hosted, self-hosted
7.1 Stable End of life GitHub-hosted, self-hosted
7.2 Stable End of life GitHub-hosted, self-hosted
7.3 Stable End of life GitHub-hosted, self-hosted
7.4 Stable End of life GitHub-hosted, self-hosted
8.0 Stable End of life GitHub-hosted, self-hosted
8.1 Stable Security fixes only GitHub-hosted, self-hosted
8.2 Stable Active GitHub-hosted, self-hosted
8.3 Stable Active GitHub-hosted, self-hosted
8.4 Stable Active GitHub-hosted, self-hosted
8.5 Nightly In development GitHub-hosted, self-hosted

Notes:

:heavy_plus_sign: PHP Extension Support

PHP extensions can be set up using the extensions input. It accepts a string in csv-format.

- name: Setup PHP with PECL extension
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    extensions: imagick, swoole
- name: Setup PHP with specific version of PECL extension
  uses: shivammathur/setup-php@v2
  with:
    php-version: '5.4'
    extensions: swoole-1.9.3
- name: Setup PHP with pre-release PECL extension
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    extensions: xdebug-beta
- name: Setup PHP and disable opcache
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    extensions: :opcache

Note: This disables all core and third-party shared extensions and thus, can break some tools which need them. Required extensions are enabled again when the tools are set up on a best-effort basis. So it is recommended to add the extensions required for your tools after none in the extensions input to avoid any issues.

- name: Setup PHP without any shared extensions except mbstring
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    extensions: none, mbstring
- name: Setup PHP with intl
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    extensions: intl-70.1
- name: Setup PHP with fail-fast
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    extensions: oci8
  env:
    fail-fast: true

:wrench: Tools Support

These tools can be set up globally using the tools input. It accepts a string in csv-format.

behat, blackfire, blackfire-player, box, castor, churn, codeception, composer, composer-dependency-analyser, composer-normalize, composer-prefetcher, composer-require-checker, composer-unused, cs2pr, deployer, ecs, flex, grpc_php_plugin, infection, parallel-lint, pecl, phan, phing, phinx, phive, php-config, php-cs-fixer, php-scoper, phpcbf, phpcpd, phpcs, phpdoc or phpDocumentor, phpize, phplint, phpmd, phpspec, phpstan, phpunit, phpunit-bridge, phpunit-polyfills, pint, prestissimo, protoc, psalm, rector, symfony or symfony-cli, vapor or vapor-cli, wp or wp-cli

- name: Setup PHP with tools
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: php-cs-fixer, phpunit
- name: Setup PHP with tools
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: vimeo/psalm
- name: Setup PHP with tools
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: php-cs-fixer:3.64, phpunit:11.4
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Setup PHP with composer v2
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: composer:v2
- name: Setup PHP without composer
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: none
- name: Setup PHP with fail-fast
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: deployer
  env:
    fail-fast: true

Notes

- name: Setup PHP with composer and custom process timeout
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
  env:
    COMPOSER_PROCESS_TIMEOUT: 300

:signal_strength: Coverage Support

Xdebug

Specify coverage: xdebug to use Xdebug and disable PCOV.
Runs on all PHP versions supported.

- name: Setup PHP with Xdebug
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    coverage: xdebug
- name: Setup PHP with Xdebug 2.x
  uses: shivammathur/setup-php@v2
  with:
    php-version: '7.4'
    coverage: xdebug2

Note: Xdebug is enabled by default on Ubuntu GitHub Actions images, so if you are not using it in your workflow it is recommended to disable it as that will have a positive impact on your PHP performance. Please refer to the disable coverage section for details.

PCOV

Specify coverage: pcov to use PCOV and disable Xdebug.
Runs on PHP 7.1 and newer PHP versions.

- name: Setup PHP with PCOV
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    ini-values: pcov.directory=api #optional, see above for usage.
    coverage: pcov
- name: Setup PCOV
  run: |
    composer require pcov/clobber
    vendor/bin/pcov clobber

Disable Coverage

Specify coverage: none to disable both Xdebug and PCOV.

Disable coverage for these reasons:

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

:memo: Usage

Inputs

Specify using with keyword

php-version (optional)

php-version-file (optional)

extensions (optional)

ini-file (optional)

ini-values (optional)

coverage (optional)

tools (optional)

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.

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

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

Flags

Specify using env keyword

fail-fast (optional)

phpts (optional)

update (optional)

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.4'
    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.2', '8.3', '8.4']
        phpunit-versions: ['latest']
        include:
          - operating-system: 'ubuntu-latest'
            php-versions: '8.1'
            phpunit-versions: 10
    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 }}

Nightly Build Setup

Set up a nightly build of PHP 8.5.

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

Debug Build Setup

Set up a PHP build with debugging symbols.

Notes

steps:
- name: Setup PHP with debugging symbols
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
  env:
    debug: true # specify true or false

Thread Safe Setup

Set up TS or NTS PHP.

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.4'
      env:
        phpts: ts # specify ts or nts

Force Update Setup

Update to the latest patch of PHP versions.

- name: Setup PHP with latest versions
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
  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.4'

Multi-Arch Setup

Set up PHP on multiple architecture on Ubuntu GitHub Runners.

jobs:
  run:
    runs-on: ubuntu-latest
    container: shivammathur/node:latest-${{ matrix.arch }}
    strategy:
      matrix:
        arch: ["amd64", "i386"]
    steps:
      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'

Self Hosted Setup

Set up PHP on a self-hosted runner.

It is recommended to specify the environment variable runner with the value self-hosted for self-hosted environments.

jobs:
  run:
    runs-on: self-hosted
    strategy:
      matrix:
        php-versions: ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4']
    name: PHP ${{ matrix.php-versions }}
    steps:
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: ${{ matrix.php-versions }}
      env:
        runner: self-hosted

Notes

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

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.

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

Cache Composer Dependencies

If your project uses composer, you can persist the composer's internal cache directory. Dependencies cached are loaded directly instead of downloading them while installation. The files cached are available across check-runs and will reduce the workflow execution time.

- name: Get composer cache directory
  id: composer-cache
  run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT

- name: Cache dependencies
  uses: actions/cache@v4
  with:
    path: ${{ steps.composer-cache.outputs.dir }}
    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
    restore-keys: ${{ runner.os }}-composer-

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

Notes

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

- 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"

PHPStan

PHPStan supports error reporting in GitHub Actions, so it does not require problem matchers.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: phpstan

- name: Run PHPStan
  run: phpstan analyse src

Psalm

Psalm supports error reporting in GitHub Actions with an output format github.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: psalm

- name: Run Psalm
  run: psalm --output-format=github

Tools with checkstyle support

For tools that support checkstyle reporting like phpstan, psalm, php-cs-fixer and phpcs you can use cs2pr to annotate your code.
For examples refer to the cs2pr documentation.

Here is an example with phpcs.

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: cs2pr, phpcs

- name: Run phpcs
  run: phpcs -q --report=checkstyle src | cs2pr

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

:bookmark: Versioning

:scroll: License

:+1: Contributions

Contributions are welcome!

Contributors of setup-php and other related projects

Contributors of setup-php and related projects

:sparkling_heart: Support This Project

Many users and organisations support setup-php via GitHub Sponsors.

Sponsor shivammathur

These companies generously provide setup-php their products and services to aid in the development of this project.

JetBrains           Mac Stadium Mac Stadium           Tidelift

:package: Dependencies

:bookmark_tabs: Further Reading