Deptrac Shim Laravel Package

Technical Evaluation

Architecture Fit Deptrac’s core purpose—enforcing architectural constraints via dependency analysis—aligns perfectly with Laravel’s layered architecture (MVC, DDD, or Clean Architecture). The package’s ability to:

• Validate layer boundaries (e.g., prevent App/Http/Controllers from depending on App/Domain/Entities).
• Detect cyclic dependencies (common in tightly coupled Laravel monoliths).
• Integrate with CI/CD as a gatekeeper for architectural drift. is a natural fit for Laravel projects exceeding 10K LoC or adopting microservices. The tool’s static analysis approach complements Laravel’s runtime flexibility without imposing runtime overhead.

Integration Feasibility

• Laravel-Specific Challenges:
  • Service Container: Deptrac cannot analyze Laravel’s dynamic bindings (e.g., bindIf(), tag()), limiting its ability to enforce rules on container-registered services. Mitigation: Define explicit layer paths in deptrac.yaml for container-bound classes.
  • Facades/Helpers: Static calls (e.g., Route::get()) may trigger false positives if not properly layered. Mitigation: Exclude vendor/ and configure paths to ignore facade-related files.
  • Event Listeners/Jobs: Deptrac won’t catch runtime dependency violations (e.g., a Job dispatching another Job in a circular fashion). Mitigation: Pair with runtime tests or custom validation.
• Toolchain Synergy:
  • PHPStan/Psalm: Deptrac can run before static analyzers to filter out architectural violations early.
  • Laravel Mix/Vite: No impact, as Deptrac operates on PHP code, not assets.
  • Database Migrations: Ignored by default (focuses on class dependencies).

Technical Risk

• Configuration Complexity:
  • deptrac.yaml requires careful layer definition. Poorly defined layers (e.g., overlapping paths) may lead to false negatives (missed violations) or false positives (legitimate dependencies flagged).
  • Risk Mitigation: Start with a minimal deptrac.yaml and iteratively refine rules.
• Performance:
  • Full scans on 50K+ LoC may add 1–5 minutes to CI pipelines. Mitigation: Cache results (--cache) and run in parallel with other checks.
• Version Lock:
  • The package is abandoned (redirects to qossmic/deptrac). Future updates may break deptrac.yaml schemas. Mitigation: Pin to 1.0.2 and monitor the main repo for breaking changes.
• Legacy Code:
  • Existing violations may require refactoring or grandfathering (e.g., @deptrac-ignore annotations). Risk: Cultural resistance to breaking changes.

Key Questions

1. Architectural Alignment:
   • Does the team’s target architecture (e.g., Hexagonal, Clean) map cleanly to Deptrac’s layer model? If not, how will gaps be addressed?
2. CI/CD Strategy:
   • Should Deptrac block merges (strict) or warn only (lenient)? How will exceptions be handled?
3. Tooling Overlap:
   • How will Deptrac interact with existing tools (e.g., PHPStan’s no-duplicate-classes)? Will it replace or supplement them?
4. Layer Granularity:
   • Should layers be coarse (e.g., App, Domain) or fine-grained (e.g., App/Http, App/Http/Controllers)? Trade-off: finer layers catch more violations but require more maintenance.
5. Runtime vs. Static:
   • Are there critical dependencies (e.g., dynamic proxy classes) that Deptrac cannot detect? If so, what’s the fallback strategy?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Composer: Seamless integration via vendor/bin/deptrac. No Laravel-specific hooks required.
  • Artisan: Can be wrapped in a custom command for IDE/CLI access (e.g., php artisan deptrac).
  • CI/CD: Native support for GitHub Actions, GitLab CI, and CircleCI via CLI.
  • Testing: Can run in phpunit.xml as a pre-test hook or standalone.
• Non-Laravel Components:
  • Works with Lumen, custom packages, or monorepos (if Composer paths are correctly configured).
  • Limitations:
    • Ignores runtime-generated classes (e.g., Str::camel()-based class names).
    • No support for Laravel’s app() helper (e.g., app()->make() bindings).

Migration Path

1. Discovery Phase (1–2 weeks):
   • Install and run Deptrac in non-blocking mode:

     composer require --dev qossmic/deptrac
     vendor/bin/deptrac analyze --fail-on=none
     

   • Document existing violations and architectural patterns.
2. Configuration Phase (2–4 weeks):
   • Define layers in deptrac.yaml:

     layers:
       - name: Presentation
         paths: [app/Http/Controllers, routes]
       - name: Application
         paths: [app/UseCases]
       - name: Domain
         paths: [app/Domain]
     

   • Start with permissive rules (e.g., allow all dependencies) and tighten incrementally.
3. Pilot Phase (3–4 weeks):
   • Integrate into CI as a warning-only check:

     # GitHub Actions
     - name: Deptrac (Warn)
       run: vendor/bin/deptrac analyze --fail-on=warning
     

   • Train developers on interpreting output and requesting exceptions.
4. Enforcement Phase (Ongoing):
   • Gradually increase strictness (e.g., --fail-on=violation for new features only).
   • Add pre-commit hooks (e.g., Husky) for local feedback.

Compatibility

• PHP Versions:
  • Supported: PHP 8.1–8.3 (Laravel 9/10).
  • Legacy: PHP 7.4 may work but lacks long-term support. Use qossmic/deptrac:0.24.0 if needed.
• Composer:
  • Requires Composer 2.x (Laravel’s minimum). No conflicts with Laravel’s platform packages.
• IDE:
  • No native IDE support, but CLI output can be parsed for warnings (e.g., via deptrac:analyze task in PHPStorm).
• Database/Queue:
  • No impact on migrations or queue workers (static analysis only).

Sequencing

1. Pre-Integration:
   • Audit current dependencies with --fail-on=none to identify hotspots (e.g., controllers depending on domain models).
   • Document known violations that require refactoring.
2. Rule Rollout:
   • Phase 1: Enforce presentation → application rules (low risk).
   • Phase 2: Enforce application → domain rules (higher risk of violations).
   • Phase 3: Add cyclic dependency checks (e.g., ServiceA ↔ ServiceB).
3. Post-Integration:
   • Monitor false positives and adjust deptrac.yaml or codebase.
   • Consider automated exception handling (e.g., @deptrac-ignore for legacy code).

Operational Impact

Maintenance

• Configuration Drift:
  • deptrac.yaml will need updates as:
    • New layers are added (e.g., App/Infrastructure for AWS integrations).
    • The architecture evolves (e.g., splitting into microservices).
  • Mitigation: Treat deptrac.yaml as part of the architecture decision records (ADRs).
• Rule Maintenance:
  • Periodically review rules to ensure they align with current best practices (e.g., deprecating old layers).
  • Tooling: Use deptrac:rules:list to audit active rules.
• Dependency Updates:
  • Deptrac itself is low-maintenance, but major version bumps (e.g., 2.0.0) may require deptrac.yaml schema updates.
  • Strategy: Pin to 1.0.2 and monitor the main repo for breaking changes.

Support

• Developer Onboarding:
  • Training Needed:
    • How to read Deptrac’s output (e.g., Violation: [Presentation] depends on [Domain]).
    • How to request exceptions (e.g., @deptrac-ignore or deptrac.yaml overrides).
  • Documentation: Create a CONTRIBUTING.md section explaining architectural rules and exceptions.
• Debugging Common Issues:
  • False Positives:
    • Cause: Misconfigured layers (e.g., `app