Listen Command

Purpose and Scope

The ListenCommand provides the queue:listen console command for starting queue workers with process spawning capabilities. Unlike the WorkCommand which runs a single worker process in daemon mode (see Work Command), the ListenCommand delegates to the Listener component which spawns child worker processes for job execution. This approach allows for process isolation and easier recovery from fatal errors.

This document covers the command's usage, options, execution flow, and integration with the Listener component. For details on the underlying process management and worker spawning, see Worker System.

Command Overview

The ListenCommand class src/Console/ListenCommand.php14-116 provides a console interface to the Listener component. The command signature is:

php bin/hyperf.php queue:listen [connection] [options]

Class Structure

Sources: src/Console/ListenCommand.php14-116

Command Options

The ListenCommand accepts the following options:

Option	Type	Default	Description
connection	Argument	config default	The name of the queue connection to use
--name	Option	default	The name of the worker process
--delay	Option	0	Deprecated - Use --backoff instead
--backoff	Option	0	Seconds to wait before retrying a job that encountered an uncaught exception
--force	Option	false	Force the worker to run even in maintenance mode
--memory	Option	128	Memory limit in megabytes for worker processes
--queue	Option	connection default	Comma-separated list of queues to listen on
--sleep	Option	3	Seconds to sleep when no job is available
--rest	Option	0	Seconds to rest between jobs
--timeout	Option	60	Maximum seconds a child process can run
--tries	Option	1	Number of times to attempt a job before logging it as failed

Sources: src/Console/ListenCommand.php21-32

Execution Flow

Command Initialization and Handling

Sources: src/Console/ListenCommand.php54-70

Queue Resolution

The command resolves which queue(s) to listen on through a hierarchical configuration lookup:

1. Connection Argument: If provided, use the specified connection; otherwise, use the default connection from queue.default src/Console/ListenCommand.php60-77
2. Queue Option: If --queue is provided, use that value src/Console/ListenCommand.php79
3. Connection Default: Otherwise, use the queue configured for the connection at queue.connections.{connection}.queue src/Console/ListenCommand.php79-82
4. Fallback: If no configuration exists, use 'default' src/Console/ListenCommand.php79-82

Sources: src/Console/ListenCommand.php54-83

Options Assembly

The gatherOptions() method src/Console/ListenCommand.php88-105 creates a ListenerOptions instance from the command options:

Backoff Handling

The command provides backward compatibility for the deprecated --delay option:

If --backoff is present, it takes precedence; otherwise, the value from --delay is used src/Console/ListenCommand.php90-92

Sources: src/Console/ListenCommand.php88-105

Listener Integration

Output Handling

The command sets up an output handler on the Listener instance to capture and display output from spawned worker processes:

The output handler is a closure that receives two parameters:

• $type: The output stream type (typically 'out' or 'err')
• $line: The line of output to display

This handler is registered during command construction src/Console/ListenCommand.php48-115 and allows the command to display real-time output from worker processes.

Sources: src/Console/ListenCommand.php42-115

Delegation to Listener

The command's primary responsibility is to gather options and delegate to the Listener component:

The Listener.listen() method handles:

• Process spawning and management
• Restarting failed processes
• Monitoring process health
• Forwarding output to the command's output handler

Sources: src/Console/ListenCommand.php65-69

Comparison with Work Command

Aspect	ListenCommand	WorkCommand
Process Model	Spawns child worker processes	Single process in daemon mode
Isolation	Each job runs in isolated process	Jobs share single process
Recovery	Automatic process restart on failure	Process exits on fatal errors
Memory	Fresh process per job batch	Accumulates memory in long runs
Performance	Higher overhead (process spawning)	Lower overhead (in-process)
Use Case	Development, unstable jobs	Production, stable jobs
Component	Uses Listener class	Uses Worker class directly
Options	Fewer options (no concurrency, etc.)	More options (concurrency, max-jobs, etc.)

The ListenCommand is generally recommended for:

• Development environments where quick restarts are beneficial
• Jobs prone to memory leaks that benefit from process isolation
• Applications with unstable dependencies where process restart can recover from errors

The WorkCommand is preferred for:

• Production environments where performance matters
• Stable applications with reliable job handling
• High-throughput scenarios requiring coroutine concurrency

Sources: src/Console/ListenCommand.php14-116

Usage Examples

Basic Usage

Listen on the default connection and queue:

Specify Connection

Listen on the Redis connection:

Multiple Queues

Process multiple queues with priority:

Resource Limits

Set memory and timeout limits:

Force Execution

Run worker even in maintenance mode:

Complete Configuration

Comprehensive example with all common options:

Sources: src/Console/ListenCommand.php21-32