Phploc Laravel Package

Product Decisions This Supports

• Refactoring prioritization: Use LOC, class/method length, and cyclomatic complexity to rank modules by maintainability risk before committing roadmap capacity to cleanup. A class with high complexity and excessive length is a candidate for a targeted refactor, not a blanket rewrite.
• Quality gates and release criteria: Establish lightweight CI thresholds—for example, fail a build when average complexity per class or maximum method length exceeds an agreed budget. This turns “code quality” into an enforceable product constraint.
• Build vs. buy for code-health reporting: Adopt this package as a cheap measurement instrument rather than building an internal metrics service. It answers “how big and complex is this codebase?” but does not replace a dashboard, static analysis platform, or security scanner.
• Roadmap and modernization sizing: Compare directories, applications, or acquired codebases to estimate relative effort for modernization, migration, or re-platforming. Metrics support capacity conversations with engineering leads.
• Due diligence and vendor assessment: Run it against acquired or outsourced PHP/Laravel code to get a fast structural baseline—size, comment ratio, class/method complexity—before signing off on maintenance budgets.
• Onboarding and code-review heuristics: Give new engineers a structural map of a legacy codebase and point reviewers toward complexity hotspots rather than reviewing uniformly.
• Use cases: quarterly code-health reviews, pre-feature risk checks in legacy areas, CI complexity budgets, comparing Laravel modules, and validating whether a refactor actually reduced complexity.

When to Consider This Package

Consider it when:

• You need a fast, zero-configuration baseline of PHP code size and complexity and can accept a CLI-only workflow.
• Your stack is PHP 7.4+ / Laravel, and you are comfortable invoking a Composer-installed binary against a directory such as app/ or src/.
• You want a low-cost, low-integration signal for technical debt—not a full static analysis platform.
• You can pin the version (for example, 8.0.8) and validate output on a representative repository before relying on it in CI.
• You have engineering capacity to parse text output or wrap the command in an Artisan command/script if you need programmatic reporting.

Look elsewhere when:

• You need actively maintained, widely adopted tooling. This fork has 27 stars, zero dependents, and a small contributor base; treat it as a stopgap, not a foundation.
• You need Laravel-specific analysis—Blade templates, Eloquent models, route/controller coupling—or modern PHP AST-level accuracy. This tool measures files; it does not understand framework semantics.
• You need machine-readable output (JSON/SARIF), an API, or native dashboard integration. Output is CLI text and requires parsing.
• You need security, duplication, or dependency vulnerability analysis. Pair with PHPStan, Psalm, PHPMD, PHP_CodeSniffer, or Composer audit instead.
• You need vendor support, SLAs, or large-monorepo performance guarantees.
• You are risk-averse about forked packages with low validation. Prefer the upstream sebastianbergmann/phploc or a commercially supported platform, and revisit this fork only if it proves stable in your environment.

How to Pitch It (Stakeholders)

For executives: This is a low-cost diagnostic, not a platform bet. It gives us a repeatable way to quantify maintainability risk—code size, comment ratio, class and method length, cyclomatic complexity—so refactoring and modernization requests can be justified with numbers instead of anecdotes. Adoption cost is one dev dependency and a CI step; the risk is maintenance, since the package is a low-adoption fork. Recommend a time-boxed pilot on one repository, with a fallback to the upstream tool or existing static analysis if output or maintenance disappoints. Do not position it as a security or quality certification tool.

For engineering: Install as a dev dependency, run phploc app/ or phploc src/, and use the output to set a small number of complexity budgets in CI—not to chase every metric. Pin the version, parse only the metrics you will act on, and validate against a known codebase first. The tool is CLI-only and text-output, so wrap it if you need structured reporting. It complements PHPStan/PHPMD; it does not replace them. Treat the fork’s low adoption and future-dated release metadata as diligence flags, and keep the upstream package or an internal script as a fallback.