Composer/GH Actions: allow for PHPUnit 11.x

PHPUnit 11.0 has been released on Feb 2, 2024.

As the PHPUnit Polyfills, as of now, will officially support PHPUnit 11.x (with the exception of the TestListeners), the GH Actions workflow should be updated to reflect this.

This commit:
* Allows for PHPUnit 11 in the `composer.json` `require`.
* Add builds for PHP 8.2 and 8.3 against low PHPUnit 11 versions for the Composer based tests.
    The "high" versions are automatically sorted via the matrix `auto` setting in combination with the Composer PHPUnit version requirements being widened.
* Add builds for PHP 8.2 and 8.3 against high/low PHPUnit 11 for the PHAR based tests.
* Add an extra experimental build in both test workflows against PHP "nightly" to ensure both PHPUnit 9.x, 10.x, as well as PHPUnit 11.x are tested with PHP 8.4.
* Updates the experimental build against "future" PHPUnit to always run against the latest official PHP release.

**Regarding PHPUnit 11 and running code coverage**:

Since PHPUnit 10, PHPUnit did not distinguish between PHPUnit and PHP deprecation notices anymore.
This means that when `failOnDeprecation` is enabled (as is done for this library to be ready early for new PHP versions), a test run will also fail if there are PHPUnit native deprecation notices.

Now PHPUnit 11.2 deprecated the use of `#[CoversClass]` for traits and introduced a `#[CoversTrait]` attribute to replace this.
However, it is currently impossible to action this deprecation notice in a PHPUnit cross-version compatible manner.
This was reported upstream in sebastianbergmann/phpunit 5937

As a result of this report, PHPUnit, as of PHPUnit 10.5.32 and PHPUnit 11.3.3 will no longer exit with a non-zero exit code when `failOnDeprecation` is enabled and the only deprecations are PHPUnit native deprecations.

The net-effect of this is as follows:
* Code coverage can run unrestricted on PHPUnit 10 for this test suite as there are no PHPUnit native deprecations which haven't been handled yet.
* Code coverage can run on PHPUnit 11.0 - 11.1.x and on PHPUnit 11.3.3 and higher, but can not run on PHPUnit 11.2.0 - 11.3.2 as, due to the deprecation notices related to `CoversClass` for traits, the exit code would be non-zero.

Refs:
* https://phpunit.de/announcements/phpunit-11.html
* https://github.com/sebastianbergmann/phpunit/blob/11.0/ChangeLog-11.0.md

.github/workflows/test.yml

@@ -25,6 +25,21 @@ jobs:
         coverage: [true]
         experimental: [false]
 
+        # Mind: code coverage can not be run on PHPUnit 11.2.0 - 11.3.2.
+        #
+        # Since PHPUnit 10.0, PHPUnit native deprecations would affect the exit code.
+        # This has been handled via various work-arounds to avoid the PHPUnit
+        # deprecation notices, up to the point where it couldn't be handled anymore *.
+        #
+        # PHPUnit 11.3.3 changes the default behaviour. PHPUnit deprecation notices will
+        # now no longer affect the exit code.
+        #
+        # * PHPUnit 11.2.0 deprecated the use of `#[CoversClass]` for tests covering traits
+        #   in favour of a new `#[CoversTrait]` attributes.
+        #   No work-around was available to avoid this deprecation notice other than to
+        #   not run code coverage.
+        #   @link https://github.com/sebastianbergmann/phpunit/issues/5937
+
         include:
           # Test against a version on the low-end of the PHPUnit versions supported for each PHP version.
           # Using the Composer `--prefer-lowest` option is, unfortunately, not viable, as
@@ -81,23 +96,35 @@ jobs:
             phpunit: '9.3.0'
             coverage: true
             experimental: false
+          - php: '8.2'
+            phpunit: '~11.1.0' # See note above about PHPUnit 11.2.
+            coverage: true
+            experimental: false
           - php: '8.3'
             phpunit: '10.1.0'
             coverage: true
             experimental: false
+          - php: '8.3'
+            phpunit: '11.0.0'
+            coverage: true
+            experimental: false
 
           # Experimental builds.
           - php: 'nightly'
             phpunit: '^9.6'
             coverage: false
             experimental: true
           - php: 'nightly'
