Phpunit Legacy Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev sanmai/phpunit-legacy-adapter:"^6.4 || ^8.2.1"
   

   Ensure compatibility with your PHPUnit version (6.x or 8.x).

2. Configuration: Add the adapter to your phpunit.xml (or phpunit.xml.dist) under <php>:

   <php>
       <autoload>
           <classmap suffix=".php" />
       </autoload>
       <server name="PHPUNIT_LEGACY_ADAPTER" value="1" />
   </php>
   

3. First Use Case: Run tests with PHPUnit 8+ on PHP 7.0/5.6:

   ./vendor/bin/phpunit
   

   The adapter automatically patches setUp(), tearDown(), and other template methods to work without void return type declarations.

Implementation Patterns

Workflow Integration

1. Legacy Test Migration:

   • Use the adapter to gradually modernize tests without rewriting all at once.
   • Example: Keep setUp() without void in legacy tests while adding it to new tests.

2. CI/CD Pipeline:

   • Run tests on PHP 7.0/5.6 (legacy) and PHP 8.x (modern) in parallel:

     # .github/workflows/tests.yml
     jobs:
       test-legacy:
         runs-on: ubuntu-18.04
         steps:
           - uses: actions/checkout@v4
           - run: docker run --rm -v $(pwd):/app composer:php7.0 install
           - run: docker run --rm -v $(pwd):/app composer:php7.0 run test
       test-modern:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: composer install
           - run: composer test
     

3. Hybrid Assertions:

   • Mix legacy assertions (e.g., assertEquals) with modern assertions (e.g., assertSame) in the same test suite.
   • The adapter ensures backward compatibility for assertions dropped in PHPUnit 8+.

4. Test Suite Isolation:

   • Use grouping to separate legacy and modern tests:

     // Legacy test (PHP 7.0/5.6)
     class LegacyTest extends \PHPUnit\Framework\TestCase {
         public function setUp() { ... } // No void return
     }
     
     // Modern test (PHP 8.x)
     class ModernTest extends \PHPUnit\Framework\TestCase {
         public function setUp(): void { ... } // Explicit void
     }
     

Gotchas and Tips

Pitfalls

1. Assertion Conflicts:

   • PHPUnit 8+ deprecated assertions like assertTrue() in favor of assertThat(). The adapter does not restore deprecated assertions—only template methods.
   • Fix: Use assertThat() or manually add legacy assertions via assertTrue() in a trait.

2. PHP Version Mismatch:

   • The adapter only works with PHP 7.0+. Tests on PHP 5.6 will still fail due to language limitations (e.g., no scalar type hints).
   • Fix: Use Docker or VMs to test PHP 5.6 separately.

3. Static Analysis Tools:

   • Tools like PHPStan or Psalm may flag setUp() without void as an error, even with the adapter.
   • Fix: Add a custom rule or suppress checks for legacy tests:

     <!-- phpstan.neon -->
     parameters:
         excludePaths:
             - tests/Legacy/
     

4. Autoloading Issues:

   • The adapter must be autoloaded before PHPUnit. Ensure it’s listed in composer.json under autoload-dev:

     "autoload-dev": {
         "psr-4": {
             "Sanmai\\LegacyAdapter\\": "vendor/sanmai/phpunit-legacy-adapter/src"
         }
     }
     

Debugging Tips

1. Verify Adapter Activation:

   • Add a test to check if the adapter is loaded:

     public function testAdapterLoaded() {
         $this->assertTrue(class_exists(\Sanmai\LegacyAdapter\LegacyAdapter::class),
             "Adapter not loaded!");
     }
     

2. Log Template Method Calls:

   • Override template methods to debug:

     public function setUp() {
         error_log("Legacy setUp() called!");
         parent::setUp(); // If using PHPUnit 8+
     }
     

3. Isolate Legacy Tests:

   • Use @group legacy and filter tests:

     ./vendor/bin/phpunit --group legacy
     

Extension Points

1. Custom Template Methods:

   • Extend the adapter to support additional methods (e.g., setUpBeforeClass):

     // src/LegacyAdapter/Extensions.php
     namespace Sanmai\LegacyAdapter;
     
     class Extensions {
         public static function patchMethods() {
             LegacyAdapter::patchMethod('setUpBeforeClass');
         }
     }
     

   • Call Extensions::patchMethods() in a bootstrap file.

2. Assertion Backporting:

   • Manually backport missing assertions (e.g., assertInternalType) by extending the adapter’s Assert class.

3. PHPUnit Event Hooks:

   • Use the adapter’s events to log or modify test execution:

     $this->addListener(new \Sanmai\LegacyAdapter\Event\LegacyTestListener());