Php Coverage Badger Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require --dev jaschilz/php-coverage-badger
   

   Add to composer.json under require-dev to ensure it’s included in CI environments.

2. Generate Clover XML Configure PHPUnit to output Clover XML in phpunit.xml:

   <logging>
       <log type="coverage-clover" target="build/clover.xml"/>
   </logging>
   

   Run tests:

   ./vendor/bin/phpunit
   

3. Generate Badge Run the CLI command:

   ./vendor/bin/php-coverage-badge build/clover.xml public/badges/coverage.svg
   

   Place the generated coverage.svg in your project’s public or storage/app/public folder.

First Use Case: CI Integration

Add a step in your CI pipeline (e.g., GitHub Actions, Travis CI) to:

1. Run PHPUnit with Clover logging.
2. Generate the badge.
3. Upload the badge to a branch (e.g., gh-pages) or artifact storage.

Example GitHub Actions snippet:

- name: Generate Coverage Badge
  run: ./vendor/bin/php-coverage-badge build/clover.xml public/badges/coverage.svg

- name: Deploy Badge
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public/badges

Implementation Patterns

Workflow: Local Development

1. On-Demand Badge Generation Use a Laravel Artisan command to wrap the badge generation:

   // app/Console/Commands/GenerateCoverageBadge.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Jaschilz\PHPCoverageBadger\PHPCoverageBadger;
   
   class GenerateCoverageBadge extends Command
   {
       protected $signature = 'coverage:badge {clover_file? : Path to Clover XML} {output? : Output SVG path}';
       protected $description = 'Generate a coverage badge from Clover XML';
   
       public function handle()
       {
           $badger = new PHPCoverageBadger();
           $badger->generate($this->argument('clover_file'), $this->argument('output'));
           $this->info("Badge generated at {$this->argument('output')}");
       }
   }
   

   Run locally:

   php artisan coverage:badge build/clover.xml public/badges/coverage.svg
   

2. Dynamic Badge Paths Store badge paths in .env:

   COVERAGE_BADGE_PATH=public/badges/coverage.svg
   COVERAGE_CLOVER_PATH=build/clover.xml
   

   Reference in your command:

   $badger->generate(env('COVERAGE_CLOVER_PATH'), env('COVERAGE_BADGE_PATH'));
   

Integration Tips

1. Laravel Blade Integration Display the badge in a view:

   <img src="{{ asset('badges/coverage.svg') }}" alt="Code Coverage">
   

   Or dynamically link to a branch-specific badge:

   // app/Helpers/CoverageHelper.php
   public static function badgeUrl($branch = 'main')
   {
       return asset("badges/{$branch}/coverage.svg");
   }
   

2. CI Artifact Storage Upload the badge as a CI artifact (e.g., GitHub Actions):

   - name: Upload Coverage Badge
     uses: actions/upload-artifact@v3
     with:
       name: coverage-badge
       path: public/badges/coverage.svg
   

3. Custom Badge Styling Extend the PHPCoverageBadger class to modify badge colors or labels:

   class CustomBadger extends PHPCoverageBadger
   {
       protected function getBadgeColor(float $coverage): string
       {
           return $coverage > 90 ? 'brightgreen' : ($coverage > 75 ? 'green' : 'yellow');
       }
   
       protected function getBadgeLabel(float $coverage): string
       {
           return "Coverage: {$coverage}% (Custom)";
       }
   }
   

Gotchas and Tips

Pitfalls

1. Clover XML Path Issues

   • Gotcha: The CLI command fails if the Clover XML path is relative or incorrect.
   • Fix: Use absolute paths or resolve them via Laravel’s storage_path():

     $cloverPath = storage_path('logs/clover.xml');
     

2. Permission Denied

   • Gotcha: Writing to public/badges/ may fail due to permissions.
   • Fix: Ensure the directory exists and is writable:

     mkdir -p public/badges && chmod -R 775 public/badges
     

     Or use Laravel’s storage_path() for safer writes.

3. Outdated Badge on CI

   • Gotcha: Badges may not update if the CI workflow skips badge generation.
   • Fix: Explicitly trigger badge generation in your CI pipeline (e.g., after tests pass).

4. Deprecated Package

   • Gotcha: The package hasn’t been updated since 2017 and lacks active maintenance.
   • Mitigation:
     • Fork and update dependencies (e.g., phpunit/phpunit).
     • Monitor for breaking changes in PHPUnit’s Clover XML format.

Debugging

1. Validate Clover XML Ensure the XML is valid before processing:

   xmllint --noout build/clover.xml
   

   Common issues:

   • Missing <metrics> or <project> tags.
   • Incorrect <coverage> line numbers.

2. Check Badge Output Inspect the generated SVG for errors:

   cat public/badges/coverage.svg | grep -A 10 "Invalid"
   

   Expected structure:

   <svg>...</svg>
   

   If empty, the Clover XML was likely malformed.

3. Log Coverage Data Debug the parsed coverage data:

   $badger = new PHPCoverageBadger();
   $data = $badger->parseCloverFile($cloverPath);
   \Log::info('Coverage Data:', $data);
   

Extension Points

1. Custom Thresholds Override the default "passing" threshold (e.g., 80%):

   class StrictBadger extends PHPCoverageBadger
   {
       protected function isCoverageAcceptable(float $coverage): bool
       {
           return $coverage >= 80;
       }
   }
   

2. Badge Templates Extend the SVG template by overriding the getBadgeTemplate() method:

   protected function getBadgeTemplate(): string
   {
       return file_get_contents(__DIR__.'/custom-badge-template.svg');
   }
   

3. Multi-Project Support Process multiple Clover files and merge coverage stats:

   $badger = new PHPCoverageBadger();
   $coverage = $badger->parseCloverFile('project1/clover.xml');
   $coverage += $badger->parseCloverFile('project2/clover.xml');
   $average = array_sum($coverage) / count($coverage);
   $badger->generateBadge($average, 'merged-coverage.svg');
   

Config Quirks

1. Default Output The package defaults to writing to the current directory. Always specify an explicit path to avoid overwrites.

2. Locale-Specific Issues If running in a non-English locale, ensure the Clover XML uses numeric values (e.g., 100.0 instead of 100,0 for German locales).

3. Case Sensitivity The Clover XML tags are case-sensitive. Ensure tags like <metrics> match exactly.