Phpcpd Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require --dev johnatas-x/phpcpd
   

   Ensure phpcpd is listed under require-dev in composer.json.

2. Basic Usage Run CPD on a directory (e.g., app/) via Artisan:

   php artisan cpdetect:run app/
   

   Output will show duplicate code blocks with file locations and line numbers.

3. First Use Case Integrate into your CI pipeline (e.g., GitHub Actions) to flag duplicates pre-merge:

   - name: Run CPD
     run: php artisan cpdetect:run app/ --min-tokens=50 --exclude=tests/
   

Implementation Patterns

Workflows

1. Pre-Commit Hook Use phpcpd via a Git hook to block duplicates early:

   composer require --dev php-cpd
   echo 'php vendor/bin/phpcpd --min-tokens=50 app/' >> .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

2. Laravel Artisan Command Extend the package’s CLI with custom logic:

   // app/Console/Commands/DetectDuplicates.php
   use Illuminate\Console\Command;
   use PhpCpd\Cpd;
   
   class DetectDuplicates extends Command {
       protected $signature = 'cpd:custom {path}';
       public function handle() {
           $cpd = new Cpd();
           $report = $cpd->processDirectory($this->argument('path'));
           $this->line($report->getReport());
       }
   }
   

3. Integration with PHPStan/Laravel-Pint Chain CPD with static analysis tools for comprehensive checks:

   composer exec phpstan analyse --level=max && php artisan cpdetect:run app/
   

Tips

• Token Threshold: Adjust --min-tokens (default: 100) to balance sensitivity vs. noise.
• Exclusions: Use --exclude to skip vendor/ or generated files:

  php artisan cpdetect:run app/ --exclude=vendor,storage
  

• HTML/JSON Output: Generate reports for dashboards:

  php artisan cpdetect:run app/ --format=html > reports/cpd.html
  

Gotchas and Tips

Pitfalls

1. False Positives

   • Issue: String literals or comments may trigger duplicates.
   • Fix: Increase --min-tokens or exclude specific files/directories.

2. Performance

   • Issue: Large codebases slow down analysis.
   • Fix: Run incrementally (e.g., per-module) or parallelize with parallel-lint.

3. Configuration Overrides

   • Issue: CLI args override config (e.g., phpcpd.php).
   • Fix: Use --config to specify a custom config file:

     php artisan cpdetect:run app/ --config=phpcpd_custom.php
     

Debugging

• Verbose Mode: Enable with -v for detailed output:

  php artisan cpdetect:run app/ -v
  

• Dry Run: Test exclusions first:

  php artisan cpdetect:run app/ --dry-run
  

Extension Points

1. Custom Report Formatting Extend the PhpCpd\Report class to add Slack/email alerts:

   class SlackReport extends \PhpCpd\Report {
       public function getReport() {
           return "```" . parent::getReport() . "```";
       }
   }
   

2. Token Filtering Override PhpCpd\Tokenizer\Tokenizer to ignore specific patterns (e.g., UUIDs):

   class CustomTokenizer extends \PhpCpd\Tokenizer\Tokenizer {
       protected function shouldIgnoreToken($token) {
           return parent::shouldIgnoreToken($token) || str_contains($token, 'uuid-');
       }
   }
   

3. CI Integration Fail builds on duplicates:

   - name: Enforce CPD
     run: php artisan cpdetect:run app/ || exit 1