Working with Drupal's Queue API

Queues move work out of interactive requests, but they do not remove responsibility for correctness. Jobs must survive retries, partial failures, and changing external systems.

Enqueue stable references

Queue items should contain identifiers and immutable context, not serialized service objects or entire entities. Load fresh state in the worker and decide whether the work is still necessary.

Make processing idempotent

Assume a job may execute more than once. Use external idempotency keys, state checks, or transactional writes so retries do not duplicate effects. Throwing an exception should leave enough context to diagnose the failure.

Operate the queue

Track backlog size, oldest-item age, throughput, failure counts, and external latency. Cron is adequate for modest work; larger systems may run dedicated workers with bounded execution.

Working example

#[QueueWorker(id: 'journal_reindex', title: new TranslatableMarkup('Reindex journal'), cron: ['time' => 30])]
final class JournalReindexWorker extends QueueWorkerBase {
  public function processItem($data): void {
    $this->indexer->indexArticle((int) $data['nid']);
  }
}

Key Takeaways

• Queue identifiers, not rich objects.
• Design every worker for retries.
• Monitor backlog age and failures.

Further Reading

• Drupal API documentation
• Drupal documentation