PHPackages francoisvaillant/twig-trace-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Templating & Views](/categories/templating) 4. / 5. francoisvaillant/twig-trace-bundle ActiveSymfony-bundle[Templating & Views](/categories/templating) francoisvaillant/twig-trace-bundle ================================== A Symfony bundle that automatically adds HTML comments to your rendered templates in development mode, making it easy to identify which Twig files, macros, and blocks are being used. v1.1.3(4mo ago)4691[1 issues](https://github.com/frvaillant/twig-trace-bundle/issues)[2 PRs](https://github.com/frvaillant/twig-trace-bundle/pulls)MITPHPPHP >=8.1CI passing Since Nov 20Pushed 4mo agoCompare [ Source](https://github.com/frvaillant/twig-trace-bundle)[ Packagist](https://packagist.org/packages/francoisvaillant/twig-trace-bundle)[ RSS](/packages/francoisvaillant-twig-trace-bundle/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (10)Versions (6)Used By (0) TwigTrace Bundle ================ [](#twigtrace-bundle) A Symfony bundle that automatically adds HTML comments to your rendered templates in development mode, making it easy to identify which Twig files, macros, and blocks are being used. Code Quality ------------ [](#code-quality) [![PHPStan](https://camo.githubusercontent.com/14995ff65edea59395c224e37e4fc66f91c1e601c1a58311e3c6f38c4fe37feb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c2532306d61782d627269676874677265656e)](https://github.com/frvaillant/twig-trace-bundle/actions/workflows/code-quality.yml?query=branch:master)[![PHP CS Fixer](https://camo.githubusercontent.com/61b997829f51bcc2b85f4724bad4dbb71b4b9c90260795119dc21f7fe7232379/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505f43535f46697865722d66697865642d627269676874677265656e)](https://github.com/frvaillant/twig-trace-bundle/actions/workflows/code-quality.yml?query=branch:master)[![Composer Audit](https://camo.githubusercontent.com/84f17a0fd46cb2e9992e43aa2d83974e9245a3ca9bac852a0fb4c47f90a3fdcb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f6d706f7365725f41756469742d7061737365642d627269676874677265656e)](https://github.com/frvaillant/twig-trace-bundle/actions/workflows/code-quality.yml?query=branch:master+job:composer-audit) [View GitHub Actions](https://github.com/frvaillant/twig-trace-bundle/blob/master/.github/workflows/code-quality.yaml) Features -------- [](#features) - **Automatic Template Tracing** - Every Twig template is wrapped with HTML comments showing its path - **Macro Detection** - Identifies which macros are being called and from which file - **Block Tracking** - Traces Twig blocks with customizable exclusions - **Fully Configurable** - Customize separators, excluded blocks, and excluded paths - **Debug Mode Only** - Only active in development, zero impact on production - **Zero Code Changes** - Works automatically without modifying your Twig templates Installation ------------ [](#installation) Install the bundle via Composer: ``` composer require francoisvaillant/twig-trace ``` If you're not using Symfony Flex, manually register the bundle in `config/bundles.php`: ``` return [ // ... Francoisvaillant\TwigTrace\TwigTraceBundle::class => ['all' => true], ]; ``` Usage ----- [](#usage) Once installed, the bundle automatically adds HTML comments to your rendered HTML in development mode: ``` > Welcome John ``` Configuration ------------- [](#configuration) If you want to customize default configuration, create a configuration file `config/packages/twig_trace.yaml`: ``` twig_trace: # Custom separators for better visibility separator_template_start: '/////////////////' separator_template_end: '/////////////////' # Custom separators for better visibility separator_macro_start: '-------------' separator_macro_end: '-------------' # Custom separators for better visibility separator_block_start: '{{{{{{' separator_block_end: '}}}}}}' # Blocks to exclude from wrapping (useful for , , etc.) excluded_blocks: - title - meta - stylesheets - javascripts # Template paths to exclude from tracing excluded_paths: - 'email/' # Exclude email templates - 'pdf/' # Exclude PDF templates - '@EasyAdmin' # Exclude EasyAdmin templates ``` ### Configuration Reference [](#configuration-reference) OptionTypeDefaultDescription`separator_template_start``string``''`Separator displayed at the start of comments for templates`separator_template_end``string``''`Separator displayed at the end of comments for templates`separator_macro_start``string``''`Separator displayed at the start of comments for macros`separator_macro_end``string``''`Separator displayed at the end of comments for macros`separator_block_start``string``''`Separator displayed at the start of comments for blocks`separator_block_end``string``''`Separator displayed at the end of comments for blocks`excluded_blocks``array``['title', 'meta', 'stylesheets', 'javascripts']`Block names to exclude from wrapping`excluded_paths``array``[]`Template paths to exclude (supports partial matches)**Note:** `@WebProfiler` templates are always excluded automatically. How It Works ------------ [](#how-it-works) The bundle uses two mechanisms to trace your Twig templates: 1. **NodeVisitor** - Intercepts template rendering after compilation to add comments around complete templates 2. **LoaderDecorator** - Modifies the template source before compilation to wrap macros and blocks This dual approach ensures: - Templates with `{% extends %}` are handled correctly - Macros are traced even when imported - Blocks can be individually traced or excluded - No conflicts with Twig's inheritance system Use Cases --------- [](#use-cases) ### **Debugging Complex Template Hierarchies** [](#debugging-complex-template-hierarchies) Quickly identify which child template is overriding a parent block. ### **Frontend Development** [](#frontend-development) Let your frontend developers know exactly which Twig file to edit. ### **Documentation** [](#documentation) Automatically document which templates are used on each page. ### **Testing** [](#testing) Verify that the correct templates and macros are being rendered. Requirements ------------ [](#requirements) - PHP 8.1 or higher - Symfony 6.4 or higher - Twig 3.0 or higher Production Safety ----------------- [](#production-safety) The bundle is **completely disabled in production** (`kernel.debug = false`). No HTML comments are added, and there is zero performance impact. Examples -------- [](#examples) ### Custom Separators [](#custom-separators) ``` twig_trace: separator_template_start: '๐Ÿ”น' separator_template_end: '๐Ÿ”น' ``` Result: ``` ``` ### Exclude Specific Directories [](#exclude-specific-directories) ``` twig_trace: excluded_paths: - 'admin/' - 'emails/' - '@SomeBundle' ``` ### Exclude Blocks That Break Layout [](#exclude-blocks-that-break-layout) Some blocks (like `title` or `meta`) should not contain HTML comments: ``` twig_trace: excluded_blocks: - title - meta - head ``` Note that if you customize the excluded\_blocks configuration, the default settings will not be applied anymore. Troubleshooting --------------- [](#troubleshooting) ### Comments not appearing? [](#comments-not-appearing) 1. Make sure you're in **debug mode** (`APP_ENV=dev`) 2. Clear the Twig cache: `php bin/console cache:clear` 3. Check your browser's "View Source" (not the Inspector, which may filter comments) ### "A template that extends another one cannot include content outside Twig blocks" [](#a-template-that-extends-another-one-cannot-include-content-outside-twig-blocks) This error should not occur with TwigTrace. If you see it, please [open an issue](https://github.com/francoisvaillant/twig-trace/issues). Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. License ------- [](#license) This bundle is released under the MIT License. See the [LICENSE](LICENSE) file for details. Credits ------- [](#credits) Created by [Franรงois Vaillant](https://github.com/frvaillant) Support ------- [](#support) - ๐Ÿ› [Report a bug](https://github.com/frvaillant/twig-trace-bundle/issues) - ๐Ÿ’ก [Request a feature](https://github.com/frvaillant/twig-trace-bundle/issues) Todo ---- [](#todo) - Add unit tests ### Health Score 38 โ€” LowBetter than 85% of packages Maintenance71 Regular maintenance activity Popularity17 Limited adoption so far Community7 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~10 days Total 5 Last Release 130d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dd84886e72173241d0e912ff66c60d5d2b0c154a66c1e908e3b124e4b61e641b?d=identicon)[frvaillant](/maintainers/frvaillant) --- Top Contributors [![frvaillant](https://avatars.githubusercontent.com/u/33039316?v=4)](https://github.com/frvaillant "frvaillant (24 commits)") ### Code Quality Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/francoisvaillant-twig-trace-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/francoisvaillant-twig-trace-bundle/health.svg)](https://phpackages.com/packages/francoisvaillant-twig-trace-bundle) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M650](/packages/sylius-sylius)[shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.0k15.4k](/packages/prestashop-prestashop)[contao/core-bundle Contao Open Source CMS 1231.6M2.3k](/packages/contao-core-bundle)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)