Coverallskit Laravel Package

Getting Started

cloak/coverallskit is a thin PHP wrapper around the Coveralls submission API: you feed it a Clover-format coverage report (the XML PHPUnit writes) plus a handful of git/CI facts (branch, commit, service name, job id, repo token) and it POSTs a JSON payload to coveralls.io. It does not produce coverage — that is still PHPUnit/Xdebug's job.

Before writing any code, read the repository in this order:

1. composer.json — PHP constraint and the HTTP client it pulls in. This is a 2015-era package, so expect php: >=5.4 and Guzzle 5/6. That constraint is the single biggest predictor of whether you can install it at all.
2. README.md — the constructor signature and the one end-to-end example. On a package this small there is no docs site; the README is the API.
3. src/ — usually 3–6 classes: a client/uploader, a payload builder, and one or more "environment" adapters that sniff Travis/Jenkins env vars.
4. tests/ — the fastest way to see the exact payload shape and which env vars are read.

Minimal first use case, run inside CI right after the test step:

# 1. produce the report
vendor/bin/phpunit --coverage-clover build/logs/clover.xml

# 2. hand it to the client (see README for the exact class/ctor)
php bin/coveralls.php build/logs/clover.xml

where bin/coveralls.php bootstraps Composer's autoloader and calls the uploader with COVERALLS_REPO_TOKEN from the environment. Verify success by checking the build's job on coveralls.io — not by the script's exit code, which on packages of this vintage often returns 0 even when the API rejects the payload.

Implementation Patterns

Generate-then-upload, never interleaved. Keep coverage generation in the test step and the upload in a separate, if: success() step. If you upload while PHPUnit is still writing clover.xml you get truncated XML and a confusing API error.

Wrap it in one script, not inline CI YAML. A bin/coveralls.php (or a Composer script) keeps the invocation identical across Travis, GitLab, and GitHub Actions, and gives you one place to change when you move CI providers. This matters because the package predates GitHub Actions and will not recognise GITHUB_* env vars — you'll be passing service_name, service_job_id, branch, and commit_sha explicitly.

Treat CI metadata as the adapter layer. The typical design has an interface for "environment detection" with one implementation per CI provider. If your provider isn't covered, implement that interface rather than post-processing — this is the cleanest extension point in the package and cheaper than forking the client.

Dry-run the payload. Before blaming the package, instantiate the payload builder alone and json_encode it. You want to see service_name, service_job_id, repo_token, git.branch, git.head.id, and a source_files array with repo-relative names. That JSON is the entire contract with Coveralls; everything else is plumbing.

Idempotency. Uploads are per-job. Re-running a CI job creates a new Coveralls job rather than overwriting, which is fine — but don't wire the upload into a retry loop that fires three times on flaky network, or you'll pollute the build history.

Gotchas and Tips

• It is archived (last release 2015-12-05). No PHP 8 support, no security patches, and its Coveralls API version is old. Pin it, expect composer install to fail on modern PHP, and be ready to either run it in a PHP 7.x container or vendor the ~200 lines of payload-building you actually need. For most teams the honest recommendation is php-coveralls/php-coveralls, which is maintained and solves the same problem.
• Path mismatches are the #1 silent failure. Coveralls resolves each source_files[].name against the repo tree. If clover.xml contains absolute paths (common when PHPUnit runs in a container with a different mount point) the upload succeeds and shows 0% or "source not found." Fix by setting --coverage-clover to a relative path and by configuring the SourceFile name mapping in the payload builder.
• Shallow clones break git metadata. actions/checkout defaults to depth 1; commit detection and any branch/PR inference then produce garbage or nulls. Set fetch-depth: 0.
• Fork PRs have no secret. COVERALLS_REPO_TOKEN isn't available on pull_request events from forks. Either guard the upload step (if: github.event.pull_request.head.repo.fork == false) or enable Coveralls' tokenless GitHub integration and skip the token entirely.
• Old Guzzle, old TLS. A 2015 HTTP client may negotiate TLS poorly or have certificate-bundle issues on modern images. If you see cURL error 60 or handshake failures, update the Guzzle constraint in your root composer.json before touching the package.
• Exit codes lie. Wrap the call and assert on the response body / status yourself; otherwise a red Coveralls badge with a green CI run will cost you an afternoon.
• Extension points worth knowing: the environment/CI adapter (add your provider there), the payload builder (override file-name normalisation and git block), and the injected HTTP client (swap transport, add logging middleware). Anything beyond those three is a fork, and for a 2-star archived package, a fork is usually the right call anyway.