README

"Who you gonna call?"

GhostHunterBundle is a code quality tool for Symfony 6.4+ and 7.0+. It performs a deep analysis of your project to detect orphaned files (Twig templates and Assets) and helps you safely remove them.

✨ Features

• 🕸️ Deep Dependency Analysis: Builds a complete dependency graph to find not just directly unused files, but also "transitive ghosts" – files that are only used by other unused files.
• ⚡️ Blazing Fast with Cache: Subsequent analyses are instantaneous thanks to a smart caching system.
• 🧠 Smart Parsing: Intelligently ignores files mentioned in comments (Twig {# ... #}, PHP //, CSS /* ... */).
• 🗑️ Soft Delete: No files are permanently deleted. They are moved to a var/ghost_trash/ directory, organized by date.
• ⚙️ Configurable: Exclude specific directories or files from the analysis.

📦 Installation

Install the bundle via Composer:

composer require anja/ghost-hunter-bundle --dev

If you are not using Symfony Flex, enable the bundle in config/bundles.php:

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

⚙️ Configuration

Create a configuration file config/packages/ghost_hunter.yaml to define paths to ignore:

ghost_hunter:
  # List of directories or files to exclude from analysis
  ignored_paths:
    - "node_modules"
    - "var"
    - "vendor"
    - "tests"
    - "admin" # Example: ignore the admin section

🎮 Usage

Run the interactive command from your terminal:

php bin/console guardian:ghosts

Note: By default, this command is interactive. It asks for confirmation before deleting anything.

Available Options

You can target a specific file type (though deep analysis is recommended):

# Analyze only Twig templates (less effective with deep analysis)
php bin/console guardian:ghosts --type=templates

# Analyze only assets
php bin/console guardian:ghosts --type=assets

CI / Audit Mode

Returns an exit code 1 if unused files are found. Ideal for CI pipelines.

php bin/console guardian:ghosts --dry-run

Cache Management

The cache is enabled by default. To force a fresh analysis, use the --no-cache flag.

php bin/console guardian:ghosts --no-cache

🛡️ Security (Soft Delete)

This bundle applies a "Soft Delete" policy.

When you confirm file deletion:

1. A var/ghost_trash directory is created at your project root.
2. A dated sub-directory is created (e.g., 2026-01-06_20-30-00).
3. The original file structure is recreated there.

Example: If you delete assets/images/old-logo.png, it will be moved to: var/ghost_trash/2026-01-06_20-30-00/assets/images/old-logo.png.

This allows you to manually restore any file in case of error.

🤝 Contribution

Contributions are welcome!

1. Fork the project.
2. Create your branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📝 Author

Developed with ❤️ by mlejeune.

📄 License

This project is licensed under the MIT License.