Roadmap v2 / PHPUnit 10

[jrfnl]

PHPUnit 10 has been released beginning of February.

As this is a major release with breaking changes, upgrading should be a done deliberately and managed.
This effectively means that upgrading to a PHPUnit Polyfills version which supports PHPUnit 10 should also be done deliberately and managed, so the Polyfills should get a new major release.

To this end, the develop branch in this repo will be renamed to 1.x and a new 2.x branch will be added to contain the code for the 2.x series.

The intention is for the 1.x series to continue to be maintained, alongside the 2.x series, for as long as PHPUnit continues to make PHPUnit 9.x compatible with new PHP versions.

Refs:

• https://phpunit.de/announcements/phpunit-10.html
• https://github.com/sebastianbergmann/phpunit/blob/main/ChangeLog-10.0.md

Proposed Roadmap for PHPUnit Polyfills 2.0 / PHPUnit 10.0 support

• Rename the develop branch to 1.x and add a 2.x branch.
• Drop support for PHPUnit < 5.7 / PHP < 5.6. - PR Drop support for PHPUnit < 5.7 and PHP < 5.6 #102
• Make all assertion methods in the public API final (following in PHPUnit's footsteps). PR PHPUnit 10 | Make all assertion/exception methods final #104
• Remove the AssertAttributeHelper which was only intended to buy people a little more time to upgrade to PHPUnit 9.x.
  Open question: should the AssertAttributeHelper still remain for the time being ? And if so, for how long ?
• Remove the ExpectPHPException Polyfill as this is functionality no longer supported in PHPUnit 10.0. - PR PHPUnit 10 | Remove support for expecting PHP notices/exceptions #108
  I wouldn't be adverse to adding a PHPErrorHelper class/trait for the time being to buy people a little more time though (which similar to the AssertAttributeHelper would still require test code changes to use, so people will still have to evaluate the tests which use(d) this functionality).
• Add a new polyfill for the new assertStringEqualsStringIgnoringLineEndings() and assertStringContainsStringIgnoringLineEndings() assertions. - PR PHPUnit 10 | AssertIgnoringLineEndings trait: polyfill the Assert::assertStringEqualsStringIgnoringLineEndings() et al methods #109
• Add a new polyfill for the new assertIsList() assertion. - PR PHPUnit 10 | AssertIsList trait: polyfill the Assert::assertIsList() method #110
• Add a new polyfill for the new PHPUnit 10.1 assertObject[Not]HasProperty() assertions. - PR PHPUnit 10.1 | AssertObjectProperty trait: polyfill the Assert::assertObject[Not]HasProperty() methods #116
• Handle the change from TestListener to Event system for the TestListener Polyfill.
• Verify the documentation is in line with the changes.
• Allow PHPUnit 10.x. - PR Composer: allow PHPUnit 10.x + update CI to match #130

Planning

Providing I manage to get everything working, release version 2.x before the end of March 2023.

Request for comments

This roadmap is open for comments and I'd especially like to hear opinions on the AssertAttributeHelper and about a potential PHPErrorHelper.

[jrfnl]

Nearly there.... just some final touches needed for the test listener implementation.

Also, looks like PHPUnit 10.1 (expected mid-April) is introducing two new assertions assertObjectHasProperty() and assertObjectNotHasProperty(), so would be good to get those polyfilled as well.

[jrfnl]

Status update

Assertions and expectations

PHPUnit 10.1 and 10.2 have been released in the mean time and the additional assertion method polyfills for PHPUnit 10.1 have been pulled & merged via #116.

TestListeners

As for the TestListeners... while I have the principle of it working without issues, the trouble I'm running into is the translation between the old Listener "events" and the new Events. There is no documentation available about this and finding which "old" events ended up triggering the test listener is not as straight forward as it seems (seemed).

I basically need a couple of days/week to research this in a lot more depth to make sure the implementation the Polyfills repo offers is comparable between PHPUnit < 10 and PHPUnit 10.x and what with there being quite a lot of other things on my plate, I haven't been able to find that time so far.

Implications

What this means is that the TestListener implementation being unfinished has been blocking the release.

Some quick code search checks finds that only three of the (public) dependents of the PHPUnit Polyfills use the TestListener Polyfill, while all other dependents only use the assertion/expectation polyfills.

Decision

So.. with the above in mind, I've decided to release the 2.0.0 version without a PHPUnit 10.x compatible TestListener implementation and to move the task of adding a PHPUnit 10.x compatible TestListener implementation to a future 2.x release of the PHPUnit Polyfills.

This will unblock the upgrade to PHPUnit 10.x for most dependents and buys me some time to ensure the PHPUnit 10.x compatible TestListener implementation will be correct and stable when it is released in a later 2.x version of the PHPUnit Polyfills.