Merge pull request #50 from Yoast/develop

Release version 1.0.1

.github/RELEASE-CHECKLIST.md

@@ -0,0 +1,31 @@
+Template to use for release PRs from `develop` to `main`
+===========================================================
+
+Title: Release version x.x.x
+
+### Functional:
+- [ ] Confirm that the most recent PHPUnit changelogs have been checked and that the library is still feature complete for those versions supported within the PHPUnit version constraints.
+- [ ] Update the `VERSION` constant in the `phpunitpolyfills-autoload.php` file.
+- [ ] Composer: check if any dependencies/version constraints need updating.
+
+### Release:
+- [ ] Add changelog for the release - PR #xxx
+    Verify that a release link at the bottom of the `CHANGELOG.md` file has been added.
+- [ ] Merge this PR.
+- [ ] Make sure all CI builds are green.
+- [ ] Tag the release (careful, GH defaults to `develop`!).
+- [ ] Create a release from the tag (careful, GH defaults to `develop`!) & 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.
+- [ ] Open a new milestone for the next release.
+- [ ] If any open PRs/issues which were milestoned for the release did not make it into the release, update their milestone.
+
+### Announce:
+- [ ] Tweet about the release.
+
+
+---
+
+Additional actions to take, not part of the release checklist:
+- [ ] Post a link to the release in the Yoast Slack.
+- [ ] Update the dependency version constraints for WP Test Utils.

.github/workflows/test.yml

@@ -71,6 +71,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
+          ini-values: error_reporting=E_ALL, display_errors=On
           coverage: none
 
       - name: 'Composer: set PHPUnit version for tests'

CHANGELOG.md

@@ -9,13 +9,27 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [1.0.1] - 2021-08-09
+
+### 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]
+
+[#43]: https://github.com/Yoast/PHPUnit-Polyfills/pull/43
+[#46]: https://github.com/Yoast/PHPUnit-Polyfills/issues/46
+[#47]: https://github.com/Yoast/PHPUnit-Polyfills/pull/47
+
+
 ## [1.0.0] - 2021-06-21
 
 ### 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 the enforcing a return type declaration of the comparator method.
+    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.
@@ -67,10 +81,12 @@ Initial release.
 
 
 [Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/main...HEAD
+[1.0.1]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.0...1.0.1
 [1.0.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.2.0...1.0.0
 [0.2.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.1.0...0.2.0
 [0.1.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/e8f8b7a73737aa9a5974bd9c73d2bd8d09f69873...0.1.0
 
 [Gary Jones]: https://github.com/GaryJones
 [Marc Siegrist]: https://github.com/mergeMarc
 [Mark Baker]: https://github.com/MarkBaker
+[Pascal Birchler]: https://github.com/swissspidy

README.md

@@ -128,7 +128,7 @@ For the polyfills to work, a test class is **required** to be a (grand-)child of
 
 If your library still needs to support PHP < 5.6 and therefore needs PHPUnit 4 for testing, there are a few caveats when using the traits stand-alone as we then enter "double-polyfill" territory.
 
-To prevent "conflicting method names" errors when a trait is `use`d multiple times in a class, the traits offered here do not attempt to solve this.
+To prevent _"conflicting method names"_ errors when a trait is `use`d multiple times in a class, the traits offered here do not attempt to solve this.
 
 You will need to make sure to `use` any additional traits needed for the polyfills to work.
 
@@ -433,27 +433,28 @@ if ( self::shouldClosedResourceAssertionBeSkipped( $actual ) === false ) {
 }
 ```
 
-> :point_right: While this polyfill is tested extensively, testing for these kind of bugs exhaustively is _hard_.
+> :point_right: While this polyfill is tested extensively, testing for these kind of bugs _exhaustively_ is _hard_.
 > Please [report any bugs](https://github.com/Yoast/PHPUnit-Polyfills/issues/new/choose) found and include a clear code sample to reproduce the issue.
 
 #### PHPUnit < 9.4.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals`
 
 Polyfills the [`Assert::assertObjectEquals()`] method to verify two (value) objects are considered equal.
 This assertion expects an object to contain a comparator method in the object itself. This comparator method is subsequently called to verify the "equalness" of the objects.
 
-The `assertObjectEquals() assertion was introduced in PHPUnit 9.4.0.
+The `assertObjectEquals()` assertion was introduced in PHPUnit 9.4.0.
 
-> :info: Due to [limitations in how this assertion is implemented in PHPUnit] itself, it is currently not possible to create a single comparator method which will be compatible with both PHP < 7.0 and PHP 7.0 or higher.
+> :information_source: Due to [limitations in how this assertion is implemented in PHPUnit] itself, it is currently not possible to create a single comparator method which will be compatible with both PHP < 7.0 and PHP 7.0 or higher.
 >
 > In effect two declarations of the same object would be needed to be compatible with PHP < 7.0 and PHP 7.0 and higher and still allow for testing the object using the `assertObjectEquals()` assertion.
 >
 > Due to this limitation, it is recommended to only use this assertion if the minimum supported PHP version of a project is PHP 7.0 or higher; or if the project does not run its tests on PHPUnit >= 9.4.0.
+>
+> The implementation of this assertion in the Polyfills is PHP cross-version compatible.
 
 [limitations in how this assertion is implemented in PHPUnit]: https://github.com/sebastianbergmann/phpunit/issues/4707
 
-<!--
-COMMENT: No documentation available (yet) for this assertion on the PHPUnit site.
--->
+[`Assert::assertObjectEquals()`]: https://phpunit.readthedocs.io/en/stable/assertions.html#assertobjectequals
+
 
 ### Helper traits
 
@@ -687,6 +688,30 @@ Yes, this package can also be used when running tests via a PHPUnit Phar file.
 In that case, make sure that the `phpunitpolyfills-autoload.php` file is explicitly `require`d in the test bootstrap file.
 (Not necessary when the Composer `vendor/autoload.php` file is used as, or `require`d in, the test bootstrap.)
 
+### Q: How can I verify the version used of the PHPUnit Polyfills library ?
+
+For complex test setups, like when the Polyfills are provided via a test suite dependency, or may already be loaded via an overarching project, it can be useful to be able to check that a version of the package is used which complies with the requirements for your test suite.
+
+As of version 1.0.1, the PHPUnit Polyfills `Autoload` class contains a version number which can be used for this purpose.
+
+Typically such a check would be done in the test suite bootstrap file and could look something like this:
+```php
+$versionRequirement = '1.0.1';
+if ( class_exists( '\Yoast\PHPUnitPolyfills\Autoload' ) === false ) {
+    require_once `vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php`;
+} elseif ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
+    || version_compare( \Yoast\PHPUnitPolyfills\Autoload::VERSION, $versionRequirement, '<' )
+) {
+    echo 'Error: Version mismatch detected for the PHPUnit Polyfills. Please ensure that PHPUnit Polyfills ',
+        $versionRequirement, ' or higher is loaded.', PHP_EOL;
+    exit(1);
+} else {
+    echo 'Error: Please run `composer update` before running the tests.' . PHP_EOL;
+    echo 'You can still use a PHPUnit phar to run them, but the dependencies do need to be installed.', PHP_EOL;
+    exit(1);
+}
+```
+
 
 Contributing
 ------------

phpunitpolyfills-autoload.php

@@ -11,6 +11,13 @@
 	 */
 	class Autoload {
 
+		/**
+		 * Version number.
+		 *
+		 * @var string
+		 */
+		const VERSION = '1.0.1';
+
 		/**
 		 * Loads a class.
 		 *