Clover Merge Laravel Package

Product Decisions This Supports

• Test-suite parallelization / CI sharding. Any investment in faster feedback loops (parallel PHPUnit runs via paratest, matrix jobs across PHP versions, splitting unit vs. integration suites) multiplies your coverage artifacts. This package is the cheap unblocker that lets you keep a single coverage number after you stop running tests serially — a prerequisite for the "cut CI time in half" roadmap item.
• Monorepo vs. polyrepo and package-splitting calls. The moment you split a codebase into packages or modules, coverage gets fragmented per package. Knowing a ~100-line merge step exists de-risks that architecture decision: you can split without losing the org-wide coverage gate that leadership and auditors actually look at.
• Coverage gate policy. One merged clover file lets you set one threshold ("no PR below 80% overall") instead of negotiating per-suite thresholds that are easy to game by leaving untested code in the suite that isn't gated. v1.0.5's new --enforce/-e <pct> flag nominally lets the merger be the gate, but the enforcement logic is roughly three lines of arithmetic over the merged totals — do not make an unmaintained binary the system of record for pass/fail. Use -e as a local convenience, and keep the authoritative gate in your own CI script or in the coverage consumer you already pay for.
• Build vs. buy. This is the evidence for not buying. Coverage aggregation of this kind is a commodity: it exists as an OSS utility, as phpcov merge inside phpunit/php-code-coverage, and as a native feature of most coverage vendors. It should never appear as a line item in a SaaS negotiation. The new threshold flag does not change this — a merge plus a covered/total comparison is not a product.
• Legacy PHP modernization guardrails. During a framework/version migration, combined coverage is one of the few objective signals that you are not quietly deleting test surface as you refactor. A merged report makes before/after comparability possible.
• Adoption of a parallel toolchain. If the team wants to move to sharded CI, this is a dependency decision on the critical path; treat it as a spike item, not a platform bet.

When to Consider This Package

Consider it when all of the following hold:

• You genuinely produce two or more clover XML files per pipeline (sharded jobs, multiple suites, per-package runs in a monorepo) and cannot or will not consolidate the test run itself.
• Your downstream consumer only ingests a single file — a custom gate script, a dashboard, an internal quality service, or a Sonar/Codecov-style integration you've configured with one path.
• You want a zero-config CLI step rather than adding a dependency on the full phpunit/php-code-coverage toolchain just for phpcov merge.
• You are on a PHP runtime the 2018-era code still parses under, verified by a one-hour spike in your own CI image — the v1.0.5 notes do not add a PHP 8.x compatibility statement, so this check still stands.
• If you intend to use --enforce, you have validated its semantics against your own numbers: which metric the threshold applies to (line vs. method vs. per-file), how rounding works, and what the exit code does under partial/empty input. A gate that silently no-ops or misfires is worse than no gate.

Look elsewhere — or write the 40 lines yourself — when:

• A single test job already emits one clover file. This package then solves a problem you don't have.
• Your consumer accepts multiple report paths (SonarQube's sonar.php.coverage.reportPaths takes a comma-separated list) or merges server-side (Codecov, Coveralls). Prefer configuring the tool you already pay for.
• You want something maintained. The v1.0.5 release is the first sign of life since October 2018 and is a net positive signal, but it is one release on a repo with 9 stars, 0 dependents and a single maintainer. There is still no security response path, no published PHP 8 compatibility matrix, and no community to absorb a breaking change in the clover schema.
• You need branch/line/path-level correctness guarantees. Merging coverage XML is deceptively fiddly (duplicate file entries, differing path roots across CI runners, method-level counters). An unmaintained merger with no test suite you trust is a silent-data-corruption risk in exactly the metric people argue about — and now that it can fail a build, a bug in it is a blocked PR, not just a wrong number.
• You only want the threshold check. That is trivially yours to own; don't adopt a merger to get an if statement.

Default recommendation: treat it as a reference implementation. Vendor or fork it, pin it, and add a fixture-based test that asserts merged totals equal the sum of inputs — and, if you use -e, that the threshold outcome matches the expected exit code at boundary values. That converts a stale 9-star dependency into an owned 100-line utility with no supply-chain surface. Pin to an exact version and do not float across major/minor updates automatically: this is now code that can turn your pipeline red.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can cut CI time roughly in proportion to how much we parallelize the PHP test suite, but today that either slows the pipeline or blinds us to total coverage. A small MIT-licensed utility — about a hundred lines, no runtime dependencies, no licence cost — recombines the per-job coverage reports into the single number we already report upward, so parallelizing tests doesn't quietly weaken our quality gate. Its newest version can also fail the build when merged coverage drops below a threshold, which is convenient but not a reason to depend on it: it is a single-maintainer project that went roughly seven years without a release before this one. Zero budget impact, low technical risk, and it removes the main objection to the CI-speed work.

For engineering (short version): Use it as a one-step CLI in the coverage stage (clover-merge a.xml b.xml -o coverage.xml) when you have sharded jobs or split suites. v1.0.5 adds --enforce/-e <pct>, which exits non-zero below the threshold — useful locally, but keep the authoritative gate in our own script so a bug in a pinned third-party binary can't block PRs on its own terms. Do not take a runtime dependency on the upstream repo: one release after a long dormancy, zero dependents, and we still can't verify PHP 8 behaviour or XXE hardening in its XML parsing. Fork it into tools/ under our own CI, pin the version, add tests asserting merged totals equal the sum of inputs plus threshold boundary cases, and disable external entity loading in the parser. If phpcov merge from phpunit/php-code-coverage is already in our lockfile, prefer that and skip this entirely. Either way, first check whether Sonar/Codecov can take the multiple paths directly — if they can, this whole card closes as "no action."