Worker Options and Configuration

This document describes the WorkerOptions class and all configurable parameters that control worker behavior during job processing. These options define resource limits, retry strategies, timing controls, and concurrency settings.

For information about the Worker class itself and the daemon processing loop, see Worker Class. For details on concurrency and resource management mechanisms, see Concurrency and Resource Management.

WorkerOptions Class

The WorkerOptions class (src/WorkerOptions.php) is a data transfer object that encapsulates all configuration parameters for worker operation. It is instantiated by the WorkCommand and passed to the Worker for job processing.

Sources: src/WorkerOptions.php src/Console/WorkCommand.php133-156

Configuration Parameters

The WorkerOptions class defines 13 public properties that control all aspects of worker behavior:

Parameter	Type	Default	Description
name	string	'default'	Worker identifier for logging and cache operations
backoff	array|int	0	Seconds to wait before retrying failed jobs
memory	int	128	Memory limit in megabytes
timeout	int	60	Maximum seconds a job can run
sleep	int	3	Seconds to sleep when no jobs available
maxTries	int	1	Maximum attempts before marking job as failed
force	bool	false	Run worker even in maintenance mode
stopWhenEmpty	bool	false	Exit when queue is empty
maxJobs	int	0	Maximum jobs to process before stopping (0 = unlimited)
maxTime	int	0	Maximum seconds worker should run (0 = unlimited)
rest	int	0	Seconds to rest between jobs
concurrency	int	1	Number of jobs to process concurrently
monitorInterval	int	1	Seconds between timeout monitoring checks

Sources: src/WorkerOptions.php25-39

Worker Identity

name (string): Identifies the worker instance for:

• Cache key prefixes when tracking job exceptions
• Custom job popping callbacks via Worker::popUsing()
• Event dispatching and logging

Set via the --name option in WorkCommand (src/Console/WorkCommand.php39).

Sources: src/WorkerOptions.php26 src/Worker.php819-823

Retry and Backoff Settings

backoff (array|int): Defines the delay in seconds before retrying a failed job. Supports two formats:

1. Single value (int): Fixed delay for all retry attempts
2. Array (int[]): Per-attempt delays (e.g., [1, 5, 10] = 1s first retry, 5s second, 10s thereafter)

The backoff is calculated in Worker::calculateBackoff():

maxTries (int): Maximum number of execution attempts before a job is marked as failed. The worker checks this in multiple places:

• Worker::markJobAsFailedIfAlreadyExceedsMaxAttempts() - Before processing
• Worker::markJobAsFailedIfWillExceedMaxAttempts() - After exception

Jobs can override this via Job::maxTries() method, which takes precedence over the worker option.

Sources: src/WorkerOptions.php27-31 src/Worker.php635-644 src/Worker.php553-570

Resource Limits

memory (int): Maximum memory in megabytes the worker process may consume. Checked via Worker::memoryExceeded():

When exceeded, the worker exits with status code Worker::EXIT_MEMORY_LIMIT (12).

timeout (int): Maximum seconds a single job may execute. The timeout monitoring system:

1. Registers each job with Worker::registerCoroutineJob() storing expires_at timestamp
2. Periodically scans via Worker::terminateTimeoutJobs()
3. Marks timed-out jobs as failed if they exceed retryUntil or maxTries

Jobs can override this via Job::timeout() method, checked in Worker::timeoutForJob().

Sources: src/WorkerOptions.php28-29 src/Worker.php744-747 src/Worker.php245-255 src/Worker.php303-306

Timing Controls

sleep (int): Seconds to pause when no jobs are available or when the queue is paused. Used in:

• Main daemon loop when getNextJob() returns null (src/Worker.php189-191)
• Pause worker situations (src/Worker.php323)
• After connection exceptions (src/Worker.php397)

rest (int): Seconds to pause between successfully processing jobs. Applied only when a job was processed (src/Worker.php187-188).

Sources: src/WorkerOptions.php30-36 src/Worker.php187-191

Concurrency Configuration

