Doctrine Custom Types Bundle Laravel Package

Technical Evaluation

Architecture Fit The package aligns well with Laravel/PHP ecosystems, particularly for projects leveraging Symfony components (e.g., PHPUnit bridge) or requiring class aliasing fixes (critical for PHP 8.x+ compatibility). The shift to Symfony’s PHPUnit bridge reduces vendor lock-in and improves test consistency, making it ideal for teams adopting modern PHP testing practices.

Integration Feasibility

• High for Laravel 8.x+ projects due to PHP 8.x support and Symfony integration.
• Moderate for legacy Laravel 7.x or PHP 7.x projects (may require composer constraints or aliasing workarounds).
• Low for projects using non-Symfony PHPUnit bridges (e.g., custom bridges) or PHP < 7.4 (due to PHPUnit 9.x+ requirements).

Technical Risk

• Breaking Changes:
  • PHP 7.x projects may fail if using older PHPUnit bridges (now enforced via Symfony’s bridge).
  • Class aliasing fixes (PHP 8.x case sensitivity) could expose undetected namespace issues in custom code.
• Deprecations:
  • Prefer-lowest 5.2.12 for Symfony bridge suggests future minimum version hikes (e.g., PHPUnit 10.x).
• Mitigations:
  • Test in a staging environment with composer why-not to audit dependency conflicts.
  • Use composer require --dev symfony/phpunit-bridge:^5.2 to isolate changes.

Key Questions

1. Does the project use custom PHPUnit bridges or non-Symfony test utilities? If yes, assess migration effort.
2. Are there PHP 7.x dependencies blocking upgrades? If so, evaluate aliasing fallbacks.
3. Will the team adopt PHP 8.x+ soon? If not, consider pinning to 1.4.* to avoid forced upgrades.
4. How are class aliases currently handled? Audit for case-sensitive namespace collisions (e.g., App\Foo vs app\Foo).

Integration Approach

Stack Fit

• Best Fit: Laravel 8.x/9.x + PHP 8.0–8.3 + PHPUnit 9.x/10.x.
• Workarounds Needed:
  • Laravel 7.x: Add composer config minimum-stability dev and pin symfony/phpunit-bridge:^5.2.
  • PHP 7.x: Use platform-check or Docker to enforce PHP 8.x during CI tests.
• Anti-Patterns: Avoid mixing this package with phpunit/phpunit directly (Symfony bridge will override configs).

Migration Path

1. Pre-Upgrade:
   • Run composer why symfony/phpunit-bridge to detect conflicts.
   • Backup phpunit.xml (Symfony bridge may override globals like <php> tags).
2. Upgrade:

   composer require vendor/package:^1.4.5 --dev
   composer require --dev symfony/phpunit-bridge:^5.2
   

3. Post-Upgrade:
   • Fix case-sensitive class aliases (e.g., use App\Services\Foo; → use App\Services\foo; if PHP 8.x).
   • Update phpunit.xml to extend Symfony’s bridge config:

     <extensions>
         <extension class="Symfony\Bridge\PhpUnit\SymfonyTestsReflectionExtension"/>
     </extensions>
     

Compatibility

• PHPUnit: Requires 9.5.x (for PHP 8.x) or 8.5.x (for PHP 7.4+). Downgrade tests for older PHP versions.
• Laravel: Tested with 8.x/9.x; 7.x may need composer.json tweaks:

  "config": {
    "platform-check": false,
    "preferred-install": "dist"
  }
  

• Composer: Uses prefer-lowest for Symfony bridge to avoid over-constraining.

Sequencing

1. Critical Path: Upgrade PHPUnit bridge first (highest risk).
2. Parallel: Fix class aliases and update test suites.
3. Validation: Run ./vendor/bin/phpunit --debug to catch Symfony bridge conflicts.

Operational Impact

Maintenance

• Pros:
  • Reduced test flakiness via Symfony’s bridge (e.g., better mocking, coverage tools).
  • PHP 8.x optimizations may improve test suite performance.
• Cons:
  • Symfony bridge adds ~50MB to vendor/ (monitor CI/CD disk usage).
  • PHPUnit config drift risk if custom extensions are used.

Support

• Debugging:
  • Use ./vendor/bin/phpunit --debug to inspect Symfony bridge overrides.
  • Check composer why symfony/phpunit-bridge for dependency chains.
• Rollback:
  • Downgrade to 1.4.4 if aliasing breaks:

    composer require vendor/package:1.4.4 --dev
    

Scaling

• Performance: Minimal impact on runtime; test suite scaling depends on PHPUnit parallelization (Symfony bridge supports --parallel).
• Resource Usage: PHP 8.x JIT may reduce test execution time by 10–20% (benchmark with/without).

Failure Modes

Ramp-Up

• Team Training:
  • Document Symfony bridge features (e.g., symfony/phpunit-bridge:mock-all).
  • Train QA on --debug flags for faster issue resolution.
• Onboarding:
  • Add a UPGRADE.md section for the package’s PHPUnit bridge changes.
  • Example CI template:

    jobs:
      test:
        runs-on: ubuntu-latest
        strategy:
          matrix:
            php: [8.1, 8.2]
        steps:
          - uses: shivammathur/setup-php@v2
            with:
              php-version: ${{ matrix.php }}
              coverage: none
          - run: composer install --prefer-dist
          - run: ./vendor/bin/phpunit --coverage-text