Getting Started

Minimal Steps

Installation:
```
composer require --dev pcov/clobber
```
This adds the pcov CLI tool to vendor/bin/ and installs the necessary PCOV drivers.
First Use Case: Replace Xdebug with PCOV in your Laravel project’s root:
```
vendor/bin/pcov clobber
```
Verify the switch with:
```
php -m | grep -E 'xdebug|pcov'
```
(Xdebug should disappear; pcov should appear.)
Where to Look First:
- CLI Usage: README.md for clobber/unclobber syntax.
- Laravel Integration: Focus on phpunit.xml and CI/CD scripts (e.g., .github/workflows/).
- Debugging: Check src/ClobberCommand.php for edge-case handling (e.g., permission errors).

Implementation Patterns

Workflows

Laravel Test Workflow:

Pre-Test Hook (e.g., in phpunit.xml or composer.json):

<!-- phpunit.xml -->
<php>
    <env name="PCOV_ENABLED" value="1"/>
    <script type="php"><![CDATA[
        putenv('PCOV_ENABLED=1');
        shell_exec('vendor/bin/pcov clobber');
    ]]></script>
</php>

Post-Test Cleanup (add to composer.json):

{
  "scripts": {
    "test": "phpunit && vendor/bin/pcov unclobber"
  }
}

CI/CD Pipeline:

GitHub Actions Example:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install --dev
      - run: vendor/bin/pcov clobber
      - run: vendor/bin/phpunit --coverage-clover=coverage.xml
      - run: vendor/bin/pcov unclobber
      - uses: actions/upload-artifact@v3
        with:
          name: coverage
          path: coverage.xml

GitLab CI:

test:
  script:
    - composer install --dev
    - vendor/bin/pcov clobber
    - vendor/bin/phpunit --coverage-text
    - vendor/bin/pcov unclobber

Local Development:

Toggle with Laravel Forge/Envoyer: Add custom commands to your deployment script:

# deploy.sh
if [ "$ENV" = "production" ]; then
  vendor/bin/pcov clobber
else
  vendor/bin/pcov unclobber
fi

Integration Tips

Laravel Forge/Envoyer:
- Use the Custom Commands feature to run pcov clobber during deployments if PCOV is required for coverage reports in staging/production.
Parallel Testing:
- If using Laravel’s --parallel flag, ensure PCOV is clobbered before all workers spawn:
```
vendor/bin/pcov clobber && vendor/bin/phpunit --parallel
```

Docker/Laravel Sail:

Add to docker-compose.yml services:

services:
  laravel.test:
    volumes:
      - ./:/var/www/html
    command: bash -c "composer install && vendor/bin/pcov clobber && php artisan test"

Laravel Mix/Webpack:
- If using laravel-mix with PHPUnit, ensure the pcov binary is available in your build environment:
```
// webpack.mix.js
mix.setPublicPath('public')
   .phpUnit(); // Ensures vendor/bin is in PATH
```

Gotchas and Tips

Pitfalls

Permission Errors:
- Issue: pcov clobber fails with Permission denied on Linux.
- Fix: Run with sudo or adjust file permissions:
```
sudo chmod -R 775 vendor/bin/pcov
```
- Laravel-Specific: Ensure your Laravel user (e.g., www-data) has write access to /usr/local/etc/php/conf.d/ (common Xdebug config path).
Xdebug 3+ Conflicts:
- Issue: Xdebug 3+ may ignore PCOV clobbering due to native PCOV support.
- Fix: Downgrade Xdebug to 2.9.x or use PHPUnit 8+:
```
pecl uninstall xdebug && pecl install xdebug-2.9.8
```
False Coverage Reports:
- Issue: PCOV may miss coverage in certain edge cases (e.g., anonymous classes, traits).
- Fix: Cross-validate with Xdebug or use --coverage-process:
```
vendor/bin/phpunit --coverage-process-isolated
```

CI/CD Flakiness:

Issue: pcov unclobber may fail if Xdebug configs are corrupted.

Fix: Backup original configs pre-clobber:

cp /usr/local/etc/php/conf.d/xdebug.ini ~/xdebug_backup.ini
vendor/bin/pcov clobber
# ... tests ...
vendor/bin/pcov unclobber || cp ~/xdebug_backup.ini /usr/local/etc/php/conf.d/xdebug.ini

Laravel Artisan Conflicts:
- Issue: Artisan commands (e.g., php artisan test) may fail if Xdebug is clobbered mid-execution.
- Fix: Restore Xdebug before running Artisan:
```
vendor/bin/pcov unclobber && php artisan test
```

Debugging Tips

Verify Clobber Status:

php -i | grep -i "xdebug\|pcov"

Expected output for PCOV:
```
pcov
pcov.enabled => On => On
```

Check PHPUnit Configuration: Ensure phpunit.xml doesn’t force Xdebug:

<!-- Remove or comment out -->
<php>
    <!-- <env name="XDEBUG_CONFIG" value="remote_enable=1"/> -->
</php>

Log Clobber Actions: Add debug output to src/ClobberCommand.php:

public function handle(): void
{
    $this->info('Clobbering Xdebug...');
    // ... existing logic ...
    $this->info('PCOV enabled. Run `php -m` to verify.');
}

Extension Points

Custom Clobber Paths: Override the default Xdebug config path in src/ClobberCommand.php:

protected function getXdebugConfigPath(): string
{
    return base_path('vendor/xdebug.ini'); // Laravel-specific path
}

Automated Clobbering: Create a Laravel service provider to auto-clobber on boot:

// app/Providers/PcovServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Symfony\Component\Process\Process;

class PcovServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->environment('testing')) {
            $process = new Process(['vendor/bin/pcov', 'clobber']);
            $process->run();
        }
    }
}

Environment-Specific Clobbering: Use Laravel’s .env to control clobbering:

PCOV_CLOBBER=true

// In a service provider or Artisan command
if (env('PCOV_CLOBBER') === 'true') {
    shell_exec('vendor/bin/pcov clobber');
}

Laravel-Specific Quirks

Laravel Valet: Clobbering may require restarting Valet:
```
vendor/bin/pcov clobber && valet restart
```

Laravel Homestead: Add clobbering to provision.sh:

echo "Running PCOV clobber..."
cd /var/www && composer require pcov/clobber --dev
vendor/bin/pcov clobber

Laravel Dusk: Ensure Dusk’s ChromeDriver isn’t affected by PCOV (it typically isn’t, but verify with php -m).

Clobber Laravel Package