Cognitive Complexity Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: The package integrates seamlessly with PHPStan, a widely adopted static analysis tool in PHP ecosystems. This aligns well with modern PHP development workflows that emphasize code quality via static analysis (e.g., PSR-12, PHPStan, PestPHP).
• Non-Invasive: Since it’s a PHPStan extension, it doesn’t modify runtime behavior, making it suitable for greenfield and legacy projects alike.
• Complementary to Existing Tools: Works alongside other PHPStan rules, SonarQube, or custom CI checks, reinforcing a layered quality assurance approach.

Integration Feasibility

• Low Barrier to Adoption: Requires minimal setup—just install via Composer and configure PHPStan. No database migrations, API changes, or runtime dependencies.
• CI/CD Friendly: Can be integrated into existing pipelines (GitHub Actions, GitLab CI, etc.) as a pre-commit or pre-merge check.
• Language-Specific: PHP-only, which simplifies dependency management for monorepos or polyglot projects where other languages are involved.

Technical Risk

• False Positives/Negatives: Cognitive complexity is subjective; thresholds (e.g., "max allowed complexity") may need tuning to avoid noisy alerts or missed issues.
• Performance Overhead: Static analysis adds CPU/memory usage during CI runs, though negligible for most projects.
• Tooling Ecosystem Lock-In: Tight coupling with PHPStan means migrating to other static analyzers (e.g., Psalm) would require reconfiguring rules.

Key Questions

1. Thresholds: What cognitive complexity thresholds align with the team’s definition of "maintainable" code?
2. Toolchain Compatibility: Does the team already use PHPStan? If not, what’s the cost to adopt it?
3. Customization Needs: Are there edge cases (e.g., legacy code, generated classes) where complexity rules should be relaxed?
4. Alert Fatigue: How will violations be surfaced (CI failures, IDE annotations, PR comments) to avoid overwhelming developers?
5. Long-Term Maintenance: Who will own updating PHPStan/PestPHP rules as the package evolves?

Integration Approach

Stack Fit

• PHP Ecosystem: Ideal for Laravel, Symfony, or custom PHP applications using PHPStan.
• Tooling Stack:
  • CI/CD: GitHub Actions/GitLab CI with PHPStan as a step.
  • IDE: PHPStorm/VSCode with PHPStan integration for real-time feedback.
  • Monorepos: Works per-project or globally (if PHPStan is configured at the root).
• Alternatives: If PHPStan isn’t used, consider migrating to it or using the package’s standalone rules via phpstan/extension-installer.

Migration Path

1. Assessment Phase:
   • Audit existing codebase for high-complexity methods/classes (e.g., using --level=max).
   • Document exceptions (e.g., legacy code, performance-critical paths).
2. Incremental Rollout:
   • Start with a permissive threshold (e.g., max-complexity=15) and tighten iteratively.
   • Add to CI as a warning before enforcing as a failure.
3. Tooling Setup:
   • Configure PHPStan (phpstan.neon) to include the extension:

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

   • Integrate with IDEs via PHPStan plugins.

Compatibility

• PHP Version: Compatible with PHP 8.0+ (PHPStan’s minimum version).
• Laravel/Symfony: No framework-specific conflicts; works with any PHP codebase.
• Generated Code: May need exclusion rules for auto-generated classes (e.g., Eloquent models, API clients).

Sequencing

1. Pre-Integration:
   • Baseline current complexity metrics (e.g., phpstan analyse --level=max).
   • Identify high-complexity hotspots for prioritization.
2. Integration:
   • Add to composer.json dev dependencies:

     "tomasvotruba/cognitive-complexity": "^x.y.z"
     

   • Configure PHPStan to enforce rules.
3. Post-Integration:
   • Monitor CI failure rates and adjust thresholds.
   • Train developers on refactoring techniques (e.g., extract methods, use strategy pattern).

Operational Impact

Maintenance

• Rule Updates: Stay aligned with PHPStan minor updates (e.g., breaking changes in tomasvotruba/cognitive-complexity).
• Custom Rules: Maintain local overrides for false positives (e.g., @phpstan-ignore-next-line).
• Documentation: Update team runbooks with complexity guidelines and refactoring examples.

Support

• Onboarding: Developers may need training on:
  • Interpreting complexity metrics.
  • Refactoring high-complexity code (e.g., breaking down methods).
• Tooling Support: Ensure IDE plugins and CI integrations are up-to-date.
• Escalation Path: Define how to handle disputes over complexity violations (e.g., code review with architects).

Scaling

• Performance: Static analysis scales linearly with codebase size; distribute CI workloads if needed (e.g., parallel PHPStan runs).
• Team Growth: Complexity rules help onboard new developers by enforcing consistency.
• Legacy Code: Use exclusion rules sparingly; prioritize incremental refactoring.

Failure Modes

• False Positives: Overly strict thresholds may block legitimate code. Mitigate with:
  • Custom annotations (@complexity-allow).
  • Exclusion lists in phpstan.neon.
• Tooling Failures: PHPStan/CI outages. Mitigate with:
  • Fallback to manual reviews during outages.
  • Redundant checks (e.g., local IDE analysis + CI).
• Alert Fatigue: Too many violations. Mitigate with:
  • Phased enforcement (warn → fail).
  • Focus on critical paths first.

Ramp-Up

• Initial Effort: Low (installation + configuration).
• Developer Adoption: Medium (requires cultural shift toward refactoring).
• ROI Timeline:
  • Short-term: Faster onboarding, fewer bugs in complex logic.
  • Long-term: Reduced technical debt, easier maintenance.
• Key Metrics to Track:
  • % of PRs with complexity violations.
  • Time spent refactoring vs. new feature development.
  • Developer satisfaction with codebase maintainability.