Merge pull request #203 from Yoast/feature/release-version-3.0

Changelog for the 3.0.0 release and other documentation updates

.github/RELEASE-CHECKLIST.md

@@ -15,7 +15,8 @@ If releases for multiple branches are to be tagged, always tag the 1.x release f
     Verify that a release link at the bottom of the `CHANGELOG.md` file has been added.
 - [ ] Merge the changelog PR.
 - [ ] Make sure all CI builds are green.
-- [ ] Tag the release on the 2.x branch (careful, GH defaults to `3.x`!).
+- [ ] Fast-forward the `main` branch to the latest `3.x` commit and push.
+- [ ] Tag the release on `main` (careful, GH defaults to `3.x`!).
 - [ ] Create a release from the tag (careful, GH defaults to `3.x`!) & copy & paste the changelog to it.
     Make sure to copy the links to the issues and the links to the GH usernames from the bottom of the changelog!
 - [ ] Close the milestone.

CHANGELOG.md

@@ -9,6 +9,61 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [3.0.0] - 2024-09-07
+
+### PHPUnit 11 support
+
+This release updates the PHPUnit Polyfills to allow for _"writing your tests for PHPUnit 11 and running them all the way back to PHPUnit 6"_. \[*\]
+
+Please keep in mind that the PHPUnit Polyfills provide _forward_-compatibility. This means that features which PHPUnit no longer supports in PHPUnit 11.x, are also no longer supported in the 3.0 release of the PHPUnit Polyfills.
+
+Please refer to the [PHPUnit 11 release notification] and [PHPUnit 11 changelog] to inform your decision on whether or not to upgrade (yet).
+
+Projects which don't use any of the new or removed functionality in their test suite, can, of course, use the PHPUnit Polyfills 1.x, 2.x and 3.x series side-by-side, like so `composer require --dev yoast/phpunit-polyfills:"^1.0 || ^2.0 || ^3.0"`.
+
+[PHPUnit 11 release notification]: https://phpunit.de/announcements/phpunit-11.html
+[PHPUnit 11 changelog]:            https://github.com/sebastianbergmann/phpunit/blob/11.0.10/ChangeLog-11.0.md
+
+\[*\]: _Note: Releases from the PHPUnit Polyfills 3.x branch will support running tests on PHPUnit 6.4.4 - 9.x and 11.x, but will not allow for running tests on PHPUnit 10 (for reasons explained in [#200])._
+_In practical terms, the net effect of this is that tests on PHP 8.1 will run on PHPUnit 9 instead of PHPUnit 10. Other than that, there is no impact._
+
+
+### Changelog
+
+#### Added
+* `Yoast\PHPUnitPolyfills\Polyfills\AssertArrayWithListKeys` trait to polyfill the `Assert::assertArrayIsEqualToArrayOnlyConsideringListOfKeys()`, `Assert::assertArrayIsEqualToArrayIgnoringListOfKeys()`, `Assert::assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys()` and `Assert::assertArrayIsIdenticalToArrayIgnoringListOfKeys()` methods as introduced in PHPUnit 11.0.0. PR [#198].
+* `Yoast\PHPUnitPolyfills\Polyfills\ExpectUserDeprecation` trait to polyfill the `TestCase::expectUserDeprecationMessage()` and `TestCase::expectUserDeprecationMessageMatches()` methods as introduced in PHPUnit 11.0.0. PR [#200].
+    These methods can largely be seen as replacements for the `TestCase::expectDeprecationMessage()` and `TestCase::expectDeprecationMessageMatches()` methods which were removed in PHPUnit 10.0, though there are significant differences between the implementation details of the old vs the new methods. Please see the [README for full details][readme-on-expectuserdeprecation].
+* `Yoast\PHPUnitPolyfills\Polyfills\AssertObjectNotEquals` trait to polyfill the `Assert::assertObjectNotEquals()` method as introduced in PHPUnit 11.2.0. PR [#199].
+
+#### Changed
+* Composer: allow for installation of PHPUnit 11.x and removed runtime support for PHPUnit 10.x. PR [#196], [#200]
+* The assertion failure message for the `assertIsList()` method has been updated to be in sync with the latest message format as used by PHPUnit 11.3.1+. [#195]
+* The visibility of the `expectExceptionMessageMatches()` method has been changed from `public` to `protected`, in line with the same changes as per PHPUnit 11.0. [#197]
+* The `assertObjectEquals()` method polyfill now behaves the same as the PHPUnit native assertion method. PR [#192]
+    Previously a comparator method could either be compatible with PHP 5.6+ in combination with PHPUnit < 9.4.0 or with PHP 7.0+, but it wasn't possible to write a comparator method which would work in both situation due to the return type declaration requirement from PHPUnit itself. With the new PHP 7.0 minimum requirement, the return type declaration is now always required and the polyfill and the PHPUnit native method are completely aligned.
+* General housekeeping.
+
+#### Removed
+* Support for PHP < 7.0. PR [#192].
+* Support for PHPUnit < 6.4.4. PR [#193].
+* The `Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper` trait. PR [#194].
+    This "helper" was only intended as a temporary measure to buy people some more time to refactor their tests.
+* The `Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionObject` trait which is no longer needed now support for PHPUnit < 6.4 has been dropped. PR [#193].
+
+[#192]: https://github.com/Yoast/PHPUnit-Polyfills/pull/192
+[#193]: https://github.com/Yoast/PHPUnit-Polyfills/pull/193
+[#194]: https://github.com/Yoast/PHPUnit-Polyfills/pull/194
+[#195]: https://github.com/Yoast/PHPUnit-Polyfills/pull/195
+[#196]: https://github.com/Yoast/PHPUnit-Polyfills/pull/196
+[#197]: https://github.com/Yoast/PHPUnit-Polyfills/pull/197
+[#198]: https://github.com/Yoast/PHPUnit-Polyfills/pull/198
+[#199]: https://github.com/Yoast/PHPUnit-Polyfills/pull/199
+[#200]: https://github.com/Yoast/PHPUnit-Polyfills/pull/200
+
+[readme-on-expectuserdeprecation]: https://github.com/Yoast/PHPUnit-Polyfills/tree/3.x?tab=readme-ov-file#phpunit--1100-yoastphpunitpolyfillspolyfillsexpectuserdeprecation
+
+
 ## [2.0.2] - 2024-09-07
 
 This is a maintenance release.
@@ -268,7 +323,8 @@ As of version 2.15.0 of the `shivammathur/setup-php` action for GitHub Actions,
 Initial release.
 
 
-[Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/2.x...HEAD
+[Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/3.x...HEAD
+[3.0.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/2.0.2...3.0.0
 [2.0.2]: https://github.com/Yoast/PHPUnit-Polyfills/compare/2.0.1...2.0.2
 [2.0.1]: https://github.com/Yoast/PHPUnit-Polyfills/compare/2.0.0...2.0.1
 [2.0.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.1.2...2.0.0

README.md

@@ -5,7 +5,7 @@ PHPUnit Polyfills
 [![CS Build Status](https://github.com/Yoast/PHPUnit-Polyfills/actions/workflows/cs.yml/badge.svg)](https://github.com/Yoast/PHPUnit-Polyfills/actions/workflows/cs.yml)
 [![Lint Build Status](https://github.com/Yoast/PHPUnit-Polyfills/actions/workflows/lint.yml/badge.svg)](https://github.com/Yoast/PHPUnit-Polyfills/actions/workflows/lint.yml)
 [![Test Build Status](https://github.com/Yoast/PHPUnit-Polyfills/actions/workflows/test.yml/badge.svg)](https://github.com/Yoast/PHPUnit-Polyfills/actions/workflows/test.yml)
-[![Coverage Status](https://coveralls.io/repos/github/Yoast/PHPUnit-Polyfills/badge.svg?branch=2.x)](https://coveralls.io/github/Yoast/PHPUnit-Polyfills?branch=2.x)
+[![Coverage Status](https://coveralls.io/repos/github/Yoast/PHPUnit-Polyfills/badge.svg?branch=3.x)](https://coveralls.io/github/Yoast/PHPUnit-Polyfills?branch=3.x)
 
 [![Minimum PHP Version](https://img.shields.io/packagist/php-v/yoast/phpunit-polyfills.svg?maxAge=3600)](https://packagist.org/packages/yoast/phpunit-polyfills)
 [![License: BSD3](https://poser.pugx.org/yoast/phpunit-polyfills/license)](https://github.com/Yoast/PHPUnit-Polyfills/blob/main/LICENSE)
@@ -34,7 +34,7 @@ Requirements
 ------------
 
 * PHP 7.0 or higher.
-* [PHPUnit] 6.4 - 10.x (automatically required via Composer).
+* [PHPUnit] 6.4 - 9.x and 11.x (automatically required via Composer).
 
 [PHPUnit]: https://packagist.org/packages/phpunit/phpunit
 
@@ -44,7 +44,7 @@ Installation
 
 To install this package, run:
 ```bash
-composer require --dev yoast/phpunit-polyfills:"^2.0"
+composer require --dev yoast/phpunit-polyfills:"^3.0"
 ```
 
 To update this package, run:
@@ -64,7 +64,7 @@ Why use the PHPUnit Polyfills?
 
 This library is set up to allow for creating PHPUnit cross-version compatible tests by offering a number of polyfills for functionality which was introduced, split up or renamed in PHPUnit.
 
-### Write your tests for PHPUnit 10.x and run them on PHPUnit 6.4 - 10.x
+### Write your tests for PHPUnit 11.x and run them on PHPUnit 6.4 - 11.x
 
 The polyfills have been setup to allow tests to be _forward_-compatible. What that means is, that your tests can use the assertions supported by the _latest_ PHPUnit version, even when running on older PHPUnit versions.
 
@@ -605,7 +605,7 @@ class MyTest extends XTestCase {
 
 > :warning: **Important** :warning:
 >
-> The TestListener polyfill in PHPUnit Polyfills 2.0 is [not (yet) compatible with PHPUnit 10.0.0][polyfill-ticket].
+> The TestListener polyfill in PHPUnit Polyfills 2.0/3.0 is [not (yet) compatible with PHPUnit 10.x/11.x][polyfill-ticket].
 >
 > If you need the TestListener polyfill, it is recommended to stay on the PHPUnit Polyfills 1.x series for the time being and to watch and upvote the [related ticket][polyfill-ticket].
 >
@@ -682,10 +682,8 @@ For frequently used, removed PHPUnit functionality, "helpers" may be provided. T
 | PHPUnit | Removed               | Issue          | Remarks                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ------- | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 9.0.0   | `assertArraySubset()` | [#1][issue #1] | The [`dms/phpunit-arraysubset-asserts`](https://packagist.org/packages/dms/phpunit-arraysubset-asserts) package polyfills this functionality.<br/>As of [version 0.3.0](https://github.com/rdohms/phpunit-arraysubset-asserts/releases/tag/v0.3.0) this package can be installed in combination with PHP 5.4 - current and PHPUnit 4.8.36/5.7.21 - current.<br/>Alternatively, tests can be refactored using the patterns outlined in [issue #1]. |
-| 10.0.0  | `expectDeprecation*()` et al | [#186][issue #186] | A [custom polyfill approach tutorial](https://github.com/Yoast/PHPUnit-Polyfills/issues/186#issuecomment-2334326687) is available. Alternatively, tests can be refactored to skip running the `expectDeprecation*()` et al or skip the test completely on PHPUnit 10, while still running them on <= PHPUnit 9. |
 
 [issue #1]: https://github.com/Yoast/PHPUnit-Polyfills/issues/1
-[issue #186]: https://github.com/Yoast/PHPUnit-Polyfills/issues/186
 
 ### Q: Can this library be used when the tests are being run via a PHPUnit Phar file ?
 
@@ -754,6 +752,16 @@ if ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
 }
 ```
 
+### Q: Why don't the PHPUnit Polyfills 3.x versions support running tests on PHPUnit 10 ?
+
+PHPUnit 11.0 introduced the `expectUserDeprecationMessage*()` methods. To polyfill these for PHPUnit 10 would mean that the Polyfills package could no longer be a "drop-in" helper package, but would need to set extra requirements on test suites using the polyfills when used with PHPUnit 10 (like hooking into events or compulsory use of the `TestCase`s provided by this package).
+
+As it was deemed desirable enough to polyfill the methods, the releases from the 3.x branch of the PHPUnit Polyfills do not support running tests on PHPUnit 10.
+
+The impact of this compromise is minimal, as, in the most common case of running the tests with Composer installed dependencies, this just and only means that test runs on PHP 8.1 will use PHPUnit 9 instead of PHPUnit 10. There is no other impact.
+
+Keep in mind that functionality _added_ in PHPUnit 10, is still polyfilled and available in PHPUnit Polyfills 3.x.
+
 
 Contributing
 ------------

phpunitpolyfills-autoload.php

@@ -18,7 +18,7 @@ final class Autoload {
 		 *
 		 * @var string
 		 */
-		const VERSION = '3.0.0-dev';
+		const VERSION = '3.0.0';
 
 		/**
 		 * Loads a class.