Robo Phpmd Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sweetchuck/robo-phpmd
   

   Add the trait to your RoboFile.php:

   use Sweetchuck\Robo\PhpMessDetector\PhpmdTaskLoader;
   

2. First Use Case: Run a basic PHPMessDetector (PHPMD) analysis on your project:

   public function phpmd()
   {
       return $this->taskPhpmdLintFiles()
           ->setPaths(['src/']);
   }
   

   Execute via CLI:

   robo phpmd
   

3. Where to Look First:

   • Review the PHPMD documentation for rule sets and configurations.
   • Check the PhpmdTaskLoader trait for available methods (e.g., setReportFormat, setRuleSetFileNames).
   • Default PHPMD rules are included, but custom rulesets (e.g., custom-rules.xml) can be loaded via setRuleSetFileNames.

Implementation Patterns

Common Workflows

1. Basic Linting:

   $this->taskPhpmdLintFiles()
       ->setPaths(['src/', 'tests/'])
       ->setReportFormat('text'); // Outputs to console
   

2. Custom Rulesets: Load a custom XML ruleset (e.g., rulesets/custom.xml):

   $this->taskPhpmdLintFiles()
       ->setRuleSetFileNames(['rulesets/custom.xml']);
   

3. Excluding Paths: Skip specific files/directories:

   $this->taskPhpmdLintFiles()
       ->setExcludePaths(['src/legacy/', 'vendor/']);
   

4. Integration with CI: Fail the build on violations (PHPMD returns non-zero exit code by default):

   $this->taskPhpmdLintFiles()
       ->setFailOnViolation(true); // Explicitly enforce failure
   

5. HTML/JSON Reports: Generate reports for dashboards or tools:

   $this->taskPhpmdLintFiles()
       ->setReportFormat('html')
       ->setReportFile('phpmd-report.html');
   

6. Parallel Execution: Use PHPMD’s parallel processing (if supported by your version):

   $this->taskPhpmdLintFiles()
       ->setParallel(4); // Process 4 files at once
   

Integration Tips

• Laravel-Specific: Target Laravel-specific paths (e.g., app/, config/, routes/):

  $this->taskPhpmdLintFiles()
      ->setPaths([
          'app/',
          'config/',
          'routes/',
          'app/Providers/',
          'app/Http/Controllers/'
      ]);
  

• Combine with Other Tasks: Chain PHPMD with other Robo tasks (e.g., run after tests):

  public function qualityCheck()
  {
      $this->taskExec('phpunit')
          ->then($this->taskPhpmdLintFiles()->setPaths(['src/']));
  }
  

• Dynamic Paths: Use Laravel’s basePath() or appPath() for path resolution:

  $this->taskPhpmdLintFiles()
      ->setPaths([base_path('app'), base_path('tests/Unit')]);
  

Gotchas and Tips

Pitfalls

1. Outdated Package:

   • Last release in 2020; ensure compatibility with your PHPMD version (test locally first).
   • May require manual updates to PhpmdTaskLoader if PHPMD’s CLI changes.

2. RuleSet File Paths:

   • Paths to setRuleSetFileNames are relative to the working directory (not RoboFile.php).
   • Use absolute paths or base_path() for reliability:

     ->setRuleSetFileNames([base_path('rulesets/custom.xml')])
     

3. Performance:

   • PHPMD can be slow on large codebases. Use --exclude-paths to narrow scope.
   • Avoid running on vendor/ or node_modules/ (irrelevant for code quality).

4. Report Formats:

   • Not all formats are supported (e.g., xml may require additional setup).
   • Test formats like html or json in a CI environment to ensure rendering works.

5. Exit Codes:

   • PHPMD returns 2 on errors (e.g., invalid ruleset). Handle gracefully:

     $this->taskPhpmdLintFiles()
         ->setFailOnViolation(true)
         ->run(); // Will throw exception on non-zero exit
     

Debugging

• Verbose Output: Enable PHPMD’s verbose mode for debugging:

  $this->taskPhpmdLintFiles()
      ->setVerbose(true);
  

• Dry Run: Test paths/rules without failing:

  $this->taskPhpmdLintFiles()
      ->setFailOnViolation(false);
  

• Check PHPMD CLI: If tasks fail, run PHPMD directly to isolate the issue:

  phpmd src/ text --exclude src/legacy/
  

Extension Points

1. Custom Rulesets: Extend PHPMD’s rules by creating a ruleset.xml (see PHPMD docs). Example structure:

   <ruleset name="Custom Rules">
       <rule ref="rulesets/codesize.xml">
           <exclude name="ExcessiveClassComplexity"/>
       </rule>
   </ruleset>
   

2. Post-Processing Reports: Parse PHPMD’s output (e.g., json) to integrate with tools like Slack or GitHub PR comments:

   $report = $this->taskPhpmdLintFiles()
       ->setReportFormat('json')
       ->run();
   // Parse $report->getMessage() for custom logic
   

3. Robo Task Extensions: Override PhpmdTaskLoader to add custom methods (e.g., setCustomRule):

   namespace App\Robo;
   use Sweetchuck\Robo\PhpMessDetector\PhpmdTaskLoader as BaseLoader;
   
   trait CustomPhpmdTaskLoader extends BaseLoader {
       public function setCustomRule(string $rule) {
           return $this->taskPhpmdLintFiles()->addArgument('--custom-rule');
       }
   }
   

4. Laravel Artisan Integration: Wrap PHPMD in an Artisan command for easier CLI access:

   // app/Console/Commands/RunPhpmd.php
   public function handle() {
       $this->call('robo', ['phpmd']);
   }