Dispatch Functions

Purpose and Scope

This document covers the two global helper functions that serve as the primary entry points for dispatching jobs in the hypervel/bus package: dispatch() and dispatch_sync(). These functions provide a simple, convenient API for triggering job execution.

For information about configuring job dispatch options (queue, delay, callbacks), see Configuring Job Dispatch. For alternative dispatch methods provided as static methods on job classes, see Dispatchable Trait. For understanding the underlying Dispatcher contract, see Core Concepts.

Sources: src/Functions.php1-36

---

Overview

The package provides two global helper functions defined in the Hypervel\Bus namespace:

Function	Purpose	Execution Mode	Return Type
dispatch()	Prepare job for dispatch with configuration	Deferred (via __destruct)	PendingDispatch or PendingClosureDispatch
dispatch_sync()	Execute job immediately in current process	Synchronous	mixed (handler result)

Both functions accept jobs (command objects) or closures, but handle them differently depending on the function and input type.

Sources: src/Functions.php12-35

---

The dispatch() Function

Function Signature

The dispatch() function wraps a job or closure in a "pending" configuration object that allows you to set dispatch options before the job is actually dispatched. The actual dispatch occurs when the pending object is destroyed (via __destruct).

Sources: src/Functions.php12-23

Return Type Branching

The function uses conditional return types based on the input:

Dispatch Function Return Type Decision Flow

Sources: src/Functions.php18-23

Closure Handling

When dispatching a closure, the function:

1. Wraps the closure in a CallQueuedClosure object using CallQueuedClosure::create($job)
2. Returns a PendingClosureDispatch instance containing the wrapped closure

The CallQueuedClosure class (from hypervel/queue) makes closures serializable so they can be queued and executed asynchronously.

Sources: src/Functions.php20-21

Job Object Handling

When dispatching a job object (any object that is not a closure):

1. Wraps the job directly in a PendingDispatch instance
2. Returns the PendingDispatch object

Sources: src/Functions.php20-22

Configuration and Execution

The returned pending object allows method chaining to configure dispatch options:

The actual dispatch to the queue or handler occurs when the PendingDispatch or PendingClosureDispatch object is destroyed (end of scope), triggering its __destruct() method. See Configuring Job Dispatch for complete configuration options.

Sources: src/Functions.php18-23

---

The dispatch_sync() Function

Function Signature

The dispatch_sync() function provides synchronous, immediate execution of jobs without involving the queue system.

Sources: src/Functions.php25-35

Synchronous Execution Flow

Synchronous Dispatch Execution Flow

Sources: src/Functions.php30-35

Implementation Details

The function:

1. Retrieves the Dispatcher instance from Hyperf's dependency injection container using ApplicationContext::getContainer()->get(Dispatcher::class)
2. Delegates to the dispatcher's dispatchSync() method
3. Returns the result from the job handler

Unlike dispatch(), this function:

• Does not return a pending configuration object
• Executes immediately in the current process
• Returns the actual result from the job handler
• Bypasses the queue system entirely

Sources: src/Functions.php30-35

Queue Behavior Note

According to the function's documentation comment, "Queueable jobs will be dispatched to the 'sync' queue." This means that even if a job implements ShouldQueue, calling dispatch_sync() forces synchronous execution rather than queuing.

Sources: src/Functions.php28-29

Parameters

Parameter	Type	Required	Description
$job	mixed	Yes	The job object or closure to execute
$handler	mixed	No	Optional handler override (defaults to null)

The optional $handler parameter allows you to specify a custom handler for the job, overriding the default handler resolution mechanism.

Sources: src/Functions.php30

---

Dispatch Mechanism Comparison

Architectural Diagram: Entry Points to Core Dispatcher

Global Functions to Core Dispatcher Architecture

Sources: src/Functions.php18-35

Functional Comparison Table

Aspect	dispatch()	dispatch_sync()
Execution timing	Deferred (on object destruction)	Immediate
Return value	Configuration object (Pending*Dispatch)	Handler result (mixed)
Configuration	Yes (queue, delay, callbacks, etc.)	No (direct execution)
Queue usage	Yes (for async jobs)	No (forced sync)
Method chaining	Yes	No
DI container access	Internal (via pending object)	Explicit (ApplicationContext)
Closure handling	Wrapped in CallQueuedClosure	Passed directly
Handler override	Not supported	Supported (2nd parameter)

Sources: src/Functions.php18-35

---

Usage Patterns

Basic Dispatch (Asynchronous)

Closure Dispatch (Asynchronous)

Synchronous Dispatch

Sources: src/Functions.php18-35

---

Code Entity Reference

Functions

• dispatch() - src/Functions.php18-23
• dispatch_sync() - src/Functions.php30-35

Classes Referenced

• PendingDispatch - Wraps job objects for configuration
• PendingClosureDispatch - Wraps closures for configuration
• CallQueuedClosure - Makes closures serializable (from hypervel/queue)
• Dispatcher (contract) - Core dispatcher interface
• ApplicationContext - Hyperf DI container accessor (from hyperf/context)

Related Namespaces

• Hypervel\Bus - Package namespace containing these functions
• Hyperf\Context - Hyperf framework context management
• Hypervel\Queue - Queue package providing CallQueuedClosure

Sources: src/Functions.php1-36