Listeners Debug Command Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require egulias/listeners-debug-command-bundle
   

   Add the bundle to config/bundles.php (Symfony 3.3+) or AppKernel.php (Symfony 2.x):

   Egulias\ListenersDebugCommandBundle\EguliasListenersDebugCommandBundle::class => ['all' => true],
   

2. First Run: Navigate to your project root and execute:

   php bin/console container:debug:listeners
   

   This lists all services tagged as kernel.event_listener with their event names, methods, and priorities.

3. First Use Case: Debug an event listener not firing as expected. Use --event=event.name to filter output:

   php bin/console container:debug:listeners --event=kernel.request
   

Implementation Patterns

Workflows

1. Event Discovery: Use the command to audit all registered listeners for a specific event (e.g., kernel.controller, security.interactive_login). Example:

   php bin/console container:debug:listeners --event=security.interactive_login
   

2. Debugging Priority Conflicts: Sort listeners by priority to identify misconfigured or conflicting priorities:

   php bin/console container:debug:listeners | grep -E "security.interactive_login|priority"
   

3. Private Services: Include private services (e.g., App\EventListener\PrivateListener) for thorough debugging:

   php bin/console container:debug:listeners --show-private
   

4. Integration with CI/CD: Add the command to a pre-deployment script to validate event listeners are correctly registered:

   php bin/console container:debug:listeners --event=kernel.request --format=json > listeners.json
   

Laravel-Specific Adaptations

1. Symfony Event Bridge: Laravel’s Event facade uses Symfony’s EventDispatcher. Register listeners in EventServiceProvider:

   protected $listen = [
       'App\Events\OrderPlaced' => [
           'App\Listeners\SendOrderConfirmation',
       ],
   ];
   

   Debug with:

   php artisan container:debug:listeners --event=App\Events\OrderPlaced
   

2. Custom Events: For events not tagged with kernel.event_listener, use Symfony’s EventDispatcher directly:

   $dispatcher->addListener('custom.event', [$listener, 'handle']);
   

   Verify registration via:

   php artisan container:debug:listeners --show-private
   

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The package is abandoned (last release: 2015). Use at your own risk.
   • For Symfony 2.2.x, explicitly require 1.4.1:

     "egulias/listeners-debug-command-bundle": "1.4.1"
     

   • For Symfony 2.0.x, use the symfony2.0.x branch (deprecated).

2. Laravel Event Limitations:

   • Laravel’s EventServiceProvider listeners won’t appear in the output unless manually tagged as kernel.event_listener.
   • Workaround: Use Symfony’s EventDispatcher directly or extend the command to support Laravel’s $listen array.

3. Private Services Filter:

   • --show-private may expose internal services (e.g., router, security.token_storage). Use cautiously in production.

Debugging Tips

1. Filter by Event Name: Narrow down results with partial matches:

   php bin/console container:debug:listeners --event="security.*"
   

2. Output Formatting: Use --format=json for machine-readable output (e.g., parsing in scripts):

   php bin/console container:debug:listeners --format=json | jq '.[] | select(.event == "kernel.request")'
   

3. Missing Listeners: If a listener isn’t listed:

   • Verify it’s a public service (not private).
   • Check for typos in the tags configuration (Symfony 2.x) or bind() calls (Symfony 3+).
   • For Laravel, ensure the listener is in $listen or bound to the EventDispatcher.

Extension Points

1. Customize Command: Override the command in a bundle to add Laravel-specific logic:

   // src/Command/DebugListenersCommand.php
   namespace App\Console\Command;
   use Egulias\ListenersDebugCommandBundle\Command\DebugListenersCommand as BaseCommand;
   
   class DebugListenersCommand extends BaseCommand {
       protected function configure() {
           $this->setName('app:debug:listeners')
                ->addOption('laravel', null, InputOption::VALUE_NONE, 'Show Laravel EventServiceProvider listeners');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output) {
           if ($input->getOption('laravel')) {
               $this->showLaravelListeners($output);
           } else {
               parent::execute($input, $output);
           }
       }
   }
   

2. Integrate with Laravel Artisan: Alias the command in artisan:

   // config/console.php
   'commands' => [
       \Egulias\ListenersDebugCommandBundle\Command\DebugListenersCommand::class => 'debug:listeners',
   ],
   

   Now run with:

   php artisan debug:listeners