Advanced Features

This page provides an overview of advanced capabilities in the hypervel/bus package beyond basic job dispatching. It covers two primary advanced features: job uniqueness constraints that prevent duplicate job execution, and event system integration for monitoring batch lifecycle.

For detailed information about unique job implementation, see Unique Jobs. For event system details, see Events.

---

Job Uniqueness Overview

The package provides a mechanism to prevent duplicate jobs from being dispatched simultaneously. Jobs that implement the ShouldBeUnique interface are automatically checked for uniqueness before dispatch. The system uses a distributed locking mechanism via the cache layer to ensure only one instance of a unique job can be dispatched at a time.

Core Components

Component	Location	Purpose
ShouldBeUnique	Interface	Marker interface for unique jobs
UniqueLock	src/UniqueLock.php9	Manages lock acquisition and release
uniqueId()	Job method	Defines uniqueness scope
uniqueFor()	Job method	Defines lock duration (seconds)
uniqueVia()	Job method	Specifies cache driver to use

The uniqueness check occurs in the PendingDispatch object before the job reaches the dispatcher. If a lock cannot be acquired, the job is silently skipped.

Sources: src/UniqueLock.php1-58

---

Uniqueness Architecture

Diagram: Job Uniqueness Lock Flow

The UniqueLock class generates lock keys using the pattern laravel_unique_job:{className}:{uniqueId} as seen in src/UniqueLock.php56 The lock duration is determined by the job's uniqueFor() method, defaulting to 0 seconds if not specified src/UniqueLock.php24-26

Sources: src/UniqueLock.php1-58

---

Uniqueness Lock Sequence

Diagram: Unique Lock Acquisition Sequence

This sequence illustrates how UniqueLock::acquire() src/UniqueLock.php22-33 checks the job for the three uniqueness methods (uniqueId, uniqueFor, uniqueVia), generates a lock key src/UniqueLock.php50-57 and attempts to acquire a distributed lock. Jobs can customize the cache driver used for locking via uniqueVia() src/UniqueLock.php28-30

Sources: src/UniqueLock.php22-57

---

Lock Management Methods

The UniqueLock class provides two primary methods:

acquire()

public function acquire(mixed $job): bool

Attempts to acquire a lock for the given job src/UniqueLock.php22-33 Returns true if the lock was acquired, false otherwise. The method:

1. Retrieves the lock duration via uniqueFor() method or property src/UniqueLock.php24-26
2. Resolves the cache driver via uniqueVia() method or uses default factory src/UniqueLock.php28-30
3. Generates the lock key using getKey() src/UniqueLock.php32
4. Attempts to acquire the lock via cache->lock()->get()

release()

public function release(mixed $job): void

Forcefully releases the lock for a job src/UniqueLock.php38-45 This method:

1. Resolves the cache driver via uniqueVia() src/UniqueLock.php40-42
2. Forces release of the lock src/UniqueLock.php44

Sources: src/UniqueLock.php22-45

---

Event System Overview

The package emits events to allow applications to react to batch processing lifecycle stages. Currently, the primary event is BatchDispatched, which fires when a batch is initially dispatched to the queue system.

Event Architecture

Event Class	Location	Trigger Point	Payload
BatchDispatched	src/Events/BatchDispatched.php9	After batch stored and jobs dispatched	Batch object

The event system integrates with Hyperf's event dispatcher, allowing applications to register listeners for batch lifecycle monitoring, logging, or custom processing logic.

Sources: src/Events/BatchDispatched.php1-15

---

BatchDispatched Event Structure

Diagram: BatchDispatched Event Class Structure

The BatchDispatched event is a simple data object containing a single public property: the Batch instance that was dispatched src/Events/BatchDispatched.php11-13 This provides listeners with full access to batch metadata including ID, name, job counts, and configuration options.

Sources: src/Events/BatchDispatched.php1-15

---

Event Flow in Batch Lifecycle

Diagram: Event Dispatch Flow During Batch Creation

The BatchDispatched event fires after the batch has been stored in the repository and all jobs have been dispatched to the queue. This ensures listeners receive a fully initialized batch with accurate job counts and metadata.

Sources: src/Events/BatchDispatched.php1-15

---

Integration Points

UniqueLock Cache Integration

The UniqueLock class depends on CacheFactory from the hypervel/cache package src/UniqueLock.php7 The factory is injected via the constructor src/UniqueLock.php14-16 Jobs can override the default cache driver by implementing a uniqueVia() method that returns a specific cache instance src/UniqueLock.php28-30

Event System Integration

Events are fired through Hyperf's event dispatcher system. The BatchDispatched event is dispatched by PendingBatch after successful batch creation. Applications register listeners using Hyperf's standard event listener configuration.

Sources: src/UniqueLock.php1-58 src/Events/BatchDispatched.php1-15

---

Feature Interaction Matrix

Feature	Interacts With	Mechanism
Unique Jobs	PendingDispatch	Checked before dispatch
Unique Jobs	Cache Layer	Distributed locking
Unique Jobs	Job Chains	Each job checked individually
Unique Jobs	Batches	Each batch job checked individually
BatchDispatched Event	PendingBatch	Fired after batch stored
BatchDispatched Event	Event Listeners	Hyperf event system
BatchDispatched Event	Batch Callbacks	Independent; both can coexist

Both advanced features integrate seamlessly with the core dispatching system. Unique jobs work with single dispatch, chains, and batches. Events complement (but don't replace) batch callbacks, providing a different integration point for cross-cutting concerns like logging and monitoring.

Sources: src/UniqueLock.php1-58 src/Events/BatchDispatched.php1-15