PHPUnit Polyfills
A set of polyfills for changed PHPUnit functionality to enable cross-version compatible PHP tests.
What is PHPUnit Polyfills?
PHPUnit Polyfills is a library that provides polyfills for changed PHPUnit functionality, enabling developers to write PHPUnit tests that are compatible across multiple PHPUnit versions. It solves the problem of API changes between PHPUnit releases by allowing tests to use the latest assertions and methods while still running on older PHPUnit versions.
PHP developers and teams who maintain test suites that need to run across different PHPUnit versions, such as library maintainers, plugin developers, or projects with complex dependency matrices.
Developers choose PHPUnit Polyfills because it eliminates the need to constantly rewrite tests when upgrading PHPUnit, reduces maintenance overhead, and provides a smooth migration path by supporting forward compatibility with the latest PHPUnit features.
Overview
Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit cross-version compatible tests
Use Cases
Best For
- Maintaining test suites across multiple PHPUnit versions
- Writing forward-compatible tests for PHP libraries
- Migrating from PHPUnit 7/8/9 to PHPUnit 11/12
- Polyfilling deprecated PHPUnit assertions like assertArraySubset
- Handling signature mismatches in TestCase fixture methods
- Ensuring test compatibility in CI/CD pipelines with varying PHPUnit versions
Not Ideal For
- Projects exclusively using PHPUnit 10.x, as the polyfills have limited support for this version in recent series
- Teams that prioritize immediate refactoring over polyfill usage to avoid perceived technical debt
- Test suites requiring the TestListener polyfill on PHPUnit 10/11/12, as it's not yet compatible per the README
- Simple projects with no cross-version testing needs, where polyfills add unnecessary complexity
Pros & Cons
Pros
Enables writing tests for PHPUnit 12.x and running them on versions 7.5 to 12.x, allowing early adoption of new syntax without breaking older environments.
Provides individual traits for specific features like AssertContainsOnly or ExpectExceptionMessageMatches, making integration flexible and targeted.
Offers custom TestCase classes that manage signature mismatches in fixture methods like setUp and tearDown, simplifying cross-version test writing.
Supports PHPUnit 7.5 to 12.x with detailed compatibility tables, though excludes PHPUnit 10.x for certain polyfills in recent series.
Cons
The TestListener polyfill is not compatible with PHPUnit 10.x, 11.x, and 12.x, forcing users to stay on older polyfill versions or refactor, as admitted in the README.
Some polyfills, like assertIsClosedResource, are affected by bugs in PHP itself (e.g., in libxml), requiring workarounds and potentially skipping tests, adding complexity.
Using the library with PHPUnit Phar files or in CI/CD pipelines like GitHub Actions requires explicit autoloading steps, which can be error-prone for inexperienced users.
Frequently Asked Questions
Related Projects
PHPUnitThe PHP Unit Testing framework.
MockeryMockery is a simple yet flexible PHP mock object framework for use in unit testing with PHPUnit, PHPSpec or any other testing framework. Its core goal is to offer a test double framework with a succinct API capable of clearly defining all possible object operations and interactions using a human readable Domain Specific Language (DSL).
ProphecyHighly opinionated mocking framework for PHP 5.3+
CodeceptionFull-stack testing PHP framework
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.