 |
VOOZH | about |
|
VOOZH | about |
The DispatchesJobs trait provides job dispatching capability to classes that are not themselves jobs. It is designed for use in application code such as controllers, services, event listeners, and command handlers that need to dispatch jobs to the queue system but do not need to be dispatchable themselves.
This trait should not be confused with the Dispatchable trait (see 5.1), which is used on job classes to make them dispatchable. The DispatchesJobs trait is used in classes that dispatch other jobs.
Sources: src/DispatchesJobs.php1-34
The DispatchesJobs trait is defined in src/DispatchesJobs.php and contains two methods that enable any class to dispatch jobs to the command bus. These methods serve as convenient facades for the underlying dispatcher system, handling both regular job objects and closures.
Sources: src/DispatchesJobs.php11-34
The DispatchesJobs trait is appropriate for classes that need to dispatch jobs but are not themselves dispatchable. Common use cases include:
| Class Type | Use Case | Example |
|---|---|---|
| Controllers | Dispatching jobs in response to HTTP requests | User registration triggering email job |
| Services | Business logic that delegates work to jobs | Order service dispatching payment processing |
| Event Listeners | Responding to domain events by dispatching jobs | User created event triggering welcome email |
| Command Handlers | CLI commands that need to queue work | Import command dispatching batch processing jobs |
| Middleware | Request/response processing that triggers background work | Logging middleware dispatching analytics jobs |
Sources: src/DispatchesJobs.php1-34
The dispatch() method wraps a job in a configuration object, enabling fluent configuration before actual dispatch.
Signature:
protected function dispatch(mixed $job): mixed
Parameters:
$job - Either a job object or a ClosureReturn Value:
PendingDispatch instance if $job is an objectPendingClosureDispatch instance if $job is a ClosureBehavior: src/DispatchesJobs.php16-21
The method checks if the provided job is a Closure. If so, it wraps it in a CallQueuedClosure (from hypervel/queue) and returns a PendingClosureDispatch. Otherwise, it returns a PendingDispatch wrapping the job object.
The returned pending object allows configuration via method chaining:
Sources: src/DispatchesJobs.php16-21
The dispatchSync() method immediately executes a job in the current process without queuing.
Signature:
public function dispatchSync(mixed $job): mixed
Parameters:
$job - The job object or closure to execute synchronouslyReturn Value:
Behavior: src/DispatchesJobs.php28-33
This method retrieves the Dispatcher from Hyperf's application container and calls its dispatchSync() method. Jobs dispatched this way execute immediately, bypassing the queue system entirely.
Note: As documented in the method's docblock src/DispatchesJobs.php24-26 queueable jobs (those implementing ShouldQueue) will be dispatched to the "sync" queue when using dispatchSync(), which still processes them synchronously but through the queue worker infrastructure.
Sources: src/DispatchesJobs.php28-33
Sources: src/DispatchesJobs.php16-21
Sources: src/DispatchesJobs.php28-33
| Feature | DispatchesJobs | Dispatchable | Global Functions |
|---|---|---|---|
| Used In | Controllers, services, non-job classes | Job classes themselves | Anywhere |
| Methods | dispatch(), dispatchSync() | Static dispatch(), dispatchSync(), dispatchIf(), etc. | dispatch(), dispatch_sync() |
| Method Visibility | protected and public | public static | Global functions |
| Returns | PendingDispatch or mixed | PendingDispatch or mixed | PendingDispatch or mixed |
| Primary Use Case | Adding dispatch capability to application classes | Making jobs self-dispatchable | Quick dispatching without trait |
| Closure Support | Yes (wraps in CallQueuedClosure) | No (jobs are classes) | Yes (wraps in CallQueuedClosure) |
Sources: src/DispatchesJobs.php1-34
Key Distinctions:
Dispatchable Trait (5.1)
Job::dispatch(), Job::dispatchSync()SendEmailJob::dispatch($user)DispatchesJobs Trait (current)
$this->dispatch($job), $this->dispatchSync($job)$this->dispatch(new SendEmailJob($user))Sources: src/DispatchesJobs.php1-34
The dispatchSync() method uses Hyperf's dependency injection container to resolve the Dispatcher instance:
This approach ensures that the correct dispatcher instance is used, respecting any custom bindings or configurations in the application's service container.
Sources: src/DispatchesJobs.php28-33
When a Closure is passed to dispatch(), it is wrapped in a CallQueuedClosure:
The CallQueuedClosure class (from hypervel/queue) serializes the closure and its bound variables so it can be queued and executed later. This is then wrapped in a PendingClosureDispatch for configuration.
Sources: src/DispatchesJobs.php16-21
The dispatch() method returns either PendingDispatch or PendingClosureDispatch, both of which support fluent configuration:
$this->dispatch($job)
->onConnection('redis')
->onQueue('high')
->delay(now()->addMinutes(5))
->afterResponse();
The actual dispatch occurs when the pending object is destructed (see 4.2 for details on the __destruct mechanism).
The dispatchSync() method returns whatever the job handler returns, making it suitable for jobs that produce results:
$result = $this->dispatchSync(new CalculateTotals($order));
// $result contains the job's return value
Sources: src/DispatchesJobs.php16-21 src/DispatchesJobs.php28-33
Sources: src/DispatchesJobs.php1-34
The DispatchesJobs trait acts as a bridge between application code and the core dispatching infrastructure. It provides a clean API surface that hides the complexity of the underlying Dispatcher and queue system.
Sources: src/DispatchesJobs.php1-34
Note the different visibility modifiers on the two methods:
dispatch() - protected src/DispatchesJobs.php16dispatchSync() - public src/DispatchesJobs.php28The dispatch() method is protected to encourage its use only within the class that uses the trait, keeping dispatching logic encapsulated. The dispatchSync() method is public, allowing external callers to request synchronous execution when needed.
Sources: src/DispatchesJobs.php16 src/DispatchesJobs.php28
The DispatchesJobs trait is a simple but essential component that enables non-job classes to participate in the job dispatching system. Its two methods provide both asynchronous and synchronous dispatch capabilities, with special handling for closures and seamless integration with the PendingDispatch configuration system.
Key Takeaways:
DispatchesJobs in controllers, services, and other application classesDispatchable trait in job classes themselves (see 5.1)dispatch() returns a PendingDispatch for configurationdispatchSync() executes immediately and returns the job resultSources: src/DispatchesJobs.php1-34
Refresh this wiki