Telegram Bundle Laravel Package

Getting Started

1. Confirm what 1.1 changed before writing code. The release note is high-level ("utilize event model of the Symfony"), so start with:

   • composer.json for required PHP/Laravel/Symfony versions.
   • CHANGELOG.md / UPGRADE.md for event class renames, listener signature changes, or dispatcher binding changes.
   • The package service provider to see whether it binds Symfony\Component\EventDispatcher\EventDispatcherInterface, aliases it to Laravel’s dispatcher, or registers its own dispatcher instance.

2. Check which dispatcher you should use day-to-day. In a Laravel app you normally call event(new MyEvent(...)), which uses Illuminate\Contracts\Events\Dispatcher. If 1.1 now dispatches through Symfony’s EventDispatcherInterface, confirm whether the package bridges the two or expects you to inject the Symfony dispatcher directly:

   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   public function __construct(private EventDispatcherInterface $dispatcher) {}
   
   public function handle(): void
   {
       $this->dispatcher->dispatch(new OrderPlaced($order), OrderPlaced::NAME);
   }
   

   If the package provides a Laravel bridge, prefer the event() helper so you keep Laravel’s testing and queue integrations.

3. First use case: listen to one lifecycle event. Register a listener in App\Providers\EventServiceProvider (or the package’s documented registration point) and log the payload:

   protected $listen = [
       \Vendor\Package\Events\SomethingHappened::class => [
           \App\Listeners\LogSomethingHappened::class,
       ],
   ];
   

   Dispatch the event from a route or artisan command, then verify with php artisan event:list if the package uses Laravel’s dispatcher. If it uses Symfony’s dispatcher directly, verify by injecting the dispatcher and adding a temporary listener that writes to the log.

4. Look first at the package’s event classes and subscriber support. Symfony-style events usually expose a NAME constant and implement Symfony\Contracts\EventDispatcher\Event. Those constants are the integration surface; use them instead of hard-coded strings.

Implementation Patterns

• Register listeners through the package’s documented path. If the package exposes an events config array or a registerListeners() method, use that rather than manually resolving the dispatcher. This keeps listener registration compatible with config caching and future releases.

• Use Symfony event subscribers for grouped listeners. If 1.1 exposes Symfony’s subscriber model, implement EventSubscriberInterface:

  public static function getSubscribedEvents(): array
  {
      return [
          OrderPlaced::NAME => [
              ['onOrderPlaced', 10],
              ['auditOrderPlaced', 0],
          ],
      ];
  }
  

  Higher priority runs first in Symfony’s dispatcher. Use priorities instead of relying on registration order.

• Bridge Symfony events into Laravel’s event system when possible. If the package dispatches Symfony events internally, add a small adapter listener that re-dispatches a Laravel event:

  $dispatcher->addListener(OrderPlaced::NAME, function (OrderPlaced $event) {
      event(new \App\Events\OrderPlaced($event->order));
  });
  

  This lets you keep Laravel’s Event::fake(), queued listeners, and broadcasting.

• Queue expensive work outside the Symfony listener. Symfony listeners are synchronous. If a listener performs I/O, dispatch a Laravel job from the listener instead of doing the work inline. Check whether the package offers a queued listener abstraction before building your own.

• Dispatch after commit for database-related events. Symfony’s dispatcher has no equivalent to Laravel’s ShouldDispatchAfterCommit. Wrap dispatches in DB::afterCommit():

  DB::afterCommit(fn () => $dispatcher->dispatch(new OrderPlaced($order), OrderPlaced::NAME));
  

• Test with the right fake. If events flow through Laravel, Event::fake([OrderPlaced::class]) works. If they flow through Symfony’s dispatcher, use a real dispatcher with a test listener, or the package’s fake if provided. Assert on the event object, not only the event name.

• Use extension points instead of decorating internals. Look for a bound EventDispatcherInterface, a configurable listener provider, or a package-level EventDispatcher factory. Prefer binding a decorator in a service provider:

  $this->app->extend(EventDispatcherInterface::class, function ($dispatcher) {
      return new LoggingEventDispatcher($dispatcher);
  });
  

Gotchas and Tips

• 1.1 is a broad internal change, so treat it as potentially breaking. "Lots of changes to utilize event model of the Symfony" likely means event class names, event name constants, listener signatures, or the dispatcher binding changed. Run the full test suite and search your codebase for package event names, dispatch( calls, and listener type-hints before deploying.

• Do not assume Laravel’s dispatcher and Symfony’s dispatcher are interchangeable. Illuminate\Contracts\Events\Dispatcher and Symfony\Component\EventDispatcher\EventDispatcherInterface have different listener signatures and propagation behavior. Injecting the wrong one is the most likely cause of “my listener never fires.” Check the package service provider for aliases and bindings.

• Propagation stopping differs. In Symfony, returning false from a listener stops later listeners. Laravel listeners do not use return values for propagation. If you bridge the two, do not rely on return values unless the bridge explicitly supports it.

• Listener ordering is not guaranteed by registration order in Symfony. Use explicit priorities. If you are migrating from Laravel-only listeners, audit any listener that assumes it runs before another.

• Clear caches after upgrading. Run php artisan config:clear, php artisan cache:clear, and php artisan event:clear where applicable. If the package caches listeners, stale caches can hide newly registered listeners.

• php artisan event:list may not show Symfony-dispatched events. It lists Laravel events. For Symfony’s dispatcher, use a temporary debug listener, package debug command, or Symfony’s debug:event-dispatcher if available.

• Long-running workers and Octane need care. Symfony’s dispatcher is stateful. If listeners are registered during each request, ensure they are not duplicated across requests in Octane. Prefer registering listeners once in a service provider.

• Watch for event name changes. Symfony-style events often use string names via Event::NAME. If 1.1 renamed those constants or switched to class-name-only dispatch, string-based listeners will silently stop firing. Search for hard-coded event name strings.

• Check queue and broadcasting compatibility. Symfony events do not automatically integrate with Laravel’s queue or broadcast systems. If your listeners implement ShouldQueue, verify the package actually routes through Laravel’s dispatcher; otherwise the interface may be ignored.

• Use the package’s extension points before subclassing internals. If 1.1 exposes a configurable dispatcher, listener provider, or subscriber registry, bind or configure those. Subclassing internal classes is more likely to break in future releases.