A dead-letter queue stores jobs that exceeded safe retry limits for investigation or replay.
What It Does and When to Use It
Route exhausted jobs to a dead-letter destination rather than retrying indefinitely. A producer publishes work, a consumer executes it, and the broker or scheduler controls delivery and retries.
Requirements, Inputs and Expected Behavior
Confirm the runtime, extension, environment variables, and permissions before running the examples in production. Include attempt count, last error class and correlation IDs without storing credentials.
Example 1: Basic Operation
Route exhausted jobs to a dead-letter destination rather than retrying indefinitely.
<?php
$delivery=['id'=>'email:92','attempt'=>4,'payload'=>['template'=>'welcome']];
$maxAttempts=4;
$destination=$delivery['attempt'] >= $maxAttempts?'emails.dead':'emails.retry';
echo $destination;Example 2: Behavior and Validation
Store safe diagnostics but never copy credentials or arbitrary request payloads into a dead-letter record.
<?php
$failed=['job_id'=>'email:92','attempts'=>4,'error_class'=>'TimeoutException','failed_at'=>gmdate(DATE_ATOM)];
$record=json_encode($failed,JSON_THROW_ON_ERROR);
echo $record;Practical Example: Application Use
Replay requires operator review, resetting retry state and preventing duplicate side effects.
<?php
$job=['id'=>'email:92','attempts'=>4];
$shouldReplay=($job['attempts']>0 && $job['attempts']<10);
if ($shouldReplay) { $job['attempts']=0; echo 'Replay approved'; }Important Behavior and Edge Cases
The second example highlights: Store safe diagnostics but never copy credentials or arbitrary request payloads into a dead-letter record. The practical example adds: Replay requires operator review, resetting retry state and preventing duplicate side effects.
Comparison with Related Approaches
| Approach | What changes |
|---|---|
| Producer, consumer and scheduler | A producer publishes work, a consumer executes it, and the broker or scheduler controls delivery and retries. |
| Choosing safely | Acknowledge completed work and use idempotency to make retries safe. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Acknowledging a job before it finishes | Mark delivery successful only after durable processing succeeds. |
| Treating retries as harmless | Use idempotency keys and a bounded retry policy with dead-letter handling. |
| Skipping operational constraints | Include attempt count, last error class and correlation IDs without storing credentials. |
Key Takeaways
- A dead-letter queue stores jobs that exceeded safe retry limits for investigation or replay.
- Replay requires operator review, resetting retry state and preventing duplicate side effects.
- Acknowledge completed work and use idempotency to make retries safe.