Php Metrics Laravel Package

Technical Evaluation

Architecture fit. PhpMetrics is a CLI-first static analysis tool, not a library. It installs as a Composer --dev dependency, walks a source tree with a PHP parser, computes class/file/project-level metrics (cyclomatic complexity, Halstead, maintainability index, CRAP, LCOM, coupling, comment ratio), and emits a self-contained HTML report plus JSON/XML/CSV variants. That means it has zero runtime footprint in production — no autoload surface, no framework coupling, no service registration. For a Laravel codebase it is architecturally inert: it reads source files and writes artifacts. The "0 dependents" signal is expected and benign; the package is a terminal node in the dependency graph, so there is no downstream coupling risk and no blast radius beyond CI.

Integration feasibility. High. Integration is a single Composer dev requirement plus one CI step invoking vendor/bin/phpmetrics --report-html=build/metrics app/. The HTML report is a static file, which makes it trivially archivable as a CI artifact or publishable to Pages/S3. Configuration is a YAML file (.phpmetrics.yml) with --config, allowing exclude rules for vendor/, generated code, and migrations. The main feasibility question is not "can we run it" but "can we enforce it" — the tool is oriented toward visual reporting, so build-breaking thresholds require either the violations report output or parsing the JSON/XML in a wrapper script. Confirm this before promising a quality gate.

Technical risk. Low-to-moderate, and entirely contained in CI:

• Parser drift — new PHP syntax support depends on the bundled parser version. Validate against your exact PHP minor before rollout.
• Memory and runtime — HTML report generation is memory-hungry on large trees; expect to raise memory_limit and possibly shard by directory (via groups) for a monorepo.
• Signal quality — maintainability index and CRAP are opinionated; naive thresholds generate noise and developer pushback. Thresholds must be calibrated against a baseline, not adopted from defaults.
• Overlap — it does not replace PHPStan/Psalm (type and correctness analysis), PHP_CodeSniffer (style), or Deptrac (architecture boundaries). Position it as the trend/complexity layer, not the correctness layer. If you already run SonarQube, treat PhpMetrics as a faster, PHP-native complement rather than a second source of truth.
• Versioning — the package name in the request (halleck45/php-metrics) differs from the Composer package to install (phpmetrics/phpmetrics). Pin explicitly; verify the release cadence and changelog for breaking changes to report formats.

Key questions. Which PHP minor versions are in scope, and does the current release parse them? Are we willing to run this alongside existing analysers, or does it need to displace one? Who owns threshold calibration? Do we need per-PR gating or is a weekly trend report sufficient? What is the CI runtime budget for a full-tree scan? Is the HTML artifact published, and to whom?

Integration Approach

Stack fit. Strong for a Laravel/PHP shop. It is a first-class Composer citizen, installs into the existing require-dev block, and requires no new runtime (no Node, no Java, no database) — a meaningful advantage over SonarQube or other platform-grade tools. The HTML output is genuinely legible to non-engineers, which makes it usable in engineering-health reviews and tech-debt conversations, not just as a developer utility. For Laravel specifically, the exclude list matters more than usual: storage/, bootstrap/cache/, generated migrations, and IDE helper stubs should be excluded so the report reflects authored code.

Migration path. Additive, with no migration. Treat it as a net-new capability: add the dev dependency, generate a baseline report against main, and use that baseline as the reference point. The only "migration" is cultural — moving from ad hoc code-review intuition about complexity to a measured, tracked number. That argues for a report-only phase of at least one sprint before any gating.

Compatibility. Dev-only dependency, so no conflict with production constraints except PHP version resolution — Composer will refuse the install if the CLI tool's PHP floor exceeds the project's. Run composer require --dev in a branch and inspect the lockfile diff; if it drags in transitive upgrades, that is the moment to stop and reconsider. Report formats (JSON/XML schema) should be treated as a contract if you write a parser around them; pin the major version.

Sequencing.

1. Pilot — install on one representative service, generate a report, validate PHP parsing and runtime/memory on the largest tree.
2. Calibrate — tune excludes, establish baseline metrics, and pick two or three thresholds that reflect current reality rather than aspiration (start with maintainability index and CRAP, not raw complexity).
3. Automate — wire into CI as a post-test job producing an archived artifact; do not gate yet. Optionally publish the HTML for visibility.
4. Gate — introduce a non-blocking violation check (warn) for one sprint, then promote to blocking only for regressions against baseline, never for absolute thresholds, to avoid freezing a legacy codebase out of compliance.
5. Review — reassess after 60 days whether the gate is generating actionable signal or has become background noise. Kill it if the latter.

Operational Impact

Maintenance. Very low. No runtime to patch, no infrastructure, no data store. The recurring cost is (a) bumping the dev dependency and (b) re-tuning excludes when the repo layout changes. Budget roughly a few hours per quarter. The real maintenance burden is threshold ownership — without a named owner, the gate drifts into either permanently red or permanently ignored.

Support. MIT license, active release cadence, documented, with a sponsorship-backed single-maintainer model. Single-maintainer is the notable risk: if upstream stalls, your mitigation is cheap — it is a dev tool, so you can pin, fork, or drop it. This is fundamentally different from a runtime library risk. No vendor SLA, no commercial support tier; internal teams must own first-line triage.

Scaling. Analysis time and memory grow with codebase size; memory is the binding constraint, not CPU. For a large monorepo, expect to shard by directory or package and aggregate reports, or restrict scanning to changed paths on PRs with a full weekly scan. CI concurrency matters: a heavyweight analysis job on every PR will contend with test suites, so schedule the full scan nightly and a scoped scan per PR. Artifact storage also accumulates — expire reports aggressively.

Failure modes to design for.

• Silent pass — no violations configured, job always green, false assurance. Mitigate with an explicit assertion that the report file exists and is non-empty.
• Memory exhaustion — job OOMs on a large tree and is retried or skipped; mask as a flaky infra issue and it will be ignored. Set an explicit memory limit and alert on OOM as a failure, not a retry.
• Parser break on new syntax — after a PHP upgrade the tool errors or under-reports. Add a smoke test to the PHP-upgrade checklist.
• Generated-code noise — false positives from stubs and generated classes erode trust fast. Excludes are a first-class deliverable, not an afterthought.
• Non-determinism — timestamps and embedded metadata in reports cause artifact churn; don't diff raw HTML in version control.
• Tool sprawl — overlapping metrics with an existing platform tool producing two conflicting "quality scores." Decide the source of truth up front.

Ramp-up. Roughly half a day for one engineer to reach productive use; the HTML report is self-explanatory, so developer onboarding is near-zero and adoption friction is genuinely low. The non-trivial learning curve is interpretation: knowing which metrics predict defects in your codebase and which are noise. Plan for one engineer to own metric literacy (half a day of reading plus two calibration cycles) and to run a short session with the team on what the report is and is not telling them. Realistic time-to-first-useful-signal: one sprint; time-to-trusted-gate: one quarter.