Cognitive Complexity Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require --dev tomasvotruba/cognitive-complexity
   

   Enable the rules in your phpstan.neon:

   includes:
       - vendor/tomasvotruba/cognitive-complexity/phpstan-rules.neon
   

2. First Run Execute PHPStan with the new rules:

   vendor/bin/phpstan analyse src
   

   Look for errors like:

   CognitiveComplexity\TooHighCognitiveComplexityMethod
   

3. First Use Case Identify a method with high cognitive complexity (e.g., > 20) and refactor it:

   // Before (complex)
   public function calculate($input): float {
       if ($input > 10) {
           if ($input % 2 === 0) {
               return $input * 0.1;
           } else {
               return $input * 0.2;
           }
       } else {
           return $input * 0.05;
       }
   }
   
   // After (simplified)
   public function calculate($input): float {
       $factor = $this->getFactor($input);
       return $input * $factor;
   }
   
   private function getFactor(float $input): float {
       if ($input <= 10) return 0.05;
       return $input % 2 === 0 ? 0.1 : 0.2;
   }
   

Implementation Patterns

Workflows

1. Integrate with CI/CD Add PHPStan to your pipeline (e.g., GitHub Actions):

   - name: PHPStan
     run: vendor/bin/phpstan analyse --level=5 src
   

   Fail builds if complexity exceeds thresholds.

2. Custom Thresholds Override defaults in phpstan.neon:

   parameters:
       cognitiveComplexity:
           maxMethodComplexity: 15
           maxClassComplexity: 50
   

3. Focused Analysis Run on specific files/directories:

   vendor/bin/phpstan analyse src/Service/
   

4. Pair with Other Tools Combine with phpstan/extension-installer for seamless updates:

   composer require --dev phpstan/extension-installer
   

Integration Tips

• Laravel-Specific Exclude vendor/ and generated files:

  excludeFiles:
      - vendor/**
      - bootstrap/**
  

• Refactoring Use IDE hints (e.g., PHPStorm) to visualize complexity before fixing.
• Documentation Add @complexity PHPDoc tags to justify high-complexity methods:

  /**
   * @complexity 25 (legacy, but well-tested)
   */
  public function legacyMethod() { ... }
  

Gotchas and Tips

Pitfalls

1. False Positives

   • Nested Ternaries: May inflate complexity unnecessarily. Fix: Break into helper methods.
   • Generated Code: Avoid analyzing auto-generated classes (e.g., Eloquent models). Fix: Exclude in phpstan.neon:

     excludeFiles:
         - app/Models/*.php
     

2. Performance

   • Large codebases may slow down analysis. Fix: Run incrementally or parallelize:

     vendor/bin/phpstan analyse --parallel
     

3. Configuration Overrides

   • Local overrides (e.g., phpstan.local.neon) can conflict with team settings. Fix: Document override rules in CONTRIBUTING.md.

Debugging

• Inspect Metrics Use --error-format=json to analyze raw complexity data:

  vendor/bin/phpstan analyse --error-format=json > complexity.json
  

• Visualize Tools like PhpDependency can map complexity to class diagrams.

Extension Points

1. Custom Rules Extend the package by creating your own PHPStan rules:

   use PHPStan\Rules\Rule;
   use CognitiveComplexity\Rules\ComplexityRule;
   
   class CustomComplexityRule extends ComplexityRule {
       protected function getMaxAllowedComplexity(): int { return 10; }
   }
   

   Register in phpstan.neon:

   services:
       - CognitiveComplexity\Rules\CustomComplexityRule
   

2. Integration with Linters Sync with ESLint (via laravel-shift/laravel-phpstan) for frontend-backend parity.

3. Dynamic Thresholds Use environment variables for dynamic thresholds:

   parameters:
       cognitiveComplexity:
           maxMethodComplexity: %env.int(MAX_METHOD_COMPLEXITY, 20)%