Ladybug Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require raulfraile/ladybug-bundle
   

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Raulfraile\LadybugBundle\RaulfraileLadybugBundle::class => ['all' => true],
   ];
   

3. First Use Case: Dump a variable in a controller:

   use Raulfraile\LadybugBundle\Ladybug\Ladybug;
   
   public function index()
   {
       $data = ['name' => 'John', 'active' => true];
       Ladybug::dump($data); // or use the helper: `ld($data)`
   }
   

   • Twig Integration: Use the |ladybug_dump filter:

     {{ dumpable_variable|ladybug_dump }}
     

Implementation Patterns

Core Workflows

1. Debugging Controllers/Commands: Replace var_dump() or dd() with Ladybug::dump() for structured output.

   public function show(User $user)
   {
       Ladybug::dump($user->toArray()); // Pretty-printed array
   }
   

2. Twig Debugging: Use the filter in templates to inspect variables:

   {% for item in items %}
       {{ item|ladybug_dump }}
   {% endfor %}
   

3. Service/Repository Debugging: Inject Ladybug service and dump complex objects:

   public function __construct(private Ladybug $ladybug) {}
   
   public function fetchData()
   {
       $result = $this->repository->findAll();
       $this->ladybug->dump($result);
       return $result;
   }
   

4. CLI Debugging: Use in console commands for real-time inspection:

   use Symfony\Component\Console\Command\Command;
   use Raulfraile\LadybugBundle\Ladybug\Ladybug;
   
   class DebugCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $data = $this->getData();
           Ladybug::dump($data, $output); // Stream to CLI
       }
   }
   

Integration Tips

• Custom Handlers: Extend Ladybug\Handler\HandlerInterface to handle specific types (e.g., Doctrine entities).
• Configuration: Override default settings via config/packages/raulfraile_ladybug.yaml:

  raulfraile_ladybug:
      handlers:
          - { service: 'app.custom_handler' }
      max_depth: 5
  

• Environment-Specific: Disable in production by checking app['kernel']->getEnvironment():

  if ($this->getParameter('kernel.environment') === 'prod') {
      return;
  }
  Ladybug::dump($data);
  

Gotchas and Tips

Common Pitfalls

1. Performance Overhead:

   • Avoid dumping in loops or production. Use if ($debug) guards.
   • Example:

     if ($this->getParameter('kernel.debug')) {
         Ladybug::dump($expensiveQueryResult);
     }
     

2. Circular References:

   • Ladybug may hang on deeply nested/circular objects. Limit depth:

     raulfraile_ladybug:
         max_depth: 3
     

3. Twig Filter Scope:

   • The |ladybug_dump filter only works in Twig if the bundle is enabled and the LadybugTwigExtension is registered (it is by default).

4. Output Buffering:

   • Ensure no output is sent before calling Ladybug::dump() (e.g., avoid echo or response->send() beforehand).

5. Deprecated Methods:

   • Prefer Ladybug::dump() over ld() helper in new code (though both work).

Debugging Tips

• Inspect Handlers: Check registered handlers via:

  $handlers = $this->container->get('raulfraile_ladybug.handler.registry')->getHandlers();
  

• Custom Styling: Override CSS by extending the default template (@RaulfraileLadybug/debug.html.twig).
• Log to File: Redirect output to a file in CLI:

  Ladybug::dump($data, new \Symfony\Component\Console\Output\BufferedOutput());
  file_put_contents('debug.log', $output->fetch());
  

Extension Points

1. Add Custom Handlers: Create a service tagged as raulfraile_ladybug.handler:

   services:
       app.custom_handler:
           class: App\Handler\CustomHandler
           tags:
               - { name: 'raulfraile_ladybug.handler', priority: 100 }
   

   Implement Raulfraile\LadybugBundle\Ladybug\Handler\HandlerInterface.

2. Override Templates: Copy vendor/raulfraile/ladybug-bundle/Resources/views/ to templates/bundles/raulfraileladybug/ and modify.

3. Hook into Dump Events: Listen for ladybug.dump events to modify output dynamically:

   $dispatcher->addListener('ladybug.dump', function ($event) {
       $event->setData(['custom_key' => 'value']);
   });