Add custom autoloader/fall-through to PHPUnit native functionality

This commit:
* Adds a custom autoloader which will either load the polyfills or will load "empty" replacements for the classes in this package which will fall through to using the PHPUnit native functionality for PHPUnit 4.x - 8.x.
* Widens the version requirements for PHP and PHPUnit to allow installing of this package on PHP 5.4 - current in combination with PHPUnit 4.8.36/5.7.21 - current.
* Updates the `autoload` section in the `composer.json` to load the custom autoloader instead of using PSR4 autoloading.
* Makes a few select exceptions to the coding standards for the custom autoloader and the "fall through" files for CS rules which require a higher minimum PHP version.
    - `strict_types` is only available as of PHP 7.0.
    - scalar type declarations and return types are only available as of PHP 7.0, with `void` only being available as of PHP 7.1.
    - Importing functions and constants with `use` statements is only available as of PHP 5.6.
* Updates the README with information about the fact that the package no longer restrict installation to PHPUnit 9.

Author: jrfnl

README.md

@@ -13,6 +13,15 @@ Simply use it by importing it with Composer
 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.
+
+
 ## Usage
 
 You have two options to use this in your classes: either directly as a static call or as a trait if you wish to keep existing references working.

assertarraysubset-autoload.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace DMS\PHPUnitExtensions\ArraySubset;
+
+if (\class_exists('DMS\PHPUnitExtensions\ArraySubset\Autoload', false) === false) {
+
+    /**
+     * Custom autoloader.
+     *
+     * {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}
+     */
+    class Autoload
+    {
+        /**
+         * Loads a class.
+         *
+         * @param string $className The name of the class to load.
+         *
+         * @return bool
+         */
+        public static function load($className)
+        {
+            // Only load classes belonging to this library.
+            if (\stripos($className, 'DMS\PHPUnitExtensions\ArraySubset') !== 0) {
+                return false;
+            }
+
+            switch ($className) {
+                case 'DMS\PHPUnitExtensions\ArraySubset\ArraySubsetAsserts':
+                    if (\method_exists('\PHPUnit\Framework\Assert', 'assertArraySubset') === false) {
+                        // PHPUnit >= 9.0.0.
+                        require_once __DIR__ . '/src/ArraySubsetAsserts.php';
+
+                        // Straight away load the other classes needed as well.
+                        // These should only ever be loaded in this context anyway.
+                        require_once __DIR__ . '/src/ArrayAccessible.php';
+                        require_once __DIR__ . '/src/Constraint/ArraySubset.php';
+
+                        return true;
+                    }
+
+                    // PHPUnit < 9.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.
+                        require_once __DIR__ . '/src/Assert.php';
+
+                        return true;
+                    }
+
+                    // PHPUnit < 9.0.0.
+                    require_once __DIR__ . '/src/AssertFallThrough.php';
+
+                    return true;
+            }
+
+            return false;
+        }
+    }
+
+    \spl_autoload_register(__NAMESPACE__ . '\Autoload::load');
+}

composer.json

@@ -3,8 +3,8 @@
     "description": "This package provides ArraySubset and related asserts once deprecated in PHPUnit 8",
     "type": "library",
     "require": {
-        "phpunit/phpunit": "^9.0",
-        "php": "^7.3|^7.4|^8.0"
+        "phpunit/phpunit": "^4.8.36 || ^5.7.21 || ^6.0 || ^7.0 || ^8.0 || ^9.0",
+        "php": "^5.4 || ^7.0 || ^8.0"
     },
     "license": "MIT",
     "authors": [
@@ -18,9 +18,7 @@
         "dms/coding-standard": "^8"
     },
     "autoload": {
-        "psr-4": {
-            "DMS\\PHPUnitExtensions\\ArraySubset\\": "src"
-        }
+        "files": ["assertarraysubset-autoload.php"]
     },
     "autoload-dev": {
         "psr-4": {

composer.lock

@@ -7,6 +7,7 @@
     <arg name="cache" value=".phpcs.cache" /> <!-- cache the results and don't commit them -->
     <arg value="np" /> <!-- n = ignore warnings, p = show progress -->
 
+    <file>assertarraysubset-autoload.php</file>
     <file>src</file>
     <file>tests</file>
 
@@ -15,6 +16,30 @@
     </rule>
 
     <rule ref="SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedEqualOperator">
-        <exclude-pattern>src/Constraint/ArraySubset.php</exclude-pattern>
+        <exclude-pattern>src/Constraint/ArraySubset\.php</exclude-pattern>
     </rule>
+
+    <!-- BC-layer: exclude rules which would prevent code from being PHP cross-version compatible. -->
+    <rule ref="Squiz.Classes.ClassFileName.NoMatch">
+        <exclude-pattern>assertarraysubset-autoload\.php</exclude-pattern>
+        <exclude-pattern>src/ArraySubsetAssertsEmpty\.php</exclude-pattern>
+        <exclude-pattern>src/AssertFallThrough\.php</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.DeclareStrictTypes.DeclareStrictTypesMissing">
+        <exclude-pattern>assertarraysubset-autoload\.php</exclude-pattern>
+        <exclude-pattern>src/ArraySubsetAssertsEmpty\.php</exclude-pattern>
+        <exclude-pattern>src/AssertFallThrough\.php</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.ReferenceViaFullyQualifiedName">
+        <exclude-pattern>assertarraysubset-autoload\.php</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint">
+        <exclude-pattern>assertarraysubset-autoload\.php</exclude-pattern>
+        <exclude-pattern>src/AssertFallThrough\.php</exclude-pattern>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint">
+        <exclude-pattern>assertarraysubset-autoload\.php</exclude-pattern>
+        <exclude-pattern>src/AssertFallThrough\.php</exclude-pattern>
+    </rule>
+
 </ruleset>

phpcs.xml.dist

@@ -0,0 +1,15 @@
+<?php
+
+namespace DMS\PHPUnitExtensions\ArraySubset;
+
+/**
+ * ArraySubsetAsserts trait for use with PHPUnit 4.x - 8.x.
+ *
+ * As this trait is empty, calls to `assertArraySubset()` will automatically fall through
+ * to PHPUnit itself and will use the PHPUnit native `assertArraySubset()` method.
+ *
+ * {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}
+ */
+trait ArraySubsetAsserts
+{
+}

src/ArraySubsetAssertsEmpty.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace DMS\PHPUnitExtensions\ArraySubset;
+
+use PHPUnit\Framework\Assert as PhpUnitAssert;
+
+/**
+ * Assert class for use with PHPUnit 4.x - 8.x.
+ *
+ * The method in this class will fall through to PHPUnit itself and use the PHPUnit
+ * native `assertArraySubset()` method.
+ *
+ * {@internal The code in this file must be PHP cross-version compatible for PHP 5.4 - current!}
+ */
+final class Assert
+{
+    /**
+     * Asserts that an array has a specified subset.
+     *
+     * @param array|ArrayAccess|mixed[] $subset
+     * @param array|ArrayAccess|mixed[] $array
+     * @param bool                      $checkForObjectIdentity
+     * @param string                    $message
+     *
+     * @throws ExpectationFailedException
+     * @throws InvalidArgumentException
+     * @throws Exception
+     */
+    public static function assertArraySubset($subset, $array, $checkForObjectIdentity = false, $message = '')
+    {
+        PhpUnitAssert::assertArraySubset($subset, $array, $checkForObjectIdentity, $message);
+    }
+}