Merge pull request #61 from Yoast/develop

Release version 1.0.2

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0']
+        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1']
         phpunit: ['auto']
         experimental: [false]
 
@@ -51,7 +51,7 @@ jobs:
             experimental: false
 
           # Experimental builds.
-          - php: '8.1'
+          - php: '8.2'
             phpunit: 'auto'
             experimental: true
 
@@ -80,13 +80,13 @@ jobs:
 
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-composer-dependencies
-      - name: Install Composer dependencies for PHP < 8.1
-        if: ${{ matrix.php < 8.1 }}
+      - name: Install Composer dependencies for PHP < 8.2
+        if: ${{ matrix.php < 8.2 }}
         uses: "ramsey/composer-install@v1"
 
-      # For PHP 8.1 and above, we need to install with ignore platform reqs as not all dependencies allow it yet.
-      - name: Install Composer dependencies for PHP >= 8.1
-        if: ${{ matrix.php >= 8.1 }}
+      # For PHP 8.2 and above, we need to install with ignore platform reqs as not all dependencies allow it yet.
+      - name: Install Composer dependencies for PHP >= 8.2
+        if: ${{ matrix.php >= 8.2 }}
         uses: "ramsey/composer-install@v1"
         with:
           composer-options: --ignore-platform-reqs
@@ -104,4 +104,10 @@ jobs:
         run: composer lint-gte80
 
       - name: Run the unit tests
+        if: ${{ matrix.phpunit != '^10.0' }}
+        run: composer test
+
+      - name: Trial run the unit tests against PHPUnit 10.0
+        if: ${{ matrix.phpunit == '^10.0' }}
+        continue-on-error: true
         run: composer test

.phpcs.xml.dist

@@ -50,6 +50,7 @@
 		<exclude name="WordPress.Security"/>
 		<exclude name="WordPress.WP"/>
 		<exclude name="Yoast.Yoast.AlternativeFunctions"/>
+		<exclude name="Yoast.NamingConventions.ObjectNameDepth.MaxExceeded"/>
 	</rule>
 
 	<!-- While PHPCompatibility is already included in the Yoast ruleset, it uses
@@ -143,6 +144,7 @@
 	<!-- Covers annotations are in the test classes, not the trait. -->
 	<rule ref="Yoast.Commenting.TestsHaveCoversTag.Missing">
 		<exclude-pattern>/tests/TestCases/TestCaseTestTrait\.php$</exclude-pattern>
