Ghost Hunter Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Specific: The package is tailored for Symfony applications, leveraging its templating (Twig) and asset management systems. If the product is built on Symfony, this aligns well with existing architecture. For non-Symfony Laravel projects, the fit is low to nonexistent unless abstracted via a custom wrapper (e.g., parsing Blade templates or asset manifests).
• Static Analysis Focus: The tool operates on static analysis (unused templates/assets), which is complementary to Laravel’s dynamic routing but may require manual mapping of Blade files to routes or assets.
• Extensibility: The bundle’s design (Symfony EventDispatcher, Console commands) suggests it can be adapted for Laravel via Laravel’s event system or Artisan commands, but this would require significant refactoring.

Integration Feasibility

• Core Functionality: Detecting unused Twig templates/assets is straightforward in Symfony but requires Laravel-specific logic for:
  • Blade template parsing (e.g., using laravel-blade-compiler or regex-based analysis).
  • Asset mapping (e.g., parsing mix-manifest.json, Vite/Inertia assets, or custom asset pipelines).
• Data Sources: Symfony relies on twig.cache and assets directories; Laravel would need equivalent paths (e.g., resources/views, public/build).
• Output: The bundle generates reports (CLI/HTML). Laravel could adopt similar formats (e.g., JSON for API integration or Markdown for docs).

Technical Risk

• High for Laravel: Direct integration risks:
  • False positives/negatives due to Laravel’s dynamic routing (e.g., Blade components, dynamic includes).
  • Asset pipeline complexity (e.g., Vite, Webpack, or custom setups).
  • Blade syntax differences (e.g., @include vs. Twig’s {% include %}).
• Mitigation:
  • Hybrid Approach: Use the bundle’s core logic (e.g., file traversal, dependency graphing) but replace Symfony-specific parts with Laravel equivalents.
  • Plugin Architecture: Design a Laravel facade over the bundle’s services, abstracting Symfony dependencies.
  • Incremental Testing: Validate against a subset of known unused files before full deployment.

Key Questions

1. Scope of Unused Files:
   • Should the tool target only Blade templates or also assets (CSS/JS), config files, or middleware?
   • How are dynamically generated routes (e.g., API resources) handled?
2. False Positive Tolerance:
   • What threshold for "unused" is acceptable (e.g., files not requested in X days)?
   • How to exclude vendor/third-party files or test-specific assets?
3. Performance Impact:
   • Will static analysis scale for large Laravel apps (e.g., 10K+ files)?
   • Can it run incrementally (e.g., only scan modified files)?
4. Tooling Integration:
   • Should results integrate with Laravel’s task runners (e.g., Forge, Envoyer) or CI/CD (e.g., GitHub Actions)?
   • Desired output format (CLI table, JSON, Slack alert)?
5. Maintenance Overhead:
   • Who will maintain the Laravel-specific adaptations if the bundle evolves?

Integration Approach

Stack Fit

• Symfony → Laravel Mapping:

  Symfony Component	Laravel Equivalent	Integration Notes
  Twig templates	Blade templates (resources/views)	Use blade-compiler or regex to parse files.
  Asset manifest (Symfony Asset)	mix-manifest.json/Vite	Parse JSON or scan public/build directory.
  EventDispatcher	Laravel Events	Replace Symfony events with Laravel’s.
  Console commands	Artisan commands	Extend Illuminate\Console\Command.

• Dependencies:
  • Requires PHP 8.0+ (check Laravel version compatibility).
  • May need symfony/console, symfony/event-dispatcher as Laravel packages (if not using native alternatives).

Migration Path

1. Proof of Concept (PoC):
   • Fork the bundle and replace Symfony-specific classes with Laravel equivalents (e.g., TwigLoader → custom Blade parser).
   • Test on a small Laravel project (e.g., a monorepo or sample app).
2. Core Adaptation:
   • Template Analysis:
     • Use File::allFiles(app_path('views')) to traverse Blade files.
     • Parse @extends, @include, and @component directives to build a dependency graph.
   • Asset Analysis:
     • Parse mix-manifest.json or scan public/build for unused JS/CSS.
     • Integrate with Laravel Mix/Vite’s asset pipeline hooks.
   • Event System:
     • Replace KernelEvents with Laravel’s Events facade or custom events.
3. Artisan Command:
   • Create a custom command (e.g., php artisan ghost:hunt) that leverages the adapted bundle logic.
4. Output Layer:
   • Extend the bundle’s reporter to support Laravel’s logging (Log::channel) or custom formats (e.g., JSON for API consumption).

Compatibility

• Laravel Versions: Test against LTS versions (e.g., 10.x, 11.x) due to PHP 8.0+ requirements.
• Asset Pipelines:
  • Vite: Parse vite-manifest.json or use Vite’s plugin API.
  • Laravel Mix: Read webpack.mix.js output or mix-manifest.json.
  • Custom: Implement a scanner for static asset directories.
• Blade vs. Twig:
  • Blade’s dynamic nature may require heuristic-based analysis (e.g., ignore @include('partials.*') if no matching files exist).

Sequencing

1. Phase 1: Template Analysis
   • Build a Blade parser to identify unused views.
   • Validate against a known dataset (e.g., a Laravel app with intentional unused files).
2. Phase 2: Asset Analysis
   • Integrate with the primary asset pipeline (Vite/Mix).
   • Handle edge cases (e.g., lazy-loaded assets, dynamic imports).
3. Phase 3: Event Integration
   • Replace Symfony events with Laravel equivalents (e.g., FilesScanned event).
4. Phase 4: CLI/UI
   • Wrap the logic in an Artisan command with Laravel-friendly output.
5. Phase 5: CI/CD Integration
   • Add as a GitHub Action or Deployer task to run on PRs/deploys.

Operational Impact

Maintenance

• Dependency Management:
  • The bundle’s Symfony dependencies may require Laravel-compatible forks or alternatives (e.g., symfony/console → laravel/framework).
  • Schedule periodic updates to the adapted bundle as the upstream evolves.
• Custom Logic:
  • Laravel-specific parsers (e.g., Blade) may need updates for new Blade features (e.g., @stack, @prepend).
  • Asset pipeline changes (e.g., Vite 5.0) may break manifest parsing.
• Tooling:
  • Document the adapted bundle’s quirks (e.g., false positives for dynamic Blade includes).

Support

• Debugging:
  • Laravel developers may lack familiarity with the bundle’s internals, requiring additional docs or a wrapper library.
  • Log detailed errors for unsupported features (e.g., "Blade @component parsing failed").
• Community:
  • Limited upstream support; rely on Laravel-specific issue trackers or forks.
  • Consider open-sourcing the Laravel adaptation to reduce maintenance burden.
• SLAs:
  • Define response times for false positives/negatives in production scans.

Scaling

• Performance:
  • Static analysis of large codebases (e.g., 50K+ files) may be slow. Optimize with:
    • Caching results (e.g., filemtime checks for incremental scans).
    • Parallel processing (e.g., Symfony’s Parallel component or Laravel’s queues).
  • Asset analysis could bottleneck if scanning thousands of files; prioritize high-traffic routes/assets.
• Resource Usage:
  • Memory-intensive for large projects; test with memory_limit adjustments.
  • Consider running in CI (e.g., GitHub Actions) to offload from production servers.
• Distributed Systems:
  • For microservices, analyze each service’s assets/templates independently or use a shared manifest.

Failure Modes