Deptrac Shim Laravel Package

Technical Evaluation

Deptrac (qossmic/deptrac) is a static dependency-analysis tool for PHP, not a Laravel package in the conventional sense: it ships no service provider, no config publish tag, and no runtime bindings. It parses the codebase with nikic/php-parser, builds a class-level dependency graph, and fails the process when edges violate layer rules declared in deptrac.yaml. This matters for positioning — it is a CI-time architecture governance tool that happens to live in require-dev, and should be evaluated against PHPStan/Larastan and code review discipline, not against application libraries.

Architecture fit. Strong for enforcing the part of a Laravel codebase that is structurally explicit: App\Domain must not depend on App\Http, controllers must not reach into repositories of another bounded context, Illuminate\* must not leak into domain services. It fits a modular monolith or DDD-layered Laravel app particularly well, because those architectures encode their boundaries as namespaces, and Deptrac's collectors operate on namespace, class, implements, and attribute matchers. Fit degrades in codebases that rely on Laravel's dynamic resolution: app(Foo::class), resolve(), facade accessors, container-tagged bindings, and string class names are opaque to static analysis. Deptrac will not see those edges, so the ruleset provides a floor, not a guarantee. That is the single most important caveat for a Laravel TPM to internalize and communicate.

Integration feasibility. Low friction. One composer require --dev qossmic/deptrac, one YAML file at the repo root, one CI step invoking vendor/bin/deptrac analyse. No application code changes, no bootstrapping, no migration. The --generate-baseline workflow lets an existing codebase adopt the tool without an immediate cleanup project — the baseline suppresses today's violations while blocking new ones. Output formatters (console, JSON, JUnit, GitHub Actions annotations, GitLab code quality, Graphviz) mean the tool slots into existing reporting without bespoke glue. The Graphviz dumper is an underrated adoption lever: a rendered dependency diagram is far more persuasive to skeptical engineers than a failing build.

Technical risk.

• Analysis blind spots — the container, facades, and magic methods are invisible; do not treat a green Deptrac run as proof of boundary integrity.
• Patch-release uncertainty — 1.0.2 is a patch within the 1.0 line and, per semver, should contain only fixes. That is an assumption, not a verified fact; the linked release notes were not included in the review packet. The concrete things to confirm are PHP version floor, cache-file format changes (a stale cache after upgrade can produce confusing results), and any formatter output changes that CI log parsers might depend on. None of these are likely to be blocking, but they should be checked before bumping in a locked pipeline.
• Config-rot false confidence — a layer name typo or an unmatched collector silently yields an empty layer, so rules pass trivially. There is no schema-level guarantee that your rules are meaningful.
• Single-maintainer / small-team exposure — the project has a long history (SensioLabs origin) but a narrow maintainer base. Mitigated entirely by it being dev-only with zero production blast radius.

Key questions. What changed in 1.0.2 specifically, and does it touch cache format, PHP floor, or formatter output? Which architectural boundary are we actually trying to protect, and is it expressible in namespaces today? Who owns deptrac.yaml when layers legitimately evolve? Do we have a baseline burn-down commitment, or will the baseline become permanent sediment?

Integration Approach

Stack fit. Works in any Composer project; nothing about it is Laravel-specific, which is both the appeal and the limitation. It coexists cleanly with Larastan/PHPStan (type and correctness analysis), Pint and PHPCS (style), and Rector (refactoring). Overlap is minimal because the axes differ: PHPStan asks "is this code correct," Deptrac asks "is this code allowed to know about that code." Both belong in CI. Requires PHP 8.1+ for the 1.0 line, so projects still on PHP 8.0 or Laravel 8/9-era stacks need to confirm the floor before adopting.

Migration path. Four stages, each independently valuable:

1. Observe — install as a dev dependency pinned to ^1.0, commit only deptrac.yaml with the namespace structure you believe you have, run locally, and read the output. No CI yet. This is a discovery exercise; it routinely surfaces boundaries that exist in documentation but not in code.
2. Baseline — generate a baseline against main so the current violation set is tolerated. The tool now blocks only new violations on day one, which is the political precondition for getting it merged at all.
3. Enforce — add a non-blocking CI job first, flip to blocking after one or two clean sprints. Publish the Graphviz output somewhere engineers actually look.
4. Ratchet — set a baseline line-count budget that must decrease each quarter, or the baseline becomes a permanent exemption list.

Compatibility. Composer-level isolation means no conflicts with application dependencies beyond the PHP floor. Lock file plus Dependabot for controlled bumps. Keep the Deptrac version consistent between developer machines and CI (the lock file handles this) — divergent versions with a shared cache file are a known source of confusing "it passed locally" reports.

Sequencing. Do not introduce Deptrac during a large refactor or a framework upgrade; the first ruleset should be built against a quiescent main. If the team is simultaneously adopting PHPStan, stagger them by a sprint — two new blocking CI gates landing at once reads as process tax and invites both to be disabled together. Pin the version bump to 1.0.2 as its own trivial PR with a full CI run on a cold cache, so any cache-format regression is isolated and attributable.

Operational Impact

Maintenance. Genuinely low. Dev-only, no runtime surface, no production dependency, no upgrade pressure tied to framework releases. The recurring cost is not the tool but the configuration: deptrac.yaml is an architectural artifact that encodes intent, and intent drifts. Assign explicit ownership (architecture lead or tech lead, not "the team") or the file will quietly diverge from reality and produce either noise or false comfort.

Support. Open source, community maintained, no vendor relationship available. Support means reading the changelog, watching the issue tracker, and accepting that a fix may need to come from the team itself. Acceptable here precisely because the blast radius of the tool being broken is "CI gate pauses," not "customers affected."

Scaling. Analysis time scales with codebase size and graph density. A mid-size Laravel app typically analyzes in seconds to low tens of seconds; a large monorepo with heavy namespaces can push into minutes. Caching (via cache file) and path scoping are the standard mitigations, and the analysis is a natural candidate for a parallel CI job rather than inline with tests. The bigger scaling constraint is organizational: one global deptrac.yaml for multiple teams becomes a coordination bottleneck, and per-module configs multiply maintenance. Decide the config topology before the second team onboards.

Failure modes to design against.

• Baseline sediment — the file grows and never shrinks; the gate becomes decorative. Counter with a metric and a quarterly review.
• Silent no-op — a renamed namespace empties a collector and every rule passes. Counter by periodically running with verbose output and confirming matched class counts are non-trivial per layer.
• False-positive fatigue — one noisy, arguably-correct violation left unresolved erodes trust faster than ten resolved ones build it. Triage aggressively at rollout.
• Cache staleness after upgrade — mitigated by clearing the cache on version bump.
• CI-only enforcement — developers discover violations after pushing. Provide the one-liner and a Composer script alias so it runs pre-push.

Ramp-up. Half a day to first meaningful run for an engineer comfortable with YAML and namespaces; the concepts (layers, collectors, ruleset, baseline) are few and well documented. Designing good layers — ones that reflect real architectural intent rather than an aspirational diagram — takes a week or two of iteration and benefits from a second reviewer. Budget a short team walkthrough focused on how to read a violation message and what the baseline means; without it, the first red build produces a round of "just add it to the baseline" that the tool cannot defend against on its own.