Backward Compatibility break in PHPUnit\Framework\Constraint\Constraint

[stof]

Q	A
PHPUnit version	11.0
PHP version	8.2.15
Installation Method	Composer / PHAR

Summary

PHPUnit 11.0 has changed the Constraint class to mark it readonly. This is a BC break for all child class (i.e. all custom constraints) because PHP requires that child classes have the same readonly flag than their parent (so either both readonly or none).
This BC break is not mentioned anywhere in the changelog. And it will make it very hard to define custom constraints compatible with multiple PHPUnit versions as it will require using conditional class definitions.

Current behavior

How to reproduce

Install PHPUnit 11 and use custom constraints that were written against previous versions. See symfony/symfony#53731

Expected behavior

[stof]

As the change has been rejected in https://wiki.php.net/rfc/readonly_amendments, this readonly flag at the class level effectively splits the classes into 2 incompatible sets as far as inheritance is concerned.
Adding it or removing it on non-final classes is a BC break.

[derrabus]

FTR, the corresponding commit was d82f5ad. I didn't find any discussion around this change though.

As @stof said, this change is a huge pain for 3rd party PHPUnit extensions that maintain compatibility for multiple PHPUnit versions. It would be really helpful if we could remove the readonly flag from classes that are meant to be extended downstream and have existed in PHPUnit 10 already.

Then again, removing the readonly flag from abstract classes like Constraint is a BC break as well. Not sure, how many projects have migrated their constraints to the new readonlyclasses already. Maybe taking back that change is acceptable if we are quick. 😕

[sebastianbergmann]

This is a BC break for all child class (i.e. all custom constraints) because PHP requires that child classes have the same readonly flag than their parent (so either both readonly or none).

This is a BC break, but it was done in a major version, so I expected this to be fine.

Do you really expect me to revert this change or is amending the ChangeLog to cover this change enough?

Nevermind, I'll revert this change and release PHPUnit 11.0.1 in a bit.

[stof]

Well, this makes it a huge pain for projects providing custom constraints. It would be great to be able to support the 2 major versions of PHPUnit at the same time (for a package that is dedicated to PHPUnit constraint, making a new major version

so I expected this to be fine

doing BC breaks in major version is indeed OK regarding semver. But to me, the fact that it was not announced (while being the most painful BC break of the release) is not. If this was known to be a BC break when doing it, it should have been announced..

Note that the commit included similar changes for some other non-final classes (TestData, TestSuite, etc...). As those are less common in third party code, it might be OK to keep them readonly in 11.x but I would still expect the changelog to be amended for them.

[stof]

Thanks for the decision to revert it. It will make things a lot easier.

[sebastianbergmann]

PHPUnit 11.0.1 has been released with this fix.

[stof]

@sebastianbergmann what about the changelog amending for other non-internal non-final classes that were turned readonly ?

[sebastianbergmann]

@sebastianbergmann what about the changelog amending for other non-internal non-final classes that were turned readonly ?

As far as I can see, this only affects value objects that are passed from PHPUnit's event system to subscribers. Please see the section titled "Event System: Value Objects" that I just added to https://phpunit.de/backward-compatibility.html.

[derrabus]

Thank you very much, @sebastianbergmann!