Clobber Laravel Package

Product Decisions This Supports

• Legacy System Modernization: Enables incremental migration from PHPUnit 5/6/7 to PHPUnit 8 by preserving PCOV functionality without forcing a full upgrade, reducing technical debt in Laravel projects tied to older PHPUnit versions.
• CI/CD Stability: Mitigates flaky test results caused by Xdebug-PCOV conflicts in CI pipelines, ensuring consistent coverage reports and faster feedback loops for Laravel teams.
• Tooling Flexibility: Provides a lightweight, MIT-licensed solution for teams constrained by dependency policies or legacy codebases, avoiding vendor lock-in or custom development efforts.
• Build vs. Buy Decision: Eliminates the need to build a custom Xdebug/PCOV clobbering tool, saving engineering time and reducing maintenance overhead.
• Use Cases:
  • Laravel Legacy Projects: Teams using Laravel 5.x–7.x with PHPUnit 5/6/7 that cannot upgrade due to compatibility issues with newer PHPUnit versions.
  • Incremental Migration: Projects planning a phased move to PHPUnit 8+ but needing PCOV support in the interim.
  • CI/CD Optimization: Environments where Xdebug slows down tests or causes conflicts with PCOV, such as Dockerized Laravel setups.
  • Developer Productivity: Local development environments where toggling between Xdebug (for debugging) and PCOV (for coverage) is required.

When to Consider This Package

• Adopt if:

  • Your Laravel project uses PHPUnit 5/6/7 and requires PCOV for code coverage without upgrading to PHPUnit 8.
  • You encounter Xdebug-PCOV conflicts in CI/CD pipelines, leading to inconsistent or failed test runs.
  • Your team is blocked by PHPUnit 8’s strict type system (e.g., void return type issues) and cannot upgrade immediately.
  • You need a quick, low-risk solution to enable PCOV in legacy Laravel applications (e.g., Laravel 5.x–7.x).
  • Your CI/CD environment lacks native PCOV support, and Xdebug is causing performance bottlenecks or coverage inaccuracies.

• Look elsewhere if:

  • You are already using PHPUnit 8+, where PCOV is natively supported and no clobbering is needed.
  • Your project uses Xdebug 3+ with native PCOV support, eliminating the need for driver conflicts.
  • You prioritize long-term maintainability over short-term compatibility, as PHPUnit 5/6/7 are end-of-life and unsupported.
  • Your team has custom Xdebug extensions or relies on PCOV forks that may conflict with this package.
  • You are using PHP 8.0+, where PCOV is integrated into PHP core and Xdebug conflicts are less likely.

How to Pitch It (Stakeholders)

For Executives: "This package allows our Laravel team to maintain PCOV-based code coverage in legacy PHPUnit 5/6/7 environments without forcing a costly upgrade to PHPUnit 8. It resolves CI/CD instability caused by Xdebug-PCOV conflicts, ensuring reliable test results and faster feedback cycles. With minimal setup and no long-term maintenance burden, it’s a low-risk solution to unblock testing for legacy projects while we plan a phased migration to modern tooling. The MIT license and lightweight implementation reduce vendor risk, and it can be removed once we upgrade PHPUnit."

For Engineering: *"pcov/clobber is a drop-in CLI tool that replaces Xdebug with PCOV for PHPUnit 5/6/7, enabling accurate code coverage in Laravel projects stuck on older PHPUnit versions. To use it:

1. Add composer require pcov/clobber --dev.
2. Run vendor/bin/pcov clobber before tests in CI or local environments.
3. Run vendor/bin/pcov unclobber afterward to restore Xdebug for debugging. This fixes flaky CI runs and coverage discrepancies caused by Xdebug conflicts, with zero code changes. Ideal for teams migrating incrementally or constrained by legacy dependencies. Just add it to your phpunit.xml or CI scripts, and you’re done."*