Cognitive Complexity Laravel Package

Product Decisions This Supports

• Code Quality & Maintainability: Enables proactive identification of overly complex code, reducing technical debt and improving developer onboarding.
• Developer Experience (DX): Aligns with engineering best practices (e.g., Clean Code principles) to streamline code reviews and reduce cognitive load.
• Automated Quality Gates: Integrates into CI/CD pipelines to enforce complexity thresholds, blocking merges for high-complexity PRs (e.g., "No method > 10 cognitive complexity").
• Metric Credibility (new in 1.3.0): Scoring now follows the original cognitive complexity paper, so thresholds can be defended as industry-reference numbers rather than an idiosyncratic implementation — useful when negotiating quality gates with skeptical stakeholders or auditors.
• Platform Reach (new in 1.3.0): PHP 7.4+ support widens applicability across legacy services and older monoliths, letting one standard cover the whole PHP estate instead of splitting policy by runtime.
• Roadmap Prioritization: Justifies investment in refactoring tools (e.g., automated suggestions) or pair programming for legacy systems.
• Build vs. Buy: Avoids reinventing complexity analysis tools; leverages open-source validation for compliance with internal standards.
• Use Cases:
  • Onboarding new devs by flagging "hard-to-understand" methods.
  • Justifying refactoring efforts for legacy systems (incl. pre-PHP 8 services).
  • Enforcing consistency across microservices or monoliths.
  • Publishing defensible, paper-aligned complexity metrics to engineering leadership.

When to Consider This Package

• Adopt if:

  • Your team struggles with high cognitive load in code reviews or debugging.
  • You prioritize sustainable velocity over short-term feature delivery.
  • PHPStan is already in your toolchain (or you’re open to adding it).
  • You lack static analysis for complexity metrics (e.g., no SonarQube or custom tools).
  • Your codebase has critical paths (e.g., payment processing, core logic) where readability is non-negotiable.
  • You run PHP 7.4+ services — 1.3.0 removes the previous runtime floor as an adoption blocker.
  • You need metrics you can defend externally — paper-aligned scoring makes thresholds easier to justify in audits or cross-team standards.

• Look elsewhere if:

  • Your team resists tooling or lacks buy-in for static analysis.
  • You need actionable refactoring suggestions (this package detects, not fixes).
  • Your stack is non-PHP (e.g., JavaScript, Python).
  • You’re already using commercial tools (e.g., NDepend, CodeScene) with built-in complexity analysis.
  • You depend on dependency-tree analysis — the dependency tree rule was removed in 1.3.0; pair with another tool or stay on the prior minor until you have a replacement.
  • You cannot absorb a re-baselining cycle — scores shift under the new paper-aligned calculation, so existing thresholds will fire differently until recalibrated.

How to Pitch It (Stakeholders)

For Executives: "This package lets us automatically catch ‘spaghetti code’ before it ships—like a spellcheck for logic. For every hour we spend fixing complex bugs later, we’ll save 10 hours now by catching issues early. The new release also aligns our scores with the published industry definition of cognitive complexity, so the numbers we report are defensible rather than homegrown, and it now covers our older PHP 7.4 services too—one standard across the whole estate. Think of it as insurance for our codebase."

For Engineering: "PHPStan + cognitive complexity rules gives us objective, data-driven code reviews. No more ‘this method feels messy’—now we can block PRs if complexity exceeds thresholds. Two things to plan for in 1.3.0: scores are recalculated to match the original cognitive complexity paper, so existing thresholds need a short recalibration pass (expect a one-off jump/dip in reported complexity), and the dependency tree rule has been removed—if any of our config referenced it, we need to strip it before upgrading. Everything else is additive: PHP 7.4+ is now supported. Let’s upgrade on a branch, re-baseline on [high-risk module], and measure the impact on review time."

For Developers: "This tool will highlight methods that are hard to test or debug—so we can refactor them before they become a pain point. It’s like a linter for your brain’s RAM. In 1.3.0 the scoring got more accurate and matches the reference definition, so some numbers will move—that’s the metric being fixed, not your code getting worse. Also note the dependency tree rule was dropped, so remove it from your PHPStan config when you bump the version. Plus, it’ll make pair programming easier by surfacing ‘complexity hotspots’ upfront."