包简介

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.

README 文档

README

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

View GitHub Actions

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

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

Once installed, the bundle automatically adds HTML comments to your rendered HTML in development mode:

<!-- TEMPLATE: index.html.twig -->
<!-- TEMPLATE: base.html.twig -->
<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" href="app.css">
    </head>
    <body>
<!-- BLOCK : index.html.twig::body -->
        <h1>Welcome 
<!-- MACRO: macros/user.html.twig::firstName -->
            <span class="user-firstname">John</span>
<!-- END MACRO: macros/user.html.twig::firstName -->
        </h1>
<!-- END TEMPLATE: home/index.html.twig -->
<!-- END BLOCK : index.html.twig::body -->
    </body>
</html>
<!-- END TEMPLATE: base.html.twig -->
<!-- END TEMPLATE: index.html.twig -->

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 <title>, <meta>, 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

Option	Type	Default	Description
`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

The bundle uses two mechanisms to trace your Twig templates:

NodeVisitor - Intercepts template rendering after compilation to add comments around complete templates
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

Debugging Complex Template Hierarchies

Quickly identify which child template is overriding a parent block.

Frontend Development

Let your frontend developers know exactly which Twig file to edit.

Documentation

Automatically document which templates are used on each page.

Testing

Verify that the correct templates and macros are being rendered.

Requirements

PHP 8.1 or higher
Symfony 6.4 or higher
Twig 3.0 or higher

Production Safety

The bundle is completely disabled in production (kernel.debug = false). No HTML comments are added, and there is zero performance impact.

Examples

Custom Separators

twig_trace:
    separator_template_start: '🔹'
    separator_template_end: '🔹'

Result:

<!-- 🔹 BEGIN TEMPLATE: home/index.html.twig 🔹 -->

Exclude Specific Directories

twig_trace:
    excluded_paths:
        - 'admin/'
        - 'emails/'
        - '@SomeBundle'

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

Comments not appearing?

Make sure you're in debug mode (APP_ENV=dev)
Clear the Twig cache: php bin/console cache:clear
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"

This error should not occur with TwigTrace. If you see it, please open an issue.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This bundle is released under the MIT License. See the LICENSE file for details.

Credits

Created by François Vaillant

Support

🐛 Report a bug
💡 Request a feature

Todo

Add unit tests

francoisvaillant/twig-trace-bundle 适用场景与选型建议

francoisvaillant/twig-trace-bundle 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 89 次下载、GitHub Stars 达 4，最近一次更新时间为 2025 年 11 月 20 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 francoisvaillant/twig-trace-bundle 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 francoisvaillant/twig-trace-bundle 我们能提供哪些服务？

定制开发 / 二次开发

基于 francoisvaillant/twig-trace-bundle 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

francoisvaillant/twig-trace-bundle

包简介