Php Code Coverage Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev phpunit/php-code-coverage
   

   Add as a dev dependency to avoid bloating production builds.

2. Basic Usage:

   use SebastianBergmann\CodeCoverage\CodeCoverage;
   use SebastianBergmann\CodeCoverage\Driver\Selector;
   use SebastianBergmann\CodeCoverage\Filter;
   use SebastianBergmann\CodeCoverage\Report\Facade;
   
   $filter = (new Filter)->includeFiles([__DIR__.'/src/**/*.php']);
   $coverage = new CodeCoverage((new Selector)->forLineCoverage($filter), $filter);
   
   $coverage->start('test-suite');
   // Execute tests or code under test
   $coverage->stop();
   
   Facade::fromObject($coverage)->renderHtml(__DIR__.'/coverage-report');
   

3. Key Classes to Know:

   • CodeCoverage: Core class for collecting coverage data.
   • Filter: Define inclusion/exclusion rules for files/methods.
   • Report\Facade: Unified interface for generating reports (HTML, XML, etc.).
   • Serialization\Serializer/Unserializer: Save/load coverage data for later use.

Implementation Patterns

Workflows

1. Test-Driven Coverage:

   // In a test bootstrap file (e.g., `tests/bootstrap.php`)
   $coverage = new CodeCoverage((new Selector)->forLineCoverage(), new Filter);
   $coverage->start('unit-tests');
   
   // Run tests (e.g., via PHPUnit or custom runner)
   $coverage->stop();
   
   // Generate report
   Facade::fromObject($coverage)->renderHtml(__DIR__.'/coverage');
   

2. CI Pipeline Integration:

   # Serialize coverage data after tests
   php vendor/bin/phpunit --coverage-php coverage.php
   
   # In CI (e.g., GitHub Actions), generate reports
   php -r "require 'vendor/autoload.php'; \SebastianBergmann\CodeCoverage\Report\Facade::fromSerializedData(unserialize(file_get_contents('coverage.php')))->renderClover('clover.xml');"
   

3. Custom Test Runners:

   // Example: Custom test runner with coverage
   $coverage = new CodeCoverage((new Selector)->forLineCoverage(), new Filter);
   $coverage->start('custom-runner');
   
   // Execute test cases
   foreach ($testCases as $case) {
       $case->run();
   }
   
   $coverage->stop();
   Facade::fromObject($coverage)->renderXml(__DIR__.'/coverage.xml');
   

Integration Tips

• PHPUnit Integration: Use --coverage-php to generate serialized coverage files, then process them with this library for custom reports.

  phpunit --coverage-php coverage.cov
  php -r "require 'vendor/autoload.php'; \SebastianBergmann\CodeCoverage\Report\Facade::fromSerializedData(unserialize(file_get_contents('coverage.cov')))->renderHtml('report');"
  

• Filtering: Exclude vendor files or specific directories:

  $filter = (new Filter)
      ->includeFiles([__DIR__.'/src/**/*.php'])
      ->excludeFiles([__DIR__.'/src/Exceptions/**']);
  

• Report Formats: Supported formats via Facade:

  • renderHtml(): Interactive HTML reports with charts.
  • renderClover()/renderOpenClover(): XML for tools like SonarQube.
  • renderText(): CLI-friendly text output.

• Performance: Use CacheWarmer to pre-warm static analysis caches for faster report generation in CI:

  $cacheWarmer = new \SebastianBergmann\CodeCoverage\CacheWarmer();
  $cacheWarmer->warmCache();
  

Gotchas and Tips

Pitfalls

1. Driver Conflicts:

   • If both Xdebug and PCov are enabled, coverage data may be corrupted. Use Selector to explicitly choose one:

     (new Selector)->forLineCoverage(new Filter, 'pcov'); // or 'xdebug'
     

2. Path Handling:

   • Serialized coverage files use relative paths by default (since v14.0.0). Ensure paths are consistent when unserializing:

     $data = (new Unserializer)->unserialize('coverage.cov');
     // Paths in `$data` are relative to the serialization directory.
     

3. Race Conditions:

   • Parallel test runners (e.g., phpunit --parallel) may cause race conditions in static analysis. Use CachingSourceAnalyser carefully or disable caching:

     $filter->setCache(new \SebastianBergmann\CodeCoverage\Cache\NullCache());
     

4. Deprecated Methods:

   • Avoid Filter::includeUncoveredFiles()/excludeUncoveredFiles() (deprecated in v11.0.9). Use includeFiles()/excludeFiles() instead.

5. PHP 8.3+:

   • This package drops support for PHP 8.3+. Ensure your project uses PHP 8.2 or lower if needed.

Debugging

• Invalid XML Reports: If XML reports fail validation, check for:

  • Mixed Xdebug/PCov usage (see above).
  • File permissions for temporary directories used by DOMDocument/XMLWriter.

• Missing Coverage Data:

  • Verify Filter rules include all target files.
  • Check if the coverage driver (Xdebug/PCov) is properly enabled in php.ini:

    ; For Xdebug
    xdebug.mode=coverage
    xdebug.start_with_request=yes
    
    ; For PCov
    extension=pcov.so
    

• Serialization Issues:

  • Ensure the serialized file (coverage.cov) is not corrupted. Re-generate it if needed:

    phpunit --coverage-php coverage.cov
    

Extension Points

1. Custom Report Formats: Extend Report\Facade or implement Report\RendererInterface for new formats:

   class CustomRenderer implements RendererInterface {
       public function render(CodeCoverage $coverage, string $path) {
           // Custom logic to generate reports
       }
   }
   

2. Filter Logic: Override Filter to implement custom inclusion/exclusion rules:

   class CustomFilter extends Filter {
       public function includeFiles(array $files): self {
           // Add custom logic (e.g., exclude files matching a pattern)
           return parent::includeFiles($files);
       }
   }
   

3. Driver Plugins: Add support for new coverage drivers by implementing Driver\DriverInterface:

   class MyDriver implements DriverInterface {
       public function start(string $name) { /* ... */ }
       public function stop() { /* ... */ }
       public function getData() { /* ... */ }
   }
   

   Register it with DriverSelector:

   $selector = new Selector;
   $selector->registerDriver('my_driver', new MyDriver());
   

4. Performance Tuning:

   • Disable caching for faster (but slower first-run) reports:

     $filter->setCache(new \SebastianBergmann\CodeCoverage\Cache\NullCache());
     

   • Use SHA-256 for cache keys (faster than MD5 in PHP 8.4+):

     $filter->setCache(new \SebastianBergmann\CodeCoverage\Cache\FileCache(__DIR__.'/cache'));
     

Configuration Quirks

• HTML Report Dark Mode: Enable via CSS or environment variable (if supported by your version):

  Facade::fromObject($coverage)->renderHtml(__DIR__.'/report', [
      'dark_mode' => true,
  ]);
  

• OpenClover vs. Clover: Use renderOpenClover() for OpenClover-compatible XML (validates against OpenClover schema). The legacy renderClover() may not validate strictly.

• Line Coverage vs. Branch Coverage: Explicitly select the driver type:

  (new Selector)->forLineCoverage($filter);       // Line coverage
  (new Selector)->forBranchCoverage($filter);    // Branch coverage