Runner Bootstrap Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your project via Composer:

   composer require --dev phpcq/runner-bootstrap
   

   This installs phpcq as a dev dependency and sets up a basic configuration.

2. First Run Execute the following command to run PHP Code Quality (phpCQ) checks:

   vendor/bin/phpcq run
   

   This triggers a default analysis of your project’s code quality metrics.

3. Where to Look First

   • Configuration File: Check phpcq.json (auto-generated in project root) for default rules.
   • Documentation: Run vendor/bin/phpcq help for built-in commands and options.
   • Composer Scripts: Add phpcq run to composer.json under "scripts" for CI/CD integration:

     "scripts": {
       "test": "phpcq run"
     }
     

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Use phpcq run in GitHub Actions, GitLab CI, or other CI tools to enforce quality gates:

   # Example GitHub Actions workflow
   jobs:
     phpcq:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install --dev
         - run: vendor/bin/phpcq run --fail-on-violations
   

2. Pre-Commit Hooks Integrate with tools like husky or pre-commit to run phpcq on staged changes:

   composer require --dev php-cs-fixer
   vendor/bin/phpcq run --files-changed
   

3. Custom Rulesets Extend phpcq.json to enforce project-specific rules:

   {
     "rules": {
       "Complexity.CyclomaticComplexity": {
         "max": 10,
         "report": true
       },
       "Files.LineLength": {
         "max": 120
       }
     }
   }
   

Laravel-Specific Use Cases

1. Artisan Command Integration Create a custom Artisan command to run phpcq with Laravel-specific paths:

   // app/Console/Commands/RunPhpcq.php
   public function handle()
   {
       $this->call('vendor:publish', ['--provider' => 'Phpcq\RunnerBootstrap\PhpcqServiceProvider']);
       $this->info('Running phpcq on Laravel app...');
       Artisan::call('phpcq:run', ['--path' => app_path()]);
   }
   

2. Testing Workflow Run phpcq alongside PHPUnit tests in phpunit.xml:

   <php>
       <env name="PHPUNIT_EXIT_CODE" value="0"/>
   </php>
   <listeners>
       <listener class="Phpcq\RunnerBootstrap\TestListener" file="vendor/bin/phpcq"/>
   </listeners>
   

Gotchas and Tips

Common Pitfalls

1. False Positives in Large Codebases

   • Issue: phpcq may flag legacy code or third-party libraries (e.g., Laravel core).
   • Fix: Exclude vendor directories and legacy paths in phpcq.json:

     {
       "exclude": [
         "vendor/**",
         "legacy/**"
       ]
     }
     

2. Performance Overhead

   • Issue: Running phpcq on monorepos or large projects can be slow.
   • Fix: Use --parallel for multi-core analysis or limit scope:

     vendor/bin/phpcq run --path=app/Http --parallel
     

3. Configuration Conflicts

   • Issue: Merging phpcq.json from multiple packages (e.g., Laravel + custom rules).
   • Fix: Use composer require --dev phpcq/runner-bootstrap --ignore-platform-reqs to override defaults.

Debugging Tips

1. Dry Run Mode Test configurations without failing builds:

   vendor/bin/phpcq run --dry-run
   

2. Verbose Output Enable debug logs for troubleshooting:

   vendor/bin/phpcq run -vvv
   

3. Cache Issues Clear phpcq cache if rules aren’t updating:

   vendor/bin/phpcq clear-cache
   

Extension Points

1. Custom Reporters Generate JUnit or custom formats for CI tools:

   vendor/bin/phpcq run --format=junit --output=phpcq-report.xml
   

2. Plugin Development Extend phpcq with custom rules using the phpcq plugin system:

   // Example plugin: app/Phpcq/LaravelPlugin.php
   namespace App\Phpcq;
   
   use Phpcq\Runner\Plugin\PluginInterface;
   
   class LaravelPlugin implements PluginInterface {
       public function getRules() {
           return ['Laravel.RouteComplexity'];
       }
   }
   

   Register in composer.json:

   "extra": {
     "phpcq": {
       "plugins": ["App\\Phpcq\\LaravelPlugin"]
     }
   }
   

3. GitHub Action Integration Use the phpcq/action for seamless CI integration (if available):

   - uses: phpcq/action@v1
     with:
       fail-on-violations: true