PHPUnit 11.5.0 | AssertContainsOnly trait: polyfill the Assert::asser…

…tContains[Not]Only*() methods (#225)

PHPUnit 11.5.0 introduced a range of new assertions. These assertions are specialized alternatives to the pre-existing `assert[Not]ContainsOnly()` methods, which are now soft deprecated and will be removed in PHPUnit 13.0.

This commit:
* Adds two traits with the same name.
    One to polyfill the methods when not available in PHPUnit.
    The other to allow for `use`-ing the trait in PHPUnit versions in which the methods are already natively available.
* Adds logic to the custom autoloader which will load the correct trait depending on the PHPUnit version used.
* Adds tests.

Most polyfilled methods can just fall-through to the pre-existing methods as a polyfill.
The exceptions to this rule are:
* `assertContains[Not]OnlyIterable()` which needs custom logic for PHPUnit < 7.1.0 in which the PHP native `iterable` type was not yet supported.
* `assertContains[Not]OnlyClosedResource()` which needs custom logic for PHP < 7.2 in which the PHP native `resource (closed)` type did not exist yet.
    In this last case, the custom logic is used for the polyfill on all PHP versions as there is no functional check (in contrast to a version check) which can be used to determine whether the `resource (closed)` type is available.

All new methods are loosely tested.

Includes:
* Adding information on the new polyfill to the README.
* Adding the new polyfill to the existing `TestCases` classes.

Refs:
* sebastianbergmann/phpunit@a726e03

Fixes 214

README.md

@@ -499,6 +499,60 @@ The `assertObjectNotEquals()` assertion was introduced in PHPUnit 11.2.0.
 
 [`Assert::assertObjectNotEquals()`]: https://docs.phpunit.de/en/11.5/assertions.html#assertobjectequals
 
+#### PHPUnit < 11.5.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertContainsOnly`
+
+Polyfills the following methods:
+
+|                                                  |                                                     |
+| ------------------------------------------------ | --------------------------------------------------- |
+| [`Assert::assertContainsOnlyArray()`]            | [`Assert::assertContainsNotOnlyArray()`]            |
+| [`Assert::assertContainsOnlyBool()`]             | [`Assert::assertContainsNotOnlyBool()`]             |
+| [`Assert::assertContainsOnlyCallable()`]         | [`Assert::assertContainsNotOnlyCallable()`]         |
+| [`Assert::assertContainsOnlyFloat()`]            | [`Assert::assertContainsNotOnlyFloat()`]            |
+| [`Assert::assertContainsOnlyInt()`]              | [`Assert::assertContainsNotOnlyInt()`]              |
+| [`Assert::assertContainsOnlyIterable()`]         | [`Assert::assertContainsNotOnlyIterable()`]         |
+| [`Assert::assertContainsOnlyNull()`]             | [`Assert::assertContainsNotOnlyNull()`]             |
+| [`Assert::assertContainsOnlyNumeric()`]          | [`Assert::assertContainsNotOnlyNumeric()`]          |
+| [`Assert::assertContainsOnlyObject()`]           | [`Assert::assertContainsNotOnlyObject()`]           |
+| [`Assert::assertContainsOnlyResource()`]         | [`Assert::assertContainsNotOnlyResource()`]         |
+| [`Assert::assertContainsOnlyClosedResource()`] * | [`Assert::assertContainsNotOnlyClosedResource()`] * |
+| [`Assert::assertContainsOnlyScalar()`]           | [`Assert::assertContainsNotOnlyScalar()`]           |
+| [`Assert::assertContainsOnlyString()`]           | [`Assert::assertContainsNotOnlyString()`]           |
+|                                                  | [`Assert::assertContainsNotOnlyInstancesOf()`]      |
+
+
+These methods were introduced in PHPUnit 11.5.0 as alternatives to the `Assert::assertContainsOnly()` and `Assert::assertNotContainsOnly()` methods, which were soft deprecated in PHPUnit 11.5.0, hard deprecated (warning) in PHPUnit 12.0.0 and will be removed in PHPUnit 13.0.0.
+
+* The `assertContains[Not]OnlyClosedResource()` methods are affected by issues in older PHP versions. Please read the [warning about checking for closed resources and how to optional skip such tests](https://github.com/Yoast/PHPUnit-Polyfills/tree/1.x?tab=readme-ov-file#phpunit--930-yoastphpunitpolyfillspolyfillsassertclosedresource).
+
+[`Assert::assertContainsOnlyArray()`]:             https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyarray
+[`Assert::assertContainsNotOnlyArray()`]:          https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyarray
+[`Assert::assertContainsOnlyBool()`]:              https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlybool
+[`Assert::assertContainsNotOnlyBool()`]:           https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlybool
+[`Assert::assertContainsOnlyCallable()`]:          https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlycallable
+[`Assert::assertContainsNotOnlyCallable()`]:       https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlycallable
+[`Assert::assertContainsOnlyFloat()`]:             https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyfloat
+[`Assert::assertContainsNotOnlyFloat()`]:          https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyfloat
+[`Assert::assertContainsOnlyInt()`]:               https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyint
+[`Assert::assertContainsNotOnlyInt()`]:            https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyint
+[`Assert::assertContainsOnlyIterable()`]:          https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyiterable
+[`Assert::assertContainsNotOnlyIterable()`]:       https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyiterable
+[`Assert::assertContainsOnlyNull()`]:              https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlynull
+[`Assert::assertContainsNotOnlyNull()`]:           https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlynull
+[`Assert::assertContainsOnlyNumeric()`]:           https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlynumeric
+[`Assert::assertContainsNotOnlyNumeric()`]:        https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlynumeric
+[`Assert::assertContainsOnlyObject()`]:            https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyobject
+[`Assert::assertContainsNotOnlyObject()`]:         https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyobject
+[`Assert::assertContainsOnlyResource()`]:          https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyresource
+[`Assert::assertContainsNotOnlyResource()`]:       https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyresource
+[`Assert::assertContainsOnlyClosedResource()`]:    https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyclosedresource
+[`Assert::assertContainsNotOnlyClosedResource()`]: https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyclosedresource
+[`Assert::assertContainsOnlyScalar()`]:            https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyscalar
+[`Assert::assertContainsNotOnlyScalar()`]:         https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyscalar
+[`Assert::assertContainsOnlyString()`]:            https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlystring
+[`Assert::assertContainsNotOnlyString()`]:         https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlystring
+[`Assert::assertContainsNotOnlyInstancesOf()`]:    https://docs.phpunit.de/en/11.5/assertions.html#assertcontainsonlyinstancesof
+
 
 ### TestCases
 

phpstan.neon.dist

@@ -15,6 +15,7 @@ parameters:
 		- src/TestCases/TestCasePHPUnitLte7.php
 		# Triggers "Referencing prefixed PHPUnit class: PHPUnitPHAR\SebastianBergmann\Exporter\Exporter." notices, which cannot be ignored.
 		- src/Polyfills/AssertClosedResource.php
+		- src/Polyfills/AssertContainsOnly.php
 		- src/Polyfills/AssertIgnoringLineEndings.php
 	treatPhpDocTypesAsCertain: false
 

phpunitpolyfills-autoload.php

@@ -98,6 +98,10 @@ public static function load( $className ) {
 					self::loadAssertObjectNotEquals();
 					return true;
 
+				case 'Yoast\PHPUnitPolyfills\Polyfills\AssertContainsOnly':
+					self::loadAssertContainsOnly();
+					return true;
+
 				case 'Yoast\PHPUnitPolyfills\TestCases\TestCase':
 					self::loadTestCase();
 					return true;
@@ -381,6 +385,23 @@ public static function loadAssertObjectNotEquals() {
 			require_once __DIR__ . '/src/Polyfills/AssertObjectNotEquals_Empty.php';
 		}
 
+		/**
+		 * Load the AssertContainsOnly polyfill or an empty trait with the same name
+		 * if a PHPUnit version is used which already contains this functionality.
+		 *
+		 * @return void
+		 */
+		public static function loadAssertContainsOnly() {
+			if ( \method_exists( Assert::class, 'assertContainsOnlyIterable' ) === false ) {
+				// PHPUnit < 11.5.0.
+				require_once __DIR__ . '/src/Polyfills/AssertContainsOnly.php';
+				return;
+			}
+
+			// PHPUnit >= 11.5.0.
+			require_once __DIR__ . '/src/Polyfills/AssertContainsOnly_Empty.php';
+		}
+
 		/**
 		 * Load the appropriate TestCase class based on the PHPUnit version being used.
 		 *