Events and Extension Points

This page documents the comprehensive event system and extension mechanisms provided by the Hypervel Queue system. The event system dispatches events at every stage of the job lifecycle, enabling observability and custom behavior injection.

---

Overview

The queue system dispatches 11 distinct event types throughout the job lifecycle, from job popping through processing to completion or failure. These events serve two primary purposes:

1. Observability: Monitor queue operations, track job execution, collect metrics, and log job activity
2. Extension: React to queue operations by registering event listeners that perform side effects or modify behavior

The event system follows the PSR-14 event dispatcher specification and integrates with Hyperf's EventDispatcherInterface. All events are dispatched through the DI container's event dispatcher instance.

Extension Points:

In addition to events, the system provides callback-based extension points:

• Job retrieval customization via Worker::popUsing() for custom job popping logic
• QueueManager helper methods for simplified event listener registration

Sources: src/Worker.php1-852 src/QueueManager.php72-124 src/Console/WorkCommand.php158-187

---

Event Lifecycle

The queue system dispatches events at 11 distinct points throughout the job lifecycle. The following diagram shows the complete event flow:

Diagram: Event Dispatch Timeline

Sources: src/Worker.php432-542 src/Worker.php649-697 src/Worker.php752-756

---

Event Reference

Job Retrieval Events

JobPopping

Event Class: Hypervel\Queue\Events\JobPopping

Dispatched immediately before the worker attempts to retrieve a job from the queue.

Properties:

Dispatch Location: src/Worker.php649-652

Use Cases:

• Pre-fetch logging
• Connection health checks before job retrieval
• Metrics collection on pop frequency

---

JobPopped

Event Class: Hypervel\Queue\Events\JobPopped

Dispatched after a job has been successfully retrieved from the queue (or after no job was available).

Properties:

Dispatch Location: src/Worker.php657-663

Use Cases:

• Post-fetch logging
• Job availability metrics
• Queue depth monitoring

Sources: src/Worker.php649-663

---

Job Execution Events

JobProcessing

Event Class: Hypervel\Queue\Events\JobProcessing

Dispatched immediately before the worker begins processing a job.

Properties:

Dispatch Location: src/Worker.php668-673

Use Cases:

• Pre-execution logging with job details
• Starting timing measurements
• Incrementing "processing" counters

Registration Helper:

Sources: src/Worker.php668-673 src/QueueManager.php75-79 src/Console/WorkCommand.php168-170

---

JobProcessed

Event Class: Hypervel\Queue\Events\JobProcessed

Dispatched after a job has been successfully processed without exceptions.

Properties:

Dispatch Location: src/Worker.php679-684

Use Cases:

• Post-execution success logging
• Recording job completion time
• Incrementing success counters
• Triggering dependent workflows

Registration Helper:

Sources: src/Worker.php679-684 src/QueueManager.php84-88 src/Console/WorkCommand.php172-174

---

JobAttempted

Event Class: Hypervel\Queue\Events\JobAttempted

Dispatched after every job attempt, regardless of whether it succeeded or failed. This event is always dispatched in the finally block of job processing.

Properties:

Dispatch Location: src/Worker.php476-480

Use Cases:

• Comprehensive attempt tracking
• Recording all execution attempts for metrics
• Calculating success rates

Sources: src/Worker.php476-480

---

Exception Events

JobExceptionOccurred

Event Class: Hypervel\Queue\Events\JobExceptionOccurred

Dispatched when an exception is thrown during job execution, before the job is released or failed.

Properties:

Dispatch Location: src/Worker.php690-696

Use Cases:

• Exception logging with full context
• Error tracking service integration (e.g., Sentry)
• Custom exception handling logic
• Alerting on specific exception types

Registration Helper:

Sources: src/Worker.php690-696 src/QueueManager.php93-97

---

JobReleasedAfterException

Event Class: Hypervel\Queue\Events\JobReleasedAfterException

Dispatched when a job is released back to the queue after an exception, indicating it will be retried later.

Properties:

Dispatch Location: src/Worker.php536-539

Use Cases:

• Tracking retry attempts
• Logging jobs being retried
• Monitoring backoff behavior

Sources: src/Worker.php536-539 src/Console/WorkCommand.php176-178

---

Failure Events

JobFailed

Event Class: Hypervel\Queue\Events\JobFailed

Dispatched when a job has permanently failed after exhausting all retry attempts or exceeding time limits.

Properties:

Dispatch Location: Called via Job::fail() method when job is marked as failed

Use Cases:

• Logging permanent failures
• Persisting to failed jobs table
• Alerting on job failures
• Triggering compensating transactions

Registration Helper:

Note: The WorkCommand automatically logs failed jobs to the FailedJobProvider when this event is dispatched src/Console/WorkCommand.php302-311

Sources: src/QueueManager.php111-115 src/Console/WorkCommand.php180-184 src/Console/WorkCommand.php302-311

---

JobTimedOut

Event Class: Hypervel\Queue\Events\JobTimedOut

Dispatched when a job exceeds its configured timeout duration during processing.

Properties:

Dispatch Location: src/Worker.php294-297

Use Cases:

• Tracking timeout occurrences
• Alerting on jobs that consistently timeout
• Adjusting timeout configurations based on metrics

Note: After this event is dispatched, the job is typically marked as failed with a TimeoutExceededException.

Sources: src/Worker.php294-297

---

Worker Events

