Twig Bridge Laravel Package

Getting Started

1. Ensure prerequisites: Install php-debugbar/php-debugbar first (e.g., via composer require barryvdh/laravel-debugbar in Laravel apps).
2. Install the bridge: Run composer require php-debugbar/twig-bridge.
3. First use: In Laravel, the bridge auto-registers via service provider discovery—no config needed. In non-Laravel apps, manually bind TwigBridge\Twig\Extension\DebugExtension to your Twig environment.
4. Verify: Render a Twig template with $debugbar['messages']->debug('Test message')—check the Debugbar panel for messages in the browser.

Implementation Patterns

• Laravel integration: After installation, debugging becomes seamless—use $debugbar inside Blade (via @php blocks) or inject \DebugBar\DebugBar into controllers, then call methods like $debugbar->info(), $debugbar->warning(), or $debugbar->addMessage() in Twig via custom extensions (the bridge itself adds the debug() function to Twig).
• Direct Twig usage: Register the DebugExtension manually:

  $twig = new \Twig\Environment($loader);
  $twig->addExtension(new \TwigBridge\Twig\Extension\DebugExtension($debugbar));
  

  Then use {{ debug('variable') }} or {{ debug() }} in templates.
• Collection-based logging: Group related debug data with collectors:

  $debugbar->addCollector(new \DebugBar\DataCollector\VariableCollector(['foo' => 'bar']));
  

  The bridge ensures variables are collected and displayed only when debug mode is enabled, avoiding production overhead.
• Template-specific debugging: Use {{ dump(variable) }} (Twig’s built-in) alongside Debugbar’s collector to inspect complex objects via the GUI.

Gotchas and Tips

• Laravel auto-registration quirk: The bridge does not register its Twig extension automatically in Laravel unless laravel-debugbar is installed (it bundles the bridge as a dependency). If using standalone Twig, register DebugExtension manually.
• Memory impact: Avoid heavy {{ debug() }} calls in loops or frequently rendered templates—each invocation serializes data and may slow dev builds. Prefer targeted uses like {{ debug(request().all()) }} only on error pages.
• Collector naming collisions: If multiple sources add variables, use named collectors:

  $debugbar->addCollector(new \DebugBar\DataCollector\VariableCollector('my_vars', $data));
  

  to avoid overwrites in the "Variables" panel.
• Extensibility: Add custom collectors (e.g., MessageCollector for user alerts) and map them to Twig via $debugbar['messages']->info('Alert!')—this message then appears in both the "Messages" panel and can be logged alongside template variables.
• Troubleshooting: If the Debugbar panel doesn’t appear, confirm:
  • Debug mode is enabled (e.g., APP_DEBUG=true in Laravel),
  • The HTTP response includes the X-Debugbar-Id header,
  • No output buffering started before Debugbar’s middleware runs.