Allow the polyfill to kick in with PHPUnit 8.x

jrfnl · jrfnl · commit e0f7d2576833 · 2021-12-27T23:01:09.000+01:00
PHPUnit 8.x deprecated the `assertArraySubset()` functionality, PHPUnit 9.x removed it.

Up to now, this package would only "kick in" in combination with PHPUnit 9.x to polyfill the functionality.

The combined changes in this commit will allow for this package to also "kick in" in combination with PHPUnit 8.x, preventing the PHPUnit native deprecation for using `assertArraySubset()` from being thrown.

This commit also includes CI changes to safeguard the correct functioning of the code when used with PHPUnit 8.x.

Notes:
* The main change is in the autoloader, most other files only contain changed annotations.
* The only functional change needed was a work-around for the PHPUnit `InvalidArgumentException`, which was only introduced in PHPUnit 8.4.0.
* This commit does change the minimum PHP version code within the actual polyfill has to be compatible with.
    Previously, the code has to be compatible with PHP 7.3 and higher (minimum supported PHP version for PHPUnit 9.x).
    Now, the code has to be compatible with PHP **7.2** and higher (minimum supported PHP version for PHPUnit 8.x).

Fixes 50
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -24,6 +24,9 @@ jobs:
         experimental: [false]
 
         include:
+          - php: '7.2'
+            dependency-version: 'prefer-lowest'
+            experimental: false
           - php: '7.3'
             dependency-version: 'prefer-lowest'
             experimental: false
@@ -58,9 +61,13 @@ jobs:
     - name: 'Composer: remove CS dependency'
       run: composer remove --dev --no-update dms/coding-standard
 
-    - name: 'Composer: update PHPUnit for testing lowest'
-      if: ${{ matrix.dependency-version == 'prefer-lowest' }}
-      run: composer require --no-update phpunit/phpunit:"^9.0"
+    - name: 'Composer: update PHPUnit for testing lowest (PHP 7.2)'
+      if: ${{ matrix.dependency-version == 'prefer-lowest' && matrix.php == '7.2' }}
+      run: composer require --no-update phpunit/phpunit:"^8.0" --no-interaction
+
+    - name: 'Composer: update PHPUnit for testing lowest (PHP 7.3+)'
+      if: ${{ matrix.dependency-version == 'prefer-lowest' && matrix.php != '7.2' }}
+      run: composer require --no-update phpunit/phpunit:"^9.0" --no-interaction
 
     - name: Install dependencies - normal
       if: ${{ matrix.php < 8.1 }}
diff --git a/README.md b/README.md
@@ -15,11 +15,9 @@ composer require --dev dms/phpunit-arraysubset-asserts
 
 > :bulb: The package can be safely required on PHP 5.4 to current in combination with PHPUnit 4.8.36/5.7.21 to current.
 >
-> When the PHPUnit `assertArraySubset()` method is natively available (PHPUnit 4.x - 8.x), the PHPUnit native functionality will be used.
-> For PHPUnit 9 and higher, the extension will kick in and polyfill the functionality which was removed from PHPUnit.
->
-> Note: PHPUnit 8.x will show deprecation notices about the use of the `assertArraySubset()` method.
-> With this extension in place, those can be safely ignored.
+> When the PHPUnit `assertArraySubset()` method is natively available and not deprecated (PHPUnit 4.x - 7.x),
+> the PHPUnit native functionality will be used.
+> For PHPUnit 8 and higher, the extension will kick in and polyfill the functionality which was removed from PHPUnit.
 
 
 ## Usage
diff --git a/assertarraysubset-autoload.php b/assertarraysubset-autoload.php
@@ -2,6 +2,9 @@
 
 namespace DMS\PHPUnitExtensions\ArraySubset;
 
