class Dispatcher implements Dispatcher

Traits

Constants

DEFERRING_CONTEXT_KEY

Context key for whether event deferral is active.

DEFERRED_EVENTS_CONTEXT_KEY

Context key for the queue of deferred events.

EVENTS_TO_DEFER_CONTEXT_KEY

Context key for the list of event classes to defer.

PUSHED_EVENTS_CONTEXT_KEY

Context key for events queued via push() and dispatched via flush().

Properties

static protected array $macros

The registered string macros.

from  Macroable
protected Container $container

The IoC container instance.

protected array<string, array<int, null|array|callable|string>> $listeners

The registered event listeners.

protected array<string, array<int, array|callable|string>> $wildcards

The wildcard listeners.

protected array<string, true> $interfaceListeners

The registered interface listener keys.

protected Closure>> $wildcardsCache

The cached wildcard listeners.

protected array $listenersCache

The cached prepared listeners.

protected array<string, bool> $hasListenersCache

The cached hasListeners results.

protected array<string, array<int, array|callable|string>> $observers

The registered event observers.

protected array<string, array<int, array|callable|string>> $observerWildcards

The wildcard observers.

protected Closure>> $observerWildcardsCache

The cached wildcard observers.

protected Closure>> $observersCache

The cached prepared observers.

protected Factory $queueResolver

The queue resolver instance.

protected callable $transactionManagerResolver

The database transaction manager resolver instance.

Methods

static void
macro(string $name, callable|object $macro)

Register a custom macro.

static void
mixin(object $mixin, bool $replace = true)

Mix another object into the class.

static bool
hasMacro(string $name)

Check if macro is registered.

static void
flushMacros()

Flush the existing macros.

static mixed
__callStatic(string $method, array $parameters)

Dynamically handle calls to the class.

mixed
__call(string $method, array $parameters)

Dynamically handle calls to the class.

mixed
getAttributeValue(object $target, string $attributeClass, string|null $property = null, mixed $default = null)

Get a configuration value from an attribute, falling back to a property.

mixed
extractAttributeValue(object $instance)

Extract the value from an attribute instance.

object|null
getAttributeInstance(object $target, string $attributeClass, ReflectionClass|null $declaringClass = null)

Get an instance of the given attribute class from the target class or its parents.

bool
propertyOverridesAttribute(object $target, ReflectionClass $reflection, string|null $property, ReflectionClass $attributeDeclaringClass)

Determine if a property declared on a child class overrides an inherited attribute.

string
firstClosureParameterType(Closure $closure)

Get the class name of the first parameter of the given Closure.

array
firstClosureParameterTypes(Closure $closure)

Get the class names of the first parameter of the given Closure, including union types.

array
closureParameterTypes(Closure $closure)

Get the class names / types of the parameters of the given Closure.

array
closureReturnTypes(Closure $closure)

Get the class names / types of the return type of the given Closure.

string|null
resolveConnectionFromQueueRoute(object $queueable)

Resolve the default connection name for a given queueable instance.

string|null
resolveQueueFromQueueRoute(object $queueable)

Resolve the default queue name for a given queueable instance.

queueRoutes()

Get the queue routes manager instance.

__construct(Container|null $container = null)

Create a new event dispatcher instance.

void
listen(array|Closure|QueuedClosure|string $events, array|object|string|null $listener = null)

Register an event listener with the dispatcher.

void
setupWildcardListen(string $event, array|object|string $listener)

Set up a wildcard listener callback.

void
observe(array|string $events, array|object|string $observer)

Register a passive event observer.

void
setupWildcardObserver(string $event, array|object|string $observer)

Set up a wildcard observer callback.

bool
hasListeners(string $eventName)

Determine if a given event has listeners.

bool
hasWildcardListeners(string $eventName)

Determine if the given event has any wildcard listeners.

bool
hasInterfaceListeners(string $eventName)

Determine if the event class implements an interface with listeners.

bool
shouldResolveInterfaceListeners(string $eventName)

Determine if interface listeners should be resolved for the event.

void
push(string $event, mixed $payload = [])

Register an event and payload to be fired later.

void
flush(string $event)

Flush a set of pushed events.

