feat: add event dispatcher facade and service provider

src/Events/Dispatcher.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Events;
 
+use Illuminate\Contracts\Events\Dispatcher as DispatcherContract;
+use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Support\Collection;
 use Siteworxpro\App\Annotations\Events\ListensFor;
 
@@ -15,7 +17,7 @@ use Siteworxpro\App\Annotations\Events\ListensFor;
  *
  * @package Siteworxpro\App\Events
  */
-class Dispatcher implements \Illuminate\Contracts\Events\Dispatcher
+class Dispatcher implements DispatcherContract, Arrayable
 {
     /**
      * @var array $listeners Registered event listeners
@@ -38,6 +40,11 @@ class Dispatcher implements \Illuminate\Contracts\Events\Dispatcher
         $this->registerListeners();
     }
 
+    /**
+     * Register event listeners based on the ListensFor attribute.
+     *
+     * @return void
+     */
     private function registerListeners(): void
     {
         // traverse the Listeners directory and register all listeners
@@ -61,26 +68,60 @@ class Dispatcher implements \Illuminate\Contracts\Events\Dispatcher
         }
     }
 
+    /**
+     * Register a listener for the given events.
+     *
+     * @param $events
+     * @param $listener
+     * @return void
+     */
     public function listen($events, $listener = null): void
     {
         $this->listeners[$events][] = $listener;
     }
 
+    /**
+     * Check if there are listeners for the given event.
+     *
+     * @param $eventName
+     * @return bool
+     */
     public function hasListeners($eventName): bool
     {
         return isset($this->listeners[$eventName]) && !empty($this->listeners[$eventName]);
     }
 
+    /**
+     * Subscribe a subscriber to the dispatcher.
+     *
+     * @param Arrayable $subscriber
+     * @return void
+     */
     public function subscribe($subscriber): void
     {
         $this->listeners = array_merge($this->listeners, (array) $subscriber);
     }
 
-    public function until($event, $payload = [])
+    /**
+     * Dispatch an event and halt on the first non-null response.
+     *
+     * @param $event
+     * @param array $payload
+     * @return array|null
+     */
+    public function until($event, $payload = []): array|null
     {
         return $this->dispatch($event, $payload, true);
     }
 
+    /**
+     * Dispatch an event to its listeners.
+     *
+     * @param $event
+     * @param array $payload
+     * @param bool $halt
+     * @return array|null
+     */
     public function dispatch($event, $payload = [], $halt = false): array|null
     {
         if (is_object($event)) {
@@ -109,11 +150,24 @@ class Dispatcher implements \Illuminate\Contracts\Events\Dispatcher
         return $responses;
     }
 
+    /**
+     * Push an event to be dispatched later.
+     *
+     * @param $event
+     * @param array $payload
+     * @return void
+     */
     public function push($event, $payload = []): void
     {
         $this->pushed->put($event, $payload);
     }
 
+    /**
+     * Flush a pushed event, dispatching it if it exists.
+     *
+     * @param $event
+     * @return void
+     */
     public function flush($event): void
     {
         if ($this->pushed->has($event)) {
@@ -123,13 +177,29 @@ class Dispatcher implements \Illuminate\Contracts\Events\Dispatcher
         }
     }
 
+    /**
+     * Forget a pushed event without dispatching it.
+     *
+     * @param $event
+     * @return void
+     */
     public function forget($event): void
     {
         $this->pushed->forget([$event]);
     }
 
+    /**
+     * Forget all pushed events.
+     *
+     * @return void
+     */
     public function forgetPushed(): void
     {
         $this->pushed = new Collection();
     }
+
+    public function toArray(): array
+    {
+        return $this->listeners;
+    }
 }