Deptrac Shim Laravel Package

Getting Started

Minimal Setup

1. Install the package (redirects to the maintained qossmic/deptrac):

   composer require --dev qossmic/deptrac-shim
   

2. Initialize configuration (generates deptrac.yaml):

   vendor/bin/deptrac init
   

3. Run a basic analysis (checks for circular dependencies):

   vendor/bin/deptrac analyze
   

First Use Case: Laravel Layer Enforcement

Define layers in deptrac.yaml to enforce Clean Architecture rules:

layers:
  - name: Domain
    paths: [app/Domain]
  - name: Application
    paths: [app/Application]
  - name: Infrastructure
    paths: [app/Infrastructure]
  - name: HTTP
    paths: [app/Http]

rules:
  Domain:
    - don't depend on Infrastructure
    - don't depend on HTTP
  Application:
    - don't depend on Infrastructure
  HTTP:
    - don't depend on Domain
    - don't depend on Application

Run with:

vendor/bin/deptrac analyze --fail-on=violation

Implementation Patterns

Workflows

1. CI/CD Integration (GitHub Actions example):

   - name: Enforce Architecture
     run: vendor/bin/deptrac analyze --fail-on=violation
   

   • Place in pull_request or push workflows to block violations early.

2. Incremental Adoption:

   • Start with --fail-on=none to identify violations without blocking builds.
   • Gradually introduce stricter rules (e.g., --fail-on=violation for critical paths).

3. Layer-Specific Rules:

   • Use paths in deptrac.yaml to target specific directories (e.g., tests/ or packages/).
   • Example: Exclude test dependencies:

     layers:
       - name: Tests
         paths: [tests]
     rules:
       Tests:
         - don't depend on Domain
         - don't depend on Application
     

Integration Tips

• Combine with PHPStan: Use Deptrac for architecture and PHPStan for type safety.

  composer require --dev phpstan/phpstan
  vendor/bin/phpstan analyse --level=max
  vendor/bin/deptrac analyze --fail-on=violation
  

• Custom Rules: Extend deptrac.yaml to enforce project-specific constraints (e.g., "No Http/Controllers dependencies in App/Jobs").
• Visualization: Generate dependency graphs for debugging:

  vendor/bin/deptrac graph --format=dot > graph.dot
  

  Convert to PNG using Graphviz: dot -Tpng graph.dot -o graph.png.

Gotchas and Tips

Pitfalls

1. False Positives:

   • Symfony/Container or Laravel Service Container: Deptrac may flag autowired dependencies as violations. Use ignore directives:

     rules:
       HTTP:
         - don't depend on Domain
         - ignore: ".*\\\\Container.*"
     

   • Dynamic Class Loading: Classes generated at runtime (e.g., via eval) won’t be analyzed. Document exceptions in deptrac.yaml.

2. Performance:

   • Large codebases (>50K LoC) may slow down CI. Mitigate with caching:

     vendor/bin/deptrac analyze --cache=/tmp/deptrac-cache
     

   • Exclude non-critical paths (e.g., vendor/, node_modules/).

3. Configuration Quirks:

   • Layer Paths: Use glob patterns for flexibility:

     paths: [app/**/Services/*.php]
     

   • Case Sensitivity: Ensure paths in deptrac.yaml match filesystem case (e.g., App/Http vs. app/Http).

4. CI/CD Failures:

   • Deptrac exits with code 1 on violations. Configure CI to treat this as a failure:

     # GitLab CI example
     test:
       script:
         - vendor/bin/deptrac analyze --fail-on=violation
       allow_failure: false
     

Debugging Tips

• Dry Run: Test rules without failing:

  vendor/bin/deptrac analyze --fail-on=none
  

• Verbose Output: Enable debug mode for detailed violations:

  vendor/bin/deptrac analyze --verbose
  

• Rule Validation: Validate deptrac.yaml syntax:

  vendor/bin/deptrac validate
  

Extension Points

1. Custom Rulesets: Create reusable rulesets for shared libraries or microservices. Example: deptrac.shared.yaml for common patterns.
2. Pre/Post-Processing: Use scripts to modify deptrac.yaml dynamically (e.g., based on environment variables).
3. Plugin Development: Extend Deptrac’s functionality by contributing to the main repository (e.g., adding Laravel-specific rules).

Laravel-Specific Notes

• Service Providers: Deptrac won’t analyze bindings in AppServiceProvider. Document these as exceptions.
• Facades: Treat facades as part of the HTTP layer to avoid false positives:

  layers:
    - name: HTTP
      paths: [app/Http, app/Facades]
  

• Migrations: Exclude migration files if they reference domain models:

  layers:
    - name: Database
      paths: [database/migrations]
  rules:
    Database:
      - ignore: ".*"