Phpunit File Coverage Inspection Laravel Package

Technical Evaluation

Architecture Fit

• Granular Coverage Enforcement: The package excels in addressing a critical gap in PHPUnit’s default coverage reporting—per-file granularity—which aligns with modern quality gates requiring file-level accountability (e.g., critical paths like src/Lib/Config/ needing 100% coverage while legacy files tolerate 80%).
• Complementary to Existing Workflows: Integrates seamlessly with PHPUnit’s clover XML output (a standard) and CI/CD pipelines (via checkstyle/GitLab formats). Avoids reinventing coverage collection; focuses on analysis and enforcement.
• Config-Driven Flexibility: XML-based rules (phpfci.xml) enable hierarchical overrides (directory → file) and temporal exceptions (e.g., allow-uncovered-methods per file), reducing rigid global thresholds.

Integration Feasibility

• Low Friction: Requires no changes to PHPUnit test suite—only post-test execution via CLI. Compatible with PHP 8.1+ and modern Laravel (PHPUnit 10/11/12).
• Output Format Agnosticism:
  • Checkstyle: Plugs into tools like SonarQube, Jenkins, or GitHub Actions for trend analysis.
  • GitLab: Native integration with GitLab CI’s test coverage parsing (e.g., coverage: 'reports/gitlab.errors.json').
  • Text/Stdout: Fallback for debugging or simple pipelines.
• Baseline Generation: Automates historical coverage normalization (e.g., phpfci baseline coverage.xml --config phpfci.xml), critical for gradual enforcement in legacy codebases.

Technical Risk

Key Questions for TPM

1. CI/CD Integration Priority:
   • Should output prioritize checkstyle (for SonarQube) or GitLab (for native CI)?
   • Example: GitLab CI snippet:

     test:
       script: phpunit --coverage-clover coverage.xml
       after_script:
         - php vendor/bin/phpfci inspect coverage.xml --reportGitlab=gl-coverage.json --exit-code-on-failure
     

2. Enforcement Strategy:
   • Hard Block: Fail builds on violations (--exit-code-on-failure).
   • Soft Warning: Log issues but allow pipeline to continue (requires custom scripting).
3. Legacy Code Path:
   • How to phase in file-level thresholds? Use baseline to auto-generate rules from current coverage.
4. Tooling Ecosystem:
   • Does the team use SonarQube, CodeClimate, or other tools that could leverage checkstyle output?
5. Maintenance Burden:
   • Who owns updating phpfci.xml as code evolves? Consider auto-generating rules from coverage trends.

Integration Approach

Stack Fit

• Laravel Compatibility:
  • PHPUnit 10/11/12: Laravel 9+ uses PHPUnit 10 by default; this package supports all three.
  • Symfony Console: Underlying dependency (v8) is compatible with Laravel’s service container.
  • No Framework Coupling: Pure CLI tool; integrates via composer and post-test hooks.
• Toolchain Synergy:
  • PHPStan/PHPUnit: Can be chained in composer.json scripts:

    "scripts": {
      "test": "phpunit",
      "coverage-check": "php vendor/bin/phpfci inspect coverage.xml --reportGitlab=gl-coverage.json --exit-code-on-failure"
    }
    

  • GitHub Actions: Native support for GitLab format:

    - name: Upload coverage
      uses: actions/upload-artifact@v3
      with:
        name: coverage-results
        path: gl-coverage.json
    

Migration Path

1. Pilot Phase:
   • Add to composer.json (dev dependency):

     composer require --dev digitalrevolution/phpunit-file-coverage-inspection:^3.0
     

   • Generate baseline rules from current coverage:

     php vendor/bin/phpfci baseline coverage.xml --config phpfci.xml --baseDir=.
     

   • Start with non-blocking mode (remove --exit-code-on-failure).
2. Incremental Rollout:
   • Phase 1: Enforce directory-level rules (e.g., src/ = 90%, tests/ = 80%).
   • Phase 2: Add file-level overrides for critical paths (e.g., src/Contracts/ = 100%).
   • Phase 3: Enable method-level checks (disable allow-uncovered-methods for new files).
3. CI Integration:
   • Add to Laravel’s phpunit.xml or composer.json:

     <php>
         <env name="COVERAGE_EXIT_ON_FAILURE" value="1"/>
     </php>
     

   • Use GitHub Actions or GitLab CI to fail builds on violations.

Compatibility

Sequencing

1. Pre-requisite: Ensure PHPUnit generates coverage.clover (default in Laravel’s phpunit.xml).
2. Order of Execution:
   • Run tests → Generate coverage → Run inspection:

     php artisan test --coverage-clover=coverage.xml
     php vendor/bin/phpfci inspect coverage.xml --reportGitlab=gl-coverage.json
     

3. Post-Processing:
   • For SonarQube, convert checkstyle to Sonar’s format using phpcs or custom scripts.
   • For GitLab, use the native JSON output for coverage parsing.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: phpfci.xml may become outdated as files are renamed/moved.
  • Mitigation:
    • Use relative paths (e.g., src/Lib/ instead of /var/www/project/src/Lib/).
    • Automate path validation in CI (e.g., check if files exist before inspection).
• Rule Updates:
  • Process: Treat phpfci.xml like phpunit.xml—version-controlled and reviewed via PRs.
  • Tooling: Use PHPStorm’s XML editor or VSCode schemas for syntax highlighting.

Support

• Debugging:
  • Text Output: Use --reportText for human-readable errors:

    php vendor/bin/phpfci inspect coverage.xml --reportText
    

  • Checkstyle: Import into IDEs for clickable violations.
• Common Issues:
  • Path Mismatches: Verify --baseDir matches the project root.
  • False Negatives: Ensure coverage.clover is generated by PHPUnit (not a custom tool).
  • Performance: For large codebases (>50K LOC), cache coverage.clover to avoid reprocessing.

Scaling

• Large Codebases:
  • Parallelism: Split tests into suites (e.g., phpunit --testsuite=Unit), generate per-suite coverage, then merge:

    php vendor/bin/phpfci inspect coverage-unit.xml coverage-integration.xml
    

  • Incremental Checks: Use