Coverage Guard Laravel Package

Product Decisions This Supports

• Targeted quality gates instead of vanity coverage: A PM can define coverage policy around critical Laravel surfaces—controllers, form requests, jobs, actions, service classes, payment/onboarding flows—rather than forcing an arbitrary global percentage.
• Legacy modernization without a big-bang cleanup: --patch mode lets teams enforce coverage only on new or changed code. This supports a roadmap where legacy modules are improved incrementally while new work is held to a higher standard.
• Build-vs-buy for CI enforcement: Avoids custom scripts to parse coverage XML, diff patches, map paths, and fail builds. Low runtime dependency footprint (nikic/php-parser) and MIT license reduce procurement friction.
• CI architecture decisions: merge and convert support parallel test jobs and artifact normalization. This matters when product delivery depends on fast CI and reliable coverage reporting across shards.
• Release-risk reduction: Enforce tests on high-risk changed methods before merge, reducing regressions in critical paths and the operational cost of post-release firefighting.
• Roadmap sequencing: Phase 1: observe coverage and configure clover.xml. Phase 2: enforce new-code-only via --patch. Phase 3: add rules for critical components. Phase 4: ratchet legacy coverage where business risk justifies it.
• Use cases: Laravel API controllers, queued jobs, billing/checkout flows, auth and permission logic, admin actions, integrations, and any method where an untested change has disproportionate customer or revenue impact.

When to Consider This Package

• Consider adopting when:
  • You run a PHP 8.1+ Laravel application with PHPUnit-compatible coverage output, ideally clover.xml.
  • Your team needs method-level or new-code-only enforcement because global coverage thresholds are too blunt or block legacy progress.
  • You want to enforce coverage on specific architectural roles, such as “all controller methods” or “changed methods above N executable lines.”
  • You run parallel CI jobs and need coverage merge/convert tooling, or you want GitLab MR coverage percentages via patch-coverage.
  • You accept a small OSS dependency with low transitive risk and can assign an engineering owner for rule configuration.
• Look elsewhere when:
  • You only need an overall coverage percentage; native PHPUnit output, Codecov, SonarQube, or similar may be sufficient.
  • Your pipeline does not produce PHPUnit-compatible coverage artifacts, or your stack is non-PHP/non-PHPUnit.
  • You need enterprise support, SLA-backed maintenance, broad adoption evidence, or a long vendor track record. The package has limited visible adoption (60 stars, 0 dependents) and release metadata should be validated.
  • You need branch coverage, mutation testing, runtime profiling, or non-code quality metrics.
  • Your team cannot maintain path mapping and rule tuning across local/CI/monorepo environments; misconfigured thresholds can create false positives.
  • Pest or other PHPUnit-based runners may work if they emit compatible coverage artifacts, but validate before committing to adoption.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, MIT-licensed CI guardrail that lets us enforce test coverage where it matters—critical Laravel code and new changes—without demanding 100% coverage of legacy systems. It reduces regression risk, avoids custom coverage tooling, and supports incremental modernization. Start with a pilot enforcing coverage only on new/modified code, measure blocked PRs and escaped defects, then expand to critical modules. Key caveat: it is a small OSS package, so assign ownership and validate maintenance before making it a mandatory gate.

For engineering: Add it as a dev dependency, generate clover.xml in the Laravel/PHPUnit CI job, run coverage-guard init, and add coverage-guard check clover.xml --patch changes.patch to PR pipelines. Configure EnforceCoverageForMethodsRule with conservative thresholds, use path mapping for CI/local differences, and use merge for parallel jobs. Prefer clover for IDE/GitLab compatibility and avoid the PHP coverage format for large suites. Pilot on new code first, tune minExecutableLines and percentage thresholds, and explicitly validate behavior around Laravel dynamic methods, generated code, and exclusions before expanding enforcement.