Php Metrics Laravel Package

Product Decisions This Supports

• Roadmap allocation: refactor vs. build. PhpMetrics turns "our code is messy" into comparable numbers (cyclomatic complexity, coupling, Halstead, maintainability index), giving you a defensible basis for deciding whether the next quarter funds a tech-debt sprint or new features.
• Technical due diligence. A one-command HTML report is a fast, low-cost input to acquisition reviews, vendor/outsourced-team audits, or pre-integration checks on a third-party PHP codebase.
• Build vs. buy. Buy—i.e., adopt. It's MIT-licensed, one composer require --dev away, zero-config by default, and produces a stakeholder-readable artifact. Building equivalent reporting is weeks of engineering for no differentiation.
• Quality-gate policy. Supports decisions about what CI enforces (complexity thresholds, maintainability floors) and whether quality gates are advisory or blocking—an org/process decision, not just a tooling one.
• Onboarding and architecture reviews. The HTML report's class/namespace views give new engineers and architects a map of hotspots before they touch code.
• Legacy modernization sequencing. Rank modules by complexity/maintainability to choose which service to extract or rewrite first.
• Engineering-health OKRs. Provides a repeatable baseline metric for "reduce complexity in the payments module by X%" style goals.

This is internal engineering tooling, not a runtime dependency. It ships nothing to end users, affects no product surface, and carries no customer-facing risk—which is exactly why it's a cheap decision.

When to Consider This Package

Adopt when:

• You own a PHP codebase large enough that "where is the risk?" is a recurring, unresolved question (multiple modules, legacy layers, several teams).
• You need a shareable artifact for non-authors—engineering managers, executives, auditors—not just terminal output for the person who wrote the code.
• You want a near-zero-friction start: no config file required, sensible defaults, HTML out of the box.
• You already run CI and can archive the JSON/HTML per build.
• You want an MIT-licensed tool with docs, changelog, and an active release cadence, without a procurement cycle.

Look elsewhere or supplement when:

• You need per-line, in-editor feedback or blocking correctness checks. That's PHPStan/Psalm territory; PhpMetrics is a periodic health report, not a linter.
• You need security or dependency-risk scanning. Use a dedicated SCA tool.
• You need trend history, per-team dashboards, and drill-down over time. PhpMetrics has no built-in historical store; you either archive artifacts yourself or pair it with SonarQube, Qodana, or a hosted platform. Decide this explicitly—teams often expect trend lines and are disappointed.
• You need a stable programmatic API. Treat it as a CLI tool. The "0 dependents" signal is expected for a binary, but it also means don't plan to build a product on its internals.
• You have polyglot repos and want one quality narrative across languages.
• You need strict, centrally governed rule configuration across many repos; the lightweight-defaults advantage becomes a limitation.

Also budget for interpretation: metrics flag generated code, fixtures, and vendor directories if unscoped, and complexity numbers can be gamed. Plan a scan-scope config and a short "how to read this report" note.

How to Pitch It (Stakeholders)

For executives: PhpMetrics is a free, MIT-licensed, mature static analysis tool for PHP (≈2.6k GitHub stars, documented, actively released). It costs one dev-dependency line and an afternoon of setup, with no license fee, no vendor contract, and no lock-in. In return we get an objective, repeatable read on code health—complexity, coupling, maintainability—which lets us argue for or against refactoring investment with numbers instead of anecdotes, and gives us a defensible input to due diligence and vendor reviews. The decision required is small; the value is in starting the measurement habit now so we have a baseline later.

For engineering: One command—php ./vendor/bin/phpmetrics --report-html=report src/—produces a readable HTML report with complexity, coupling, maintainability index, and class maps. It runs in CI, is configurable via a simple config file, and complements rather than replaces PHPStan/Psalm: they catch defects, PhpMetrics shows structural risk and hotspots. Recommend it as a periodic, scoped health check with artifacts archived per build, and be explicit that it is a diagnostic aid, not a gate we turn on blindly in week one.