From 1dee067adc264a01d51b9d3be88515c4bdd7e035 Mon Sep 17 00:00:00 2001 From: Shivam Mathur Date: Wed, 19 Aug 2020 06:49:39 +0530 Subject: [PATCH] Update README --- README.md | 171 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 111 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 12abef44..53e9f9cd 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,13 @@

GitHub Actions status Codecov Code Coverage - LICENSE - PHP Versions Supported - setup-php twitter + 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](https://github.com/features/actions "GitHub Actions"). This action gives you a cross platform interface to setup the PHP environment you need to test your application. Refer to [Usage](#memo-usage "How to use this") section and [examples](#examples "Examples of use") to see how to use this. @@ -100,11 +104,12 @@ Both `GitHub-hosted` runners and `self-hosted` runners are supported on the foll - On `ubuntu` by default extensions which are available as a package can be installed. PECL extensions if not available as a package can be installed by specifying `pecl` in the tools input. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - tools: pecl - extensions: swoole +- name: Setup PHP with pecl extension + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + tools: pecl + extensions: swoole ``` - On `windows` PECL extensions which have the `DLL` binary can be installed. @@ -116,30 +121,43 @@ with: - Specific versions of PECL extensions can be installed by suffixing the version. This is useful for installing old versions of extensions which support end of life PHP versions. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '5.4' - tools: pecl - extensions: swoole-1.9.3 +- name: Setup PHP with specific version of PECL extension + uses: shivammathur/setup-php@v2 + with: + php-version: '5.4' + tools: pecl + extensions: swoole-1.9.3 ``` - Pre-release versions of PECL extensions can be setup by suffixing the extension with its state i.e `alpha`, `beta`, `devel` or `snapshot`. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - tools: pecl - extensions: xdebug-beta +- name: Setup PHP with pre-release PECL extension + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + tools: pecl + extensions: xdebug-beta ``` - Shared extensions can be removed by prefixing them with a `:`. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - extensions: :opcache +- name: Setup PHP and remove shared extension + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + extensions: :opcache +``` + +- Extension `intl` can be setup with specific `ICU` version for `PHP 5.6` to `PHP 7.4` in `Ubuntu` workflows by suffixing `intl` with the `ICU` version. `ICU 50.2` and newer versions are supported. Refer to [`ICU builds`](https://github.com/shivammathur/icu-intl#icu4c-builds) for the specific versions supported. + +```yaml +- name: Setup PHP with intl + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + extensions: intl-67.1 ``` - Extensions which cannot be added or removed gracefully leave an error message in the logs, the action is not interrupted. @@ -150,36 +168,42 @@ with: These tools can be setup globally using the `tools` input. -`blackfire`, `blackfire-player`, `codeception`, `composer`, `composer-normalize`, `composer-prefetcher`, `composer-require-checker`, `composer-unused`, `cs2pr`, `deployer`, `flex`, `grpc_php_plugin`, `infection`, `pecl`, `phan`, `phinx`, `phive`, `phpcbf`, `phpcpd`, `php-config`, `php-cs-fixer`, `phpcs`, `phpize`, `phpmd`, `phpstan`, `phpunit`, `prestissimo`, `protoc`, `psalm`, `symfony`, `vapor-cli` +`blackfire`, `blackfire-player`, `codeception`, `composer`, `composer-normalize`, `composer-prefetcher`, `composer-require-checker`, `composer-unused`, `cs2pr`, `deployer`, `flex`, `grpc_php_plugin`, `infection`, `pecl`, `phan`, `phing`, `phinx`, `phive`, `phpcbf`, `phpcpd`, `php-config`, `php-cs-fixer`, `phpcs`, `phpize`, `phpmd`, `phpstan`, `phpunit`, `prestissimo`, `protoc`, `psalm`, `symfony`, `vapor-cli` ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - tools: php-cs-fixer, phpunit +- name: Setup PHP with tools + 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`. Latest stable version of `composer` is setup by default. You can setup the required version by specifying `v1`, `v2`, `snapshot` or `preview` as version. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - tools: composer:v2 +- name: Setup PHP with composer v2 + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + tools: composer:v2 ``` -Version for other tools should be in `semver` format and a valid release of the tool. +Latest versions of both agent `blackfire-agent` and client `blackfire` are setup when `blackfire` is specified in tools input. Please refer to the [official documentation](https://blackfire.io/docs/integrations/ci/github-actions "Blackfire.io documentation for GitHub Actions") for using `blackfire` with GitHub Actions. + +Version for other tools should be in `semver` format and a valid release of the tool. +This is useful for installing tools for older versions of PHP. +For example to setup `PHPUnit` on `PHP 7.2`. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - tools: php-cs-fixer:2.16.2, phpunit:8.5.1 +- name: Setup PHP with tools + uses: shivammathur/setup-php@v2 + with: + php-version: '7.2' + tools: phpunit:8.5.8 ``` **Notes** -- Latest versions of both agent `blackfire-agent` and client `blackfire` are setup when `blackfire` is specified in tools input. - If you have a tool in your `composer.json`, do not setup it globally using this action as the two instances of the tool might conflict. - Tools which cannot be setup gracefully leave an error message in the logs, the action is not interrupted. @@ -191,10 +215,11 @@ Specify `coverage: xdebug` to use `Xdebug`. Runs on all [PHP versions supported](#tada-php-support "List of PHP versions supported on this GitHub Action"). ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - coverage: xdebug +- name: Setup PHP with Xdebug + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + coverage: xdebug ``` ### PCOV @@ -205,11 +230,23 @@ Tests with `PCOV` run much faster than with `Xdebug`. If your source code directory is other than `src`, `lib` or, `app`, specify `pcov.directory` using the `ini-values` input. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - ini-values: pcov.directory=api #optional, see above for usage. - coverage: pcov +- name: Setup PHP with PCOV + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + ini-values: pcov.directory=api #optional, see above for usage. + coverage: pcov +``` + +`PHPUnit` 8 and above supports `PCOV` out of the box. +If you are using `PHPUnit` 5, 6 or 7, you will need `krakjoe/pcov-clobber`. +Before executing your tests add the following step. + +```yaml +- name: Setup PCOV + run: | + composer require pcov/clobber + vendor/bin/pcov clobber ``` ### Disable Coverage @@ -223,10 +260,11 @@ Consider disabling the coverage using this PHP action for these reasons. - You are profiling your code using `blackfire`. ```yaml -uses: shivammathur/setup-php@v2 -with: - php-version: '7.4' - coverage: none +- name: Setup PHP with no coverage driver + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + coverage: none ``` ## :memo: Usage @@ -326,7 +364,7 @@ steps: - name: Checkout uses: actions/checkout@v2 -- name: Setup PHP +- name: Setup nightly PHP uses: shivammathur/setup-php@v2 with: php-version: '8.0' @@ -438,7 +476,7 @@ jobs: - You can specify the `update` environment variable to `true` to force update to the latest release. ```yaml -- name: Setup PHP +- name: Setup PHP with latest versions uses: shivammathur/setup-php@v2 with: php-version: '7.4' @@ -453,7 +491,7 @@ jobs: To debug any issues, you can use the `verbose` tag instead of `v2`. ```yaml -- name: Setup PHP +- name: Setup PHP with logs uses: shivammathur/setup-php@verbose with: php-version: '7.4' @@ -613,21 +651,33 @@ Examples of using `setup-php` with various PHP Frameworks and Packages. - See [Contributor's Guide](.github/CONTRIBUTING.md "shivammathur/setup-php contribution guide") before you start. - If you face any issues while using this or want to suggest a feature/improvement, create an issue [here](https://github.com/shivammathur/setup-php/issues "Issues reported"). +*Join the list of setup-php contributors* + +

+ + setup-php contributers + +

+ ## :sparkling_heart: Support This Project - Please star the project and share it. If you blog, please share your experience of using this action. -- Please consider supporting our work by sponsoring using [Paypal](https://www.paypal.me/shivammathur "Shivam Mathur PayPal") or by subscribing on [Patreon](https://www.patreon.com/shivammathur "Shivam Mathur Patreon"). +- Please consider supporting our work by sponsoring using [Open Collective](https://opencollective.com/setup-php), [Paypal](https://www.paypal.me/shivammathur "Shivam Mathur PayPal") or [Patreon](https://www.patreon.com/shivammathur "Shivam Mathur Patreon"). - If you use `setup-php` at your company, please [reach out](mailto:contact@setup-php.com) to sponsor the project. *Huge thanks to the following companies for supporting `setup-php`* -

+

- JetBrains - - spacer - - Tidelift + JetBrains + +           + + Blackfire + +           + + Tidelift

@@ -641,6 +691,7 @@ Examples of using `setup-php` with various PHP Frameworks and Packages. - [shivammathur/composer-cache](https://github.com/shivammathur/composer-cache "Cache composer releases") - [shivammathur/homebrew-extensions](https://github.com/shivammathur/homebrew-extensions "Tap for PHP extensions on MacOS") - [shivammathur/homebrew-php](https://github.com/shivammathur/homebrew-php "Tap for PHP builds on MacOS") +- [shivammathur/icu-intl](https://github.com/shivammathur/icu-intl "icu4c and php-intl builds") - [shivammathur/php-builder](https://github.com/shivammathur/php-builder "Nightly PHP package for Ubuntu") - [shivammathur/php-builder-windows](https://github.com/shivammathur/php-builder-windows "Nightly PHP package for Windows") - [shivammathur/php-ubuntu](https://github.com/shivammathur/php-ubuntu "Cache stable PHP Packages for Ubuntu")