Dead Code Detector Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package is explicitly designed for Laravel (Eloquent, Routes, Events, Console, etc.), making it a near-perfect fit for Laravel-based codebases. It leverages PHPStan’s extension system, which integrates seamlessly with Laravel’s dependency injection, service containers, and framework-specific patterns (e.g., #[AsCommand], #[ObservedBy]).
• Modular Design: The package’s architecture is modular, with support for multiple libraries (Symfony, Doctrine, Twig, etc.) auto-enabled when dependencies are present. This reduces configuration overhead for Laravel projects.
• Customization Points: The ability to extend usage providers (e.g., for custom middleware, traits, or legacy patterns) ensures adaptability to non-standard Laravel implementations.

Integration Feasibility

• Low Friction: Installation is straightforward (composer require --dev), and integration requires minimal configuration (adding includes to phpstan.neon). No runtime dependencies or framework modifications are needed.
• CI/CD Friendly: The package is designed for static analysis, making it ideal for CI pipelines (e.g., GitHub Actions, GitLab CI). The --error-format removeDeadCode flag enables automated cleanup, though this should be gated behind manual review.
• Test Compatibility: Supports Laravel’s testing stack (PHPUnit, Pest) and can exclude test-only usages, preventing false positives in test-heavy codebases.

Technical Risk

• False Positives/Negatives:
  • Risk: Laravel’s dynamic features (e.g., dynamic route binding, late-static binding, or magic methods like handle() in controllers) may trigger false positives. The package mitigates this with customizable usage providers, but edge cases (e.g., app()->make() calls) might require manual exclusion.
  • Mitigation: Use the MemberUsageExcluder interface or configure shipmonkDeadCode.usageProviders to disable problematic providers (e.g., vendor, reflection).
• Performance Overhead:
  • Risk: Analyzing large Laravel monoliths (e.g., with heavy service containers or complex Eloquent relationships) could slow down PHPStan runs.
  • Mitigation: Run analysis incrementally (e.g., --generate-baseline) or exclude specific paths (e.g., vendor/, storage/) from the scan.
• Breaking Changes:
  • Risk: The package is actively maintained (last release: 2026-07-08), but PHPStan’s API evolves. Laravel-specific features (e.g., new attributes like #[AsPeriodicTask]) may require updates.
  • Mitigation: Monitor the release notes and pin the package version in composer.json.

Key Questions

1. Scope of Analysis:
   • Should the analysis include all code (src + tests) or only production code? If tests are excluded, enable tests usage excluder to avoid false positives.
   • Are there dynamic Laravel features (e.g., app()->bind(), macro() calls) that might bypass static analysis? If so, implement a custom MemberUsageProvider.
2. Automation Strategy:
   • Will dead code removal be fully automated (via --error-format removeDeadCode) or reviewed manually first? Automated removal risks breaking tests or logic.
   • How will test exclusions be handled? Enable tests excluder but verify that test-only usages are clearly marked (e.g., Unused X (all usages excluded by tests excluder)).
3. Performance Trade-offs:
   • For large codebases, should analysis be parallelized (PHPStan 1.10+ supports --parallel) or split by module?
   • Are there specific Laravel components (e.g., Livewire, Forge) that require custom providers?
4. Tooling Integration:
   • Will results be visualized (e.g., via IDE plugins like PHPStan’s VSCode extension) or integrated into PR checks (e.g., GitHub Advanced Security)?
   • Should dead code reports be linked to Git blame for easier triage?

Integration Approach

Stack Fit

• PHPStan Integration: The package is a PHPStan extension, aligning with Laravel’s static analysis ecosystem. PHPStan is already a dependency in many Laravel projects (e.g., for type checking), reducing adoption friction.
• Laravel-Specific Support: Out-of-the-box coverage for:
  • Routing: Route::get(), resource(), controller@method syntax.
  • Eloquent: Model observers, accessors, factories, migrations.
  • Events/Jobs: Event::listen(), Schedule::job(), #[AsCommand].
  • Testing: PHPUnit/Pest test methods, data providers.
• Toolchain Synergy:
  • Works alongside Laravel Pint (for code formatting) and Pest/Tests (for test coverage).
  • Complements Laravel Forge/Envoyer for deployment hygiene (removing dead code pre-deploy).

Migration Path

1. Pilot Phase:
   • Install in development mode (--dev) and run against a subset of modules (e.g., a single feature branch).
   • Configure phpstan.neon with minimal settings:

     includes:
         - vendor/shipmonk/dead-code-detector/rules.neon
     parameters:
         shipmonkDeadCode:
             usageExcluders:
                 tests:
                     enabled: true
     

   • Validate false positives/negatives manually.
2. Gradual Rollout:
   • Add to CI pipeline (e.g., run on PRs targeting main).
   • Use --error-format=github for actionable feedback.
   • Enable automated removal in a separate step (e.g., post-merge):

     vendor/bin/phpstan analyse --error-format=removeDeadCode --level=max
     git diff --exit-code || echo "Dead code removal failed"
     

3. Full Integration:
   • Extend with custom providers for unsupported Laravel patterns (e.g., custom macros).
   • Integrate with code review tools (e.g., GitHub’s "required checks").

Compatibility

• Laravel Versions: Supports modern Laravel (8.0+) with Symfony 6+/7+ components. Older versions may lack support for newer attributes (e.g., #[AsPeriodicTask]).
• PHPStan Version: Requires PHPStan 1.0+. Check compatibility with your Laravel project’s PHPStan version (e.g., phpstan/phpstan:^1.10).
• Dependency Conflicts: No known conflicts with Laravel’s core dependencies, but test if other PHPStan extensions (e.g., phpstan/phpstan-symfony) interact unexpectedly.

Sequencing

1. Pre-Analysis:
   • Audit the codebase for dynamic Laravel patterns (e.g., app()->make(), macro()) that might cause false positives.
   • Configure phpstan.neon to exclude non-critical paths (e.g., storage/logs/, bootstrap/cache/).
2. Initial Run:
   • Run with --level=max to catch all potential dead code.
   • Review results for false positives (e.g., dead code used via reflection or dynamic calls).
3. Customization:
   • Implement MemberUsageProvider for unsupported patterns (e.g., custom middleware invocations).
   • Adjust shipmonkDeadCode parameters to disable problematic providers (e.g., vendor if using app()->make() heavily).
4. Automation:
   • Gate dead code removal behind a manual approval (e.g., via a GitHub workflow step).
   • Schedule weekly dry runs in CI to catch regressions.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: As Laravel evolves, new attributes/methods (e.g., #[AsPeriodicTask]) may require updates to the package or custom providers.
  • Mitigation: Subscribe to the release notes and test upgrades in a staging environment.
• Custom Provider Maintenance:
  • Risk: Custom MemberUsageProvider implementations may break if PHPStan’s internals change.
  • Mitigation: Isolate custom providers in a separate package or namespace for easier updates.
• False Positive Management:
  • Risk: Over time, false positives may accumulate, requiring manual exclusions.
  • Mitigation: Use MemberUsageExcluder for common patterns (e.g., exclude all app()->make() calls) and document exclusions in phpstan.neon.

Support

• Debugging:
  • Tools: Leverage PHPStan’s --debug flag and the package’s detailed error messages (e.g., transitive dead code tips).
  • Community: The package has 493 stars and active maintenance (last release: 2026). Issues are likely to be addressed promptly.
• Onboarding:
  • **Documentation