-            phpunit: 'auto' # PHPUnit 10.x.
+            phpunit: '^10.5'
+            coverage: false
+            experimental: true
+          - php: 'nightly'
+            phpunit: 'auto' # PHPUnit 11.x.
             coverage: false
             experimental: true
 
-          - php: '8.3'
-            phpunit: 'dev-main' # PHPUnit 11.x
+          - php: 'latest'
+            phpunit: 'dev-main' # PHPUnit 11.x/12.x.
             coverage: false
             experimental: true
 
@@ -164,7 +191,7 @@ jobs:
             echo 'NEEDS_MIGRATION=true' >> $GITHUB_OUTPUT
           elif [ "${{ steps.phpunit_version.outputs.VERSION }}" == "10.0" ]; then
             echo 'FILE=phpunit10.xml.dist' >> $GITHUB_OUTPUT
-          elif [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}" == "true" ]; then
+          elif [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) || startsWith( steps.phpunit_version.outputs.VERSION, '11.' ) }}" == "true" ]; then
             echo 'FILE=phpunit10.xml.dist' >> $GITHUB_OUTPUT
             echo 'NEEDS_MIGRATION=true' >> $GITHUB_OUTPUT
           else
@@ -299,11 +326,28 @@ jobs:
             phpunit: '10'
             coverage: true
 
+          # PHPUnit 11 is fully supported for the officially supported PHP versions.
+          #
+          # Mind: code coverage can not be run on PHPUnit 11.2.0 - 11.3.2.
+          # For a full explanation, see above (in the strategy for the other test job).
+          - php: '8.2'
+            phpunit: '11.0'
+            coverage: true
+          - php: '8.2'
+            phpunit: '11'
+          - php: '8.3'
+            phpunit: '11.0'
+          - php: '8.3'
+            phpunit: '11'
+            coverage: true
+
           # Experimental builds.
           - php: 'nightly'
             phpunit: '9'
           - php: 'nightly'
             phpunit: '10'
+          - php: 'nightly'
+            phpunit: '11'
 
     name: "PHAR test: PHP ${{ matrix.php }} - PHPUnit: ${{matrix.phpunit}}"
 
@@ -369,7 +413,7 @@ jobs:
         run: |
           if [ "${{ steps.phpunit_version.outputs.VERSION }}" == "10.0" ]; then
             echo 'FILE=phpunit10.xml.dist' >> $GITHUB_OUTPUT
-          elif [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) }}" == "true" ]; then
+          elif [ "${{ startsWith( steps.phpunit_version.outputs.VERSION, '10.' ) || startsWith( steps.phpunit_version.outputs.VERSION, '11.' ) }}" == "true" ]; then
             echo 'FILE=phpunit10.xml.dist' >> $GITHUB_OUTPUT
             echo 'NEEDS_MIGRATION=true' >> $GITHUB_OUTPUT
           else

composer.json

@@ -27,7 +27,7 @@
 	},
 	"require": {
 		"php": ">=7.0",
-		"phpunit/phpunit": "^6.4.4 || ^7.0 || ^8.0 || ^9.0 || ^10.0"
+		"phpunit/phpunit": "^6.4.4 || ^7.0 || ^8.0 || ^9.0 || ^10.0 || ^11.0"
 	},
 	"require-dev": {
 		"php-parallel-lint/php-console-highlighter": "^1.0.0",
@@ -98,7 +98,7 @@
 		"fix-cs": "Auto-fix code style violations in the PHP files.",
 		"test": "Run the unit tests without code coverage (PHPUnit < 10).",
 		"coverage": "Run the unit tests with code coverage (PHPUnit < 10).",
-		"test10": "Run the unit tests without code coverage using the PHPUnit 10 configuration file.",
-		"coverage10": "Run the unit tests with code coverage using the PHPUnit 10 configuration file."
+		"test10": "Run the unit tests without code coverage using the PHPUnit 10/11 configuration file.",
+		"coverage10": "Run the unit tests with code coverage using the PHPUnit 10/11 configuration file."
 	}
 }