Crap Metric Analyzer Laravel Package

Getting Started

• Install with composer require --dev <vendor>/<package> (confirm the exact name in the release/README) and, if the package ships a config file, publish it with php artisan vendor:publish.
• Look first at the README’s quick-start and the package’s tests for example clover fixtures — those show the exact report shape the parser expects.
• First use case: generate a clover report from your test suite, then feed it to the package.

php artisan test --coverage-clover=build/coverage/clover.xml

Then point the package at that file through its config or API. If you are on v1.0.4+, verify your generated clover file matches the newest structure before wiring it into CI.

Implementation Patterns

• CI coverage gate: Generate clover.xml in CI, parse it with the package, and fail the build when coverage drops below a threshold. Keep the clover generation and parsing steps in the same job so the report matches the code under test.
• Artisan command wrapper: Wrap parsing in a small Artisan command (e.g. coverage:report) so local developers and CI use the same code path. Return a non-zero exit code when thresholds fail.
• Per-directory or per-class reporting: Parse once, then aggregate results by namespace or directory to produce team-facing summaries. Cache the parsed result if you run multiple checks against the same report.
• Pull-request feedback: Generate clover on the PR branch, parse it, and post a coverage summary. Store the report as a CI artifact for debugging.
• Version alignment: Since v1.0.4 only supports the newest clover structure, align PHPUnit/Pest and the package version in composer.json. Treat the clover schema as part of your dependency contract.

// Illustrative: parse once, then apply your own threshold logic.
$report = $coverage->parse('build/coverage/clover.xml');

if ($report->totalPercentage() < 80.0) {
    return self::FAILURE;
}

Gotchas and Tips

• Newest clover structure only: v1.0.4 explicitly states the package will support only the newest clover structure. Older PHPUnit versions or custom coverage tools may emit a different structure and fail to parse. Regenerate with a current PHPUnit/Pest release before filing a bug.
• Pin and upgrade deliberately: Pin the package and PHPUnit versions together. When upgrading PHPUnit, regenerate a sample clover file and run the package’s parser against it before merging.
• Validate the XML first: If parsing fails, open the clover file and confirm it is well-formed and non-empty. Coverage tools can emit empty reports when no tests execute or when coverage drivers (Xdebug/PCOV) are missing.
• Path handling: Clover files contain file paths relative to the environment that generated them. Parsing a report generated in a different working directory or container can produce confusing path-based results. Generate and parse in the same context where possible.
• Missing coverage driver: A valid clover file requires a coverage driver. In CI, confirm Xdebug or PCOV is enabled; otherwise PHPUnit may produce no report and the package will have nothing to parse.
• Debugging strategy: Start with the package’s test fixtures, compare your clover file’s root elements and attributes against them, and isolate whether the issue is report generation or parsing.
• Extension points: If you need custom reporting, keep parsing and presentation separate. Parse the clover file once into the package’s model, then build your own formatter or threshold checker on top so future clover-schema changes are isolated to the parsing layer.