Deptrac Shim Laravel Package

Product Decisions This Supports

• Architecture governance as a roadmap gate. Deptrac is a fitness function for your codebase: you declare layers (Domain, Application, Infrastructure, HTTP, etc.) and rules ("Domain must not depend on Infrastructure"), and it fails CI when someone violates them. That turns architecture from a wiki page into an enforceable, reviewable contract — useful when you're committing publicly to a modular-monolith or DDD direction.
• Build vs. buy. This is a "buy" (adopt OSS) decision, not a build one. The alternative isn't a competitor product, it's (a) an internal PHPStan/Psalm custom rule set, (b) reviewer vigilance, or (c) a commercial platform (SonarQube, Snyk) that gives you dashboards but not PHP-namespace-level layer rules. Deptrac wins on fit and cost for the specific job of boundary enforcement; the others win if you need a single cross-language quality dashboard for execs.
• Incremental tech-debt paydown on a legacy Laravel app. The baseline feature lets you snapshot existing violations and fail only on new ones. That converts "our architecture is a mess" from an unfundable epic into a ratchet: no new coupling today, N violations burned down per sprint. This is the single most useful PM-facing capability, because it makes remediation measurable and safe to schedule.
• Modularization / service-extraction sequencing. The dependency-graph output (Graphviz, JSON) quantifies coupling between layers and modules. Use it to pick which module to extract first, and to prove the boundary held afterwards. Strong input to "which team owns which module" and to a monolith-to-services roadmap.
• Due diligence and onboarding. Point it at an inherited or acquired PHP codebase to get a fast, objective read on how tangled it is; point new hires at the ruleset as executable documentation of "how we build things here."
• Definition-of-done and release-gating decisions. Wiring it into CI makes "no cross-layer imports" a merge criterion rather than a code-review opinion, which reduces review friction and reviewer-dependent quality.
• Security/compliance boundary enforcement. Rules like "only the Infrastructure layer may touch payment SDKs" or "domain code may not call outbound HTTP" become mechanically verifiable, which is auditable for reviews.

Limits worth stating up front: Deptrac is purely static. It sees use statements and references, not runtime container wiring — Laravel's service container, facades, app() helper, and package auto-discovery can hide real dependencies and produce both false positives and false negatives. It also says nothing about runtime correctness, performance, or test coverage. Treat it as one signal, not a quality score.

When to Consider This Package

Adopt when most of these hold:

• The codebase is a Laravel/PHP application or monorepo past roughly 30–50k LOC, or growing past the point where one or two people hold the whole architecture in their heads.
• There is a real, articulable layer story — modular monolith, hexagonal/ports-and-adapters, DDD bounded contexts, or at minimum "HTTP → Service → Repository → Model." If nobody can agree on the layers, the tool will only document the disagreement.
• CI already exists and runs on every PR (GitHub Actions, GitLab CI, Bitbucket). Deptrac ships formatters for GitHub Actions, GitLab, JUnit, and CodeClimate, so surfacing violations in the PR is close to free.
• You have existing coupling pain: cyclic dependencies, controllers reaching into models directly, "shared" or "common" packages that everything imports, refactors that keep getting reverted.
• You need an incremental adoption path — i.e., a legacy codebase where an all-violations-must-fail policy would block the team on day one. The baseline mechanism is the deciding feature here.
• PHP 8.1+ and a Composer-based workflow are already in place; the 1.0.x line is the current, stable major and safe to pin as ^1.0.

Look elsewhere, or defer, when:

• The app is small, single-team, and short-lived. The config-maintenance cost will exceed the value.
• The team cannot yet name its layers. Do the architecture workshop first; Deptrac is the enforcement mechanism, not the design exercise. Adopting it prematurely locks in a bad layer model as CI failures people learn to ignore.
• You need runtime dependency analysis, coupling/cohesion metrics, or complexity scoring — that's PHPStan/Psalm (with strict levels), phpMetrics, or a commercial platform.
• You need a single vendor dashboard spanning multiple languages for leadership reporting. Deptrac's JSON/Graphviz output can feed one, but it is not one.
• The codebase leans heavily on dynamic resolution (string class names, container make() with variables, heavy macro/magic usage). Coverage will be patchy and the team will lose trust in the signal quickly.
• You want to enforce boundaries across JS/TS, Go, or Python services too. Department-level coverage will be uneven; consider per-language tooling under one reporting layer.

If you adopt: start with two or three coarse layers and a handful of rules on one module, run in report-only mode for a sprint to measure the false-positive rate against Laravel idioms (facades, Eloquent relations, config/repository bindings), then flip to blocking with a baseline for the rest.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have an architectural rule set that lives in documentation and code review and is therefore enforced inconsistently. Deptrac is a mature, free, open-source PHP static-analysis tool that turns those rules into an automated check on every pull request: if a controller imports from the persistence layer, or domain code reaches for an HTTP client, the build fails. There is no license cost and no vendor lock-in; integration is a single configuration file plus one CI step. It also gives us a number we currently lack — how much architectural debt exists, and whether it is going up or down each sprint — which lets us fund cleanup incrementally instead of as a big-bang rewrite. The current release is 1.0.2, a patch on the stable 1.0 line: bug fixes only, no breaking changes, no migration work. The ask is one to two engineer-days for a scoped pilot on one module, with a go/no-go after thirty days based on violation trend and false-positive rate.

For engineering leadership: it is a linting layer for dependencies. It complements PHPStan/Psalm rather than replacing them: those check types and correctness, Deptrac checks who is allowed to talk to whom. The 1.0.x config format is stable, so our ruleset won't churn under us. Risks are honest: Laravel's container and facades can obscure real dependencies, so we should run report-only first and tune collectors; and a ruleset nobody maintains becomes noise, so we should assign an owner (usually the platform or architecture lead) and review the config quarterly. Success looks like: rules green on the target module, zero new violations per sprint, and a declining baseline count. If those three numbers don't move in a quarter, we drop it — the exit cost is deleting one config file and one CI step.