Installation

Install Twig Inspector Bundle in your Symfony project via Composer, with or without Symfony Flex.

Twig Inspector Bundle is a development tool only. Never register or enable it in the prod environment. Always restrict the bundle and its routes to dev and test.

Requirements

Requirement	Version
PHP	>= 8.1, < 8.6
Symfony	^6.0 | ^7.0 | ^8.0
Symfony Web Profiler Bundle	Required
Twig	^3.8 | ^4.0

1. Install via Composer

   Run the following command in your project root. The --dev flag ensures it is added to require-dev and never installed in production environments.

   composer require nowo-tech/twig-inspector-bundle --dev
   

   To pin to the current major version:

   composer require nowo-tech/twig-inspector-bundle:^1.0 --dev
   
2. Register the bundle

   With Symfony Flex

   If you use Symfony Flex and install from Packagist, the recipe runs automatically and:

   • Registers the bundle in config/bundles.php
   • Creates config/packages/dev/nowo_twig_inspector.yaml
   • Adds routes to config/routes.yaml for dev and test

   No manual steps are needed. Continue to step 4 to verify.

   Without Flex (manual)

   Add the bundle class to config/bundles.php, restricted to dev and test environments:

   <?php
   // config/bundles.php
   
   return [
       // ... other bundles ...
       Nowo\TwigInspectorBundle\NowoTwigInspectorBundle::class => ['dev' => true, 'test' => true],
   ];
   
3. Add the bundle routes

   Skip this step if you used Symfony Flex — routes are already configured by the recipe.

   The bundle provides a controller that handles the “open in IDE” redirect. Add its route resource to config/routes.yaml, restricted to dev and test:

   # 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 import must be wrapped in when@dev: and when@test:. Importing without an environment guard would expose the route in production. Even if mistakenly imported, the controller returns 404 in prod as a safety measure — but the bundle itself must never be active there.

4. (Optional) Run the install command

   If the Flex recipe did not run (for example, when installing from a private repository or directly from Git), you can use the install command to generate the config file and update routes automatically:

   php bin/console nowo:twig-inspector:install
   

   This creates config/packages/dev/nowo_twig_inspector.yaml and updates config/routes.yaml if needed.

   Additional options:

   # Generate config for the test environment
   php bin/console nowo:twig-inspector:install --env=test
   
   # Overwrite an existing config file
   php bin/console nowo:twig-inspector:install --force
   
5. Verify the installation

   Clear the cache and open your application:

   php bin/console cache:clear --env=dev
   

   Open any page in the browser with the Symfony Web Profiler toolbar visible. You should see a </> icon in the toolbar. Click it to open the Twig Inspector dropdown — if it appears, the bundle is installed correctly.

   For the full usage walkthrough (enabling the overlay, hovering, clicking), see the Quickstart.

IDE integration

To enable click-to-open in your IDE, set the framework.ide option in your dev framework configuration. The bundle uses Symfony’s standard %%f (file path) and %%l (line number) placeholders.

# config/packages/dev/framework.yaml
framework:
    ide: 'phpstorm://open?file=%%f&line=%%l'

URL handler examples for common editors:

IDE	URL handler
PhpStorm	phpstorm://open?file=%%f&line=%%l
VS Code	vscode://file/%%f:%%l
Cursor	cursor://file/%%f:%%l
JetBrains Fleet	fleet://open?path=%%f&line=%%l
Sublime Text	subl://open?url=file://%%f&line=%%l

On macOS and Linux you may need to register the URL scheme handler for your IDE. PhpStorm and VS Code do this automatically when installed. For other editors, consult their documentation.