void
subscribe(object|string $subscriber)

Register an event subscriber with the dispatcher.

mixed
resolveSubscriber(object|string $subscriber)

Resolve the subscriber instance.

mixed
until(object|string $event, mixed $payload = [])

Fire an event until the first non-null response is returned.

mixed
dispatch(object|string $event, mixed $payload = [], bool $halt = false)

Fire an event and call the listeners.

mixed
invokeListeners(string $event, array $payload, bool $halt = false)

Broadcast an event and call its listeners.

void
invokeObservers(string $event, array $payload)

Invoke passive observers for the event.

array
parseEventAndPayload(object|string $event, mixed $payload)

Parse the given event and payload and prepare them for dispatching.

bool
shouldBroadcast(array $payload)

Determine if the payload has a broadcastable event.

bool
broadcastWhen(mixed $event)

Check if the event should be broadcasted by the condition.

void
broadcastEvent(ShouldBroadcast $event)

Broadcast the given event class.

array
getListeners(string $eventName)

Get all of the listeners for a given event name.

array
getWildcardListeners(string $eventName)

Get the wildcard listeners for the event.

array
addInterfaceListeners(string $eventName, array $listeners = [])

Add the listeners for the event's interfaces to the given array.

array
prepareListeners(string $eventName)

Prepare the listeners for a given event.

array
getObservers(string $eventName)

Get all observers for a given event name.

array
prepareObservers(string $eventName)

Prepare the observers for a given event.

array
getWildcardObservers(string $eventName)

Get the wildcard observers for the event.

makeListener(array|object|string $listener, bool $wildcard = false)

Register an event listener with the dispatcher.

makeObserver(array|object|string $observer)

Create a callable for the given observer.

createClassListener(array|string $listener, bool $wildcard = false)

Create a class based listener using the IoC container.

callable
createClassCallable(array|string $listener)

Create the class based event callable.

array
parseClassCallable(string $listener)

Parse the class listener into class and method.

bool
handlerShouldBeQueued(string $class)

Determine if the event handler class should be queued.

createQueuedHandlerCallable(string $class, string $method)

Create a callable for putting an event handler on the queue.

bool
handlerShouldBeDispatchedAfterDatabaseTransactions(mixed $listener)

Determine if the given event handler should be dispatched after all database transactions have committed.

createCallbackForListenerRunningAfterCommits(mixed $listener, string $method)

Create a callable for dispatching a listener after database transactions.

bool
handlerWantsToBeQueued(string $class, array $arguments)

Determine if the event handler wants to be queued.

void
queueHandler(string $class, string $method, array $arguments)

Queue the handler class.

array
createListenerAndJob(string $class, string $method, array $arguments)

Create the listener and job for a queued listener.

propagateListenerOptions(mixed $listener, CallQueuedListener $job)

Propagate listener options to the job.

void
forget(string $event)

Remove a set of listeners from the dispatcher.

void
forgetPushed()

Forget all events queued via push() in the current coroutine.

resolveQueue()

Get the queue implementation from the resolver.

setQueueResolver(callable $resolver)

Set the queue resolver implementation.

resolveTransactionManager()

Get the database transaction manager implementation from the resolver.

setTransactionManagerResolver(callable $resolver)

Set the database transaction manager resolver implementation.

mixed
defer(callable $callback, array|null $events = null)

Execute the given callback while deferring events, then dispatch all deferred events.

bool
shouldDeferEvent(string $event)

Determine if the given event should be deferred.

array
getRawListeners()

Get the raw, unprepared listeners.

static void
flushState()

Flush all static state.

Details

in Macroable at line 28
static void macro(string $name, callable|object $macro)

Register a custom macro.

Boot-only. Macros persist in a static property for the worker lifetime and apply to every subsequent call on the macroable class.

Parameters

string $name
callable|object $macro

Return Value

void

in Macroable at line 41
static void mixin(object $mixin, bool $replace = true)

Mix another object into the class.

Boot-only. Delegates to macro() for each method; registered macros persist in a static property for the worker lifetime.

Parameters

object $mixin
bool $replace

Return Value

void

Exceptions

ReflectionException

