Phpinsights Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nunomaduro/phpinsights --dev
   

   For Laravel projects, publish the config:

   php artisan vendor:publish --provider="NunoMaduro\PhpInsights\Application\Adapters\Laravel\InsightsServiceProvider"
   

2. First Run:

   ./vendor/bin/phpinsights
   

   For Laravel:

   php artisan insights
   

3. Key Files:

   • phpinsights.php (or config/insights.php in Laravel) – Main configuration.
   • phpinsights.json – Optional custom ruleset file.

First Use Case

Run a pre-commit hook or CI check to enforce code quality before merging:

./vendor/bin/phpinsights --no-interaction --format=json > insights.json

Use the JSON output to fail builds if thresholds aren’t met (e.g., via GitHub Actions).

Implementation Patterns

Daily Workflow

1. Local Development: Run insights after major refactors or PRs:

   php artisan insights --fix
   

   The --fix flag auto-corrects fixable issues (e.g., PSR-12 formatting).

2. Team Enforcement:

   • Add to .git/hooks/pre-commit:

     #!/bin/sh
     ./vendor/bin/phpinsights --no-interaction --format=json | jq '.errors | length' -e | grep -q '0' || exit 1
     

   • Or integrate with GitHub Actions:

     - name: Run PHP Insights
       run: ./vendor/bin/phpinsights --format=github
     

3. Custom Rulesets: Extend phpinsights.json to disable/enable checks:

   {
     "exclude": ["tests/*", "vendor/*"],
     "presets": ["slevomat"],
     "insights": {
       "NunoMaduro\\PhpInsights\\Domain\\Insights\\ForbiddenTraits": {
         "enabled": false
       }
     }
   }
   

Laravel-Specific Patterns

• Artisan Integration: Use php artisan insights:report to generate HTML reports for stakeholders.
• CI Feedback: Upload reports to Slack or Discord using the --format=slack flag.

Performance Optimization

• Cache Results:

  php artisan insights --cache
  

  Re-run with --cache-clear to refresh.

• Parallel Execution: Enable in phpinsights.php:

  'parallel' => true,
  

Gotchas and Tips

Common Pitfalls

1. False Positives:

   • Issue: ForbiddenTraits may flag Laravel’s built-in traits (e.g., MustVerifyEmail).
   • Fix: Exclude them in phpinsights.json:

     "exclude": ["app/Models/*"]
     

2. Configuration Overrides:

   • Issue: Custom maxComplexity values in phpinsights.php may conflict with team standards.
   • Fix: Use presets (e.g., "presets": ["symfony"]) to inherit defaults.

3. Slow Analysis:

   • Issue: Large codebases (e.g., Magento) cause timeouts.
   • Fix: Limit scope:

     phpinsights --directory=app/Http
     

Debugging Tips

• Verbose Output:

  phpinsights --verbose
  

  Reveals skipped files and insight execution order.

• Dry Run:

  phpinsights --dry-run
  

  Simulates checks without modifying files.

Extension Points

1. Custom Insights: Create a new insight by extending NunoMaduro\PhpInsights\Domain\InsightInterface and register it in phpinsights.php:

   'insights' => [
       \App\Insights\CustomInsight::class,
   ],
   

2. Hooks: Use the insights.run event in Laravel’s EventServiceProvider:

   protected $listen = [
       'NunoMaduro\PhpInsights\Events\InsightsRun' => [
           \App\Listeners\LogInsights::class,
       ],
   ];
   

3. Preset Management: Share custom presets via Packagist or GitHub:

   'presets' => [
       'custom-preset' => __DIR__.'/config/insights-preset.php',
   ],
   

Laravel Quirks

• Service Provider: Ensure InsightsServiceProvider is registered in config/app.php under providers.
• Artisan Commands: Override the default command in app/Console/Kernel.php:

  protected $commands = [
      \NunoMaduro\PhpInsights\Application\Adapters\Laravel\Console\InsightsCommand::class,
  ];