Cognitive Complexity Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: The package remains a PHPStan extension and still integrates seamlessly with PHPStan-based quality pipelines. No change to the runtime model — it does not modify application behavior, so it stays viable for both greenfield and legacy Laravel codebases.
• Non-Invasive: Unchanged. Adoption is still configuration-only (Composer dev dependency + phpstan.neon include), with no database, queue, or service-provider footprint.
• Complementary to Existing Tools: Unchanged. It composes with other PHPStan rules, SonarQube, and custom CI gates.
• New — Rules Surface Shrank: 1.3.0 removes the dependency-tree rule. Projects that referenced that rule explicitly in phpstan.neon (or relied on it as a gate) will lose coverage silently or error on an unknown rule identifier. Treat this as a scope reduction of the tool's value proposition, not just a version bump.
• New — Scoring Is Now Specification-Aligned: Complexity scores now follow the original cognitive complexity paper more closely. This is architecturally positive (defensible numbers, easier to justify in code review) but it means the metric is not continuous across the upgrade — numbers from 1.2.x and 1.3.x are not comparable.

Integration Feasibility

• Low Barrier to Adoption: Unchanged — install via Composer, enable the extension, run PHPStan. Still no migrations or API surface changes.
• CI/CD Friendly: Unchanged, but the rollout must account for a one-time score discontinuity (see Integration Approach).
• New — Wider Language Floor: PHP 7.4+ is now supported, which extends viability to older Laravel 8-era applications still on 7.4. Practically, the effective floor is set by the PHPStan major version you run, not by this package alone — confirm the PHPStan release in use still supports your PHP runtime.
• Language-Specific: Still PHP-only; unchanged dependency-management profile for polyglot monorepos.

Technical Risk

• Breaking Change — Removed Rule: The dependency-tree rule is gone. Any phpstan.neon reference to it, or any baseline entry generated by it, must be cleaned up. Risk of silent loss of a quality gate if removal is not paired with a config audit.
• Behavioral Change — Recalibrated Scores: Because scoring now matches the reference paper, previously passing code may fail and previously failing code may pass. Baselines (phpstan-baseline.neon) and inline @phpstan-ignore annotations generated under 1.2.x are unreliable and should be regenerated rather than patched.
• Threshold Drift: A threshold tuned to the old algorithm (e.g. max-complexity=15) no longer means the same thing. Alert volume will shift in both directions immediately after upgrade.
• False Positives/Negatives: Still present and now transiently amplified during the version transition. Plan for a short period of noisy or under-reporting results.
• Performance Overhead: Unchanged — static analysis cost only, negligible for most Laravel projects.
• Tooling Ecosystem Lock-In: Unchanged — still coupled to PHPStan; still requires reconfiguration to move to Psalm or similar.

Key Questions

1. Baseline Regeneration: Who owns regenerating phpstan-baseline.neon and re-running the initial complexity survey after upgrade, and on what branch?
2. Removed Rule Usage: Do any projects in the portfolio explicitly enable the dependency-tree rule or depend on its output in a dashboard/report?
3. Threshold Recalibration: Given the paper-aligned scoring, does the current max-complexity value still represent "maintainable" for this team? Who signs off on the new number?
4. Runtime Support Matrix: Is PHP 7.4 support actually needed by any in-scope application, or is the team's floor already 8.1+? This determines whether the widened support is meaningful or just a constraint to verify against PHPStan.
5. Transition Window: Will the upgrade be done in a single PR per repo, or staged with a temporary "warn-only" period to absorb the score delta?
6. Long-Term Ownership: Who tracks upstream rule removals (this release removed one) and validates scope before the next minor bump?

Integration Approach

Stack Fit

• PHP Ecosystem: Unchanged — Laravel, Symfony, or bespoke PHP applications using PHPStan.
• Tooling Stack:
  • CI/CD: GitHub Actions/GitLab CI with PHPStan as a step; unchanged.
  • IDE: PHPStorm/VSCode PHPStan integrations; unchanged, but expect score changes to surface as new annotations until baselines are refreshed.
  • Monorepos: Unchanged; note that score shifts will land per-project and should be reviewed per-project rather than across the whole repo at once.
• New — Wider Runtime Fit: PHP 7.4+ support means older Laravel 8/9 applications on 7.4 are now in scope. Verify the paired PHPStan version supports 7.4 before promising this to stakeholders.
• Alternatives: Unchanged — standalone rule registration via phpstan/extension-installer remains an option where PHPStan is not yet adopted.

Migration Path

1. Pre-Upgrade Audit:
   • Grep all phpstan.neon / phpstan.neon.dist files for references to the removed dependency-tree rule; delete those entries and any baseline lines they produced.
   • Record the current complexity score distribution per repo as the 1.2.x reference point (needed to explain score deltas to reviewers).
2. Controlled Upgrade:
   • Bump to ^1.3 in composer.json dev dependencies on a dedicated branch.
   • Run PHPStan and diff the violation set against the pre-upgrade snapshot; expect both new and cleared violations purely from the rescoring.
