Overview

Purpose and Scope

This document provides an overview of the hypervel/bus package, a command bus and job dispatching system for the Hyperf framework. It introduces the package's purpose, core capabilities, system architecture, and key components. For detailed information on specific features, refer to the specialized pages: Installation and Configuration, Core Concepts, Dispatching Jobs, Job Traits, Job Chaining, Batch Processing, and Advanced Features.

What is Hypervel Bus?

hypervel/bus is a command bus implementation that provides a unified interface for dispatching commands and jobs in Hyperf applications. A command bus decouples the request to perform an action from the actual execution, enabling:

• Deferred execution: Jobs can be queued for asynchronous processing
• Separation of concerns: Business logic is encapsulated in job classes
• Centralized dispatch logic: All job execution flows through a single dispatcher
• Flexible routing: Jobs can execute immediately (synchronous) or via queue workers (asynchronous)

The package serves as the foundation for job orchestration, providing the infrastructure to dispatch single jobs, chain multiple jobs together, or batch jobs for coordinated execution.

Sources: composer.json1-60 LICENSE.md1-23

Core Capabilities

Capability	Description	Key Components
Synchronous Dispatch	Execute jobs immediately in the current process	dispatch_sync(), Dispatcher::dispatchSync()
Asynchronous Dispatch	Queue jobs for background processing	dispatch(), QueueingDispatcher::dispatch()
Job Chaining	Execute jobs sequentially, with each job triggering the next	PendingChain, Queueable::withChain()
Batch Processing	Group jobs together with shared lifecycle callbacks and state tracking	PendingBatch, Batch, BatchRepository
Unique Jobs	Prevent duplicate job dispatch based on custom uniqueness criteria	ShouldBeUnique, UniqueLock
Flexible Configuration	Configure connection, queue, delay, and callbacks per dispatch	PendingDispatch, Queueable trait
Lifecycle Hooks	Register callbacks for before/after dispatch, batch progress, errors	Callback methods on pending objects

Sources: composer.json1-60

System Architecture

The package is organized into four primary architectural layers:

Diagram: Package Architecture and Component Relationships

Layer Responsibilities

1. Public API Layer: Entry points for developers, including global helper functions dispatch() and dispatch_sync() from src/Functions.php and reusable traits that add dispatch capabilities to job classes.

2. Job Configuration Layer: "Pending" objects (PendingDispatch, PendingChain, PendingBatch) that accumulate configuration before dispatch. These provide fluent interfaces for setting queue names, delays, callbacks, and other options.

3. Core Dispatching Engine: The Dispatcher class implements dispatch logic, routing jobs to either synchronous execution or the queue system. UniqueLock enforces job uniqueness constraints. ConfigProvider registers all services with Hyperf's dependency injection container.

4. Batch Processing System: Specialized components for managing batched job execution, including state tracking, persistence via BatchRepository, and lifecycle callbacks.

Sources: composer.json37-43

Package Structure

The codebase maps to functional areas as follows:

Diagram: Package File Structure and Component Organization

Key Directories

Directory	Purpose	Key Files
src/ (root)	Global functions and core dispatcher	Functions.php, Dispatcher.php, ConfigProvider.php
src/Contracts/	Interfaces defining core abstractions	Dispatcher.php, QueueingDispatcher.php, BatchRepository.php
src/Traits/	Mixins providing reusable job capabilities	Dispatchable.php, Queueable.php, Batchable.php
src/ (pending classes)	Configuration wrappers for fluent API	PendingDispatch.php, PendingChain.php, PendingBatch.php
src/ (batch classes)	Batch execution and storage	Batch.php, ChainedBatch.php, DatabaseBatchRepository.php
src/Factories/	Factory classes for DI instantiation	DispatcherFactory.php, DatabaseBatchRepositoryFactory.php
src/Events/	Event classes for lifecycle notifications	BatchDispatched.php

Sources: composer.json37-43

Integration with Hypervel Ecosystem

hypervel/bus is part of the Hypervel framework ecosystem and integrates tightly with complementary packages:

Diagram: Package Dependencies and Integration Points

Required Dependencies

• PHP 8.2+: Minimum language version requirement
• Hyperf 3.1.0: Framework foundation providing DI container, coroutine management, and core contracts
• hypervel/support: Shared utility functions and base classes
• hypervel/cache: Required for UniqueLock to prevent duplicate job dispatch

Optional Dependencies

• hypervel/queue: Suggested for asynchronous job dispatch and required when using closures in job chains (see composer.json53-55)

Integration Points

The package integrates with external systems through:

1. Dependency Injection: ConfigProvider registers bindings with Hyperf's DI container
2. Queue System: Dispatcher pushes jobs to queues via QueueFactory
3. Cache System: UniqueLock stores locks via CacheFactory
4. Database: DatabaseBatchRepository persists batch state to database tables

Sources: composer.json23-35 composer.json53-55

Key Components and Code Entities

The following table maps conceptual components to concrete code entities:

Concept	Primary Class/File	Contract/Interface	Purpose
Job Dispatch	Dispatcher	Contracts\Dispatcher	Routes jobs to sync or async execution
Queue Dispatch	Dispatcher	Contracts\QueueingDispatcher	Adds batch and queue-specific methods
Configuration Wrapper	PendingDispatch	N/A	Fluent API for configuring single job dispatch
Chain Configuration	PendingChain	N/A	Configures sequential job execution
Batch Configuration	PendingBatch	N/A	Configures grouped job execution
Batch Execution	Batch	N/A	Manages batch state and job coordination
Batch Storage	DatabaseBatchRepository	Contracts\BatchRepository	Persists batch data to database
Uniqueness Lock	UniqueLock	N/A	Prevents duplicate job dispatch
DI Registration	ConfigProvider	N/A	Registers services with Hyperf container
Static Dispatch	Traits\Dispatchable	N/A	Adds static dispatch() method to jobs
Queue Config	Traits\Queueable	N/A	Adds queue properties to jobs
Batch Association	Traits\Batchable	N/A	Links jobs to parent batches
Global Helpers	Functions.php	N/A	Provides dispatch() and dispatch_sync()

Sources: composer.json37-43

Dispatch Flow Overview

The typical dispatch flow follows this pattern:

Diagram: Standard Job Dispatch Sequence

1. Developer calls dispatch() helper with a job instance
2. PendingDispatch wraps the job and collects configuration via fluent methods
3. When PendingDispatch destructs, it triggers Dispatcher::dispatch()
4. If job implements ShouldBeUnique, UniqueLock checks for duplicates
5. If job implements ShouldQueue, it's pushed to the queue; otherwise executed immediately

Sources: composer.json41-43

Getting Started

To begin using hypervel/bus:

1. Install the package: See Installation and Configuration
2. Understand core concepts: Review Core Concepts for foundational knowledge
3. Create and dispatch jobs: Follow Dispatching Jobs to learn dispatch patterns
4. Add job capabilities: Use Job Traits to enable queuing, batching, and more
5. Implement advanced features: Explore Job Chaining, Batch Processing, and Advanced Features

Sources: README.md1-3