Failed Job Management Commands

This document covers the console commands for managing failed jobs in the hypervel/queue package. These commands provide administrative tools for retrying, listing, deleting, and pruning jobs that have exceeded their retry attempts or encountered fatal errors during processing.

Overview

The failed job management commands provide a comprehensive CLI interface for operating on jobs stored by the FailedJobProviderInterface. All commands are registered in the DI container and available via the Hyperf console.

Command Registration

Sources: src/ConfigProvider.php40-52

Available Commands

Command	Signature	Purpose
RetryCommand	queue:retry	Re-queue failed jobs back to the queue
ListFailedCommand	queue:failed	Display a table of all failed jobs
ForgetFailedCommand	queue:forget	Delete a single failed job by ID
FlushFailedCommand	queue:flush	Delete all or old failed jobs
PruneFailedJobsCommand	queue:prune-failed	Remove old failed job records

Sources: src/ConfigProvider.php40-52

Command Dependencies

All failed job commands depend on the FailedJobProviderInterface for accessing stored failed job records. The RetryCommand additionally depends on QueueFactory for re-queuing jobs and EventDispatcherInterface for dispatching retry events.

RetryCommand (queue:retry)

The RetryCommand re-queues failed jobs back to their original queue with reset attempt counters and updated timeout values. It supports flexible job selection via IDs, queue names, or numeric ranges.

Command Signature

Sources: src/Console/RetryCommand.php28-31

Dependencies

The RetryCommand constructor injects FailedJobProviderInterface for accessing failed job records. The command also uses QueueFactory, EventDispatcherInterface, and optionally Encrypter via the application container.

Dependency Injection

Sources: src/Console/RetryCommand.php41-45

Job Selection Strategies

The command supports four job selection methods via the getJobIds() method:

Selection Method	Syntax	Implementation
Specific IDs	queue:retry 123 456	$this->argument('id') returns array of IDs
All jobs	queue:retry all	Checks $ids[0] === 'all', calls $this->failer->ids()
Queue filter	queue:retry --queue=emails	Calls getJobIdsByQueue($queue) with filtered lookup
Numeric ranges	queue:retry --range=1-10,15-20	Regex /^[0-9]+\-[0-9]+$/ with range() expansion

Job Selection Logic

Sources: src/Console/RetryCommand.php78-98 src/Console/RetryCommand.php103-118 src/Console/RetryCommand.php123-134

Retry Execution Flow

For each selected job ID, the command executes a multi-step retry process:

Retry Process Sequence

Sources: src/Console/RetryCommand.php50-73

Payload Manipulation Methods

The retry process modifies the job payload in two ways before re-queuing:

1. resetAttempts()

Resets the attempt counter for jobs that store attempts in their payload (e.g., Redis jobs):

Sources: src/Console/RetryCommand.php152-161

2. refreshRetryUntil()

Updates the retryUntil timestamp by deserializing the job instance and calling its retryUntil() method:

Deserialization and Refresh Process

This handles both encrypted (ShouldBeEncrypted) and unencrypted job payloads, with proper error handling for incomplete classes.

Sources: src/Console/RetryCommand.php168-195

Usage Examples

Sources: src/Console/RetryCommand.php28-31

Forget Failed Command

The ForgetFailedCommand provides targeted deletion of individual failed jobs by ID.

Command Signature

queue:forget {id : The ID of the failed job}

Implementation

The command performs a simple operation: calls FailedJobProviderInterface::forget($id) and provides appropriate feedback based on the return value src/Console/ForgetFailedCommand.php30-36 Returns exit code 1 if the job ID is not found.

Sources: src/Console/ForgetFailedCommand.php18 src/Console/ForgetFailedCommand.php28-39

Flush Failed Command

The FlushFailedCommand handles bulk deletion of failed jobs with optional time-based filtering.

Command Signature

queue:flush {--hours= : The number of hours to retain failed job data}

Functionality

The command supports two modes:

1. Complete Flush: Removes all failed jobs when no --hours option is provided
2. Time-Based Flush: Removes only jobs that failed more than the specified number of hours ago

The implementation delegates to FailedJobProviderInterface::flush($hours) where the hours parameter controls the deletion scope src/Console/FlushFailedCommand.php30-31

Sources: src/Console/FlushFailedCommand.php18 src/Console/FlushFailedCommand.php28-40

Failed Job Command Workflow

Sources: src/Console/RetryCommand.php61-72 src/Console/ListFailedCommand.php51 src/Console/ForgetFailedCommand.php30 src/Console/FlushFailedCommand.php30-31