+		<exclude-pattern>/tests/Polyfills/Fixtures/*\.php$</exclude-pattern>
 	</rule>
 
 	<!-- These fixtures for the assertEqualObject() tests will only be loaded on PHP 7+/8+ respectively. -->

CHANGELOG.md

@@ -9,6 +9,25 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [1.0.2] - 2021-10-03
+
+As of version 2.15.0 of the `shivammathur/setup-php` action for GitHub Actions, the PHPUnit Polyfills can be installed directly from this action using the `tools` key.
+
+### Added
+* README: FAQ section about installing and using the library via the `shivammathur/setup-php` action. PR [#52]
+
+### Changed
+* README: minor textual clarifications and improvements. PRs [#52], [$54], props [Pierre Gordon].
+* General housekeeping.
+
+### Fixed
+* Autoloader: improved compatibility with packages which create a `class_alias` for the `PHPUnit_Runner_Version` or `PHPUnit\Runner\Version` class. PR [#59]
+
+[#52]: https://github.com/Yoast/PHPUnit-Polyfills/pull/52
+[#54]: https://github.com/Yoast/PHPUnit-Polyfills/pull/54
+[#59]: https://github.com/Yoast/PHPUnit-Polyfills/pull/59
+
+
 ## [1.0.1] - 2021-08-09
 
 ### Added
@@ -81,6 +100,7 @@ Initial release.
 
 
 [Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/main...HEAD
+[1.0.2]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.1...1.0.2
 [1.0.1]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.0...1.0.1
 [1.0.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.2.0...1.0.0
 [0.2.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.1.0...0.2.0
@@ -90,3 +110,5 @@ Initial release.
 [Marc Siegrist]: https://github.com/mergeMarc
 [Mark Baker]: https://github.com/MarkBaker
 [Pascal Birchler]: https://github.com/swissspidy
+[Pierre Gordon]: https://github.com/pierlon
+

README.md

@@ -46,6 +46,8 @@ To update this package, run:
 composer update --dev yoast/phpunit-polyfills --with-dependencies
 ```
 
+Make sure to either use the Composer `vendor/autoload.php` file _as_ your test bootstrap file; òr require the `vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php` file _in_ your test bootstrap.
+
 
 Why use the PHPUnit Polyfills?
 ------------------------------
@@ -688,6 +690,38 @@ Yes, this package can also be used when running tests via a PHPUnit Phar file.
 In that case, make sure that the `phpunitpolyfills-autoload.php` file is explicitly `require`d in the test bootstrap file.
 (Not necessary when the Composer `vendor/autoload.php` file is used as, or `require`d in, the test bootstrap.)
 
+
+### Q: How do I run my tests when the library is installed via the GitHub Actions `setup-php` action ?
+
+As of [shivammathur/setup-php](https://github.com/shivammathur/setup-php) version [2.15.0](https://github.com/shivammathur/setup-php/releases/tag/2.15.0), the PHPUnit Polyfills are available as one of the tools which can be installed directly by the Setup-PHP GitHub action.
+
+```yaml
+- name: Setup PHP with tools
+  uses: shivammathur/setup-php@v2
+  with:
+    php-version: '8.0'
+    tools: phpunit-polyfills
+```
+
+The above step will install both the PHPUnit Polyfills, as well as PHPUnit, as Composer global packages.
+
+After this step has run, you can run PHPUnit, like you would normally, by using `phpunit`.
+```yaml
+- name: Run tests
+  run: phpunit
+```
+
+:point_right: If you rely on Composer for autoloading your project files, you will still need to run `composer dump-autoload --dev` and include the project local `vendor/autoload.php` file as/in your test bootstrap.
+
+> :mortar_board: Why this works:
+>
+> Composer will place all files in the global Composer `bin` directory in the system path and the Composer installed PHPUnit version will load the Composer global `autoload.php` file, which will automatically also load the PHPUnit Polyfills.
+
+Now you may wonder, _"what about if I explicitly request both `phpunit` as well as `phpunit-polyfills` in `tools`?"_
+
+In that case, when you run `phpunit`, the PHPUnit PHAR will not know how to locate the PHPUnit Polyfills, so you will need to do some wizardry in your test bootstrap to get things working.
+
+
 ### Q: How can I verify the version used of the PHPUnit Polyfills library ?
 
 For complex test setups, like when the Polyfills are provided via a test suite dependency, or may already be loaded via an overarching project, it can be useful to be able to check that a version of the package is used which complies with the requirements for your test suite.
@@ -696,17 +730,19 @@ As of version 1.0.1, the PHPUnit Polyfills `Autoload` class contains a version n
 
 Typically such a check would be done in the test suite bootstrap file and could look something like this:
 ```php
-$versionRequirement = '1.0.1';
 if ( class_exists( '\Yoast\PHPUnitPolyfills\Autoload' ) === false ) {
-    require_once `vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php`;
-} elseif ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
+    require_once 'vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php';
+}
+
+$versionRequirement = '1.0.1';
+if ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
     || version_compare( \Yoast\PHPUnitPolyfills\Autoload::VERSION, $versionRequirement, '<' )
 ) {
     echo 'Error: Version mismatch detected for the PHPUnit Polyfills. Please ensure that PHPUnit Polyfills ',
         $versionRequirement, ' or higher is loaded.', PHP_EOL;
     exit(1);
 } else {
-    echo 'Error: Please run `composer update` before running the tests.' . PHP_EOL;
+    echo 'Error: Please run `composer update -W` before running the tests.' . PHP_EOL;
     echo 'You can still use a PHPUnit phar to run them, but the dependencies do need to be installed.', PHP_EOL;
     exit(1);
 }

composer.json

@@ -27,9 +27,7 @@
         "phpunit/phpunit": "^4.8.36 || ^5.7.21 || ^6.0 || ^7.0 || ^8.0 || ^9.0"
     },
     "require-dev": {
-        "php-parallel-lint/php-parallel-lint": "^1.3.0",
-        "php-parallel-lint/php-console-highlighter": "^0.5",
-        "yoast/yoastcs": "^2.1.0"
+        "yoast/yoastcs": "^2.2.0"
     },
     "autoload": {
         "files": ["phpunitpolyfills-autoload.php"]

phpunit.xml.dist

@@ -6,6 +6,7 @@
     bootstrap="./tests/bootstrap.php"
     beStrictAboutTestsThatDoNotTestAnything="true"
     colors="true"
+    convertDeprecationsToExceptions="true"
     forceCoversAnnotation="true">
 
     <testsuites>

phpunitpolyfills-autoload.php

@@ -3,6 +3,7 @@
 namespace Yoast\PHPUnitPolyfills;
 
 use PHPUnit\Runner\Version as PHPUnit_Version;
+use PHPUnit_Runner_Version;
 
 if ( \class_exists( 'Yoast\PHPUnitPolyfills\Autoload', false ) === false ) {
 
@@ -16,7 +17,7 @@ class Autoload {
 		 *
 		 * @var string
 		 */