in Macroable at line 57
static bool hasMacro(string $name)

Check if macro is registered.

Parameters

string $name

Return Value

bool

in Macroable at line 68
static void flushMacros()

Flush the existing macros.

Boot or tests only. Clears worker-wide macros; concurrent coroutines may resolve different methods depending on timing.

Return Value

void

in Macroable at line 78
static mixed __callStatic(string $method, array $parameters)

Dynamically handle calls to the class.

Parameters

string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

in Macroable at line 103
mixed __call(string $method, array $parameters)

Dynamically handle calls to the class.

Parameters

string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

protected mixed getAttributeValue(object $target, string $attributeClass, string|null $property = null, mixed $default = null)

Get a configuration value from an attribute, falling back to a property.

Parameters

object $target
string $attributeClass
string|null $property
mixed $default

Return Value

mixed

protected mixed extractAttributeValue(object $instance)

Extract the value from an attribute instance.

Parameters

object $instance

Return Value

mixed

protected object|null getAttributeInstance(object $target, string $attributeClass, ReflectionClass|null $declaringClass = null)

Get an instance of the given attribute class from the target class or its parents.

Parameters

object $target
string $attributeClass
ReflectionClass|null $declaringClass

Return Value

object|null

protected bool propertyOverridesAttribute(object $target, ReflectionClass $reflection, string|null $property, ReflectionClass $attributeDeclaringClass)

Determine if a property declared on a child class overrides an inherited attribute.

Parameters

object $target
ReflectionClass $reflection
string|null $property
ReflectionClass $attributeDeclaringClass

Return Value

bool

in ReflectsClosures at line 25
protected string firstClosureParameterType(Closure $closure)

Get the class name of the first parameter of the given Closure.

Parameters

Closure $closure

Return Value

string

Exceptions

ReflectionException
RuntimeException

in ReflectsClosures at line 48
protected array firstClosureParameterTypes(Closure $closure)

Get the class names of the first parameter of the given Closure, including union types.

Parameters

Closure $closure

Return Value

array

Exceptions

ReflectionException
RuntimeException

in ReflectsClosures at line 74
protected array closureParameterTypes(Closure $closure)

Get the class names / types of the parameters of the given Closure.

Parameters

Closure $closure

Return Value

array

Exceptions

ReflectionException

in ReflectsClosures at line 94
protected array closureReturnTypes(Closure $closure)

Get the class names / types of the return type of the given Closure.

Parameters

Closure $closure

Return Value

array

Exceptions

ReflectionException

string|null resolveConnectionFromQueueRoute(object $queueable)

Resolve the default connection name for a given queueable instance.

Parameters

object $queueable

Return Value

string|null

string|null resolveQueueFromQueueRoute(object $queueable)

Resolve the default queue name for a given queueable instance.

Parameters

object $queueable

Return Value

string|null

protected QueueRoutes queueRoutes()

Get the queue routes manager instance.

Return Value

QueueRoutes

at line 173
__construct(Container|null $container = null)

Create a new event dispatcher instance.

Parameters

Container|null $container

at line 184
void listen(array|Closure|QueuedClosure|string $events, array|object|string|null $listener = null)

Register an event listener with the dispatcher.

Boot-only. The listener registry persists on the singleton Dispatcher for the worker lifetime; per-request registration races across coroutines.

Parameters

array|Closure|QueuedClosure|string $events
array|object|string|null $listener

Return Value

void

at line 235
protected void setupWildcardListen(string $event, array|object|string $listener)

Set up a wildcard listener callback.

Parameters

string $event
array|object|string $listener

Return Value

void

at line 257
void observe(array|string $events, array|object|string $observer)

Register a passive event observer.

Boot-only. The observer registry persists on the singleton Dispatcher for the worker lifetime; per-request registration races across coroutines.

Observers receive dispatched events but are not counted by hasListeners(). They are invoked after all active listeners, do not participate in halt or propagation-stop semantics, and run synchronously (no queue support).

Use this for observability tooling (tracing, metrics, logging) that must not influence whether guarded events fire.

Parameters

array|string $events
array|object|string $observer

Return Value

void

