Dead Code Detector Laravel Package

Product Decisions This Supports

• Codebase Health & Maintainability:

  • Enable automated dead code removal to reduce technical debt, improve CI/CD performance, and simplify refactoring.
  • Justify investment in developer tooling by quantifying time saved (e.g., "X hours/week spent manually cleaning dead code").

• Roadmap Prioritization:

  • Build vs. Buy: Replace custom scripts or manual audits with a battle-tested solution, reducing engineering overhead.
  • Feature Flags: Integrate dead-code detection into a "code quality" initiative tied to developer productivity metrics.
  • Legacy Modernization: Target high-maintenance modules (e.g., monolithic Symfony/Laravel apps) for quick wins.

• Use Cases:

  • Pre-Merge Gates: Fail CI if dead code exceeds a threshold (e.g., >5% of methods).
  • Onboarding: Automatically clean dead code during new developer setup to avoid "legacy cruft" surprises.
  • Security: Remove unused dependencies or callbacks (e.g., #[AsEventListener]) to reduce attack surface.
  • Performance: Eliminate unused Doctrine listeners or Eloquent observers to speed up ORM operations.

• Cross-Team Alignment:

  • DevOps: Reduce build times by shrinking codebase size.
  • QA: Align with testing teams to exclude test-only usages (avoid breaking tests during cleanup).
  • Architecture: Identify unused Symfony services or Laravel routes to streamline dependency graphs.

When to Consider This Package

Adopt If:

• Your PHP codebase is >50K LOC or growing rapidly (manual audits become unsustainable).
• You use Symfony/Laravel/Eloquent and want to detect framework-specific dead code (e.g., unused event listeners, routes, or observers).
• CI/CD bottlenecks are caused by large test suites or slow static analysis.
• Onboarding new devs is hindered by outdated or unused code.
• You’re migrating legacy systems and need to identify safe-to-remove cruft.
• Security audits require removing unused callbacks or dependencies.

Look Elsewhere If:

• Your project is small (<10K LOC) or has no technical debt backlog.
• You don’t use PHPStan (this is a PHPStan extension; requires existing static analysis).
• Your codebase relies on heavy runtime reflection or dynamic calls (may generate false positives).
• You need fine-grained control over dead-code removal (e.g., per-file approvals) and prefer a GUI tool like PHPStorm’s "Remove Unused Code" action.
• Tests are tightly coupled to implementation (e.g., characterization tests), making exclusion logic complex.

Alternatives to Evaluate:

• PHPStan + phpstan/extension-installer: For basic dead-code detection without removal.
• Psalm: If your team uses Psalm instead of PHPStan (similar features exist but with different syntax).
• Custom Scripts: For projects with highly specific usage patterns (e.g., custom DI containers).
• IDE Plugins: For interactive cleanup (e.g., PHPStorm’s "Optimize Imports" or "Remove Unused Code").

How to Pitch It (Stakeholders)

For Executives (Business Impact):

*"This tool automates the cleanup of unused PHP code—like a ‘spring cleaning’ for our codebase. For every 10% of dead code we remove:

• Dev productivity improves by reducing context-switching time (studies show unused code increases onboarding time by 20–30%).
• CI/CD speeds up by shrinking test suites and analysis scope (target: 15–20% faster builds).
• Technical debt decreases, lowering future refactoring costs.

Cost: Minimal (one-time setup + ~5 dev-hours/year for maintenance). ROI: 3–5x in saved engineering time. We’ll pilot it in [High-Maintenance Module X] and measure impact before scaling."*

For Engineering Leaders (Technical Fit):

*"This is a PHPStan extension that detects and removes dead code—methods, properties, constants, and even framework-specific cruft (e.g., unused Symfony event listeners or Laravel routes). It’s non-destructive by default (shows what it would remove before acting) and supports:

• Framework integrations: Symfony, Laravel, Doctrine, PHPUnit, Twig, etc.
• Customization: Extend it for your DI container or runtime magic (e.g., #[AsTwigComponent]).
• Safe removal: Exclude test-only usages and handle transitive dead code (e.g., if MethodA calls MethodB, both are removed).

Why now?

• Our [Module Y] has Z% dead code (from manual audit), slowing down PR reviews.
• [Team Z] spends ~X hours/week manually cleaning up unused callbacks.
• It integrates with our existing PHPStan setup (no new tools).

Next steps:

1. Run it in dry mode against [Target Module] to validate false-positive rate.
2. Automate removal in CI for low-risk files (e.g., non-test classes).
3. Expand to other modules based on impact."*

For Developers (Day-to-Day Value):

*"Imagine running a command that:

• Finds unused methods, properties, and constants (even in tests!).
• Automatically removes them with one flag (--removeDeadCode).
• Works with Symfony/Laravel/Eloquent out of the box (no config for 90% of use cases).
• Safe for tests: Exclude usages only in tests/ if needed.

Example workflow:

# Step 1: Find dead code (dry run)
vendor/bin/phpstan analyse --error-format=removeDeadCode --no-progress

# Step 2: Review changes (IDE will show diffs)
# Step 3: Remove for real
vendor/bin/phpstan analyse --error-format=removeDeadCode

Pro tip: Add it to your pre-commit hook for critical paths or run weekly in CI to keep the codebase lean.

Try it today: Just add it to composer.json and update phpstan.neon!"*