Unused Public Laravel Package

Getting Started

Install the package via Composer with composer require tomasvotruba/unused-public --dev. It integrates with PHPStan, so no additional setup is needed if you’re using the phpstan/extension-installer. Enable detection by adding a simple config to phpstan.neon:

parameters:
    unused_public:
        methods: true
        properties: true
        constants: true

Run it via vendor/bin/unused-public (or ./vendor/bin/unused-public on Windows). Start with a minimal scope—e.g., scan just app/Http/Controllers—to build confidence in results before expanding coverage.

Implementation Patterns

• CI Integration: Add unused-public as a step in GitHub Actions/GitLab CI to fail builds when unused public elements exceed thresholds (e.g., methods: 2.5).
• Gradual Triage: Use percentage-based limits (methods: 2.5) to prevent overwhelming teams—fix regressions before tackling historical debt.
• Template-Aware Scanning: Configure template_paths for Blade (resources/views) or Twig to avoid false positives for methods used in views (e.g., {{ $book->getTitle() }}).
• API Surface Preservation: Add @api annotations to public methods intended for external consumption (e.g., packages, SDKs) to exclude them from reports.
• Local Usage Focus: Enable local_methods: true to flag public methods only used within the class—ideal for identifying candidates to downgrade to private/protected.

Gotchas and Tips

• Framework False Positives: Laravel’s dynamic features (routes, events, observers, console commands) often trigger false negatives. Silence these with @phpstan-ignore-line or exclusions in config (e.g., exclude_paths: ['app/Console/Commands']).
• Reflection-Heavy Code: DTOs, formatters, or serializer classes using __get, __call, or Symfony OptionsResolver may be incorrectly flagged—annotate with @api or exclude explicitly.
• Debugging Reports: Run with --debug to see why an element is marked unused/used—this reveals missing usages (e.g., in string-based method calls like call_user_func([$obj, 'getTitle'])).
• Partial Configuration: Mix strict mode (methods: true) with targeted thresholds (methods: 5.0) per namespace via custom PHPStan configs for incremental adoption.
• No Auto-Fix: This is strictly a detection tool—never auto-remove code. Always validate reported items against HTTP routes, job dispatchers, API contracts, and test suites before deletion.