at line 274
protected void setupWildcardObserver(string $event, array|object|string $observer)

Set up a wildcard observer callback.

Parameters

string $event
array|object|string $observer

Return Value

void

at line 285
bool hasListeners(string $eventName)

Determine if a given event has listeners.

Parameters

string $eventName

Return Value

bool

at line 300
bool hasWildcardListeners(string $eventName)

Determine if the given event has any wildcard listeners.

Parameters

string $eventName

Return Value

bool

at line 314
protected bool hasInterfaceListeners(string $eventName)

Determine if the event class implements an interface with listeners.

Parameters

string $eventName

Return Value

bool

at line 334
protected bool shouldResolveInterfaceListeners(string $eventName)

Determine if interface listeners should be resolved for the event.

Relies on interface listener keys being classified at registration time.

Parameters

string $eventName

Return Value

bool

at line 342
void push(string $event, mixed $payload = [])

Register an event and payload to be fired later.

Parameters

string $event
mixed $payload

Return Value

void

at line 355
void flush(string $event)

Flush a set of pushed events.

Parameters

string $event

Return Value

void

at line 368
void subscribe(object|string $subscriber)

Register an event subscriber with the dispatcher.

Boot-only. Subscriber registrations persist on the singleton Dispatcher for the worker lifetime; per-request registration races across coroutines.

Parameters

object|string $subscriber

Return Value

void

at line 392
protected mixed resolveSubscriber(object|string $subscriber)

Resolve the subscriber instance.

Parameters

object|string $subscriber

Return Value

mixed

at line 404
mixed until(object|string $event, mixed $payload = [])

Fire an event until the first non-null response is returned.

Parameters

object|string $event
mixed $payload

Return Value

mixed

at line 412
mixed dispatch(object|string $event, mixed $payload = [], bool $halt = false)

Fire an event and call the listeners.

Parameters

object|string $event
mixed $payload
bool $halt

Return Value

mixed

at line 457
protected mixed invokeListeners(string $event, array $payload, bool $halt = false)

Broadcast an event and call its listeners.

Parameters

string $event
array $payload
bool $halt

Return Value

mixed

at line 496
protected void invokeObservers(string $event, array $payload)

Invoke passive observers for the event.

Observers do not participate in halt or propagation-stop semantics. They always run, and their return values are ignored.

Parameters

string $event
array $payload

Return Value

void

at line 508
protected array parseEventAndPayload(object|string $event, mixed $payload)

Parse the given event and payload and prepare them for dispatching.

Parameters

object|string $event
mixed $payload

Return Value

array

at line 520
protected bool shouldBroadcast(array $payload)

Determine if the payload has a broadcastable event.

Parameters

array $payload

Return Value

bool

at line 530
protected bool broadcastWhen(mixed $event)

Check if the event should be broadcasted by the condition.

Parameters

mixed $event

Return Value

bool

at line 540
protected void broadcastEvent(ShouldBroadcast $event)

Broadcast the given event class.

Parameters

ShouldBroadcast $event

Return Value

void

at line 548
array getListeners(string $eventName)

Get all of the listeners for a given event name.

Parameters

string $eventName

Return Value

array

at line 569
protected array getWildcardListeners(string $eventName)

Get the wildcard listeners for the event.

Parameters

string $eventName

Return Value

array

at line 587
protected array addInterfaceListeners(string $eventName, array $listeners = [])

Add the listeners for the event's interfaces to the given array.

Parameters

string $eventName
array $listeners

Return Value

array

at line 605
protected array prepareListeners(string $eventName)

Prepare the listeners for a given event.

Parameters

string $eventName

Return Value

array

at line 619
array getObservers(string $eventName)

Get all observers for a given event name.

Parameters

string $eventName

Return Value

array

at line 638
protected array prepareObservers(string $eventName)

Prepare the observers for a given event.

Parameters

string $eventName

Return Value

array

at line 652
protected array getWildcardObservers(string $eventName)

Get the wildcard observers for the event.

Parameters

string $eventName

Return Value

array

at line 670
Closure makeListener(array|object|string $listener, bool $wildcard = false)

Register an event listener with the dispatcher.

Parameters