Looping

Event Class: Hypervel\Queue\Events\Looping

Dispatched at the beginning of each iteration of the worker's daemon loop, before attempting to fetch the next job.

Properties:

Property Considerations:

The Looping event includes a shouldRun() method that can be used to control whether the worker should continue processing. If this method returns false, the worker pauses src/Worker.php311-316

Dispatch Location: src/Worker.php315

Use Cases:

• Implementing custom pause logic
• Injecting behavior between job processing cycles
• Periodic cleanup tasks
• Dynamic worker control

Registration Helper:

Sources: src/Worker.php311-316 src/QueueManager.php102-106

---

WorkerStopping

Event Class: Hypervel\Queue\Events\WorkerStopping

Dispatched when the worker is about to stop, providing an opportunity for cleanup operations.

Properties:

Dispatch Location: src/Worker.php754 src/Worker.php766

Use Cases:

• Graceful shutdown procedures
• Releasing resources
• Logging worker shutdown events
• Cleanup before process termination

Registration Helper:

Sources: src/Worker.php752-756 src/Worker.php764-778 src/QueueManager.php120-124

---

Event Listener Registration

Direct Registration via EventDispatcher

Event listeners can be registered directly through the PSR-14 EventDispatcherInterface:

Sources: src/Console/WorkCommand.php167-170

---

QueueManager Helper Methods

The QueueManager class provides convenience methods for registering listeners for common events:

Diagram: QueueManager Event Registration Methods

Helper Method Reference:

Method	Event	Location
before(callable)	JobProcessing	src/QueueManager.php75-79
after(callable)	JobProcessed	src/QueueManager.php84-88
exceptionOccurred(callable)	JobExceptionOccurred	src/QueueManager.php93-97
looping(callable)	Looping	src/QueueManager.php102-106
failing(callable)	JobFailed	src/QueueManager.php111-115
stopping(callable)	WorkerStopping	src/QueueManager.php120-124

Usage Example:

Sources: src/QueueManager.php72-124

---

WorkCommand Event Listeners

The WorkCommand class registers event listeners to provide console output during job processing. This demonstrates a complete implementation of event-driven monitoring:

Diagram: WorkCommand Event Registration Flow

Event Registration: src/Console/WorkCommand.php161-187

The WorkCommand demonstrates:

• Console output generation based on job events
• Failed job logging via FailedJobProviderInterface src/Console/WorkCommand.php302-311
• JSON output mode for structured logging
• Timing measurements across job execution

Sources: src/Console/WorkCommand.php161-187 src/Console/WorkCommand.php193-281 src/Console/WorkCommand.php302-311

---

Extension Points

Worker::popUsing()

The Worker::popUsing() static method allows customization of the job retrieval logic. This enables advanced use cases like:

• Custom queue prioritization
• Job filtering based on runtime conditions
• Integration with external scheduling systems
• A/B testing different queue strategies

Method Signature:

Parameters:

Parameter	Type	Description
$workerName	string	The name of the worker to customize
$callback	?callable	The callback to use for popping jobs, or null to remove customization

Callback Signature:

The callback receives two parameters:

• $popJobCallback: The default pop callback: fn($queue, $index) => $connection->pop($queue, $index)
• $queue: The comma-separated queue names to process

Implementation Location: src/Worker.php828-835

Usage in Worker: src/Worker.php378-383

Usage Example:

Remove Custom Logic:

Sources: src/Worker.php828-835 src/Worker.php370-401

---

Event Summary Table

The following table provides a quick reference for all queue events:

Event	Dispatched When	Key Properties	Helper Method
JobPopping	Before job retrieval	$connectionName	-
JobPopped	After job retrieval	$connectionName, $job	-
JobProcessing	Before job execution	$connectionName, $job	before()
JobProcessed	After successful execution	$connectionName, $job	after()
JobAttempted	After each attempt	$connectionName, $job, $exceptionOccurred	-
JobExceptionOccurred	When exception thrown	$connectionName, $job, $exception	exceptionOccurred()
JobReleasedAfterException	When job released for retry	$connectionName, $job	-
JobFailed	When job permanently fails	$connectionName, $job, $exception	failing()
JobTimedOut	When job exceeds timeout	$connectionName, $job	-
Looping	At start of each daemon loop	$connectionName, $queue	looping()
WorkerStopping	When worker is stopping	$status, $options	stopping()

Sources: src/Worker.php1-852 src/QueueManager.php72-124

---

Common Event Patterns

Logging All Job Activity

Metrics Collection

Error Tracking Integration

Sources: src/QueueManager.php72-124 src/Console/WorkCommand.php161-187

---

Summary

The queue system's contract and trait architecture provides:

1. Clear Extension Points: Queue and Job contracts define driver requirements
2. Reusable Functionality: Traits provide composable behaviors for job classes
3. Type Safety: Interface-based programming ensures polymorphism
4. Testing Support: Traits include assertion methods for testing job behavior
5. Flexibility: Composition over inheritance allows mixing capabilities as needed

Custom implementations should implement the relevant contracts while leveraging existing traits where appropriate to maintain consistency with the rest of the system.

Sources: src/Contracts/Job.php1-116 src/Contracts/Queue.php1-62 src/InteractsWithQueue.php1-211 src/CallQueuedClosure.php1-96 src/QueuePoolProxy.php1-94 src/Exceptions/EntityNotFoundException.php1-21