Polyfill Laravel Package

Getting Started

Install via Composer:

composer require --dev phpunitgoodpractices/polyfill

No configuration is required. Once installed, polyfills are auto-loaded via Composer’s autoloader — just run phpunit and they activate automatically in the test environment. Start by using newer PHPUnit features (e.g., assertDoesNotAssertAnything() or modern string assertion helpers) in tests; if running on older PHP/PHPUnit versions, the polyfill ensures they work consistently. First use case: write a test using assertArrayNotHasKey() on PHP 7.1 — it will still pass if the polyfill is loaded, even though that method was added in PHPUnit 9.1.

Implementation Patterns

• Autoloading-only usage: The package uses autoload-dev in its composer.json, so it only loads during test runs — zero impact on production. Ideal for libraries targeting PHP 7.4–8.2+ with varying PHPUnit versions.
• Version-gap bridging: Use modern assertion helpers (e.g., assertJsonStringEqualsJsonString()) or expectations (e.g., expectsOutputFromInput()) without version guards.
• CI compatibility layer: Wrap the polyfill in your CI setup (e.g., php:8.0 + phpunit/phpunit:^9 and php:7.4 + phpunit/phpunit:^8) to unify test behavior. No more “works on PHP 8, breaks on 7.4” noise.
• Non-intrusive integration: No code changes needed — it simply extends missing symbols into PHPUnit\Framework or global namespace as appropriate. Ideal for legacy codebases upgrading gradually.

Gotchas and Tips

• Archived package: Since it’s archived (as of 2023-03-07), don’t expect new features — only bugfixes. Verify it still works with PHPUnit 10+ (use composer require phpunitgoodpractices/polyfill:^1.3 and test edge cases).
• Namespace collisions: Avoid naming conflicts — the polyfill never overrides existing functions. Check src/ to see exactly which symbols it injects (e.g., assertStringContainsString, assertStringEndsNotWith, assertJsonStringEqualsJsonString).
• No runtime side effects: It only affects the test environment. If you accidentally include it in production (e.g., via require-dev misconfiguration), PHP will throw a fatal error on double declaration — use --no-dev in production builds.
• Debugging tip: Run phpunit --filter TestName --verbose and inspect autoloader output via composer dump-autoload --dev -v to confirm polyfill classes are loaded.
• Extension points: It intentionally offers no config — to extend coverage, fork and add a polyfill for your missing helper (e.g., str_starts_with() for PHP < 8), then replace via repositories in composer.json.