array|object|string $listener
bool $wildcard

Return Value

Closure

at line 696
protected Closure makeObserver(array|object|string $observer)

Create a callable for the given observer.

Unlike makeListener(), this never consults queue or after-commit logic. Observers are always invoked synchronously and always receive the wildcard-style (string $event, array $payload) arguments.

Parameters

array|object|string $observer

Return Value

Closure

at line 718
Closure createClassListener(array|string $listener, bool $wildcard = false)

Create a class based listener using the IoC container.

Parameters

array|string $listener
bool $wildcard

Return Value

Closure

at line 736
protected callable createClassCallable(array|string $listener)

Create the class based event callable.

Parameters

array|string $listener

Return Value

callable

at line 767
protected array parseClassCallable(string $listener)

Parse the class listener into class and method.

Parameters

string $listener

Return Value

array

at line 775
protected bool handlerShouldBeQueued(string $class)

Determine if the event handler class should be queued.

Parameters

string $class

Return Value

bool

at line 791
protected Closure createQueuedHandlerCallable(string $class, string $method)

Create a callable for putting an event handler on the queue.

Parameters

string $class
string $method

Return Value

Closure

at line 807
protected bool handlerShouldBeDispatchedAfterDatabaseTransactions(mixed $listener)

Determine if the given event handler should be dispatched after all database transactions have committed.

Parameters

mixed $listener

Return Value

bool

at line 817
protected Closure createCallbackForListenerRunningAfterCommits(mixed $listener, string $method)

Create a callable for dispatching a listener after database transactions.

Parameters

mixed $listener
string $method

Return Value

Closure

at line 835
protected bool handlerWantsToBeQueued(string $class, array $arguments)

Determine if the event handler wants to be queued.

Parameters

string $class
array $arguments

Return Value

bool

at line 851
protected void queueHandler(string $class, string $method, array $arguments)

Queue the handler class.

Parameters

string $class
string $method
array $arguments

Return Value

void

at line 903
protected array createListenerAndJob(string $class, string $method, array $arguments)

Create the listener and job for a queued listener.

Parameters

string $class
string $method
array $arguments

Return Value

array

Exceptions

ReflectionException

at line 916
protected CallQueuedListener propagateListenerOptions(mixed $listener, CallQueuedListener $job)

Propagate listener options to the job.

Parameters

mixed $listener
CallQueuedListener $job

Return Value

CallQueuedListener

at line 969
void forget(string $event)

Remove a set of listeners from the dispatcher.

Boot or tests only. The listener registry persists on the singleton Dispatcher for the worker lifetime; per-request removal races across coroutines and can remove application listeners for other requests.

Parameters

string $event

Return Value

void

at line 997
void forgetPushed()

Forget all events queued via push() in the current coroutine.

Return Value

void

at line 1005
protected Factory resolveQueue()

Get the queue implementation from the resolver.

Return Value

Factory

at line 1018
Dispatcher setQueueResolver(callable $resolver)

Set the queue resolver implementation.

Boot-only. The resolver persists on the singleton Dispatcher for the worker lifetime and is consulted whenever a queued listener is dispatched.

Parameters

callable $resolver

Return Value

Dispatcher

at line 1028
protected DatabaseTransactionsManager|null resolveTransactionManager()

Get the database transaction manager implementation from the resolver.

Return Value

DatabaseTransactionsManager|null

at line 1045
Dispatcher setTransactionManagerResolver(callable $resolver)

Set the database transaction manager resolver implementation.

Boot-only. The resolver persists on the singleton Dispatcher for the worker lifetime and is consulted for every transaction-aware dispatch.

Parameters

callable $resolver

Return Value

Dispatcher

at line 1061
mixed defer(callable $callback, array|null $events = null)

Execute the given callback while deferring events, then dispatch all deferred events.

Parameters

callable $callback
array|null $events

Return Value

mixed

at line 1091
protected bool shouldDeferEvent(string $event)

Determine if the given event should be deferred.

Parameters

string $event

Return Value

bool

at line 1105
array getRawListeners()

Get the raw, unprepared listeners.

Return Value

array

at line 1113
static void flushState()

Flush all static state.

Return Value

void