Complexity Laravel Package

Getting Started

Install sebastian/complexity as a dev dependency via Composer (composer require --dev sebastian/complexity). It requires PHP ≥8.4 and nikic/php-parser ^5.0. Begin by analyzing a single class or method using its core calculator classes—e.g., Complexity\Calculator and Complexity\AstVisitor. The simplest first use case is to run complexity calculations over unit tests to identify overly complex methods that may need refactoring. Check the examples/ directory in the repository for minimal working examples.

Implementation Patterns

• Static Analysis Integration: Integrate the calculator into CI pipelines to gate code quality by failing builds when cyclomatic or Cognitive Complexity thresholds are exceeded. Use Calculator::calculateForFunctionLike() to analyze methods/functions.
• Custom Metric Reporting: Extend Complexity\AstVisitor to collect additional context (e.g., per-file, per-class complexity averages) and emit JSON or TSV for dashboarding.
• Test-Driven Refactoring: Write unit tests for existing code that assert complexity scores are below a defined limit (e.g., ≤10 for methods), enabling proactive refactoring before complexity debt accumulates.
• Laravel-Specific Use: Create an Artisan command (php complexity:check) that walks your app’s app/ directory, calculates complexity for controllers, services, and listeners, and outputs violations.

Gotchas and Tips

• PHP Version Lock-in: Version 6.0+ drops support for PHP <8.4. Ensure your CI environment matches this requirement or pin to ^5.0 if still on PHP 8.3.
• AST Parsing Accuracy: Complexity is computed from the AST, so it only counts syntactic branches (e.g., if, for, &&, ?:, catch)—not logical complexity like internal state dependencies. Combine with static analysis (PHPStan) for broader insights.
• Method vs. Class Scope: Use calculateForFunctionLike() (for methods/functions) or calculateForClass() (for aggregating method complexities). Avoid computing class-level cyclomatic complexity—it’s rarely meaningful.
• Performance Considerations: AST parsing with php-parser is fast, but scanning large codebases recursively in CI may benefit from parallelization or caching (e.g., store results per-file in storage/).