Configuration options

Complete reference for all nowo_twig_inspector configuration options.

All options live under the nowo_twig_inspector key in your YAML config file. The bundle works with default values even if no configuration file exists — you only need to set what you want to change.

Full example

# config/packages/dev/nowo_twig_inspector.yaml
nowo_twig_inspector:
    # Extensions
    enabled_extensions:
        - '.html.twig'
        # - '.twig'
        # - '.xml.twig'

    # Template exclusions
    excluded_templates:
        # - 'admin/*'
        # - 'email/*.html.twig'
    excluded_templates_regex:
        # - '/^email\//'
    excluded_templates_prefixes:
        # - '@Admin/'
        # - 'components/'

    # Block exclusions
    excluded_blocks:
        # - 'javascript'
        # - 'head_*'
    excluded_blocks_regex: []

    # Behaviour
    enable_metrics: true
    inject_on_sub_requests: false
    cookie_name: 'twig_inspector_is_active'
    max_injection_depth: 0

    # Overlay UI
    overlay_theme: light
    overlay_compact: false
    reduced_motion: false
    keyboard_shortcut: 'Ctrl+Shift+T'

Options reference

Extensions

enabled_extensions · string[]

List of template file extensions to inspect. Only templates whose filename ends with one of the listed extensions are processed.

Default: ['.html.twig']

enabled_extensions:
    - '.html.twig'
    - '.twig'

Template exclusions

excluded_templates · string[]

Template names or patterns to exclude from inspection. Supports wildcards with *.

Default: []

excluded_templates:
    - 'admin/*'
    - 'email/*.html.twig'
    - 'security/*'

excluded_templates_regex · string[]

Additional template exclusion patterns as regular expressions. Applied in addition to excluded_templates.

Default: []

excluded_templates_regex:
    - '/^email\//'

excluded_templates_prefixes · string[]

Template name prefixes to exclude. Useful for excluding entire Twig namespaces or directories.

Default: []

excluded_templates_prefixes:
    - '@Admin/'
    - 'components/'

Block exclusions

excluded_blocks · string[]

Block names or patterns to exclude from inspection. Supports wildcards with *. Useful for excluding large blocks such as inline JavaScript or CSS.

Default: []

excluded_blocks:
    - 'javascript'
    - 'head_*'
    - 'styles'

excluded_blocks_regex · string[]

Additional block exclusion patterns as regular expressions.

Default: []

excluded_blocks_regex:
    - '/^legacy_/'

Behaviour

enable_metrics · boolean

Enable collection of template usage metrics in the Symfony Web Profiler DataCollector. When enabled, the profiler panel shows statistics about templates and blocks used in each request, including render counts and timing data.

Default: true

inject_on_sub_requests · boolean

When true, the bundle also injects HTML comments during sub-requests (for example when the main content is rendered as a fragment via {{ render(controller(...)) }}). Enable this if all your templates show “sub-request” in the panel and none get inspected.

Default: false

cookie_name · string

Name of the browser cookie used to enable or disable the inspector. Change this if the default name conflicts with another cookie in your application.

Default: 'twig_inspector_is_active'

max_injection_depth · integer

Maximum nesting depth for HTML comment injection. Set to 0 for unlimited depth. Reducing this value can lower overhead on very deep or highly recursive template trees.

Minimum: 0 (unlimited)

Default: 0

Overlay UI

overlay_theme · string

Visual theme for the overlay tooltip.

Accepted values: 'light', 'dark', 'auto' (follows the system’s prefers-color-scheme).

Default: 'light'

overlay_compact · boolean

Use compact tooltip style for the overlay. When true, the overlay tooltip takes up less screen space.

Default: false

reduced_motion · boolean

Respect reduced motion for accessibility. When true, or when the system reports prefers-reduced-motion, overlay animations are minimized.

Default: false

keyboard_shortcut · string

Keyboard shortcut to toggle the inspector overlay. Set to an empty string to disable the shortcut entirely.

Default: 'Ctrl+Shift+T'

Routes configuration

In addition to the nowo_twig_inspector YAML config, the bundle requires its routes to be imported in config/routes.yaml. This is handled automatically by the Flex Recipe or the install command, but you can add it manually if needed.

Routes must be restricted to dev and test environments. Never import them in production.

# config/routes.yaml
when@dev:
    nowo_twig_inspector:
        resource: '@NowoTwigInspectorBundle/Resources/config/routes.yaml'

when@test:
    nowo_twig_inspector:
        resource: '@NowoTwigInspectorBundle/Resources/config/routes.yaml'

The route uses a pattern that allows slashes in template names to support templates in subdirectories (for example admin/users/list.html.twig). Security validations in the controller prevent path traversal attacks.

The bundle handles route generation gracefully if routes are not available — it returns a fallback URL instead of throwing an exception, so it is safe in non-dev environments even if misconfigured.