+use PHPUnit\Runner\Version as PHPUnit_Version;
+use PHPUnit_Runner_Version;
+
 if (\class_exists('DMS\PHPUnitExtensions\ArraySubset\Autoload', false) === false) {
 
     /**
@@ -25,49 +28,51 @@ public static function load($className)
                 return false;
             }
 
+            $loadPolyfill = \version_compare(self::getPHPUnitVersion(), '8.0.0', '>=');
+
             switch ($className) {
                 case 'DMS\PHPUnitExtensions\ArraySubset\ArraySubsetAsserts':
-                    if (\method_exists('\PHPUnit\Framework\Assert', 'assertArraySubset') === false) {
-                        // PHPUnit >= 9.0.0.
+                    if ($loadPolyfill === true) {
+                        // PHPUnit >= 8.0.0.
                         require_once __DIR__ . '/src/ArraySubsetAsserts.php';
 
                         return true;
                     }
 
-                    // PHPUnit < 9.0.0.
+                    // PHPUnit < 8.0.0.
                     require_once __DIR__ . '/src/ArraySubsetAssertsEmpty.php';
 
                     return true;
 
                 case 'DMS\PHPUnitExtensions\ArraySubset\Assert':
-                    if (\method_exists('\PHPUnit\Framework\Assert', 'assertArraySubset') === false) {
-                        // PHPUnit >= 9.0.0.
+                    if ($loadPolyfill === true) {
+                        // PHPUnit >= 8.0.0.
                         require_once __DIR__ . '/src/Assert.php';
 
                         return true;
                     }
 
-                    // PHPUnit < 9.0.0.
+                    // PHPUnit < 8.0.0.
                     require_once __DIR__ . '/src/AssertFallThrough.php';
 
                     return true;
 
                 /*
-                 * Handle arbitrary additional classes via PSR-4, but only allow loading on PHPUnit >= 9.0.0,
-                 * as additional classes should only ever _need_ to be loaded when using PHPUnit >= 9.0.0.
+                 * Handle arbitrary additional classes via PSR-4, but only allow loading on PHPUnit >= 8.0.0,
+                 * as additional classes should only ever _need_ to be loaded when using PHPUnit >= 8.0.0.
                  */
                 default:
-                    if (\method_exists('\PHPUnit\Framework\Assert', 'assertArraySubset') === true) {
+                    if ($loadPolyfill === false) {
                         // PHPUnit < 9.0.0.
                         throw new \RuntimeException(
                             \sprintf(
-                                'Using class "%s" is only supported in combination with PHPUnit >= 9.0.0',
+                                'Using class "%s" is only supported in combination with PHPUnit >= 8.0.0',
                                 $className
                             )
                         );
                     }
 
-                    // PHPUnit >= 9.0.0.
+                    // PHPUnit >= 8.0.0.
                     $file = \realpath(
                         __DIR__ . \DIRECTORY_SEPARATOR
                         . 'src' . \DIRECTORY_SEPARATOR
@@ -83,6 +88,27 @@ public static function load($className)
 
             return false;
         }
+
+        /**
+         * 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');
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
@@ -16,7 +16,7 @@
     <testsuites>
         <testsuite name="unit">
             <directory>tests/Availability</directory>
-            <directory phpVersion="7.3.0" phpVersionOperator=">=">tests/Unit</directory>
+            <directory phpVersion="7.2.0" phpVersionOperator=">=">tests/Unit</directory>
         </testsuite>
     </testsuites>
 
diff --git a/src/ArraySubsetAsserts.php b/src/ArraySubsetAsserts.php
@@ -10,7 +10,9 @@
 use PHPUnit\Framework\Assert as PhpUnitAssert;
 use PHPUnit\Framework\ExpectationFailedException;
 use PHPUnit\Framework\InvalidArgumentException;
+use PHPUnit\Util\InvalidArgumentHelper;
 
+use function class_exists;
 use function is_array;
 
 trait ArraySubsetAsserts
@@ -22,20 +24,38 @@ trait ArraySubsetAsserts
      * @param array|ArrayAccess|mixed[] $array
      *
      * @throws ExpectationFailedException
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException|Exception
      * @throws Exception
      */
     public static function assertArraySubset($subset, $array, bool $checkForObjectIdentity = false, string $message = ''): void
     {
         if (! (is_array($subset) || $subset instanceof ArrayAccess)) {
-            throw InvalidArgumentException::create(
+            if (class_exists(InvalidArgumentException::class)) {
+                // PHPUnit 8.4.0+.
+                throw InvalidArgumentException::create(
+                    1,
+                    'array or ArrayAccess'
+                );
+            }
+
+            // PHPUnit < 8.4.0.
+            throw InvalidArgumentHelper::factory(
                 1,
                 'array or ArrayAccess'
             );
         }
 
         if (! (is_array($array) || $array instanceof ArrayAccess)) {
-            throw InvalidArgumentException::create(
+            if (class_exists(InvalidArgumentException::class)) {
+                // PHPUnit 8.4.0+.
+                throw InvalidArgumentException::create(
+                    2,
+                    'array or ArrayAccess'
+                );
+            }
+
+            // PHPUnit < 8.4.0.
+            throw InvalidArgumentHelper::factory(
                 2,
                 'array or ArrayAccess'
             );
diff --git a/src/ArraySubsetAssertsEmpty.php b/src/ArraySubsetAssertsEmpty.php
@@ -3,7 +3,7 @@
 namespace DMS\PHPUnitExtensions\ArraySubset;
 
 /**
- * ArraySubsetAsserts trait for use with PHPUnit 4.x - 8.x.
+ * ArraySubsetAsserts trait for use with PHPUnit 4.x - 7.x.
  *
  * As this trait is empty, calls to `assertArraySubset()` will automatically fall through
  * to PHPUnit itself and will use the PHPUnit native `assertArraySubset()` method.
diff --git a/src/AssertFallThrough.php b/src/AssertFallThrough.php
@@ -5,7 +5,7 @@
 use PHPUnit\Framework\Assert as PhpUnitAssert;
 
 /**
- * Assert class for use with PHPUnit 4.x - 8.x.
+ * Assert class for use with PHPUnit 4.x - 7.x.
  *
  * The method in this class will fall through to PHPUnit itself and use the PHPUnit
  * native `assertArraySubset()` method.
@@ -23,7 +23,7 @@ final class Assert
      * @param string                    $message
      *
      * @throws ExpectationFailedException
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException|Exception
      * @throws Exception
      */
     public static function assertArraySubset($subset, $array, $checkForObjectIdentity = false, $message = '')
diff --git a/src/Constraint/ArraySubset.php b/src/Constraint/ArraySubset.php
@@ -61,7 +61,7 @@ public function __construct(iterable $subset, bool $strict = false)
      * @return mixed[]|bool|null
      *
      * @throws ExpectationFailedException
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException|Exception
      */
     public function evaluate($other, string $description = '', bool $returnResult = false): ?bool
     {
@@ -103,7 +103,7 @@ public function evaluate($other, string $description = '', bool $returnResult =
     /**
      * Returns a string representation of the constraint.
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException|Exception
      */
     public function toString(): string
     {
@@ -118,7 +118,7 @@ public function toString(): string
      *
      * @param mixed $other evaluated value or object
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException|Exception
      */
     protected function failureDescription($other): string
     {
diff --git a/tests/Availability/AutoloadExceptionTest.php b/tests/Availability/AutoloadExceptionTest.php
@@ -6,22 +6,22 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- * Testing that autoloading classes which should only ever be loaded on PHPUnit >= 9 will
- * generate an exception when attempted on PHPUnit < 9..
+ * Testing that autoloading classes which should only ever be loaded on PHPUnit >= 8 will
+ * generate an exception when attempted on PHPUnit < 8.
  *
- * Note: the autoloading in combination with PHPUnit 9+ is automatically tested via the
+ * Note: the autoloading in combination with PHPUnit 8+ is automatically tested via the
  * actual tests for the polyfill as the class will be called upon.
  *
  * {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}
  *
- * @requires PHPUnit < 9
+ * @requires PHPUnit < 8
  */
 final class AutoloadExceptionTest extends TestCase
 {
     public function testAutoloadException()
     {
         $expection = '\RuntimeException';
-        $message   = 'Using class "DMS\PHPUnitExtensions\ArraySubset\Constraint\ArraySubset" is only supported in combination with PHPUnit >= 9.0.0';
+        $message   = 'Using class "DMS\PHPUnitExtensions\ArraySubset\Constraint\ArraySubset" is only supported in combination with PHPUnit >= 8.0.0';
 
         if (\method_exists('\PHPUnit\Framework\TestCase', 'expectException') === true) {
             $this->expectException($expection);
diff --git a/tests/Availability/AvailibilityViaClassTest.php b/tests/Availability/AvailibilityViaClassTest.php
@@ -6,7 +6,7 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- * Testing that the autoloading of the fall-through `Assert` class for PHPUnit 4.x - 8.x works correctly.
+ * Testing that the autoloading of the fall-through `Assert` class for PHPUnit 4.x - 7.x works correctly.
  *
  * {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}
  */
diff --git a/tests/Availability/AvailibilityViaTraitTest.php b/tests/Availability/AvailibilityViaTraitTest.php
@@ -6,7 +6,7 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- * Testing that the autoloading of the empty `ArraySubsetAsserts` trait for PHPUnit 4.x - 8.x works correctly.
+ * Testing that the autoloading of the empty `ArraySubsetAsserts` trait for PHPUnit 4.x - 7.x works correctly.
  *
  * {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}
  */
diff --git a/tests/Unit/AssertTest.php b/tests/Unit/AssertTest.php
@@ -10,7 +10,7 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- * @requires PHPUnit >= 9
+ * @requires PHPUnit >= 8
  */
 final class AssertTest extends TestCase
 {
diff --git a/tests/Unit/Constraint/ArraySubsetTest.php b/tests/Unit/Constraint/ArraySubsetTest.php
@@ -18,7 +18,7 @@
 use function sprintf;
 
 /**
- * @requires PHPUnit >= 9
+ * @requires PHPUnit >= 8
  */
 final class ArraySubsetTest extends TestCase
 {
@@ -60,7 +60,7 @@ public static function evaluateDataProvider(): array
      * @param array|Traversable|mixed[] $other
      *
      * @throws ExpectationFailedException
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException|Exception
      *
      * @dataProvider evaluateDataProvider
      */

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`namespace DMS\PHPUnitExtensions\ArraySubset;`
`4`	`4`
`5`	`5`	`/**`
`6`		`- * ArraySubsetAsserts trait for use with PHPUnit 4.x - 8.x.`
	`6`	`+ * ArraySubsetAsserts trait for use with PHPUnit 4.x - 7.x.`
`7`	`7`	`*`
`8`	`8`	* As this trait is empty, calls to `assertArraySubset()` will automatically fall through
`9`	`9`	* to PHPUnit itself and will use the PHPUnit native `assertArraySubset()` method.
Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ public function __construct(iterable $subset, bool $strict = false)`
`61`	`61`	`* @return mixed[]\|bool\|null`
`62`	`62`	`*`
`63`	`63`	`* @throws ExpectationFailedException`
`64`		`- * @throws InvalidArgumentException`
	`64`	`+ * @throws InvalidArgumentException\|Exception`
`65`	`65`	`*/`
`66`	`66`	`public function evaluate($other, string $description = '', bool $returnResult = false): ?bool`
`67`	`67`	`{`
`@@ -103,7 +103,7 @@ public function evaluate($other, string $description = '', bool $returnResult =`
`103`	`103`	`/**`
`104`	`104`	`* Returns a string representation of the constraint.`
`105`	`105`	`*`
`106`		`- * @throws InvalidArgumentException`
	`106`	`+ * @throws InvalidArgumentException\|Exception`
`107`	`107`	`*/`
`108`	`108`	`public function toString(): string`
`109`	`109`	`{`
`@@ -118,7 +118,7 @@ public function toString(): string`
`118`	`118`	`*`
`119`	`119`	`* @param mixed $other evaluated value or object`
`120`	`120`	`*`
`121`		`- * @throws InvalidArgumentException`
	`121`	`+ * @throws InvalidArgumentException\|Exception`
`122`	`122`	`*/`
`123`	`123`	`protected function failureDescription($other): string`
`124`	`124`	`{`
Original file line number	Diff line number	Diff line change
`@@ -6,22 +6,22 @@`
`6`	`6`	`use PHPUnit\Framework\TestCase;`
`7`	`7`
`8`	`8`	`/**`
`9`		`- * Testing that autoloading classes which should only ever be loaded on PHPUnit >= 9 will`
`10`		`- * generate an exception when attempted on PHPUnit < 9..`
	`9`	`+ * Testing that autoloading classes which should only ever be loaded on PHPUnit >= 8 will`
	`10`	`+ * generate an exception when attempted on PHPUnit < 8.`
`11`	`11`	`*`
`12`		`- * Note: the autoloading in combination with PHPUnit 9+ is automatically tested via the`
	`12`	`+ * Note: the autoloading in combination with PHPUnit 8+ is automatically tested via the`
`13`	`13`	`* actual tests for the polyfill as the class will be called upon.`
`14`	`14`	`*`
`15`	`15`	`* {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}`
`16`	`16`	`*`
`17`		`- * @requires PHPUnit < 9`
	`17`	`+ * @requires PHPUnit < 8`
`18`	`18`	`*/`
`19`	`19`	`final class AutoloadExceptionTest extends TestCase`
`20`	`20`	`{`
`21`	`21`	`public function testAutoloadException()`
`22`	`22`	`{`
`23`	`23`	`$expection = '\RuntimeException';`
`24`		`- $message = 'Using class "DMS\PHPUnitExtensions\ArraySubset\Constraint\ArraySubset" is only supported in combination with PHPUnit >= 9.0.0';`
	`24`	`+ $message = 'Using class "DMS\PHPUnitExtensions\ArraySubset\Constraint\ArraySubset" is only supported in combination with PHPUnit >= 8.0.0';`
`25`	`25`
`26`	`26`	`if (\method_exists('\PHPUnit\Framework\TestCase', 'expectException') === true) {`
`27`	`27`	`$this->expectException($expection);`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`use PHPUnit\Framework\TestCase;`
`7`	`7`
`8`	`8`	`/**`
`9`		- * Testing that the autoloading of the fall-through `Assert` class for PHPUnit 4.x - 8.x works correctly.
	`9`	+ * Testing that the autoloading of the fall-through `Assert` class for PHPUnit 4.x - 7.x works correctly.
`10`	`10`	`*`
`11`	`11`	`* {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}`
`12`	`12`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@`
`10`	`10`	`use PHPUnit\Framework\TestCase;`
`11`	`11`
`12`	`12`	`/**`
`13`		`- * @requires PHPUnit >= 9`
	`13`	`+ * @requires PHPUnit >= 8`
`14`	`14`	`*/`
`15`	`15`	`final class AssertTest extends TestCase`
`16`	`16`	`{`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@`
`18`	`18`	`use function sprintf;`
`19`	`19`
`20`	`20`	`/**`
`21`		`- * @requires PHPUnit >= 9`
	`21`	`+ * @requires PHPUnit >= 8`
`22`	`22`	`*/`
`23`	`23`	`final class ArraySubsetTest extends TestCase`
`24`	`24`	`{`
`@@ -60,7 +60,7 @@ public static function evaluateDataProvider(): array`
`60`	`60`	`* @param array\|Traversable\|mixed[] $other`
`61`	`61`	`*`
`62`	`62`	`* @throws ExpectationFailedException`
`63`		`- * @throws InvalidArgumentException`
	`63`	`+ * @throws InvalidArgumentException\|Exception`
`64`	`64`	`*`
`65`	`65`	`* @dataProvider evaluateDataProvider`
`66`	`66`	`*/`