Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork405
GitHub action to set up PHP with extensions, php.ini configuration, coverage drivers, and various tools.
License
shivammathur/setup-php
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Setup PHP with required extensions, php.ini configuration, code-coverage support and various tools like composer inGitHub Actions. This action gives you a cross-platform interface to set up the PHP environment you need to test your application. Refer toUsage section andexamples to see how to use this.
- OS/Platform Support
- PHP Support
- PHP Extension Support
- Tools Support
- Coverage Support
- Usage
- Inputs
- Outputs
- Flags
- Basic Setup
- Matrix Setup
- Nightly Build Setup
- Debug Build Setup
- Thread Safe Setup
- Force Update Setup
- Verbose Setup
- Multi-Arch Setup
- Self Hosted Setup
- Local Testing Setup
- JIT Configuration
- Cache Extensions
- Cache Composer Dependencies
- GitHub Composer Authentication
- Private Packagist Authentication
- Manual Composer Authentication
- Inline PHP Scripts
- Problem Matchers
- Examples
- Versioning
- License
- Contributions
- Support This Project
- Dependencies
- Further Reading
BothGitHub-hosted andself-hosted runners are supported bysetup-php on the following OS/Platforms.
| Virtual environment | Arch | YAML workflow label | Pre-installed PHP |
|---|---|---|---|
| Ubuntu 24.04 | x86_64 | ubuntu-latest orubuntu-24.04 | PHP 8.3 |
| Ubuntu 22.04 | x86_64 | ubuntu-22.04 | PHP 8.1 |
| Ubuntu 24.04 | aarch64 | ubuntu-24.04-arm | PHP 8.3 |
| Ubuntu 22.04 | aarch64 | ubuntu-22.04-arm | PHP 8.1 |
| Windows Server 2025 | x64 | windows-2025 | PHP 8.3 |
| Windows Server 2022 | x64 | windows-latest orwindows-2022 | PHP 8.3 |
| macOS Tahoe 26.x | arm64 | macos-26 | - |
| macOS Sequoia 15.x | arm64 | macos-latest ormacos-15 | - |
| macOS Sonoma 14.x | arm64 | macos-14 | - |
| macOS Sequoia 15.x | x86_64 | macos-15-intel | PHP 8.3 |
| macOS Ventura 13.x | x86_64 | macos-13 | PHP 8.3 |
| Host OS/Virtual environment | YAML workflow label |
|---|---|
| Ubuntu 24.04 | self-hosted orLinux |
| Ubuntu 22.04 | self-hosted orLinux |
| Debian 13 | self-hosted orLinux |
| Debian 12 | self-hosted orLinux |
| Debian 11 | self-hosted orLinux |
| Windows 7 and newer | self-hosted orWindows |
| Windows Server 2012 R2 and newer | self-hosted orWindows |
| macOS Tahoe 26.x x86_64/arm64 | self-hosted ormacOS |
| macOS Sequoia 15.x x86_64/arm64 | self-hosted ormacOS |
| macOS Sonoma 14.x x86_64/arm64 | self-hosted ormacOS |
- Refer to theself-hosted setup to use the action on self-hosted runners.
- Operating systems based on the above Ubuntu and Debian versions are also supported on best effort basis.
- If the requested PHP version is pre-installed,
setup-phpswitches to it, otherwise it installs the PHP version.
On all supported OS/Platforms, the following PHP versions can be set up as per the runner.
- PHP 5.3 to PHP 8.6 on GitHub-hosted runners, except for macOS ARM64 runners (macos-14).
- PHP 5.6 to PHP 8.6 on GitHub-hosted macOS ARM64 runners (macos-14).
- PHP 5.6 to PHP 8.6 on self-hosted runners.
| 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 | Security fixes only | GitHub-hosted,self-hosted |
8.3 | Stable | Active | GitHub-hosted,self-hosted |
8.4 | Stable | Active | GitHub-hosted,self-hosted |
8.5 | Stable | Active | GitHub-hosted,self-hosted |
8.6 | Nightly | In development | GitHub-hosted,self-hosted |
Note
- Specifying
8.6inphp-versioninput installs a nightly build ofPHP 8.6.0-devfrom the master branch of PHP. Seenightly build setup for more information. - To use JIT on
PHP 8.0and above, refer to theJIT configuration section.
PHP extensions can be set up using theextensions input. It accepts astring in csv-format.
- On
Ubuntu, extensions which are available as a package, available onPECLor a git repository can be set up.
-name:Setup PHP with PECL extensionuses:shivammathur/setup-php@v2with:php-version:'8.5'extensions:imagick, redis
On
Windows, extensions available onPECLwhich have theDLLbinary can be set up.On
macOS, extensions available onPECLor a git repository can be set up.On
UbuntuandmacOSto compile and install an extension from a git repository follow thisguide.Extensions installed along with PHP if specified are enabled.
Specific versions of extensions available on
PECLcan be set up by suffixing the extension's name with the version. This is useful for installing old versions of extensions which support end of life PHP versions.
-name:Setup PHP with specific version of PECL extensionuses:shivammathur/setup-php@v2with:php-version:'5.4'extensions:swoole-1.9.3
- Extensions with pre-release versions available on
PECLcan be set up by suffixing the extension's name with its state i.ealpha,beta,develorsnapshot.
-name:Setup PHP with pre-release PECL extensionuses:shivammathur/setup-php@v2with:php-version:'8.5'extensions:xdebug-beta
On
UbuntuandmacOSto compile and install an extension from PECL with libraries or custom configuration follow thisguide.Shared extensions can be disabled by prefixing them with a
:. All extensions depending on the specified extension will also be disabled.
-name:Setup PHP and disable opcacheuses:shivammathur/setup-php@v2with:php-version:'8.5'extensions::mbstring
- All shared extensions can be disabled by specifying
none. Whennoneis specified along with other extensions, it is hoisted to the start of the input. So, all the shared extensions will be disabled first, then rest of the extensions in the input will be processed.
This disables all core and third-party shared extensions and thus, can break some tools that 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 afternone in theextensions input to avoid any issues.
-name:Setup PHP without any shared extensions except mbstringuses:shivammathur/setup-php@v2with:php-version:'8.5'extensions:none, mbstring
- Extension
intlcan be set up with specificICUversion forPHP 5.6and above inUbuntuworkflows by suffixingintlwith theICUversion.ICU 50.2and newer versions are supported for PHP 8.4 and lower,ICU 57.2and newer versions are supported for PHP 8.5 and above. Refer toICU buildsfor the specific versions supported.
-name:Setup PHP with intluses:shivammathur/setup-php@v2with:php-version:'8.5'extensions:intl-77.1
Extensions loaded by default after
setup-phpruns can be found on thewiki.These extensions have custom support:
cubridandpdo_cubridonUbuntu.event,gearman,geosandrelayonUbuntuandmacOS.blackfire,couchbase,ibm_db2,ioncube,oci8,pdo_firebird,pdo_ibm,pdo_oci,pecl_http,phalcon3,phalcon4,phalcon5, andzephir_parseron all supported OS.
By default, extensions which cannot be added or disabled gracefully leave an error message in the logs, the execution is not interrupted. To change this behaviour you can set
fail-fastflag totrue.
-name:Setup PHP with fail-fastuses:shivammathur/setup-php@v2with:php-version:'8.5'extensions:oci8env:fail-fast:true
These tools can be set up globally using thetools input. It accepts a string in csv-format.
backward-compatibility-check,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,mago,name-collision-detector,parallel-lint,pecl,phan,phing,phinx,phive,php-config,php-cs-fixer,php-scoper,phpcbf,phpcpd,phpcs,phpdoc orphpDocumentor,phpize,phplint,phpmd,phpspec,phpstan,phpunit,phpunit-bridge,phpunit-polyfills,pie,pint,prestissimo,protoc,psalm,rector,symfony orsymfony-cli,vapor orvapor-cli,wp orwp-cli
-name:Setup PHP with toolsuses:shivammathur/setup-php@v2with:php-version:'8.5'tools:php-cs-fixer, phpunit
- In addition to above tools any composer tool or package can also be set up globally by specifying it as
vendor/packagematching the listing on Packagist. This format accepts the sameversion constraints ascomposer.
-name:Setup PHP with toolsuses:shivammathur/setup-php@v2with:php-version:'8.5'tools:vimeo/psalm
To set up a particular version of a tool, specify it in the form
tool:version.Version can be in the following format:
- Semver. For example
tool:1.2.3ortool:1.2.3-beta1. - Major version. For example
tool:1ortool:1.x. - Major and minor version. For example
tool:1.2ortool:1.2.x.
When you specify just the major version or the version in
major.minorformat, the latest patch version matching the input will be setup.- Semver. For example
The latest stable version of
composeris set up by default. You can set up the requiredcomposerversion by specifying the major versionv1orv2, or the version inmajor.minororsemverformat. Additionally, for composersnapshotandpreviewcan also be specified to set up the respective releases.
-name:Setup PHP with composer v2uses:shivammathur/setup-php@v2with:php-version:'8.5'tools:composer:v1
- If you do not use composer in your workflow, you can specify
tools: noneto skip it.
-name:Setup PHP without composeruses:shivammathur/setup-php@v2with:php-version:'8.5'tools:none
Tools
pear,pecl,phpizeandphp-configare set up by default for all supported PHP versions on Linux and macOS.The latest version of
blackfirecli is set up whenblackfireis specified in tools input. Please refer to theofficial documentation for usingblackfirewith GitHub Actions.Tools
prestissimoandcomposer-prefetcherwill be skipped unlesscomposer:v1is also specified in tools input. It is recommended to dropprestissimoand usecomposer v2.By default, except
composertools which cannot be set up gracefully leave an error message in the logs, the execution is not interrupted. To change this behaviour you can setfail-fastflag totrue.
-name:Setup PHP with fail-fastuses:shivammathur/setup-php@v2with:php-version:'8.5'tools:deployerenv:fail-fast:true
- By default,
composerblocks all its plugins. If you are using thetoolsinput to install a composer plugin it will be added to the allow list, alternatively if your dependencies have composer plugins, you can allow them by settingCOMPOSER_ALLOW_PLUGINSthat accepts a csv string of plugin names.
-name:Setup PHP with fail-fastuses:shivammathur/setup-php@v2with:php-version:'8.5'env:COMPOSER_ALLOW_PLUGINS:composer/installers, composer/satis
Note
- Input
toolsis useful to set up tools which are only used in CI workflows, thus keeping yourcomposer.jsontidy. - If you do not want to use all your dev-dependencies in workflow, you can run composer with
--no-devand install required tools usingtoolsinput to speed up your workflow. - By default,
COMPOSER_NO_INTERACTIONis set to1andCOMPOSER_PROCESS_TIMEOUTis set to0. In effect, this means that Composer commands in your scripts do not need to specify--no-interaction. - Also,
COMPOSER_NO_AUDITis set to1. So if you want to audit your dependencies for security vulnerabilities, it is recommended to add acomposer auditstep before you install them. - If you want to set a different
COMPOSER_PROCESS_TIMEOUT, you can set it in your workflow file using theenvkeyword.
-name:Setup PHP with composer and custom process timeoutuses:shivammathur/setup-php@v2with:php-version:'8.5'env:COMPOSER_PROCESS_TIMEOUT:300
Specifycoverage: xdebug to useXdebug and disablePCOV.
Runs on allPHP versions supported.
-name:Setup PHP with Xdebuguses:shivammathur/setup-php@v2with:php-version:'8.5'coverage:xdebug
- When you specify
coverage: xdebug, the latest version of Xdebug compatible with the PHP version is set up by default. - If you need Xdebug 2.x on PHP 7.2, 7.3 or 7.4, you can specify
coverage: xdebug2.
-name:Setup PHP with Xdebug 2.xuses:shivammathur/setup-php@v2with: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 thedisable coverage section for details.
Specifycoverage: pcov to usePCOV and disableXdebug.
Runs on PHP 7.1 and newer PHP versions.
- If your source code directory is other than
src,libor,app, specifypcov.directoryusing theini-valuesinput.
-name:Setup PHP with PCOVuses:shivammathur/setup-php@v2with:php-version:'8.5'ini-values:pcov.directory=api#optional, see above for usage.coverage:pcov
- PHPUnit 8.x and above support PCOV out of the box.
- If you are using PHPUnit 5.x, 6.x or 7.x, you need to set up
pcov/clobberbefore executing your tests.
-name:Setup PCOVrun:| composer require pcov/clobber vendor/bin/pcov clobber
Specifycoverage: none to disable bothXdebug andPCOV.
Disable coverage for these reasons:
- You are not generating coverage reports while testing.
- You are using
phpdbgfor running your tests. - You are profiling your code using
blackfire. - You are using PHP in JIT mode. Please refer toJIT configuration section for more details.
-name:Setup PHP with no coverage driveruses:shivammathur/setup-php@v2with:php-version:'8.5'coverage:none
Specify using
withkeyword
- Specify the PHP version you want to set up.
- Accepts a
string. For example'8.5'. - Accepts
lowestto set up the lowest supported PHP version. - Accepts
highestorlatestto set up the latest stable PHP version. - Accepts
nightlyto set up a nightly build from the master branch of PHP. - Accepts
pre-installedto set up the highest pre-installed PHP version. You can combine this withupdate: trueto update the pre-installed PHP version. - Accepts the format
d.x, wheredis the major version. For example5.x,7.xand8.x. - SeePHP support for the supported PHP versions.
- If not specified, it looks for the following in order:
- The
php-version-fileinput if it exists - A
composer.lockfile and theplatform-overrides.phpvalue - A
composer.jsonfile and theconfig.platform.phpvalue - If the
composer.lockorcomposer.jsonfile is in a subdirectory in your repository, please specify the subdirectory path inCOMPOSER_PROJECT_DIRenv.
- The
- Specify a file with the PHP version you want to set up.
- Accepts a
string. For example'.phpenv-version'. - SeePHP support for the supported PHP versions.
- By default,
.php-versionfile is used. - The file needs to either have the PHP version as its content or follows the asdf
.tool-versionsformat. - If not specified and the default
.php-versionfile is not found, the latest stable PHP version is set up.
- Specify the extensions you want to add or disable.
- Accepts a
stringin csv-format. For examplembstring, :opcache. - Accepts
noneto disable all shared extensions. - Shared extensions prefixed with
:are disabled. - SeePHP extension support for more info.
- Specify the base
php.inifile. - Accepts
production,developmentornone. - By default, production
php.inifile is used.
- Specify the values you want to add to
php.ini. - Accepts a
stringin csv-format. For examplepost_max_size=256M, max_execution_time=180. - Accepts ini values with commas if wrapped in quotes. For example
xdebug.mode="develop,coverage".
- Specify the code-coverage driver you want to set up.
- Accepts
xdebug,pcovornone. - Seecoverage support for more info.
- Specify the tools you want to set up.
- Accepts a
stringin csv-format. For example:phpunit, phpcs - Seetools support for tools supported.
- Specify the GitHub token to use for authentication.
- Accepts a
string. - By default,
GITHUB_TOKENsecret provided by GitHub Actions is used. - For GitHub Enterprise users, it is recommended to use a Personal Access Token (PAT).
On GitHub Actions you can assign thesetup-php step anid, you can use the same to get the outputs in a later step.
- Provides the PHP version in semver format.
-name:Setup PHPid:setup-phpuses:shivammathur/setup-php@v2with:php-version:'8.5'-name:Print PHP versionrun:echo ${{ steps.setup-php.outputs.php-version }}
Specify using
envkeyword
- 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
trueandfalse.
- Specify to set up a thread-safe build of PHP.
- Accepts
ntsfor non-thread-safe andztsortsfor thread-safe. - By default, it is set to
nts. - Seethread safe setup for more info.
- Specify to update PHP on the runner to the latest patch version.
- Accepts
trueandfalse. - By default, it is set to
false. - Seeforce update setup for more info.
See below for more info.
Set up a particular PHP version.
steps:-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'extensions:mbstring, intlini-values:post_max_size=256M, max_execution_time=180coverage:xdebugtools:php-cs-fixer, phpunit
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', '8.5']phpunit-versions:['latest']include: -operating-system:'ubuntu-latest'php-versions:'8.1'phpunit-versions:10steps: -name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:${{ matrix.php-versions }}extensions:mbstring, intlini-values:post_max_size=256M, max_execution_time=180coverage:xdebugtools:php-cs-fixer, phpunit:${{ matrix.phpunit-versions }}
Set up a nightly build of
PHP 8.6.
- These PHP versions are currently in active development and might contain bugs and breaking changes.
- Some user space extensions might not support these versions currently.
steps:-name:Setup nightly PHPuses:shivammathur/setup-php@v2with:php-version:'8.6'extensions:mbstringini-values:post_max_size=256M, max_execution_time=180coverage:xdebugtools:php-cs-fixer, phpunit
Set up a PHP build with debugging symbols.
- Production release builds of PHP without debugging symbols are set up by default.
- You can use the
debugenvironment variable to set up a build with debugging symbols for PHP 5.6 and above.
Note
- On Linux, the debug symbols are added asdebug info files in the
/usr/lib/debug/.build-iddirectory. These files match thebuild-idin the ELF section of the PHP binaries and debugging tools likegdbare able to resolve the symbols from these files. - On Windows, the debug symbols are added as
pdbfiles in the PHP installation directory. - On macOS, the debug symbols are compiled into the binaries.
steps:-name:Setup PHP with debugging symbolsuses:shivammathur/setup-php@v2with:php-version:'8.5'env:debug:true# specify true or false
Set up
TSorNTSPHP.
NTSversions are set up by default.
jobs:run:runs-on:[ubuntu-latest, windows-latest, macos-latest]name:Setup PHP TSsteps: -name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'env:phpts:ts# specify ts or nts
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/phpis missing on the Ubuntu GitHub environment, the PHP version is updated to the latest patch release. - You can specify the
updateenvironment variable totruefor updating to the latest release.
-name:Setup PHP with latest versionsuses:shivammathur/setup-php@v2with:php-version:'8.5'env:update:true# specify true or false
Debug your workflow
To debug any issues, you can use theverbose tag instead ofv2.
-name:Setup PHP with logsuses:shivammathur/setup-php@verbosewith:php-version:'8.5'
Set up PHP on multiple architecture on Ubuntu GitHub Runners.
PHP 5.6toPHP 8.5are supported bysetup-phpon multiple architecture onUbuntuandDebian.- For this, you can use
shivammathur/nodeimages as containers. These have compatibleNodejsandPHPinstalled forsetup-php.
jobs:run:runs-on:${{ matrix.os }}container:shivammathur/node:php-${{ matrix.php-versions }}-24.04-${{ matrix.arch }}strategy:matrix:arch:["amd64", "arm64v8"]php-versions:[8.4, 8.5]include: -arch:"amd64"os:"ubuntu-24.04" -arch:"arm64v8"os:"ubuntu-24.04-arm"steps: -name:Install PHPuses:shivammathur/setup-php@v2with:php-version:${{ matrix.php-versions }}
Set up PHP on a self-hosted runner.
To set up a containerised self-hosted runner, refer to the following guides as per your base operating system.
To set up the runner directly on the host OS or in a virtual machine, follow thisrequirements guide before setting up the self-hosted runner.
If your workflow usesservice containers, then set up the runner on a Linux host or in a Linux virtual machine. GitHub Actions does not support nested virtualization on Linux, so services will not work in a dockerized container.
It is recommended to specify the environment variablerunner with the valueself-hosted for self-hosted environments.
jobs:run:runs-on:self-hostedstrategy: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', '8.5']name:PHP ${{ matrix.php-versions }}steps: -name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:${{ matrix.php-versions }}env:runner:self-hosted
Note
- Do not set up multiple self-hosted runners on a single server instance as parallel workflow will conflict with each other.
- Do not set up self-hosted runners on the side of your development environment or your production server.
- Avoid using the same labels for your
self-hostedrunners which are used byGitHub-hostedrunners.
Test your
Ubuntuworkflow locally usingnektos/act.
jobs:run:runs-on:ubuntu-lateststeps: -name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'
Run the workflow locally withact usingshivammathur/node docker images.
Choose the image tag which matches theruns-on property in your workflow. For example, if you are usingubuntu-22.04 in your workflow, runact -P ubuntu-22.04=shivammathur/node:22.04.
# For runs-on: ubuntu-latestact -P ubuntu-latest=shivammathur/node:latest# For runs-on: ubuntu-24.04act -P ubuntu-24.04=shivammathur/node:24.04# For runs-on: ubuntu-22.04act -P ubuntu-22.04=shivammathur/node:22.04
Enable Just-in-time (JIT) on PHP 8.0 and above.
- To enable JIT, enable
opcachein cli mode by settingopcache.enable_cli=1. - JIT conflicts with
Xdebug,PCOV, and other extensions which overridezend_execute_exfunction, so setcoverage: noneand disable any such extension if added. - By default,
opcache.jit=1235andopcache.jit_buffer_size=256M(opcache.jit_buffer_size=128Mon ARM-based environments) are set which can be changed usingini-valuesinput. - For detailed information about JIT related directives refer to the
official PHP documentation.
For example to enable JIT intracing mode with buffer size of64 MB.
-name:Setup PHP with JIT in tracing modeuses:shivammathur/setup-php@v2with:php-version:'8.5'coverage:noneini-values:opcache.enable_cli=1, opcache.jit=tracing, opcache.jit_buffer_size=64M
You can cache PHP extensions usingshivammathur/cache-extensions andaction/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 toshivammathur/cache-extensions for details.
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 directoryid:composer-cacherun:echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT-name:Cache dependenciesuses:actions/cache@v4with:path:${{ steps.composer-cache.outputs.dir }}key:${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}restore-keys:${{ runner.os }}-composer--name:Install dependenciesrun:composer install --prefer-dist
Note
- Please do not cache
vendordirectory usingaction/cacheas that will have side effects. - If you do not commit
composer.lock, you can use the hash ofcomposer.jsonas the key for your cache.
key:${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
- If you support a range of
composerdependencies and useprefer-lowestandprefer-stableoptions, you can store them in your matrix and add them to the keys.
key:${{ runner.os }}-composer-${{ matrix.prefer }}-${{ hashFiles('**/composer.lock') }}restore-keys:${{ runner.os }}-composer-${{ matrix.prefer }}-
By default, setup-php uses theGITHUB_TOKEN secret that is generated for each workflow run. In case you want to use a Personal Access Token (PAT) instead, you can set thegithub-token input.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'github-token:${{ secrets.YOUR_PAT_TOKEN }}
TheCOMPOSER_TOKEN andGITHUB_TOKEN environment variables have been deprecated in favor of thegithub-token input and will be removed in the next major version.
For GitHub Enterprise users, thegithub-token input does not default to theGITHUB_TOKEN secret. Therefore, it's recommended to set thegithub-token input to a Personal Access Token (PAT).
If you use Private Packagist for your private composer dependencies, you can set thePACKAGIST_TOKEN environment variable to authenticate.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'env:PACKAGIST_TOKEN:${{ secrets.PACKAGIST_TOKEN }}
In addition to GitHub or Private Packagist, if you want to authenticate private repositories hosted elsewhere, you can set theCOMPOSER_AUTH_JSON environment variable with the authentication methods and the credentials in json format.Please refer to the authentication section incomposer documentation for more details.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'env:COMPOSER_AUTH_JSON:| { "http-basic": { "example.org": { "username": "${{ secrets.EXAMPLE_ORG_USERNAME }}", "password": "${{ secrets.EXAMPLE_ORG_PASSWORD }}" } } }
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 asphp {0}.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'-name:Run PHP codeshell:php {0}run:| <?php $welcome = "Hello, world"; echo $welcome;
Problem matchers arejson 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.
Setup problem matchers for yourPHP output by adding this step after thesetup-php step.
-name:Setup problem matchers for PHPrun:echo "::add-matcher::${{ runner.tool_cache }}/php.json"
Setup problem matchers for yourPHPUnit output by adding this step after thesetup-php step.
-name:Setup problem matchers for PHPUnitrun:echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
PHPStan supports error reporting in GitHub Actions, so it does not require problem matchers.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'tools:phpstan-name:Run PHPStanrun:phpstan analyse src
Psalm supports error reporting in GitHub Actions with an output formatgithub.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'tools:psalm-name:Run Psalmrun:psalm --output-format=github
For tools that supportcheckstyle reporting likephpstan,psalm,php-cs-fixer andphpcs you can usecs2pr to annotate your code.
For examples refer to thecs2pr documentation.
Here is an example with
phpcs.
-name:Setup PHPuses:shivammathur/setup-php@v2with:php-version:'8.5'tools:cs2pr, phpcs-name:Run phpcsrun:phpcs -q --report=checkstyle src | cs2pr
Examples of usingsetup-php with various PHP frameworks and packages.
| Framework/Package | Runs on | Workflow |
|---|---|---|
| Blackfire | macOS,ubuntu andwindows | blackfire.yml |
| Blackfire Player | macOS,ubuntu andwindows | blackfire-player.yml |
CakePHP withMySQL andRedis | ubuntu | cakephp-mysql.yml |
CakePHP withPostgreSQL andRedis | ubuntu | cakephp-postgres.yml |
| CakePHP without services | macOS,ubuntu andwindows | cakephp.yml |
| CodeIgniter | macOS,ubuntu andwindows | codeigniter.yml |
| Laminas MVC | macOS,ubuntu andwindows | laminas-mvc.yml |
Laravel withMySQL andRedis | ubuntu | laravel-mysql.yml |
Laravel withPostgreSQL andRedis | ubuntu | laravel-postgres.yml |
| Laravel without services | macOS,ubuntu andwindows | laravel.yml |
Lumen withMySQL andRedis | ubuntu | lumen-mysql.yml |
Lumen withPostgreSQL andRedis | ubuntu | lumen-postgres.yml |
| Lumen without services | macOS,ubuntu andwindows | lumen.yml |
Phalcon withMySQL | ubuntu | phalcon-mysql.yml |
Phalcon withPostgreSQL | ubuntu | phalcon-postgres.yml |
| Roots/bedrock | ubuntu | bedrock.yml |
| Roots/sage | ubuntu | sage.yml |
| Slim Framework | macOS,ubuntu andwindows | slim-framework.yml |
Symfony withMySQL | ubuntu | symfony-mysql.yml |
Symfony withPostgreSQL | ubuntu | symfony-postgres.yml |
| Symfony without services | macOS,ubuntu andwindows | symfony.yml |
Yii2 Starter Kit withMySQL | ubuntu | yii2-mysql.yml |
Yii2 Starter Kit withPostgreSQL | ubuntu | yii2-postgres.yml |
- Use the
v2tag assetup-phpversion. It is a rolling tag and is synced with the latest minor and patch releases. Withv2you automatically get the bug fixes, security patches, new features and support for latest PHP releases. - Semantic release versions can also be used. It is recommended touse dependabot with semantic versioning to keep the actions in your workflows up to date.
- Commit SHA can also be used, but are not recommended unless you set up tooling to update them with each release of the action.
- A new major version of the action will only be tagged when there are breaking changes in the setup-php API i.e. inputs, outputs, and environment flags.
- For debugging any issues
verbosetag can be used temporarily. It outputs all the logs and is also synced with the latest releases. - It is highly discouraged to use the
mainbranch as version, it might break your workflow after major releases as they have breaking changes. - If you are using the
v1tag or a1.x.yversion, you shouldswitch to v2 asv1is not supported anymore.
- The scripts and documentation in this project are under theMIT License.
- This project has multipledependencies. Their licenses can be found in their respective repositories.
- The logo for
setup-phpis a derivative work ofphp.net logo and is licensed under theCC BY-SA 4.0 License.
Contributions are welcome!
- SeeContributor's Guide before you start.
- If you face any issues or want to suggest a feature/improvement, start a discussionhere.
Contributors ofsetup-php and other related projects
These companies generously provide setup-php their products and services to aid in the development of this project.
Many users and organizations support setup-php viaGitHub Sponsors.
- If you use setup-php, please consider starring the project and share it.
- If you blog, please share your experience of using
setup-php. - Pleasereach out if you have any questions about sponsoring setup-php.
- Node.js dependencies
- aaronparker/VcRedist
- mlocati/powershell-phpmanager
- ppa:ondrej/php
- shivammathur/cache-extensions
- shivammathur/composer-cache
- shivammathur/homebrew-extensions
- shivammathur/homebrew-php
- shivammathur/icu-intl
- shivammathur/php-builder
- shivammathur/php-builder-windows
- shivammathur/php-ubuntu
- shivammathur/php5-darwin
- shivammathur/php5-ubuntu
About
GitHub action to set up PHP with extensions, php.ini configuration, coverage drivers, and various tools.
Topics
Resources
License
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
Packages0
Uh oh!
There was an error while loading.Please reload this page.

