Ghost Hunter Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle via Composer:

   composer require anja/ghost-hunter-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Anja\GhostHunterBundle\GhostHunterBundle::class => ['all' => true],
   ];
   

2. First Run Execute the CLI command to scan for unused files:

   php bin/console ghosthunter:scan
   

   Review the generated report in var/log/ghosthunter_report.log (or configured output path).

3. Quick Use Case Identify unused Twig templates or JavaScript/CSS assets in a Symfony project before refactoring or cleanup.

Implementation Patterns

Workflows

1. Pre-Refactoring Audit Run ghosthunter:scan before major refactoring to identify safe-to-remove files:

   php bin/console ghosthunter:scan --format=json > unused_files.json
   

2. CI/CD Integration Add to a post-deploy or pre-cleanup script to enforce unused file removal:

   # .github/workflows/deploy.yml
   - name: Scan for unused files
     run: php bin/console ghosthunter:scan --fail-on-unused
   

3. Custom Rules Extend the scanner by creating a custom rule (e.g., ignore files in src/Old/):

   // config/packages/ghost_hunter.yaml
   ghost_hunter:
       ignored_paths:
           - '%kernel.project_dir%/src/Old/'
   

Integration Tips

• Symfony Flex: Works seamlessly with Flex recipes; no manual config needed for basic use.
• Twig Integration: Automatically detects unused templates by parsing compiled Twig cache.
• Asset Mapping: Supports both Webpack Encore and manual asset definitions (via assets.json).
• Event Listeners: Hook into ghosthunter.scan.complete to process results programmatically:

  // src/EventListener/GhostHunterListener.php
  public function onScanComplete(ScanCompleteEvent $event) {
      $unusedFiles = $event->getUnusedFiles();
      // Log or notify team
  }
  

Gotchas and Tips

Pitfalls

1. False Positives

   • Issue: Dynamic template/asset loading (e.g., {{ asset('dynamic-' ~ id ~ '.js') }}) may flag files as unused.
   • Fix: Use --ignore-dynamic flag or whitelist paths in config.

2. Performance

   • Issue: Large projects may slow down during scans.
   • Fix: Limit scans to specific directories:

     php bin/console ghosthunter:scan --path=templates,assets
     

3. Cache Dependencies

   • Issue: Outdated Twig cache may hide actual usage.
   • Fix: Clear cache (php bin/console cache:clear) before scanning.

4. Asset Build Tools

   • Issue: Webpack Encore’s publicPath misconfiguration may break asset detection.
   • Fix: Ensure assets.json is up-to-date and publicPath matches your setup.

Debugging Tips

• Verbose Output: Use --verbose to debug scanning logic:

  php bin/console ghosthunter:scan --verbose
  

• Dry Run: Test with --dry-run to preview changes without modifying files.
• Custom Loggers: Override the default logger to route output to a database or Slack.

Extension Points

1. Custom Scanners Implement Anja\GhostHunterBundle\Scanner\ScannerInterface to add support for new file types (e.g., PHP includes):

   class MyCustomScanner implements ScannerInterface {
       public function scan(ScanContext $context) {
           // Custom logic here
       }
   }
   

   Register in services.yaml:

   services:
       App\Scanner\MyCustomScanner:
           tags: [ghosthunter.scanner]
   

2. Post-Scan Actions Use the ghosthunter.scan.complete event to trigger cleanup or notifications:

   // config/services.yaml
   App\EventListener\PostScanListener:
       tags:
           - { name: kernel.event_listener, event: ghosthunter.scan.complete, method: onScanComplete }
   

3. Configuration Overrides Override default settings (e.g., report format, thresholds) in config/packages/ghost_hunter.yaml:

   ghost_hunter:
       report:
           format: json
           path: '%kernel.project_dir%/var/unused_files.json'
       thresholds:
           unused_templates: 10  # Fail if >10 unused templates