Phpmetrics Collector Bundle Laravel Package

Technical Evaluation

Architecture fit — poor as packaged, salvageable as a component. The package is a Symfony bundle that registers a DataCollector with Symfony's WebProfilerBundle and renders a panel in the Symfony debug toolbar. Laravel has no equivalent extension point: its debug bar (barryvdh/laravel-debugbar) wraps PHP DebugBar's DataCollectorInterface, a different abstraction. Every Laravel integration path requires replacing the bundle's Symfony wiring rather than reusing it. The genuinely portable asset is the upstream phpmetrics/phpmetrics analysis engine, which is framework-agnostic.

Integration feasibility — low for the bundle, moderate for the engine. Two viable paths:

1. (Recommended) Adopt phpmetrics/phpmetrics as a dev dependency and run it in CI, publishing the HTML report as a build artifact / GitLab Pages / GitHub Pages target. Zero framework coupling, no fork to maintain.
2. (Optional) Write a small custom Laravel debug bar collector that shells out to PhpMetrics, parses the JSON/XML report, and caches results keyed by git rev-parse HEAD + file mtime hash. Estimated 1–3 days of engineering; the bundle itself contributes little more than a reference UI.

Note the conceptual mismatch: PhpMetrics performs static analysis (cyclomatic complexity, maintainability index, Halstead, coupling, LCOM). It is not a runtime profiler. Embedding it in a debug bar implies analyzing the whole codebase on a request — a pattern that only works behind aggressive caching and is better served by an on-demand command or CI job.

Technical risk — elevated. Signals: 51 stars, 0 dependents, stale Symfony constraint set, and an "opportunity" score of 0.34 (low incremental value versus existing QA tooling). Risks include: composer conflicts from old symfony/* constraints in a modern Laravel app; incompatibility of the bundle with PHP 8.2/8.3 and Laravel 10–12; no production validation anywhere; and reliance on WebProfilerBundle, which is a dev-only, version-sensitive internal.

Key questions for the team:

• Is the objective per-request developer insight or code-quality gating in CI? Only the latter justifies adoption.
• What does PhpMetrics surface that PHPStan/Psalm/PHPMD/GrumPHP do not already surface for us?
• What are our supported PHP/Laravel versions, and does phpmetrics/phpmetrics still release against them?
• Who owns a fork or custom collector, and what is the deprecation plan if upstream stalls?
• What is the acceptance criterion — a working debug-bar panel, or a quality threshold enforced on merges?

Integration Approach

Stack fit. Do not install the bundle in a Laravel application. Treat the repository as reference material: it demonstrates how to wire PhpMetrics into a debug surface. Reuse the engine (phpmetrics/phpmetrics), discard the Symfony integration layer.

Migration path.

• composer require --dev phpmetrics/phpmetrics
• Add a console command (php artisan quality:metrics) that invokes the analyzer against app/, src/, or configured paths and writes JSON to storage/app/metrics/.
• If in-editor feedback is genuinely wanted, implement App\Support\DebugBar\PhpMetricsCollector implements DataCollectorInterface and register it via the debugbar.collectors config key, guarded by APP_DEBUG and a metrics.enabled flag.
• Cache aggressively: key the artifact on Git SHA plus a hash of analyzed files; never analyze on a normal request.

Compatibility.

• Verify the PhpMetrics release supports our PHP runtime; pin the version in composer.json.
• Do not pull symfony/web-profiler-bundle or the bundle's transitive Symfony constraints into the application — conflict risk is high and the benefit is nil.
• Confirm the debug bar version in use and the exact DataCollectorInterface signature before writing the collector; this interface has changed across PHP DebugBar majors.

Sequencing.

1. Baseline current quality tooling; identify the specific gap PhpMetrics fills (maintainability index, class coupling, complexity distribution).
2. Spike the CLI path and publish a report artifact — one sprint.
3. If stakeholders find the report actionable, add a CI threshold (e.g., fail on new classes exceeding a complexity budget) rather than a blocking global gate.
4. Only then evaluate the debug-bar collector as a developer-convenience layer.
5. Explicitly close out the "install the Symfony bundle" option in the decision record.

Operational Impact

Maintenance. The bundle has no meaningful maintenance signal and zero dependents — we would be the sole consumer of any fork. Owning a fork of a Symfony dev-tool bundle inside a Laravel codebase is a poor long-term trade. The CLI path reduces our maintainable surface to a pinned dev dependency and one Artisan command.

Support. No vendor support; small community (~51 stars) means Stack Overflow and issue-tracker answers will be thin. Internal ownership and documentation are mandatory. Budget a named owner for the quality-tooling domain.

Scaling. Static analysis cost scales with codebase size, not traffic — safe in CI, unsafe per request. Large monorepos may need path scoping, memory limit raises (-d memory_limit=1G), and parallelism. The debug bar panel, if built, must read a cached artifact and degrade gracefully to "no report available" rather than triggering analysis inline.

Failure modes to design for.

• Shell-exec or subprocess failure (analyzer missing, non-zero exit) — surface as a skipped check, not a broken build.
• Memory exhaustion or timeout on large codebases — scope paths, enforce a hard timeout.
• Stale cached reports after branch switches — key cache on commit SHA, invalidate on merge.
• Debug bar breakage on Laravel or PHP DebugBar upgrades — wrap the collector registration in a class_exists/interface-version guard.
• Composer resolution conflicts from Symfony constraints — avoided entirely by not installing the bundle.

Ramp-up. Low for the CLI/report path — a mid-level engineer can wire it in a day. Moderate for a custom collector, mainly in learning PHP DebugBar's collector contract and rendering API. The larger ramp is interpretive: the team must be able to read complexity, maintainability index, and coupling scores and convert them into review guidance, otherwise the report is decorative.

TPM recommendation. Score the package itself as do-not-adopt: the Symfony-specific surface does not transfer, and the project shows no adoption or maintenance momentum. Adopt the underlying phpmetrics/phpmetrics engine as a CI-only quality artifact, gate on deltas rather than absolutes, and defer any Laravel debug-bar UI to a small, opt-in, cached collector built in-house if developer demand is demonstrated.