yoast/phpunit-polyfills

PHPUnit 12 support

This release updates the PHPUnit Polyfills to allow for "writing your tests for PHPUnit 12 and running them all the way back to PHPUnit 7". [*]

Please keep in mind that the PHPUnit Polyfills provide forward-compatibility. This means that features which PHPUnit no longer supports in PHPUnit 12.x, are also no longer supported in the 4.0 release of the PHPUnit Polyfills.

Please refer to the PHPUnit 12 release notification and PHPUnit 12 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, 3.x and 4.x series side-by-side, like so composer require --dev yoast/phpunit-polyfills:"^1.0 || ^2.0 || ^3.0 || ^4.0".

[*]: Note: Releases from the PHPUnit Polyfills 4.x branch will support running tests on PHPUnit 7.5.0 - 9.x, 11.x and 12.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

Changed

• Composer: allow for installation of PHPUnit 12.x. PR #247
• Scalar parameter type declarations and return type declarations are now used where possible. PR #241
• General housekeeping.

Removed

• Support for PHP < 7.1. PR #238.
• Support for PHPUnit < 7.5.0. PR #239.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertIsType trait which is no longer needed now support for PHPUnit < 7.5 has been dropped. PR #239.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains trait which is no longer needed now support for PHPUnit < 7.5 has been dropped. PR #239.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertEqualsSpecializations trait which is no longer needed now support for PHPUnit < 7.5 has been dropped. PR #239.

PHPUnit 12 support

This release updates the PHPUnit Polyfills to allow for "writing your tests for PHPUnit 12 and running them all the way back to PHPUnit 7". [*]

Please keep in mind that the PHPUnit Polyfills provide forward-compatibility. This means that features which PHPUnit no longer supports in PHPUnit 12.x, are also no longer supported in the 4.0 release of the PHPUnit Polyfills.

Please refer to the PHPUnit 12 release notification and PHPUnit 12 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, 3.x and 4.x series side-by-side, like so composer require --dev yoast/phpunit-polyfills:"^1.0 || ^2.0 || ^3.0 || ^4.0".

[*]: Note: Releases from the PHPUnit Polyfills 4.x branch will support running tests on PHPUnit 7.5.0 - 9.x, 11.x and 12.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

Changed

• Composer: allow for installation of PHPUnit 12.x. PR #247
• Scalar parameter type declarations and return type declarations are now used where possible. PR #241
• General housekeeping.

Removed

