 |
VOOZH | about |
|
VOOZH | about |
The Dispatchable trait provides static factory methods that enable job classes to dispatch themselves. When a job class uses this trait, it gains convenient static methods like dispatch(), dispatchSync(), and withChain() that create and configure job dispatches without requiring direct instantiation or interaction with the dispatcher service.
This document covers the methods provided by the trait and their behavior. For configuring the dispatch (queue, delay, callbacks), see Configuring Job Dispatch. For details on job chaining, see Job Chaining. For the underlying Queueable properties used with Dispatchable, see Queueable Trait.
The Dispatchable trait serves as a static factory interface for job classes. It allows jobs to be dispatched using an expressive, static method syntax rather than requiring manual instantiation and dispatcher injection.
Location: src/Dispatchable.php14-87
Primary Purpose: Transform new Job($args) followed by dispatcher calls into a single fluent call like Job::dispatch($args).
Title: Dispatchable Trait Integration Pattern
Sources: src/Dispatchable.php14-87
The trait provides six primary static methods, each serving a different dispatch pattern.
| Method | Return Type | Purpose |
|---|---|---|
dispatch(...$arguments) | PendingDispatch | Creates a pending dispatch for async/sync execution |
dispatchIf($boolean, ...$arguments) | PendingDispatch|Fluent | Conditionally dispatches if condition is true |
dispatchUnless($boolean, ...$arguments) | PendingDispatch|Fluent | Conditionally dispatches if condition is false |
dispatchSync(...$arguments) | mixed | Immediately executes job in current process |
dispatchAfterResponse(...$arguments) | mixed | Dispatches after HTTP response is sent |
withChain(array $chain) | PendingChain | Creates a job chain with this job as the first |
Sources: src/Dispatchable.php19-86
The dispatch() method is the primary entry point for job dispatching. It instantiates the job with the provided arguments and wraps it in a PendingDispatch object.
Title: Dispatch Method Execution Flow
Implementation: src/Dispatchable.php19-22
Signature:
Parameters:
...$arguments - Variable arguments passed to the job's constructorReturns: A PendingDispatch instance that allows further configuration before actual dispatch
Key Behavior: The method uses new static(...$arguments) to instantiate the job class, ensuring that child classes work correctly with inheritance.
Sources: src/Dispatchable.php19-22
Conditionally creates a PendingDispatch based on a boolean test. This method prevents the need for explicit if-statement wrapping around dispatch calls.
Implementation: src/Dispatchable.php27-40
Signature:
Parameters:
$boolean - A boolean value or Closure that returns a boolean...$arguments - Arguments for the job constructorReturn Behavior:
PendingDispatch if condition evaluates to trueFluent (no-op object) if condition evaluates to falseClosure Parameter Pattern: When $boolean is a Closure, the job instance is passed to the closure, allowing the condition to inspect the job:
Title: dispatchIf with Closure Parameter Flow
Sources: src/Dispatchable.php27-40
The inverse of dispatchIf(). Dispatches when the condition is false.
Implementation: src/Dispatchable.php45-58
Signature:
Logic: Identical to dispatchIf() but negates the boolean test (! value($boolean) instead of value($boolean)).
Sources: src/Dispatchable.php45-58
The dispatchSync() method bypasses the pending dispatch system entirely and immediately executes the job in the current process.
Implementation: src/Dispatchable.php65-70
Title: Synchronous Dispatch Execution Path
Signature:
Key Characteristics:
PendingDispatch object; executes immediatelyApplicationContext::getContainer()->get(Dispatcher::class) to resolve the dispatcherShouldQueue, it will be dispatched to the "sync" queue, executing immediatelyUse Cases:
Sources: src/Dispatchable.php65-70
This method provides a convenient shorthand for dispatching a job after the HTTP response has been sent to the client.
Implementation: src/Dispatchable.php75-78
Signature:
Equivalent Call Chain:
Implementation Detail: The method simply calls static::dispatch(...$arguments)->afterResponse(), demonstrating method chaining composition.
Sources: src/Dispatchable.php75-78
The withChain() method creates a PendingChain object, allowing the job to be the first job in a chain with subsequent jobs.
Implementation: src/Dispatchable.php83-86
Signature:
Parameters:
$chain - Array of job instances or class names to execute after this job completes successfullyTitle: withChain Method Execution Flow
Key Behavior:
static::class) to PendingChainPendingChain will instantiate the first job when dispatch() is calledFor detailed chain mechanics, see Job Chaining.
Sources: src/Dispatchable.php83-86
This creates a PendingDispatch that will dispatch when it destructs (see Configuring Job Dispatch).
The PendingDispatch provides fluent configuration methods before dispatch.
Sources: src/Dispatchable.php14-87
The trait uses new static(...$arguments) rather than new self(...$arguments). This late static binding ensures that when a child class uses the trait, the child class is instantiated, not the trait's defining class.
Example:
Sources: src/Dispatchable.php21-22
When dispatchIf() or dispatchUnless() conditions fail, they return a Fluent object instead of null. The Fluent class (from Hyperf\Support\Fluent) provides a no-op object that safely absorbs method calls without errors.
Behavior:
This allows method chaining without conditional wrapping.
Sources: src/Dispatchable.php34-57
The dispatchSync() method resolves the Dispatcher contract from the application container using ApplicationContext::getContainer()->get(Dispatcher::class).
Dependency Chain:
ApplicationContext from Hyperf\Context\ApplicationContextget() method resolves Dispatcher::classConfigProvider has registered the binding (see Installation and Configuration)DispatcherFactory creates the Dispatcher instanceSources: src/Dispatchable.php67-68
The Dispatchable trait creates PendingDispatch objects that read properties from the Queueable trait:
Title: Dispatchable and Queueable Trait Interaction
The Queueable trait provides properties like connection, queue, and delay that PendingDispatch reads when determining how to dispatch the job.
Sources: src/Dispatchable.php19-22
Jobs using both Dispatchable and Batchable can be dispatched as part of batches:
The Batchable trait allows the job to access its parent batch during execution. See Batchable Trait for details.
Sources: src/Dispatchable.php14-87
| Entity | Type | Location |
|---|---|---|
Dispatchable | Trait | src/Dispatchable.php14 |
PendingDispatch | Class | Referenced in trait, defined elsewhere |
PendingChain | Class | Referenced in trait, defined elsewhere |
Dispatcher | Contract | Hypervel\Bus\Contracts\Dispatcher |
Fluent | Class | Hyperf\Support\Fluent |
| Method | Lines | Signature |
|---|---|---|
dispatch() | src/Dispatchable.php19-22 | public static function dispatch(mixed ...$arguments): PendingDispatch |
dispatchIf() | src/Dispatchable.php27-40 | public static function dispatchIf(bool|Closure $boolean, mixed ...$arguments): Fluent|PendingDispatch |
dispatchUnless() | src/Dispatchable.php45-58 | public static function dispatchUnless(bool|Closure $boolean, mixed ...$arguments): Fluent|PendingDispatch |
dispatchSync() | src/Dispatchable.php65-70 | public static function dispatchSync(mixed ...$arguments): mixed |
dispatchAfterResponse() | src/Dispatchable.php75-78 | public static function dispatchAfterResponse(mixed ...$arguments): mixed |
withChain() | src/Dispatchable.php83-86 | public static function withChain(array $chain): PendingChain |
| Import | Purpose |
|---|---|
Closure | Type hint for conditional dispatch closures |
Hyperf\Context\ApplicationContext | Container access for dispatchSync() |
Hyperf\Support\Fluent | No-op return object for failed conditions |
Hypervel\Bus\Contracts\Dispatcher | Contract for dispatcher resolution |
function Hyperf\Support\value | Helper to evaluate values or closures |
Sources: src/Dispatchable.php1-87
Refresh this wiki