3. Baseline Regeneration:
   • Regenerate phpstan-baseline.neon rather than hand-editing it. Do not carry forward 1.2.x suppressions.
   • Re-evaluate inline @phpstan-ignore annotations; the release notes explicitly document error-ignoring behavior, so review that guidance before re-adding suppressions.
4. Threshold Recalibration:
   • Pick the new max-complexity value from the regenerated distribution, not from the old number.
   • Run warn-only for one or two sprints before enforcing as a CI failure.

Compatibility

• PHP Version: Changed — now PHP 7.4+ (previously documented here as 8.0+). Confirm against your PHPStan major version; the tighter of the two constraints governs.
• Laravel/Symfony: No framework-specific conflicts; unchanged.
• Generated Code: Unchanged — Eloquent models, API clients, and other generated classes may still need exclusion rules.
• Config Compatibility: Breaking at the config layer for anyone referencing the removed rule. Validate every phpstan.neon in the portfolio.
• Metric Compatibility: Breaking at the reporting layer — dashboards, trend lines, and quality gates that track complexity over time will show an artificial step change at the upgrade commit. Annotate the transition point.

Sequencing

1. Audit (portfolio-wide, small): inventory PHPStan versions, PHP runtimes, and any usage of the removed rule.
2. Pilot (one mid-size Laravel repo): upgrade, regenerate baseline, capture score delta, choose a candidate threshold.
3. Rollout (remaining repos): apply the validated config and threshold; stagger so CI noise does not hit all teams simultaneously.
4. Enforce: after a warn-only window, promote the complexity rule to a failing CI check.
5. Document: update the team runbook with the new scoring model, the new threshold, and the fact that pre-1.3 numbers are not comparable.

Operational Impact

Maintenance

• Rule Updates: 1.3.0 demonstrates that rules can be removed, not only added. Maintenance must include reading each release for scope reduction, not just for new checks.
• Baseline Hygiene: Post-upgrade baselines are effectively new artifacts. Schedule a baseline regeneration at the same time as the version bump to avoid stale suppressions masking real issues.
• Custom Rules / Overrides: Local overrides and @phpstan-ignore usage should be reviewed against the newly documented error-ignoring behavior; expect some annotations to become redundant or malformed.
• Documentation: Update runbooks, threshold rationale, and any onboarding material that quotes complexity numbers, since historical figures are no longer apples-to-apples.

Support

• Onboarding: Largely unchanged, but developers who learned the 1.2.x scoring will see different numbers. A short note explaining the paper alignment prevents "why did my score change?" support load.
• Tooling Support: Ensure IDE plugins and CI images use a PHPStan version compatible with both the package and, where relevant, PHP 7.4.
• Escalation Path: Unchanged — code review with architects for disputed violations. Add an interim path for "this violation is a rescoring artifact, not a new problem."

Scaling

• Performance: Unchanged — linear with codebase size; parallelize PHPStan runs where needed.
• Team Growth: Unchanged benefit — consistent, now defensible complexity scoring eases onboarding.
• Legacy Code: The broadened PHP 7.4 support brings older applications into scope. Use exclusion rules sparingly; prioritize incremental refactoring rather than mass suppression on newly-eligible legacy repos.

Failure Modes

• Config Resolution Errors: A leftover reference to the removed dependency-tree rule can break the PHPStan run entirely. Mitigate by auditing configs before bumping.
• Baseline Churn: Regenerating baselines can absorb real regressions hidden among rescoring noise. Mitigate by diffing violation sets and reviewing new entries rather than accepting the regenerated file wholesale.
• Threshold Miscalibration: A value carried over from 1.2.x may be far too strict or too loose. Mitigate with a warn-only window and a data-driven threshold.
• Silent Coverage Loss: The removed rule may have been the only check for a class of issue. Mitigate by confirming whether that check is covered elsewhere (e.g., another PHPStan rule set) or consciously accepting the gap.
• Alert Fatigue: Rescoring will produce a one-time burst. Mitigate by timing the rollout away from release deadlines and communicating the transition in advance.

Ramp-Up

• Initial Effort: Low-to-medium — install and config are trivial; the effort sits in the config audit, baseline regeneration, and threshold recalibration.
• Developer Adoption: Medium — unchanged cultural shift toward refactoring, plus a short adjustment to new score semantics.
• ROI Timeline:
  • Short-term: Defensible, paper-aligned complexity numbers; cleaner configs where the removed rule is retired.
  • Long-term: Reduced technical debt and a quality gate that can be explained to stakeholders by reference to a published definition rather than an arbitrary formula.
• Key Metrics to Track:
  • Count of configs still referencing the removed rule (target: zero).
  • Score delta per repo at the upgrade commit (expected non-zero; should be explainable).
  • % of PRs with complexity violations before vs. after threshold recalibration.
  • Baseline entries added per sprint (a rising trend signals threshold miscalibration, not code decay).
  • Developer satisfaction with codebase maintainability.