-		const VERSION = '1.0.1';
+		const VERSION = '1.0.2';
 
 		/**
 		 * Loads a class.
@@ -426,9 +427,7 @@ public static function loadAssertObjectEquals() {
 		 * @return void
 		 */
 		public static function loadTestCase() {
-			if ( \class_exists( '\PHPUnit_Runner_Version' ) === true
-				|| \version_compare( PHPUnit_Version::id(), '8.0.0', '<' )
-			) {
+			if ( \version_compare( self::getPHPUnitVersion(), '8.0.0', '<' ) ) {
 				// PHPUnit < 8.0.0.
 				require_once __DIR__ . '/src/TestCases/TestCasePHPUnitLte7.php';
 				return;
@@ -444,7 +443,7 @@ public static function loadTestCase() {
 		 * @return void
 		 */
 		public static function loadTestListenerDefaultImplementation() {
-			if ( \class_exists( '\PHPUnit_Runner_Version' ) === true ) {
+			if ( \version_compare( self::getPHPUnitVersion(), '6.0.0', '<' ) ) {
 				/*
 				 * Alias one particular PHPUnit 4/5 class to its PHPUnit >= 6 name.
 				 *
@@ -474,6 +473,26 @@ public static function loadTestListenerDefaultImplementation() {
 			// PHPUnit >= 7.0.0.
 			require_once __DIR__ . '/src/TestListeners/TestListenerDefaultImplementationPHPUnitGte7.php';
 		}
+
+		/**
+		 * Retrieve the PHPUnit version id.
+		 *
+		 * As both the pre-PHPUnit 6 class, as well as the PHPUnit 6+ class contain the `id()` function,
+		 * this should work independently of whether or not another library may have aliased the class.
+		 *
+		 * @return string Version number as a string.
+		 */
+		public static function getPHPUnitVersion() {
+			if ( \class_exists( '\PHPUnit\Runner\Version' ) ) {
+				return PHPUnit_Version::id();
+			}
+
+			if ( \class_exists( '\PHPUnit_Runner_Version' ) ) {
+				return PHPUnit_Runner_Version::id();
+			}
+
+			return '0';
+		}
 	}
 
 	\spl_autoload_register( __NAMESPACE__ . '\Autoload::load' );