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 setup the PHP environment you need to test your application. Refer to Usage section and examples to see how to use this.
- PHP Support
- OS/Platform Support
- PHP Extension Support
- Tools Support
- Coverage support
- Usage
- License
- Contributions
- Support This Project
- Dependencies
- Further Reading
PHP Version | Stability | Release Support |
---|---|---|
5.3 | Stable |
End of life |
5.4 | Stable |
End of life |
5.5 | Stable |
End of life |
5.6 | Stable |
End of life |
7.0 | Stable |
End of life |
7.1 | Stable |
End of life |
7.2 | Stable |
Security fixes only |
7.3 | Stable |
Active |
7.4 | Stable |
Active |
8.0 | Experimental |
In development |
Note: Specifying 8.0
in php-version
input installs a nightly build of PHP 8.0.0-dev
with PHP JIT
, Union Types v2
and other new features. See experimental setup for more information.
Virtual environment | matrix.operating-system |
---|---|
Windows Server 2019 | windows-latest or windows-2019 |
Ubuntu 18.04 | ubuntu-latest or ubuntu-18.04 |
Ubuntu 16.04 | ubuntu-16.04 |
macOS X Catalina 10.15 | macos-latest or macOS-10.15 |
- On
ubuntu
by default extensions which are available as a package can be installed. If the extension is not available as a package but it is onPECL
, it can be installed by specifyingpecl
in the tools input.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
tools: pecl
extensions: swoole
-
On
windows
extensions which havewindows
binary onPECL
can be installed. -
On
macOS
extensions which are onPECL
can be installed. -
Extensions which are installed along with PHP if specified are enabled.
-
Specific versions of PECL extensions can be installed by suffixing the extension with the version. This is useful for installing old versions of extensions which support end of life PHP versions.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
tools: pecl
extensions: pcov-1.0.6
- Pre-release versions of PECL extensions can be installed by suffixing the extension with its state i.e
alpha
,beta
,devel
orsnapshot
.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
tools: pecl
extensions: xdebug-beta
- Extensions which cannot be installed gracefully leave an error message in the logs, the action is not interrupted.
These tools can be setup globally using the tools
input.
codeception
, composer
, composer-prefetcher
, cs2pr
, deployer
, pecl
, phinx
, phive
, phpcbf
, phpcpd
, php-config
, php-cs-fixer
, phpcs
, phpize
, phpmd
, phpstan
, phpunit
, prestissimo
, psalm
, symfony
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
tools: php-cs-fixer, phpunit
To setup a particular version of a tool, specify it in the form tool:version
.
Version should be in semver format and a valid release of the tool.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
tools: php-cs-fixer:2.15.5, phpunit:8.5.1
Note
composer
is setup by default.- Specifying version for
composer
andpecl
has no effect, latest versions of both tools which are compatible with the PHP version will be setup. - If the version specified for the tool is not in semver format, latest version of the tool will be setup.
- Tools which cannot be installed gracefully leave an error message in the logs, the action is not interrupted.
Specify coverage: xdebug
to use Xdebug
.
Runs on all PHP versions supported except 8.0
.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
coverage: xdebug
Specify coverage: pcov
to use PCOV
and disable Xdebug
.
It is much faster than Xdebug
.
PCOV
needs PHP >= 7.1
.
If your source code directory is other than src
, lib
or, app
, specify pcov.directory
using the ini-values
input.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
ini-values: pcov.directory=api #optional, see above for usage.
coverage: pcov
Specify coverage: none
to remove both Xdebug
and PCOV
.
Consider disabling the coverage using this PHP action for these reasons.
- You are not generating coverage reports while testing.
- It will remove
Xdebug
, which will have a positive impact on PHP performance. - You are using
phpdbg
for running your tests.
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
coverage: none
- Specify the PHP version you want to setup.
- Accepts a
string
. For example'7.4'
. - See PHP support for supported PHP versions.
- Specify the extensions you want to setup.
- Accepts a
string
in csv-format. For examplembstring, zip
. - See PHP extension support for more info.
- Specify the values you want to add to
php.ini
. - Accepts a
string
in csv-format. For examplepost_max_size=256M, short_open_tag=On
.
- Specify the code coverage driver you want to setup.
- Accepts
xdebug
,pcov
ornone
. - See coverage support for more info.
- Specify the tools you want to setup.
- Accepts a
string
in csv-format. For examplephpunit, phpcs
- See tools Support for tools supported.
See below for more info.
Setup a particular PHP version.
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
extensions: mbstring, intl
ini-values: post_max_size=256M, short_open_tag=On
coverage: xdebug
tools: php-cs-fixer, phpunit
Setup 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: ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4']
name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-versions }}
extensions: mbstring, intl
ini-values: post_max_size=256M, short_open_tag=On
coverage: xdebug
tools: php-cs-fixer, phpunit
Setup a nightly build of
PHP 8.0.0-dev
from the master branch of PHP.
- This version is currently in development and is an experimental feature on this action.
PECL
is installed by default with this version onubuntu
.- Some extensions might not support this version currently.
- Refer to this RFC for configuring
PHP JIT
on this version. - Refer to this list of RFCs implemented in this version.
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.0'
extensions: mbstring
ini-values: opcache.jit_buffer_size=256M, opcache.jit=1235, pcre.jit=1
coverage: pcov
tools: php-cs-fixer, phpunit
NTS
versions are setup by default.- On
ubuntu
andmacOS
only NTS versions are supported. - On
windows
bothTS
andNTS
versions are supported.
jobs:
run:
runs-on: windows-latest
name: Setup PHP TS on Windows
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
env:
PHPTS: ts # specify ts or nts
- PHP versions which are pre-installed on the GitHub Actions runner are not updated to their latest patch release by default.
- You can specify the
update
environment variable totrue
to force update to the latest release.
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
env:
update: true # specify true or false
- To debug any issues, you can use the
verbose
tag instead ofv2
.
- name: Setup PHP
uses: shivammathur/setup-php@verbose
with:
php-version: '7.4'
You can persist PHP extensions you setup using the shivammathur/cache-extensions
and action/cache
GitHub Actions. Extensions which take very long to setup if cached are available in the next workflow run and enabled directly which reduces the workflow execution time.
runs-on: ${{ matrix.operating-system }}
strategy:
matrix:
operating-system: [ubuntu-latest, windows-latest, macos-latest]
php-versions: ['7.2', '7.3', '7.4']
name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
env:
extensions: intl, pcov
key: cache-v1 # can be any string, change to clear the extension cache.
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup cache environment
id: cache-env
uses: shivammathur/cache-extensions@v1
with:
php-version: ${{ matrix.php-versions }}
extensions: ${{ env.extensions }}
key: ${{ env.key }}
- name: Cache extensions
uses: actions/cache@v1
with:
path: ${{ steps.cache-env.outputs.dir }}
key: ${{ steps.cache-env.outputs.key }}
restore-keys: ${{ steps.cache-env.outputs.key }}
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-versions }}
extensions: ${{ env.extensions }}
You can persist composer's internal cache directory using the action/cache
GitHub Action. 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.
Note: Please do not cache vendor
directory using action/cache
as that will have side-effects.
- name: Get Composer Cache Directory
id: composer-cache
run: echo "::set-output name=dir::$(composer config cache-files-dir)"
- name: Cache dependencies
uses: actions/cache@v1
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
In the above example, if you support a range of composer
dependencies and do not commit composer.lock
, you can use the hash of composer.json
as the key for your cache.
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
Setup problem matchers for your PHP
output by adding this step after the setup-php
step. This will scan the logs for PHP errors and warnings, and surface them prominently in the GitHub Actions UI by creating annotations and log file decorations.
- name: Setup Problem Matchers for PHP
run: echo "::add-matcher::${{ runner.tool_cache }}/php.json"
Setup problem matchers for your PHPUnit
output by adding this step after the setup-php
step. This will scan the logs for failing tests and surface that information prominently in the GitHub Actions UI by creating annotations and log file decorations.
- name: Setup Problem Matchers for PHPUnit
run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
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 cs2pr documentation.
Here is an example with
phpstan
.
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
tools: cs2pr, phpstan
- name: PHPStan
run: phpstan analyse src --error-format=checkstyle | cs2pr
Examples for setting up this GitHub Action with different PHP Frameworks/Packages.
Framework/Package | Runs on | Workflow |
---|---|---|
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 |
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 |
Zend Framework | macOS , ubuntu and windows |
zend-framework.yml |
The scripts and documentation in this project are released under the MIT License. This project has multiple dependencies. Their licenses can be found in their respective repositories.
Contributions are welcome! See Contributor's Guide. If you face any issues while using this or want to suggest a feature/improvement, create an issue here.
If this action helped you.
- Please star the project and share it with the community.
- If you blog, write about your experience while using this action.
- I maintain this in my free time, please support me with a Patreon subscription or a one time contribution using Paypal.
- If you need any help using this, please contact me using Codementor