Dead Code Detector Laravel Package

Technical Evaluation

Architecture Fit

• Leverage PHPStan Integration: The package is a PHPStan extension, making it a natural fit for projects already using PHPStan for static analysis. It aligns with modern PHP tooling ecosystems (e.g., Symfony, Laravel, Doctrine) and complements existing toolchains like phpstan/extension-installer.
• Dead Code Elimination as a First-Class Concern: Unlike ad-hoc solutions (e.g., manual grep or IDE-based tools), this package provides structured, rule-based dead code detection with transitive analysis, reducing technical debt proactively.
• Framework-Agnostic with Framework-Specific Support: While it works universally, its deep integration with Laravel/Symfony/Doctrine/etc. means it can handle framework-specific edge cases (e.g., DIC services, event listeners, Eloquent observers) without manual overrides.

Integration Feasibility

• Low Friction for Existing PHPStan Users:
  • Requires zero changes beyond adding the package and including its rules in phpstan.neon.
  • No runtime overhead during development (only analysis phase).
• Composer Dependency:
  • Installs as a dev dependency, avoiding production bloat.
  • No PHP version constraints beyond PHPStan’s (currently PHP 8.1+).
• Configuration Overrides:
  • Highly customizable via phpstan.neon (e.g., disabling dead constants, excluding test usages).
  • Supports custom usage providers for bespoke logic (e.g., detecting usages in Twig templates or reflection-based calls).

Technical Risk

• False Positives/Negatives:
  • Risk: Misconfigured usage providers (e.g., Symfony DIC not detected) or custom logic errors could lead to incorrect dead code removal.
  • Mitigation:
    • Start with dry runs (--error-format=json) to review findings before auto-removal.
    • Use tests usage excluder to avoid removing code only used in tests.
    • Leverage reportTransitivelyDeadMethodAsSeparateError for granular debugging.
• Breaking Changes:
  • Risk: PHPStan version compatibility (e.g., PHPStan 1.x vs. 2.x APIs).
  • Mitigation:
    • Pin PHPStan version in composer.json to avoid surprises.
    • Monitor the package’s release notes for API changes.
• Performance Impact:
  • Risk: Large codebases may experience slower analysis due to transitive dead code detection.
  • Mitigation:
    • Run incrementally (e.g., --generate-baseline) or in CI with caching.
    • Exclude non-critical paths (e.g., vendor/) from analysis.

Key Questions for TPM

1. Adoption Readiness:
   • Does the team already use PHPStan? If not, what’s the cost to onboard it?
   • Are there legacy systems (e.g., pre-PHP 8.1) that would block adoption?
2. CI/CD Integration:
   • How will dead code removal be gated (e.g., manual review vs. automated PRs)?
   • Should auto-removal be opt-in (e.g., via a --remove flag) or opt-out?
3. Customization Needs:
   • Are there framework-specific quirks (e.g., custom event listeners) that require custom usage providers?
   • Should test exclusions be enabled by default, or configured per project?
4. Monitoring:
   • How will false positives be tracked and resolved (e.g., Jira tickets, GitHub issues)?
   • Should pre- and post-removal metrics (e.g., lines deleted, test coverage impact) be logged?
5. Long-Term Maintenance:
   • Who will update the PHPStan dependency and handle breaking changes?
   • Should the package be vendor-locked (e.g., forked) for critical projects?

Integration Approach

Stack Fit

• PHPStan-Centric Workflow:
  • Ideal for projects using PHPStan for static analysis (e.g., type checking, PSR compliance).
  • Integrates seamlessly with Symfony Flex, Laravel, and Doctrine projects due to built-in support.
• Complementary Tools:
  • PHP-CS-Fixer: Auto-format dead code removal diffs.
  • GitHub/GitLab CI: Run as a pre-commit hook or PR check.
  • IDE Plugins: Use PHPStan’s IDE integration to highlight dead code interactively.
• Non-PHPStan Projects:
  • Workaround: Use the package’s standalone analysis mode (via CLI) if PHPStan isn’t used, but lose some framework integrations.

Migration Path

1. Phase 1: Analysis-Only Mode

   • Install the package and configure phpstan.neon:

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

   • Run in dry mode:

     vendor/bin/phpstan analyse --error-format=json > dead-code.json
     

   • Review findings with the team (prioritize high-impact dead code).

2. Phase 2: Incremental Removal

   • Enable auto-removal in CI (e.g., GitHub Actions):

     - name: Remove dead code
       run: vendor/bin/phpstan analyse --error-format=removeDeadCode
     

   • Gate removals behind a feature flag or manual approval.

3. Phase 3: Customization (Optional)

   • Implement custom usage providers for unsupported frameworks/libraries.
   • Tune phpstan.neon to exclude false positives (e.g., dynamic calls).

Compatibility

• Framework Support:
  • Laravel: Full support for routes, events, Eloquent, queues, etc.
  • Symfony: DIC services, annotations (#[AsController], #[EventListener]), workflows.
  • Doctrine: Entity listeners, lifecycle callbacks, enums.
  • Testing: PHPUnit, Behat, PhpBench (avoids removing test-only code).
• Edge Cases:
  • Dynamic Proxies: Works with Symfony’s proxy classes (e.g., ContainerInterface).
  • Reflection: Detects usages via ReflectionClass (e.g., getMethod()).
  • Twig: Tracks view objects passed to templates.
• Anti-Patterns:
  • Avoid: Overriding vendor/ classes (handled via VendorUsageProvider).
  • Avoid: False positives from new $unknown() (configurable via unknownTypeMethodName).

Sequencing

1. Pre-requisite: Ensure PHPStan is version 1.0+ (package requires PHPStan 1.x).
2. Order of Operations:
   • Run full analysis before incremental changes.
   • Test exclusions first to avoid breaking tests.
   • Auto-remove in CI after manual validation.
3. Rollback Plan:
   • Commit dead code removal as a separate PR for easy revert.
   • Use git restore or git checkout for accidental removals.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: phpstan.neon changes may break dead code detection.
  • Mitigation:
    • Store configurations in version control (e.g., .phpstan.neon).
    • Use CI checks to validate configurations.
• Dependency Updates:
  • Risk: PHPStan major versions may require package updates.
  • Mitigation:
    • Pin versions in composer.json (e.g., shipmonk/dead-code-detector:^0.7).
    • Test updates in a staging environment before production.
• Custom Providers:
  • Risk: Bespoke usage providers may break with PHPStan updates.
  • Mitigation:
    • Isolate custom logic in separate packages (e.g., company/dead-code-providers).
    • Add deprecation warnings for custom code.

Support

• Developer Onboarding:
  • Training Needed:
    • Explain false positives (e.g., Symfony DIC, dynamic calls).
    • Teach how to exclude usages (e.g., tests excluder).
  • Documentation:
    • Create an internal wiki with common pitfalls (e.g., Laravel’s Route::get()).
    • Link to the official slides and YouTube recording.
• Support Channels:
  • **