Php Coveralls Laravel Package

Getting Started

Install via Composer as a dev dependency:

composer require --dev php-coveralls/php-coveralls

Configure PHPUnit to generate Clover XML coverage reports:
Add <clover outputFile="build/logs/clover.xml"/> to phpunit.xml under <coverage><report>, or run tests with --coverage-clover build/logs/clover.xml.

Run Coveralls upload in CI after tests succeed (e.g., in .travis.yml after_success: or GitHub Actions step):

php vendor/bin/php-coveralls

By default, it reads build/logs/clover.xml and uploads to coveralls.io using detected CI context and repo token from environment.

Implementation Patterns

• CI Integration: Use standard env vars (COVERALLS_REPO_TOKEN, COVERALLS_RUN_LOCALLY, COVERALLS_PARALLEL, COVERALLS_FLAG_NAME) for token injection and parallel builds.
• Multiple Coverage Files: In complex builds (parallel tests, multi-suite), either:
  • Use .coveralls.yml with coverage_clover: [file1.xml, file2.xml] or glob pattern (build/logs/clover-*.xml),
  • Or generate PHPUnit --coverage-php files and merge with phpcov merge --clover build/logs/clover.xml build/cov.
• Flexible Configuration: Prefer .coveralls.yml for static config (e.g., custom entry_point for self-hosted Coveralls), CLI flags (-x, --root_dir) for per-run overrides.
• Local Testing: Set COVERALLS_RUN_LOCALLY=1 and COVERALLS_REPO_TOKEN=xxx to dry-run or simulate production upload locally (with --dry-run to avoid sending).
• GitHub Actions: Use secrets.GITHUB_TOKEN as COVERALLS_REPO_TOKEN, and consider --coverage_clover explicit to avoid ambiguity.

Gotchas and Tips

• Clover file parsing: Only <line type="stmt" ...> is used for coverage; type="method"/class entries are ignored—even if counted, they misrepresent actual coverage (e.g., abstract methods). Verify your Clover XML has type="stmt" for executable lines.
• Root directory assumptions: By default, paths are resolved relative to the current working directory. Use --root_dir or root_dir: in config if running from subdirectories (common in monorepos or nested CI scripts).
• Token security: Never commit .coveralls.yml with repo_token. Use CI environment variables instead—GitHub Actions secrets are ideal.
• Xdebug required: Coverage generation needs Xdebug enabled. On Travis/CircleCI, explicitly enable Xdebug in config (e.g., sed on xdebug.ini) or set XDEBUG_MODE=coverage.
• Memory limits: Merging many coverage files with phpcov may exhaust memory; use -d memory_limit=-1.
• Dry-run & verbose mode: Use --dry-run and --verbose (-v) during setup to inspect payload (build/logs/coveralls-upload.json) and debug failures without uploading.
• PHP version compatibility: Ensure version alignment—2.9+ requires PHP 7.4+, and drops older Symfony versions. Check composer.json requirements when upgrading.
• Parallel builds: Set COVERALLS_PARALLEL=true and COVERALLS_FLAG_NAME per job; remember to trigger the parallel completion webhook manually if not using native CI integrations.