Twig Inspector is a development-only tool. Never enable it in production. Register the bundle for
dev and test environments only.Key features
Visual overlay
A blue highlight and popup on hover shows which template(s) rendered each HTML element, including nested blocks.
Click to open in IDE
Click any highlighted element to open the template file at the exact line in PhpStorm, VS Code, Cursor, Sublime Text, or any IDE with a URL handler.
Web Profiler integration
A dedicated
</> panel in the Symfony toolbar shows template usage metrics, block counts, and controller information (main and fragment).Controller tracking
Tracks the main controller and every fragment rendered via
render(controller(...)) — with Main/Fragment badges and render counts in the profiler.Cookie-based activation
Toggle the inspector on or off via a browser cookie. No code changes, no cache clears — just check the “Enable” checkbox in the toolbar dropdown.
Configurable exclusions
Exclude specific templates or blocks from inspection using wildcard patterns. Customize the cookie name, overlay theme, and more.
Performance optimized
Processing is entirely skipped when the inspector is disabled, so there is zero overhead in normal development sessions.
Symfony Flex recipe
Installing via Composer with Flex automatically registers the bundle, creates the config file, and adds routes — no manual steps required.
How it works
The bundle injects HTML comments before and after every Twig block and template during rendering. When the inspector is enabled, a JavaScript overlay reads those comments, maps them to DOM elements, and draws the blue highlight and popup on hover. Clicking an element sends a request to the bundle’s controller, which redirects your browser to the configured IDE URL handler. When the inspector is active, it also injects controller boundary comments into the HTML source — the main controller after<body>, and start/end markers around each fragment rendered by render(controller(...)).
Requirements
| Requirement | Version |
|---|---|
| PHP | >= 8.1, < 8.6 |
| Symfony | ^6.0 | ^7.0 | ^8.0 |
| Symfony Web Profiler Bundle | Required for toolbar and collector |
| Twig | ^3.8 | ^4.0 |
Next steps
Installation
Add the bundle to your project in minutes with Composer.
Quickstart
Follow a step-by-step guide to get the overlay working in under 5 minutes.
Configuration
Customize exclusions, the cookie name, overlay theme, and IDE URL handler.