Twig Copy Location Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev arkounay/twig-copy-location-bundle
   

   • Ensure your project uses Symfony 6.4+ (or Symfony 7) and PHP 8+ (required since v2.0.0).
   • The package is dev-only—exclude it from production builds.

2. Enable the Bundle: Add to config/bundles.php (if not auto-discovered):

   Arkounay\TwigCopyLocationBundle\ArkounayTwigCopyLocationBundle::class => ['dev' => true],
   

3. First Use Case:

   • Trigger a debug request (e.g., visit a route in dev mode).
   • Open the Web Profiler toolbar.
   • Look for the "Twig Copy Location" panel (appears under the "Twig" tab).
   • Click the copy icon next to the Twig filename or controller path to copy it directly to your clipboard.

Implementation Patterns

Workflows

1. Debugging Twig Templates:

   • Quick Navigation: Copy the Twig path to open the file in your IDE (e.g., VSCode, PhpStorm) via Ctrl+Shift+F or Cmd+Shift+O.
   • Template Hierarchy: Use the panel to trace nested includes/extends (e.g., _layout.html.twig → homepage.html.twig).

2. Controller Debugging:

   • Route Resolution: Copy the controller path (e.g., App\Controller\ProductController::index) to jump to the controller class/method.
   • Action Mapping: Verify the correct controller/action is being called (useful for debugging routing issues).

3. Collaboration:

   • Share Twig paths with teammates to pinpoint template locations in PRs or Slack.
   • Example: "Check templates/product/_card.html.twig for the styling issue."

Integration Tips

• IDE Shortcuts:

  • Bind a keyboard shortcut to paste the copied path into your IDE’s search bar (e.g., Ctrl+V → Ctrl+Shift+F).
  • Use PhpStorm’s "Open File at Caret" (Ctrl+Shift+O) for instant navigation.

• Customizing the Panel:

  • Override the Twig template for the panel by extending the bundle’s resources:

    # templates/bundles/ArkounayTwigCopyLocation/debug/twig_copy_location.html.twig
    {% extends '@ArkounayTwigCopyLocation/debug/twig_copy_location.html.twig' %}
    {% block title %}{{ parent() }} (Customized){% endblock %}
    

  • Clear the cache after changes:

    php bin/console cache:clear
    

• Symfony Flex Compatibility:

  • The bundle auto-configures with Symfony’s environment (no manual services.yaml edits needed).

• CI/CD Pipelines:

  • Exclude the bundle from production builds by ensuring it’s only required in dev environments (handled by composer.json require-dev).

Gotchas and Tips

Pitfalls

1. Missing Debug Toolbar:

   • Cause: The bundle only appears in dev environments. Ensure:
     • APP_ENV=dev in .env.
     • The Web Profiler is enabled (check config/packages/dev/web_profiler.yaml).
   • Fix: Restart your dev server after switching environments.

2. PHP Version Mismatch:

   • Error: Class 'Arkounay\TwigCopyLocationBundle\...' not found.
   • Cause: PHP < 8.0 or Symfony < 6.4.
   • Fix: Update composer.json and run composer update.

3. Twig Path Not Showing:

   • Cause: The bundle hooks into Symfony’s event system. If Twig paths are blank:
     • Ensure the twig bundle is loaded (check config/bundles.php).
     • Verify no custom Twig_Environment overrides the default one.
   • Debug: Add this to a controller to test Twig integration:

     use Symfony\Bundle\TwigBundle\TwigBundle;
     // Ensure TwigBundle is enabled in bundles.php
     

4. Controller Path Empty:

   • Cause: The bundle relies on Symfony’s kernel.controller event. If empty:
     • Check for custom middleware or event listeners modifying the request early.
     • Test with a basic controller to isolate the issue.

Debugging Tips

• Log the Bundle’s Data: Add this to config/packages/dev/debug.yaml to log Twig/controller paths:

  services:
      Arkounay\TwigCopyLocationBundle\EventListener\DebugListener:
          arguments:
              $logger: '@logger'
  

  • Check logs for DEBUG entries like:

    [TwigCopyLocation] Current Twig: templates/product/show.html.twig
    [TwigCopyLocation] Current Controller: App\Controller\ProductController::showAction
    

• Override the Copy Logic: Extend the bundle’s DebugListener to customize copied data:

  // src/EventListener/CustomDebugListener.php
  namespace App\EventListener;
  
  use Arkounay\TwigCopyLocationBundle\EventListener\DebugListener as BaseListener;
  
  class CustomDebugListener extends BaseListener
  {
      public function getTwigPath(): string
      {
          $path = parent::getTwigPath();
          return str_replace('templates/', 'src/Templates/', $path); // Example: Adjust paths
      }
  }
  

  • Register the service in config/services.yaml:

    services:
        App\EventListener\CustomDebugListener:
            tags: [kernel.event_listener]
            arguments: ['@logger']
    

Extension Points

1. Add Custom Data: Extend the debug panel to include additional context (e.g., Git blame info):

   {% block twig_data %}
       {{ parent() }}
       <div class="git-info">
           {{ app.git_blame(twig_path) }}
       </div>
   {% endblock %}
   

2. Localize Paths: Convert Windows paths to Unix-style for cross-platform teams:

   // Override DebugListener::getTwigPath()
   return str_replace('\\', '/', $path);
   

3. Security Note:

   • The copied paths are publicly exposed in the debug toolbar. Avoid leaking sensitive paths (e.g., /var/www/private/templates/).
   • Use realpath() to normalize paths before copying:

     return realpath($path) ?: $path;
     

4. Performance:

   • The bundle adds minimal overhead (~1ms per request). No impact in production (dev-only).