• Support for PHP < 7.1. PR #238.
• Support for PHPUnit < 7.5.0. PR #239.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertIsType trait which is no longer needed now support for PHPUnit < 7.5 has been dropped. PR #239.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains trait which is no longer needed now support for PHPUnit < 7.5 has been dropped. PR #239.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertEqualsSpecializations trait which is no longer needed now support for PHPUnit < 7.5 has been dropped. PR #239.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 4.x branch. PR #249
• General housekeeping.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 4.x branch. PR [#249]
• General housekeeping.

<!-- Link to #249 is defined on the 1.1.4 release. -->

Fixed

• AssertContainsOnly::assertContainsNotOnlyInstancesOf(): incorrect parameter name. PR #235

Changed

• General housekeeping.

Fixed

• AssertContainsOnly::assertContainsNotOnlyInstancesOf(): incorrect parameter name. PR #235

Changed

• General housekeeping.

Added

• Yoast\PHPUnitPolyfills\Polyfills\AssertContainsOnly trait to polyfill the specialized Assert::assertContains[Not]Only*() methods as introduced in PHPUnit 11.5.0. PR #225.

Changed

• README: fix links which were broken due to an upstream branch removal. PR #213.
• README: fixed a few broken badges.
• General housekeeping.

Added

• Yoast\PHPUnitPolyfills\Polyfills\AssertContainsOnly trait to polyfill the specialized Assert::assertContains[Not]Only*() methods as introduced in PHPUnit 11.5.0. PR #225.

Changed

• README: fix links which were broken due to an upstream branch removal. PR #213.
• README: fixed a few broken badges.
• General housekeeping.

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".

[*]: 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.
• 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.

Fixed

• PHP 8.5 deprecation notice when using the AssertAttributeHelper::getProperty() and AssertAttributeHelper::getPropertyValue() methods. PR #261

Changed

• General housekeeping.

Fixed

• PHP 8.5 deprecation notice when using the AssertAttributeHelper::getProperty() and AssertAttributeHelper::getPropertyValue() methods. PR [#261]

Changed

• General housekeeping.

<!-- Link to #261 is defined on the 1.1.5 release. -->

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 4.x branch. PR #249
• General housekeeping.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 4.x branch. PR [#249]
• General housekeeping.

<!-- Link to #249 is defined on the 1.1.4 release. -->

This is a maintenance release.

Changed

• README: fixed a few broken badges.
• General housekeeping.

This is a maintenance release.

Changed

• README: fixed a few broken badges.
• General housekeeping.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 3.x branch. PR [#188]
• README: FAQ updated with info about ability to polyfill the removed expectDeprecation*() methods et al. PR #187, props [Tonya Mork].
• README: links to the PHPUnit manual now point explicitly to the PHPUnit 10.x documentation. PR [#190]
• General housekeeping.

<!-- Link to #188 is defined on the 1.1.2 release. --> [#190]: https://github.com/Yoast/PHPUnit-Polyfills/pull/190

Added

• Compatibility fixes for running tests using a PHPUnit PHAR file for PHPUnit 8.5.38+, 9.6.19+ and PHPUnit 10.5.17+. PRs [#161], #164.

Changed

• General housekeeping.

PHPUnit 10 support

This release updates the PHPUnit Polyfills to allow for "writing your tests for PHPUnit 10 and running them all the way back to PHPUnit 5".

Please keep in mind that the PHPUnit Polyfills provide forward-compatibility. This means that features which PHPUnit no longer supports in PHPUnit 10.x, like expecting PHP deprecation notices or warnings, are also no longer supported in the 2.0 release of the PHPUnit Polyfills.

Please refer to the PHPUnit 10 release notification and PHPUnit 10 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 and 2.x series side-by-side, like so composer require --dev yoast/phpunit-polyfills:"^1.0 || ^2.0".

:warning: Important: about the TestListener polyfill :warning:

The TestListener polyfill in PHPUnit Polyfills 2.0 is not (yet) compatible with PHPUnit 10.0.0.

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 the related ticket.

Changelog

Added

• Yoast\PHPUnitPolyfills\Polyfills\AssertIgnoringLineEndings trait to polyfill the Assert::assertStringEqualsStringIgnoringLineEndings() and the Assert::assertStringContainsStringIgnoringLineEndings() methods as introduced in PHPUnit 10.0.0. PR #109.
• Yoast\PHPUnitPolyfills\Polyfills\AssertIsList trait to polyfill the Assert::assertIsList() method as introduced in PHPUnit 10.0.0. PR #110.
• Yoast\PHPUnitPolyfills\Polyfills\AssertObjectProperty trait to polyfill the Assert::assertObjectHasProperty() and the Assert::assertObjectNotHasProperty() methods as introduced in PHPUnit 10.1.0. PR #116.

Changed

• Composer: allow for installation of PHPUnit 10.x. PR #130
• Nearly all assertion methods are now final. This alignes them with the same change made upstream in PHPUnit 10.0.0. PR #104.
• General housekeeping.

Removed

• Support for PHP < 5.6. PR #102.
• Support for PHPUnit < 5.7.21. PR #102.
• Support for expecting PHP deprecations, notices, warnings and error via the Yoast\PHPUnitPolyfills\Polyfills\ExpectPHPException trait. PR #108. The trait has been removed completely as PHPUnit 10 no longer supports this functionality.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertNumericType trait which is no longer needed now support for PHPUnit < 5.7 has been dropped. PR #102.
• The Yoast\PHPUnitPolyfills\Polyfills\ExpectException trait which is no longer needed now support for PHPUnit < 5.7 has been dropped. PR #102.
• The Yoast\PHPUnitPolyfills\Polyfills\AssertFileDirectory trait which is no longer needed now support for PHPUnit < 5.7 has been dropped. PR #102.

Fixed

• PHP 8.5 deprecation notice when using the AssertAttributeHelper::getProperty() and AssertAttributeHelper::getPropertyValue() methods. PR #261

Changed

• General housekeeping.

Fixed

• PHP 8.5 deprecation notice when using the AssertAttributeHelper::getProperty() and AssertAttributeHelper::getPropertyValue() methods. PR #261

Changed

• General housekeeping.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 4.x branch. PR #249
• General housekeeping.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 4.x branch. PR #249
• General housekeeping.

This is a maintenance release.

Changed

• README: fixed a few broken badges.
• General housekeeping.

This is a maintenance release.

Changed

• README: fixed a few broken badges.
• General housekeeping.

This is a maintenance release.

Changed

• README: updated sub-section about PHPUnit version support with information about the PHPUnit Polyfills 3.x branch. PR #188
• General housekeeping.

Added

• Compatibility fix for running tests using a PHPUnit PHAR file for PHPUnit 8.5.38+ and PHPUnit 9.6.19+. PR #161.

Changed

• General housekeeping.

Added

• Yoast\PHPUnitPolyfills\Polyfills\AssertObjectProperty trait to polyfill the Assert::assertObjectHasProperty() and Assert::assertObjectNotHasProperty() methods as backported from PHPUnit 10.1.0 to PHPUnit 9.6.11. PR #135.

Changed

• General housekeeping.

Fixed

• A custom $message parameter passed to an assertion, will no longer overrule an emulated "assertion failed" message, but will be prefixed to it instead. PR #97. This applies to the following polyfills:
  • assertIsClosedResource()
  • assertIsNotClosedResource()
  • assertIsReadable()
  • assertNotIsReadable()
  • assertIsWritable()
  • assertNotIsWritable()
  • assertDirectoryExists()
  • assertDirectoryNotExists()
  • assertStringNotContainsString()
  • assertStringNotContainsStringIgnoringCase()

Changed

• The develop branch has been removed. Development will now take place in the 1.x and 2.x branches.
• README: links to the PHPUnit manual now point explicitly to the PHPUnit 9.x documentation. PR #94.
• README: new sub-section about PHPUnit version support. PR #99.
• README: various minor improvements. PRs #92, #93.
• General housekeeping.

This is a maintenance release.

Changed

• The Yoast\PHPUnitPolyfills\Autoload class is now final. PR #77.
• README: clear up minor language confusion. Props [Phil E. Taylor] and [fredericgboutin-yapla] for pointing it out.
• README: fix links which were broken due to an upstream branch rename. PR #80.
• Verified PHP 8.2 compatibility.
• General housekeeping.

Changed

• General housekeeping.

Fixed

• The failure message thrown for the assertIsClosedResource() and assertIsNotClosedResource() assertions will now be more informative, most notably, when the value under test is a closed resource. PR #65, props [Alain Schlesser] for reporting.

As of version 2.15.0 of the shivammathur/setup-php action for GitHub Actions, the PHPUnit Polyfills can be installed directly from this action using the tools key.

Added

• README: FAQ section about installing and using the library via the shivammathur/setup-php action. PR #52.

Changed

• README: minor textual clarifications and improvements. PRs #52, #54, props [Pierre Gordon].
• General housekeeping.

Fixed

• Autoloader: improved compatibility with packages which create a class_alias for the PHPUnit_Runner_Version or PHPUnit\Runner\Version class. PR #59.

Added

• The Yoast\PHPUnitPolyfills\Autoload class now contains a VERSION constant. Issue #46, PR #47, props [Pascal Birchler] for the suggestion. This version constant can be used by (complex) test setups to verify that the PHPUnit Polyfills which will be loaded, comply with the version requirements for the test suite.

Changed

• Minor documentation updates. #43

Added

• Yoast\PHPUnitPolyfills\Polyfills\AssertClosedResource trait to polyfill the Assert::assertIsClosedResource() and Assert::assertIsNotClosedResource() methods as introduced in PHPUnit 9.3.0. PR #27.
• Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals trait to polyfill the Assert::assertObjectEquals() method as introduced in PHPUnit 9.4.0. PR #38. The behaviour of the polyfill closely matches the PHPUnit native implementation, but is not 100% the same. Most notably, the polyfill will check the type of the returned value from the comparator method instead of enforcing a return type declaration for the comparator method.
• Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations trait to polyfill the Assert::equalToCanonicalizing(), Assert::equalToIgnoringCase() and Assert::equalToWithDelta() methods as introduced in PHPUnit 9.0.0. PR #28, props [Marc Siegrist].
• Polyfills for the PHP native Error and TypeError classes as introduced in PHP 7.0. PR #36.
• README: FAQ section covering functionality removed from PHPUnit and usage with a Phar.

Changed

• The minimum supported PHP version has been lowered to PHP 5.4 (was 5.5). PR #19.
• XTestCase: the visibility of the setUpFixtures() and the tearDownFixtures() methods has been changed to protected (was public). Issue #10, PR #20, props [Mark Baker] for reporting.
• README: re-ordered the sections and various other improvements.
• Initial preparation for PHPUnit 10.0 compatibility.
• General housekeeping.

Fixed

• Issue #17 via PR #18 - AssertStringContainString: PHPUnit < 6.4.2 would throw a "mb_strpos(): empty delimiter" PHP warning when the $needle passed was an empty string. Props [Gary Jones].

Added

• Yoast\PHPUnitPolyfills\TestListeners\TestListenerDefaultImplementation: a cross-version compatible base implementation for TestListeners using snake_case method names to replace the PHPUnit native method names.
• Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper trait containing a getProperty() and a getPropertyValue() method. This is a stop-gap solution for the removal of the PHPUnit assertAttribute*() methods in PHPUnit 9. It is strongly recommended to refactor your tests/classes in a way that protected and private properties no longer be tested directly as they should be considered an implementation detail. However, if for some reason the value of protected or private properties still needs to be tested, this helper can be used to get access to their value.
• Yoast\PHPUnitPolyfills\Polyfills\AssertNumericType trait to polyfill the Assert::assertFinite(), Assert::assertInfinite() and Assert::assertNan() methods as introduced in PHPUnit 5.0.0.
• Yoast\PHPUnitPolyfills\Polyfills\ExpectException trait to polyfill the TestCase::expectException(), TestCase::expectExceptionMessage(), TestCase::expectExceptionCode() and TestCase::expectExceptionMessageRegExp() methods, as introduced in PHPUnit 5.2.0 to replace the Testcase::setExpectedException() and the Testcase::setExpectedExceptionRegExp() method.
• Yoast\PHPUnitPolyfills\Polyfills\AssertFileDirectory trait to polyfill the Assert::assertIsReadable(), Assert::assertIsWritable() methods and their file/directory based variations, as introduced in PHPUnit 5.6.0.
• Yoast\PHPUnitPolyfills\TestCases\TestCase: support for the assertPreConditions() and assertPostConditions() methods.

Changed

• The minimum supported PHP version has been lowered to PHP 5.5 (was 5.6).
• The minimum supported PHPUnit version has been lowered to PHP 4.8.36 (was 5.7). Note: for PHPUnit 4, only version 4.8.36 is supported, for PHPUnit 5, only PHPUnit >= 5.7.21 is supported.
• Readme: documentation improvements.

Initial release.