Phpunit Legacy Adapter Laravel Package

Getting Started

This package provides a bridge to run tests written for PHPUnit 8–9 using newer PHPUnit versions (10+), by automatically mapping deprecated classes and namespaces. Start by installing via Composer: composer require --dev sanmai/phpunit-legacy-adapter. Once installed, the adapter loads automatically—no configuration needed for basic use—but you can opt-in to stricter behavior via config if desired. The first use case is typically upgrading a legacy Laravel project’s test suite (e.g., upgrading from Laravel 8 to 9/10) without rewriting all tests immediately.

Implementation Patterns

• Gradual migration: Keep legacy test syntax (e.g., PHPUnit\Framework\TestCase extends or assertSelectCount() calls) while running tests against PHPUnit 10+.
• Laravel integration: Works out-of-the-box with Laravel’s phpunit.xml and TestCase classes. No changes to tests/TestCase.php required—just add the adapter as a dev dependency.
• Testing multiple PHP/PHPUnit versions: Useful in CI pipelines where you want to test backward compatibility (e.g., via phpunit-legacy-adapter + vimeo/psalm or static analysis) without duplicating test files.

Gotchas and Tips

• Namespace mapping is shallow: Only core classes/namespaces are remapped. Custom traits, helpers, or third-party PHPUnit extensions may still break if they rely on removed internals (e.g., PHPUnit_Util_Log_TeamCity).
• Deprecation warnings will appear: Expect deprecation notices like assertRegExp() being deprecated—even with the adapter—because core PHPUnit logic itself changed. Consider running tests with --display-deprecations to surface issues early.
• Don’t overuse as a permanent solution: This is a migration aid, not a long-term compatibility layer. Plan to refactor deprecated assertions and class usage (e.g., replace assertNotNull($x) with assertThat($x, isNotNull())).
• Check phpunit-legacy-adapter version compatibility: Ensure the adapter version supports your target PHPUnit version (e.g., sanmai/phpunit-legacy-adapter ^10.0 for PHPUnit 10+). Its last release was May 2023, so verify alignment with PHPUnit 11+.