Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nowo-tech/TwigInspectorBundle/llms.txt

Use this file to discover all available pages before exploring further.

Twig Inspector Bundle is a development tool. It exposes template paths and IDE-open routes that must never be accessible in a production environment. This page documents the built-in safeguards and the recommended deployment posture.
Never register Twig Inspector Bundle in a production environment. It injects HTML comments that reveal your template structure and exposes a route that opens files in your IDE.

​
Bundle security measures

​
Environment restriction

OpenTemplateController maintains a hard-coded allow-list of safe environments: 
private const ALLOWED_ENVIRONMENTS = ['dev', 'test'];
As the very first action in __invoke(), the controller checks kernel.environment against this list and throws a NotFoundHttpException (HTTP 404) if the environment is not dev or test. This applies even if the route was accidentally registered in production — it acts as a defense-in-depth layer independent of routing configuration.

​
Template name validation

Before the controller loads any file, validateTemplateName() inspects the raw template string passed in the URL:
CheckRejection reason
Empty stringTemplate name cannot be empty.
Contains ..Path traversal detected
Contains a null byte (\0)Path traversal detected
Starts with /Absolute path not allowed
Matches [A-Za-z]:\\Absolute Windows path not allowed
Any violation throws a BadRequestException (HTTP 400) before the Twig loader is invoked.

​
File path verification

After Twig resolves the template name to an absolute path, validateFilePath() runs a second check:
  1. realpath() normalizes the resolved path, removing symlink indirection and .. segments.
  2. The method collects every registered path from the active Twig loader (FilesystemLoader paths, traversing ChainLoader recursively).
  3. It verifies that the resolved file path starts with at least one allowed loader path.
If the file falls outside all registered Twig template directories, a BadRequestException is thrown.
When only an ArrayLoader is configured (no FilesystemLoader), validateFilePath() delegates security to Twig’s own loader security and returns early. This is an edge case for non-filesystem template sources.

​
Line number validation

The line query parameter is parsed as an integer. Any value less than 1 causes a BadRequestException. This prevents both negative values and crafted inputs from influencing the IDE URL.

​
Route restrictions

Routes must be imported under when@dev: and when@test: guards in config/routes.yaml: 
# 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'
With Symfony Flex, these entries are created automatically by the bundle recipe. For manual installation, php bin/console nowo:twig-inspector:install writes them for you.

​
Deployment checklist

Bundle registered only under dev and test in config/bundles.php:
NowoTwigInspectorBundle::class => ['dev' => true, 'test' => true]
Routes imported with when@dev: and when@test: guards — never under a bare _default key.
framework.ide is set to a local IDE URL scheme (e.g. phpstorm://open?file=%%f&line=%%l). This URL is only ever opened by the developer’s own browser.
Inspector cookie (twig_inspector_is_active) is set only on localhost or a private dev server. Do not commit it to shared staging environments.
Never expose the dev server (port 8000, FrankenPHP, etc.) to the public internet while the bundle is active.

​
Integrator considerations

  • Template paths in the overlay: when the inspector is enabled, the JavaScript tooltip shows template names and file paths to the developer. Ensure those paths are not visible to untrusted users if you run the dev server on a shared network.
  • IDE URL schemes: the framework.ide value is used verbatim in the redirect. Use only local IDE URL schemes (e.g. phpstorm://, vscode://, subl://). Remote or HTTP URLs should not be configured here in any environment.
  • Cookie scope: the inspector cookie is scoped to the origin. It does not travel to other domains, but it does apply to all paths on the dev server origin.

​
Supported versions

VersionSupported
1.xYes
Older versions do not receive security backports. Update to the latest 1.x release to receive fixes.

​
Reporting a vulnerability

If you discover a security vulnerability in Twig Inspector Bundle, please report it responsibly — do not open a public GitHub issue.
1

Contact the maintainer privately

Send details to hectorfranco@nowo.tech (or the maintainers listed in composer.json).
2

Include reproduction details

Provide a clear description of the vulnerability, steps to reproduce it, and an assessment of the potential impact.
3

Allow time for a fix

The maintainer will acknowledge receipt, may ask follow-up questions, and will work on a fix. Please allow reasonable time before any public disclosure.
4

Coordinate disclosure

After a fix is released, the maintainer can coordinate a security advisory so users have time to update before details are public.
Responsible disclosure helps protect all users of the bundle. We appreciate the effort to report privately.

Build docs developers (and LLMs) love

Get started for freeTalk to us