Class Leak Laravel Package

Getting Started

Install the package via Composer in your Laravel project’s dev dependencies:

composer require --dev tomasvotruba/class-leak

Run the analyzer on your codebase:

vendor/bin/class-leak

Start with high-impact areas like app/Services, app/Http/Controllers, or app/Models—these often hide legacy or unused classes. The output lists potential leaks with file paths and usage context. Prioritize reviewing classes flagged in production-critical paths first.

Implementation Patterns

• Pre-commit Hook / CI Guard: Add vendor/bin/class-leak --error-format=checkstyle > class-leaks.xml to CI. Fail builds only if new leaks are introduced (use --diff or -v to compare against baseline).
• Targeted Refactoring: Generate diffs for safe removal with --output-diff=rector.yaml, then apply using Rector (ensure tests pass before committing).
• Manual Validation Workflow: For classes suspected as leaks, verify by:
  • Searching for new Classname, app()->make(), config(), routes, event listeners, and facade usage.
  • Checking Doctrine annotations, YAML/XML configs, and Laravel’s service container bindings.
• Baseline Generation: On first run, generate a baseline (--generate-baseline) to track new leaks over time—critical for long-term maintainability SLAs.

Gotchas and Tips

• Laravel-Specific False Negatives: The tool performs static analysis and won’t detect usage in dynamic contexts like:

  • app()->call([NewClass(), 'method'])
  • Event listener bindings in EventServiceProvider
  • Route closures or controller actions defined via strings ('UserController@index')
  • Config-driven class resolution (e.g., config('services.driver.class')) → Fix: Use @Leaking annotations on intentionally unused classes, or wrap with @phpstan-ignore where appropriate.

• Autoloading Misconfiguration: If Composer’s autoload config (psr-4, classmap) is incorrect, the tool may miss references. Verify composer dump-autoload --optimize works and composer show -o matches your app/ structure.

• Exclude Legacy Code: Add a class-leak.neon config to silence known leaks:

  parameters:
      paths:
          - app
      excludePaths:
          - app/Legacy/*
          - app/Infrastructure/Bridge/*
  

• Debug Traces: Run with -vvv to see why a class is considered leaking—including which references were found (or not). This helps distinguish missing usage from reflection-based usage.

• False Positives with Factories: Laravel’s model factories (Factory::new()->create()) may trigger leaks on factory classes—mark them with @Leaking or add database/factories/* to excludes.