Twig Inspector Laravel Package

Getting Started

First Steps

1. Installation:

   composer require oro/twig-inspector
   

   Add the bundle to config/bundles.php (Symfony) or register the service provider in config/app.php (Laravel via Symfony bridge).

2. Enable in Dev Environment: Ensure the bundle is only active in APP_ENV=dev by checking the KERNEL environment variable or Symfony’s APP_DEBUG mode.

3. First Use Case: Visit /_inspector (default route) to see a live list of all Twig templates and blocks rendered on the current page. Useful for debugging layouts, partials, or inherited blocks.

Implementation Patterns

Daily Workflows

1. Debugging Template Hierarchy:

   • Use the inspector to trace which template renders a specific section (e.g., header, footer).
   • Example: Identify if a block like body_content is overridden in a child template.

2. Performance Profiling:

   • Check for excessive template nesting or unused blocks that could be removed.
   • Compare template counts between routes to spot inefficiencies.

3. Collaboration:

   • Share inspector screenshots in PRs to highlight template changes (e.g., "This block was moved from base.html.twig to layout.html.twig").

4. Integration with Laravel:

   • If using Laravel with Twig (via symfony/twig-bridge), ensure the inspector’s routes are excluded from production by middleware:

     Route::middleware(['web', 'inspector'])->group(function () {
         // Inspector routes
     });
     

5. Customizing Output:

   • Extend the inspector’s data provider (via Symfony’s twig.inspector.data_provider service) to add custom metadata (e.g., template file size, last modified time).

Gotchas and Tips

Common Pitfalls

1. Route Conflicts:

   • The default /_inspector route may clash with existing routes. Rename it in config/packages/oro_twig_inspector.yaml:

     oro_twig_inspector:
         route: /debug/twig
     

2. Caching Issues:

   • Clear Twig cache after template changes (php artisan cache:clear or php bin/console cache:clear).
   • Disable Twig’s auto-reload in config/packages/twig.yaml if inspector data appears stale:

     twig:
         auto_reload: true
     

3. Laravel-Specific Quirks:

   • If using Laravel’s Blade + Twig hybrid, the inspector only shows Twig templates. Exclude Blade files from inspection by filtering the data provider.

4. Performance Overhead:

   • The inspector adds minimal overhead in dev mode. For CI/CD, disable it via:

     APP_ENV=testing php artisan serve
     

Pro Tips

1. Filtering Templates:

   • Use the inspector’s search bar to filter by template name or block ID (e.g., header).
   • Bookmark URLs with query params like ?_inspector=blocks to focus on specific data.

2. Template Line Numbers:

   • Click a template in the inspector to jump to its file in your IDE (if using PHPStorm/VSCode with Twig plugins).

3. Extending Data:

   • Add custom columns to the inspector’s table by overriding the Oro\TwigInspectorBundle\DataProvider\TemplateDataProvider service:

     services:
         App\TwigInspector\CustomDataProvider:
             decorates: oro_twig_inspector.data_provider.template
             arguments: ['@.inner']
     

4. Headless Mode:

   • For APIs or CLI commands, disable the inspector’s HTML output by setting:

     oro_twig_inspector:
         enabled: false
     

     Then use the underlying data provider programmatically:

     $provider = $container->get('oro_twig_inspector.data_provider.template');
     $templates = $provider->getTemplates();