concurrency (int): Number of jobs to process simultaneously using coroutines. The WorkCommand gathers this from two sources with priority:

The Worker uses this to create a Concurrent instance (src/Worker.php146) which controls coroutine execution slots.

monitorInterval (int): Seconds between timeout monitoring checks. Used by Worker::monitorTimeoutJobs() to create a timer that periodically calls Worker::terminateTimeoutJobs() (src/Worker.php224).

Sources: src/WorkerOptions.php37-38 src/Console/WorkCommand.php135-139 src/Worker.php146

Control Flags

force (bool): When true, allows the worker to process jobs even when the application is in maintenance mode. Checked in Worker::daemonShouldRun() (src/Worker.php313).

stopWhenEmpty (bool): When true, the worker exits immediately when getNextJob() returns null. Checked in Worker::stopIfNecessary() (src/Worker.php337).

maxJobs (int): Maximum number of jobs to process before stopping. When non-zero and jobsProcessed >= maxJobs, worker exits with EXIT_SUCCESS. Checked in Worker::stopIfNecessary() (src/Worker.php339).

maxTime (int): Maximum seconds the worker should run. When non-zero and elapsed time exceeds this value, worker exits with EXIT_SUCCESS. Checked in Worker::stopIfNecessary() (src/Worker.php338).

Sources: src/WorkerOptions.php32-35 src/Worker.php331-341

Option Gathering in WorkCommand

The WorkCommand::gatherWorkerOptions() method creates the WorkerOptions instance from command-line arguments and configuration:

Note: The --delay option is deprecated and combined with --backoff using max() for backward compatibility (src/Console/WorkCommand.php143).

Sources: src/Console/WorkCommand.php133-156

Worker Option Usage in Processing

The following diagram maps each WorkerOptions property to where it is used in the Worker class:

Sources: src/Worker.php135-208 src/Worker.php311-316 src/Worker.php331-341

Backoff Strategy Details

The backoff calculation supports progressive retry delays to reduce load during failures:

Example configurations:

Backoff Value	Attempt 1	Attempt 2	Attempt 3	Attempt 4+
10	10s	10s	10s	10s
[5, 15, 30]	5s	15s	30s	30s
[1, 2, 4, 8, 16]	1s	2s	4s	8s, 16s, 16s...

Sources: src/Worker.php635-644

Configuration Examples

Basic Worker

Minimal configuration for simple queue processing:

Creates WorkerOptions with:

• name: "default"
• maxTries: 3
• All other defaults (128MB memory, 60s timeout, 3s sleep)

High-Throughput Worker

Configuration for processing many small jobs quickly:

Creates WorkerOptions with:

• concurrency: 50 (process 50 jobs simultaneously)
• timeout: 10 (short timeout for fast jobs)
• sleep: 1 (minimal sleep when idle)
• rest: 0 (no delay between jobs)
• memory: 512 (higher limit for concurrency)

Long-Running Worker

Configuration for resource-intensive jobs with progressive backoff:

Creates WorkerOptions with:

• timeout: 300 (5-minute job timeout)
• memory: 1024 (1GB memory limit)
• maxTries: 5
• backoff: [10, 30, 60, 120, 300] (progressive delays)
• maxJobs: 100 (restart after 100 jobs for memory cleanup)
• maxTime: 3600 (restart after 1 hour)

Batch Processing Worker

Configuration for processing until queue is empty:

The --once flag changes the execution mode (calls runNextJob() instead of daemon()), but still uses WorkerOptions with:

• stopWhenEmpty: true
• Processes single job then exits

Sources: src/Console/WorkCommand.php37-56 src/Console/WorkCommand.php123

Configuration Priority

When multiple sources define the same parameter:

Priority order:

1. Job-level methods (Job::maxTries(), Job::timeout(), Job::backoff()) - checked at runtime
2. Command-line options - set when creating WorkerOptions
3. Configuration file - only for concurrency_number
4. Defaults - defined in WorkerOptions constructor

Sources: src/Worker.php555 src/Worker.php305 src/Worker.php637-639