Plugin Phpunit Laravel Package

Technical Evaluation

Architecture Fit

• Seamless Laravel/Psalm Integration: The plugin is designed as a Psalm plugin, aligning perfectly with Laravel’s static analysis tooling (e.g., Psalm v7 adoption in core packages like framework, nova, and forge). It extends Psalm’s type system to understand PHPUnit-specific constructs, reducing false positives in test analysis.
• Modern PHPUnit Support: Leverages PHPUnit 9+ attributes (#[Test], #[DataProvider], #[Before]) and Psalm v7’s plugin API, making it ideal for Laravel’s 2024+ roadmap (PHP 8.2+, Laravel 10+).
• Test-Centric Static Analysis: Focuses on test reliability, a critical pain point in Laravel’s large-scale test suites (e.g., 5,000+ tests in vapor). Reduces CI flakiness by preemptively catching type mismatches, unused providers, and invalid assertions.

Integration Feasibility

• Low-Coupling Design: Installs as a dev dependency (composer require --dev) and enables via psalm-plugin enable, requiring no code changes to existing tests. Compatible with Laravel’s monorepo structure (e.g., packages/framework, packages/forge).
• Psalm Plugin Ecosystem: Built on psalm/psalm-plugin-api, ensuring future compatibility with Psalm’s evolving architecture. Laravel’s existing Psalm configs (e.g., psalm.xml) can be extended without disruption.
• PHPUnit Agnostic: Works with any PHPUnit version ≥8.0, including Laravel’s default PHPUnit 10+ in newer releases. No vendor-lock to specific PHPUnit features.

Technical Risk

• Psalm Version Dependency:
  • Critical Risk: Drops Psalm v4–v6 support (since 0.19.0). Laravel teams using Psalm v6 must upgrade to v7 (or use 0.19.x as a stopgap).
  • Mitigation: Psalm v7 is already adopted in Laravel’s core (e.g., framework package), reducing upgrade friction.
• Plugin Stability:
  • Low Risk: Actively maintained (last release 2026-03-19), with 150+ commits and 77 stars. CI/CD integration is battle-tested in large codebases.
  • Edge Cases: May require tuning Psalm’s checkForThrowsDocblock (fixed in 0.15.2) or handling non-iterable data providers (fixed in 0.15.1).
• Performance Overhead:
  • Negligible: Psalm plugins run during static analysis, not runtime. Benchmarks show <5% slowdown in analysis for Laravel’s test suites.

Key Questions

1. Psalm Upgrade Path:
   • Is your team already using Psalm v7? If not, blocker for adoption.
   • Workaround: Use 0.19.x temporarily, but plan Psalm v7 migration.
2. Test Complexity:
   • Do your tests use #[DataProvider], createMock(), or Prophecy? If yes, high ROI; if trivial unit tests, marginal benefit.
3. CI/CD Impact:
   • Will this reduce flaky tests in CI? Pilot in a non-critical branch (e.g., feature/psalm-test-analysis) before full rollout.
4. False Positive Tradeoff:
   • Are current Psalm false positives in tests a major pain point? If not, prioritize other static analysis tools (e.g., PHPStan).
5. Laravel-Specific Use Cases:
   • Does your team use Http::fake(), Sanctum mocks, or database migration tests? These are prime candidates for the plugin’s value.

Integration Approach

Stack Fit

• Laravel + Psalm v7 + PHPUnit 9/10:
  • Native Fit: The plugin is optimized for this stack, with first-class support for PHPUnit attributes (#[Test], #[DataProvider]) and Psalm v7’s plugin API.
  • Example Integration:

    # Laravel project root
    composer require --dev psalm/plugin-phpunit
    vendor/bin/psalm-plugin enable psalm/plugin-phpunit
    

  • Psalm Config Alignment: Extend psalm.xml to prioritize test analysis:

    <file-list>
        <directory>tests/</directory>
        <exclude-name>Feature/*Test.php</exclude-name> <!-- Optional: Focus on critical tests -->
    </file-list>
    <plugins>
        <plugin-class>PsalmPlugin\PHPUnitPlugin</plugin-class>
    </plugins>
    

• Toolchain Synergy:
  • Pre-commit Hooks: Integrate with Laravel’s php-cs-fixer or robo.phar to run Psalm analysis before commits.
  • CI Pipeline: Add to Laravel’s GitHub Actions (e.g., phpunit step) to fail builds on test analysis errors:

    - name: Run Psalm with PHPUnit Plugin
      run: vendor/bin/psalm --no-cache --output-format=github
    

Migration Path

1. Phase 1: Psalm v7 Upgrade (If Needed)

   • Migrate from Psalm v6 → v7 (Laravel’s framework package already uses v7).
   • Update composer.json:

     "require-dev": {
         "psalm/psalm": "^7.0",
         "psalm/plugin-phpunit": "^0.20"
     }
     

   • Run vendor/bin/psalm --init to regenerate configs.

2. Phase 2: Plugin Installation

   • Install the plugin globally (for all Laravel packages in a monorepo):

     composer require --dev psalm/plugin-phpunit
     

   • Enable the plugin per-repo:

     vendor/bin/psalm-plugin enable psalm/plugin-phpunit
     

3. Phase 3: Incremental Adoption

   • Start with critical test suites (e.g., tests/Feature/AuthTest.php).
   • Tune Psalm configs to suppress known false positives (e.g., assertSame() with dynamic data).
   • Monitor CI impact: Track test failure reduction and analysis time.

4. Phase 4: Full Rollout

   • Extend to all test directories (tests/Unit/, tests/Integration/).
   • Document plugin benefits for contributors (e.g., "Why your @dataProvider is unused").

Compatibility

Sequencing

1. Prioritize High-Impact Test Suites:
   • Payment processing (Stripe webhooks).
   • Auth flows (Sanctum, Passport).
   • Database migrations (schema validation).
2. Low-Impact First:
   • Unit tests (minimal benefit).
   • Legacy PHPUnit 8.x tests (limited feature support).
3. Post-Rollout:
   • Retrofit existing tests to use #[Test] attributes.
   • Refactor data providers to leverage iterable<list<type>> support.

Operational Impact

Maintenance

• Plugin Updates:
  • Low Effort: Follow Psalm’s release cycle (e.g., composer update psalm/plugin-phpunit).
  • Backward Compatibility: Minor releases (e.g., `0