[12.x] Improve event types (#57986)

* Improve types in `\Illuminate\Events\Dispatcher`

* `Dispatcher::until()` must return the same as `Dispatcher::dispatch()`

as the former simply calls the latter

* Improve types in `\Illuminate\Database\Eloquent\Concerns\HasEvents`

Author: shaedrich

src/Illuminate/Database/Eloquent/Concerns/HasEvents.php

@@ -18,7 +18,7 @@ trait HasEvents
      *
      * Allows for object-based events for native Eloquent events.
      *
-     * @var array
+     * @var array<string, class-string>
      */
     protected $dispatchesEvents = [];
 
@@ -27,7 +27,7 @@ trait HasEvents
      *
      * These are extra user-defined events observers may subscribe to.
      *
-     * @var array
+     * @var string[]
      */
     protected $observables = [];
 
@@ -66,7 +66,7 @@ public static function resolveObserveAttributes()
     /**
      * Register observers with the model.
      *
-     * @param  object|array|string  $classes
+     * @param  object|string[]|string  $classes
      * @return void
      *
      * @throws \RuntimeException
@@ -106,7 +106,7 @@ protected function registerObserver($class)
      * Resolve the observer's class name from an object or string.
      *
      * @param  object|string  $class
-     * @return string
+     * @return class-string
      *
      * @throws \InvalidArgumentException
      */
@@ -126,7 +126,7 @@ private function resolveObserverClassName($class)
     /**
      * Get the observable event names.
      *
-     * @return array
+     * @return string[]
      */
     public function getObservableEvents()
     {
@@ -143,7 +143,7 @@ public function getObservableEvents()
     /**
      * Set the observable event names.
      *
-     * @param  array  $observables
+     * @param  string[]  $observables
      * @return $this
      */
     public function setObservableEvents(array $observables)
@@ -156,7 +156,7 @@ public function setObservableEvents(array $observables)
     /**
      * Add an observable event name.
      *
-     * @param  mixed  $observables
+     * @param  string|string[]  $observables
      * @return void
      */
     public function addObservableEvents($observables)
@@ -169,7 +169,7 @@ public function addObservableEvents($observables)
     /**
      * Remove an observable event name.
      *
-     * @param  mixed  $observables
+     * @param  string|string[]  $observables
      * @return void
      */
     public function removeObservableEvents($observables)
@@ -230,8 +230,8 @@ protected function fireModelEvent($event, $halt = true)
      * Fire a custom model event for the given event.
      *
      * @param  string  $event
-     * @param  string  $method
-     * @return mixed
+     * @param  'until'|'dispatch'  $method
+     * @return array|null|void
      */
     protected function fireCustomModelEvent($event, $method)
     {

src/Illuminate/Events/Dispatcher.php

@@ -37,28 +37,28 @@ class Dispatcher implements DispatcherContract
     /**
      * The registered event listeners.
      *
-     * @var array
+     * @var array<string, callable|array|class-string|null>
      */
     protected $listeners = [];
 
     /**
      * The wildcard listeners.
      *
-     * @var array
+     * @var array<string, \Closure|string>
      */
     protected $wildcards = [];
 
     /**
      * The cached wildcard listeners.
      *
-     * @var array
+     * @var array<string, \Closure|string>
      */
     protected $wildcardsCache = [];
 
     /**
      * The queue resolver instance.
      *
-     * @var callable
+     * @var callable(): \Illuminate\Contracts\Queue\Queue
      */
     protected $queueResolver;
 
@@ -86,7 +86,7 @@ class Dispatcher implements DispatcherContract
     /**
      * The specific events to defer (null means defer all events).
      *
-     * @var array|null
+     * @var string[]|null
      */
     protected $eventsToDefer = null;
 
@@ -231,8 +231,8 @@ public function subscribe($subscriber)
     /**
      * Resolve the subscriber instance.
      *
-     * @param  object|string  $subscriber
-     * @return mixed
+     * @param  object|class-string  $subscriber
+     * @return $subscriber is object ? object : mixed
      */
     protected function resolveSubscriber($subscriber)
     {
@@ -248,7 +248,7 @@ protected function resolveSubscriber($subscriber)
      *
      * @param  string|object  $event
      * @param  mixed  $payload
-     * @return mixed
+     * @return array|null
      */
     public function until($event, $payload = [])
     {
@@ -339,7 +339,7 @@ protected function invokeListeners($event, $payload, $halt = false)
      *
      * @param  mixed  $event
      * @param  mixed  $payload
-     * @return array
+     * @return array{string, array}
      */
     protected function parseEventAndPayload($event, $payload)
     {
@@ -466,7 +466,7 @@ protected function prepareListeners(string $eventName)
     /**
      * Register an event listener with the dispatcher.
      *
-     * @param  \Closure|string|array  $listener
+     * @param  \Closure|string|array{class-string, string}  $listener
      * @param  bool  $wildcard
      * @return \Closure
      */
@@ -512,7 +512,7 @@ public function createClassListener($listener, $wildcard = false)
     /**
      * Create the class based event callable.
      *
-     * @param  array|string  $listener
+     * @param  array{class-string, string}|string  $listener
      * @return callable
      */
     protected function createClassCallable($listener)
@@ -540,7 +540,7 @@ protected function createClassCallable($listener)
      * Parse the class listener into class and method.
      *
      * @param  string  $listener
-     * @return array
+     * @return array{class-string, string}
      */
     protected function parseClassCallable($listener)
     {
@@ -550,8 +550,9 @@ protected function parseClassCallable($listener)
     /**
      * Determine if the event handler class should be queued.
      *
-     * @param  string  $class
+     * @param  class-string  $class
      * @return bool
+     * @phpstan-assert-if-true \Illuminate\Contracts\Queue\ShouldQueue $class
      */
     protected function handlerShouldBeQueued($class)
     {
@@ -567,9 +568,9 @@ protected function handlerShouldBeQueued($class)
     /**
      * Create a callable for putting an event handler on the queue.
      *
-     * @param  string  $class
+     * @param  class-string  $class
      * @param  string  $method
-     * @return \Closure
+     * @return \Closure(): void
      */
     protected function createQueuedHandlerCallable($class, $method)
     {
@@ -620,7 +621,7 @@ function () use ($listener, $method, $payload) {
     /**
      * Determine if the event handler wants to be queued.
      *
-     * @param  string  $class
+     * @param  class-string  $class
      * @param  array  $arguments
      * @return bool
      */
@@ -667,10 +668,11 @@ protected function queueHandler($class, $method, $arguments)
     /**
      * Create the listener and job for a queued listener.
      *
-     * @param  string  $class
+     * @template TListener
+     * @param  class-string<TListener>  $class
      * @param  string  $method
      * @param  array  $arguments
-     * @return array
+     * @return array{TListener, mixed}
      */
     protected function createListenerAndJob($class, $method, $arguments)
     {
@@ -686,7 +688,7 @@ protected function createListenerAndJob($class, $method, $arguments)
      *
      * @param  mixed  $listener
      * @param  \Illuminate\Events\CallQueuedListener  $job
-     * @return mixed
+     * @return \Illuminate\Events\CallQueuedListener
      */
     protected function propagateListenerOptions($listener, $job)
     {
@@ -767,7 +769,7 @@ protected function resolveQueue()
     /**
      * Set the queue resolver implementation.
      *
-     * @param  callable  $resolver
+     * @param  callable(): \Illuminate\Contracts\Queue\Queue  $resolver
      * @return $this
      */
     public function setQueueResolver(callable $resolver)
@@ -790,7 +792,7 @@ protected function resolveTransactionManager()
     /**
      * Set the database transaction manager resolver implementation.
      *
-     * @param  callable  $resolver
+     * @param  (callable(): \Illuminate\Database\DatabaseTransactionsManager|null)  $resolver
      * @return $this
      */
     public function setTransactionManagerResolver(callable $resolver)
@@ -803,9 +805,10 @@ public function setTransactionManagerResolver(callable $resolver)
     /**
      * Execute the given callback while deferring events, then dispatch all deferred events.
      *
-     * @param  callable  $callback
-     * @param  array|null  $events
-     * @return mixed
+     * @template TResult
+     * @param  callable(): TResult  $callback
+     * @param  string[]|null  $events
+     * @return TResult
      */
     public function defer(callable $callback, ?array $events = null)
     {