Phpunit Polyfills Laravel Package

Getting Started

Start by installing the package as a dev dependency: composer require --dev yoast/phpunit-polyfills:^4.0. Ensure your test bootstrap loads the polyfill autoloader—either via Composer’s vendor/autoload.php or explicitly require vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php. Your test classes must extend PHPUnit\Framework\TestCase (directly or indirectly) for polyfills to work. The simplest first step is to use use Yoast\PHPUnitPolyfills\TestCases\TestCase; as your base class, which automatically applies all relevant polyfills. Then, begin using modern assertions like $this->assertIsList($array) or self::assertObjectHasProperty('name', $object) even if your CI runs older PHPUnit versions.

Implementation Patterns

• Trait-based granular usage: Import only needed polyfill traits (e.g., use Yoast\PHPUnitPolyfills\Polyfills\AssertObjectProperty;) in specific test classes when avoiding full TestCase replacement—ideal for large, modular codebases.
• TestCases in lieu of native TestCase: Extend Yoast\PHPUnitPolyfills\TestCases\TestCase for straightforward, all-in-one integration; especially useful for new test suites targeting multiple PHPUnit versions.
• Conditional skipping for fragile assertions: Use helper methods like shouldClosedResourceAssertionBeSkipped() inside test methods or setUpBeforeClass() to gracefully handle known PHP bugs (e.g., for libxml resources).
• Version-specific strategy planning: Align your polyfill version (e.g., 4.x for PHPUnit 7.5–12.x excluding 10) with your project’s PHPUnit matrix. Drop polyfill usage by removing older PHPUnit versions from phpunit.xml or composer.json constraints when upgrading the test suite to a newer baseline.

Gotchas and Tips

• Avoid PHPUnit 10 in 4.x series: The 4.x release explicitly excludes PHPUnit 10 support—double-check your phpunit/phpunit constraint to avoid silent failures.
• Forward-compatibility ≠ backward-feature parity: Features removed in current PHPUnit (e.g., expectDeprecation() in 10+) won’t be re-added—even if polyfilled. Always verify feature support per the README’s compatibility matrix.
• Trait vs. TestCase naming conflicts: If using polyfill traits in addition to extending the polyfill TestCase, you may get trait method conflicts; prefer one pattern consistently.
• Autoloading gotcha: For non-Composer setups (e.g., custom phpunit.xml bootstrap), explicitly require phpunitpolyfills-autoload.php or include the path in autoload_files—otherwise polyfills silently do nothing.
• Debug tip: If an assertion like assertObjectHasProperty() fails with “method not found”, verify use statements, extends TestCase, and the phpunitpolyfills-autoload.php inclusion. Run composer dump-autoload -o to rule out classmap issues.