Listeners Debug Laravel Package

Product Decisions This Supports

• Debugging & Observability for Event-Driven Architectures:

  • Enables deeper visibility into Symfony2/Laravel event listeners (e.g., priorities, dependencies) to resolve race conditions, propagation issues, or unintended side effects. Critical for teams using domain events, DDD, or microservices where event flows are complex.
  • Justifies investment in internal debugging tools (e.g., CLI commands, admin panels) to reduce manual tracing time by 30–50% for event-related bugs.

• Developer Productivity & Onboarding:

  • Automates documentation of event listeners, reducing onboarding time for new hires by providing a programmatic listener map (e.g., fetchListeners('user.created')).
  • Supports self-service debugging for developers, aligning with platform-as-a-product goals where engineers should resolve issues without relying on senior staff.

• Build vs. Buy Decision:

  • Favors build for teams already using Symfony2/Laravel and needing lightweight, customizable debugging. Avoids vendor lock-in from proprietary tools (e.g., Sentry, Laravel Debugbar) while offering MIT-licensed flexibility.
  • Avoids buy if the goal is real-time monitoring (use Laravel Horizon or Symfony Profiler) or GUI debugging (use Debugbar).

• Roadmap Priorities:

  • Phase 1 (0–3 months): Integrate into CI/CD to auto-generate listener maps for onboarding (e.g., php artisan debug:listeners).
  • Phase 2 (3–6 months): Extend to visualize listener dependencies (e.g., DAGs or Mermaid.js diagrams) for architectural reviews.
  • Phase 3 (6–12 months): Add real-time monitoring (e.g., WebSocket updates) for live debugging in staging/prod, integrating with Laravel Echo or Symfony Mercure.

• Use Cases:

  • Post-mortems: Quickly identify why an event (e.g., PaymentFailedEvent) didn’t trigger expected listeners (e.g., sendRefundEmail).
  • Performance tuning: Pinpoint high-priority listeners causing bottlenecks in event propagation.
  • Security audits: Verify that sensitive events (e.g., UserPasswordReset) have the correct access controls (e.g., private listeners).
  • Legacy migration: Debug event flows when transitioning from Symfony2 to Laravel (if using a hybrid stack).

When to Consider This Package

Adopt If:

• Your app uses Symfony2 (or Laravel via Symfony Bridge) and relies on event listeners for core logic (e.g., >50 listeners or complex event graphs).
• Debugging event flows is a frequent bottleneck:

  • 20% of bug reports involve event misfires or propagation issues.

  • Developers spend >1 hour/week manually tracing listeners (e.g., grepping for addListener calls).
• You need programmatic access to listener metadata for:
  • CI/CD pipelines (e.g., auto-generating docs).
  • Custom tooling (e.g., a ListenerGraph CLI command).
• Your team prioritizes open-source, self-hosted solutions over SaaS (cost, privacy, or compliance reasons).
• You’re using Symfony2 in a Laravel context (e.g., legacy migration) and need to inspect Symfony listeners without switching IDEs.

Look Elsewhere If:

• Not using Symfony2/Laravel:
  • This package is Symfony2-centric; Laravel’s event system differs (uses EventDispatcher + closures, not DIC tags).
• Events are simple:
  • <10 listeners total or manually traceable (e.g., Event::listen('user.created', fn() => ...)).
• You need real-time monitoring:
  • This is a debug tool, not a production monitor. Use:
    • Laravel: spatie/laravel-debugbar, laravel-horizon, or custom middleware.
    • Symfony: symfony/profiler, blackfire.io.
• Maintenance risk is unacceptable:
  • Last release: 2015 (PHP 5.3). Requires forking for PHP 8.1+/Laravel 10+.
• You prefer GUI tools:
  • Use Symfony Profiler, Laravel Debugbar, or Tideways instead of CLI/programmatic debugging.

How to Pitch It (Stakeholders)

For Executives:

*"This is a zero-cost, open-source tool to reduce event-related debugging time by 30–50%, saving ~100 dev hours/year for our Symfony2/Laravel apps. Here’s why it’s worth prioritizing:

• Problem: Event-driven bugs (e.g., ‘Why didn’t OrderCancelledEvent trigger the refund?’) cost us $X/year in dev time and lost revenue.
• Solution: This package automates listener discovery via CLI/API, so teams can:
  • Dump all listeners for an event in seconds (vs. hours of manual tracing).
  • Generate auto-updated docs for onboarding (e.g., ‘user.created triggers sendWelcomeEmail’).
• ROI:
  • Phase 1 (3 months): Integrate into CI/CD for listener maps → $Y saved in onboarding.
  • Phase 2 (6 months): Add dependency visualization → $Z saved in architectural reviews.
• Risk: Low. MIT license, no vendor lock-in, and we can fork it if needed. Recommend funding a 3-week spike to prototype a Laravel-compatible version, with a focus on the debug:listeners CLI command."

For Engineering:

*"This package gives us programmatic access to Symfony2’s event listener registry, which we can adapt for Laravel to:

• Dump listener metadata (event name, service ID, priority) via CLI or API.
• Filter by event to isolate relevant listeners (e.g., fetchListeners('user.created')).
• Extend it to build custom tools (e.g., a ListenerGraph command to visualize event flows).

Pros:

• Lightweight: ~100 LOC core; no heavy dependencies.
• MIT license: Full control to fork/modify for Laravel.
• Symfony2 compatibility: Useful if we’re migrating legacy Symfony2 subsystems.

Cons:

• Stale: Last release 2015 (PHP 5.3). Needs updates for PHP 8.1+/Laravel 10+.
• Not Laravel-native: Requires rewriting ListenerFetcher to work with Laravel’s EventDispatcher.
• No GUI: Best paired with existing tools like Laravel Debugbar.

Suggestion:

1. Prototype a Laravel adapter (1–2 weeks):
   • Fork the package and rewrite ListenerFetcher to use app('events')->getListeners().
   • Add a debug:listeners Artisan command.
2. Evaluate alternatives:
   • If we only need basic listener inspection, Laravel’s native EventDispatcher or Debugbar may suffice.
   • If we need advanced filtering (e.g., by priority), this package’s ListenerFilter could be ported.
3. Plan for maintenance:
   • Assign ownership to a team member to keep it updated with Laravel/Symfony versions.
   • Deprecate if Laravel adds native support for this functionality.

Example Use Case:

# Future CLI command (after adaptation)
php artisan debug:listeners user.created
# Output:
# - sendWelcomeEmail (priority: 0)
# - logUserCreation (priority: 10)
# - notifyAdmin (priority: 20, private: true)
```"

---
### **For Developers**:
*"If you’re tired of **spending hours** tracing why `OrderPlacedEvent` isn’t triggering your listener, this tool can help. Here’s how it works:
1. **Install**:
   ```bash
   composer require egulias/listeners-debug

2. Use (Symfony2 example):

   $fetcher = new ListenerFetcher($containerBuilder);
   $listeners = $fetcher->fetchListeners(); // All listeners
   $filtered = $fetcher->fetchListener('user.created'); // Specific event
   

3. For Laravel:
   • We’d need to fork and adapt it to use app('events')->getListeners().
   • Example output:

     {
       "user.created": [
         { "listener": "App\Listeners\SendWelcomeEmail", "priority": 0 },
         { "listener": "App\Listeners\LogUserCreation", "priority": 10 }
       ]
     }
     

Why This Matters:

• No more grep-ing for addListener in 50+ files.
• Auto-generate docs for your event system.
• Find misconfigured listeners (e.g