Coverage Laravel Package

Getting Started

First, decide whether you should install this at all. The repository is archived and deprecated; the README points you at codacy-coverage-reporter instead. Use codacy/coverage only if you are maintaining a legacy PHP 5.x/7.x pipeline that already depends on it — for anything new, wire up the reporter (Docker image or GitHub Action) directly. Both consume the same Clover input, so the migration is a one-line CI change.

If you do proceed, the minimal path is:

1. Add the uploader as a dev dependency. The README suggests "codacy/coverage": "dev-master", but pin a tagged 1.x release instead — dev-master on an archived repo is unreproducible if the branch ever moves.

   composer require --dev codacy/coverage:^1.4
   

2. Make PHPUnit emit Clover. You need a coverage driver (Xdebug or PCOV) for this to produce anything:

   XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover build/logs/clover.xml
   

3. Export the project token from Codacy (Project → Settings → Integrations → Project API token) as CODACY_PROJECT_TOKEN in your CI environment. Never commit it.
4. Upload in a post-test CI step:

   vendor/bin/codacycoverage clover build/logs/clover.xml
   

Where to look first: the README's usage section (it is short), then vendor/bin/codacycoverage --help for the exact flags of the version you pinned, and finally your Codacy project's coverage tab to confirm the commit landed.

The first realistic use case is a single upload from your default branch on CI to get a baseline coverage percentage and a badge. Do that before touching PR builds — it isolates token/CI problems from branch/commit-attribution problems.

Implementation Patterns

Separate generation from upload. Have the test job write build/logs/clover.xml and publish it as a CI artifact; have the upload run as a distinct step (or even a separate job) that consumes the artifact. You then re-upload after a Codacy outage or a bad token without re-running the whole suite.

Wrap the call in a Makefile/script target. Something like make coverage-upload that shells out to codacycoverage. When you migrate to codacy-coverage-reporter (report -l PHP -r build/logs/clover.xml), you edit one file instead of hunting through YAML.

Upload from exactly one job. In a CI matrix (PHP 7.4/8.0/8.1), gate the upload on one leg only. Multiple concurrent uploads race, and the last write wins — often from the leg you least expected.

# GitHub Actions-ish sketch
- run: XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover build/logs/clover.xml
- if: matrix.php == '8.1' && github.event_name == 'push'
  run: vendor/bin/codacycoverage clover build/logs/clover.xml
  env:
    CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}

Merge suites before uploading. If you run PHPUnit plus Behat/PHPSpec, merge Clover files with phpcov merge --clover build/logs/merged.xml build/coverage/ and upload the merged file. The uploader accepts one report per invocation.

Full clone in CI. Commit attribution relies on git metadata in the workspace; actions/checkout defaults to fetch-depth: 1, which can break it. Use fetch-depth: 0 so coverage is attached to the right commit rather than the branch tip.

Skip uploads on forked PRs. Secrets aren't exposed there, so the step either fails or no-ops noisily. Guard it: if: github.event.pull_request.head.repo.fork == false.

Gotchas and Tips

• It's archived. No fixes for PHP 8.x deprecations, no new PHPUnit format support, no security updates. Set a calendar reminder to migrate; the reporter is a drop-in for Clover input.
• phpunit subcommand is dead weight. It handles PHPUnit's XML format, which only PHPUnit < 4 emits. On any modern PHPUnit, use clover only.
• Empty Clover uploads 0%. If the coverage driver isn't loaded, PHPUnit still writes a file — sometimes an empty one — and you silently tank your dashboard. Guard with test -s build/logs/clover.xml || exit 1 before uploading.
• Xdebug 3 needs XDEBUG_MODE=coverage. Without it, no coverage data is generated at all. This is the single most common cause of "the upload worked but coverage is 0".
• Stale reports. Clean build/logs/ at the start of the job and gitignore it; a leftover Clover file from a previous branch will happily get uploaded.
• The wrapper delegates to the Java coverage reporter. If your CI image is minimal (slim PHP images, Alpine), check that a JRE is resolvable — a missing Java surfaces as an opaque exec error rather than a clear message. Corporate proxies need HTTPS_PROXY/JAVA_TOOL_OPTIONS set for the upload to reach api.codacy.com.
• Token handling. Prefer CODACY_PROJECT_TOKEN over --token on the command line; CLI args land in CI logs.
• vendor/bin may not exist. If your CI installs with --no-dev, the binary is absent. Either install dev deps in the coverage job or download the phar explicitly.
• No enforcement built in. This tool only uploads; it won't fail a build on a coverage drop. Add a separate gate (--coverage-text parsing or a threshold check) if you want PRs blocked on regression.
• Extension points are essentially nil. It's a packaged CLI. If you need custom behaviour (retries, custom commit metadata), wrap it in your own shell script rather than patching the phar — and put that retry logic in the wrapper you'll keep when you migrate.