CRM_Queue_BasicHandlerTrait
`CRM_Queue_BasicHandlerTrait` is a base-class that helps to execute queue-items.
It takes a batch of items and executes them 1-by-1. It enforces the
queue configuration options, such as retry_limit=>5 and error=>abort.
This class will have an incubation period circa Feb 2025 - Dec 2025. Unless otherwise noted, it should be considered stable at that point.
Table of Contents
Methods
- run() : string
- Run a specific item. Determine its status. Update the others.
- runBatch() : void
- Run a batch of items, one-by-one.
- getItemDetails() : array<string|int, mixed>
- Get detailed info about the item. This is used for debugging.
- getItemTitle() : string
- Get a nice title for the item.
- isRetriable() : bool
- runItem() : void
- Do a unit of work with one item from the queue.
- validateItem() : bool
- relinquishItems() : void
- If the batch of items encounters an 'abort', then any subsequent items (within the same batch) should be returned to the queue for future work.
Methods
run()
Run a specific item. Determine its status. Update the others.
public
final run(CRM_Queue_Queue $queue, mixed $item) : string
Parameters
- $queue : CRM_Queue_Queue
- $item : mixed
Tags
Return values
string —One of the following:
- 'ok': Task executed normally. Removed from queue.
- 'retry': Task encountered an error. Will try again later.
- 'delete': Task encountered an error. Will not try again later. Removed from queue.
- 'abort': Task encountered an error. Will not try again later. Stopped the queue.
runBatch()
Run a batch of items, one-by-one.
public
final runBatch(CRM_Queue_Queue $queue, array<string|int, mixed> $items, array<string|int, mixed> &$outcomes) : void
Parameters
- $queue : CRM_Queue_Queue
- $items : array<string|int, mixed>
- $outcomes : array<string|int, mixed>
Tags
getItemDetails()
Get detailed info about the item. This is used for debugging.
protected
getItemDetails(mixed $item) : array<string|int, mixed>
Parameters
- $item : mixed
Return values
array<string|int, mixed>getItemTitle()
Get a nice title for the item.
protected
getItemTitle(CRM_Queue_DAO_QueueItem $item) : string
Parameters
- $item : CRM_Queue_DAO_QueueItem
Return values
stringisRetriable()
protected
final isRetriable(CRM_Queue_Queue $queue, mixed $item) : bool
Parameters
- $queue : CRM_Queue_Queue
- $item : mixed
Return values
boolrunItem()
Do a unit of work with one item from the queue.
protected
abstract runItem(mixed $item, CRM_Queue_Queue $queue) : void
This should emit an exception if there is a problem handling the item. If runItem() encounters a fatal, then
Parameters
- $item : mixed
- $queue : CRM_Queue_Queue
validateItem()
protected
validateItem(mixed $item) : bool
Parameters
- $item : mixed
Return values
boolrelinquishItems()
If the batch of items encounters an 'abort', then any subsequent items (within the same batch) should be returned to the queue for future work.
private
relinquishItems(CRM_Queue_Queue|CRM_Queue_Queue_BatchQueueInterface $queue, array<string|int, mixed> $items) : void
Parameters
- $queue : CRM_Queue_Queue|CRM_Queue_Queue_BatchQueueInterface
- $items : array<string|int, mixed>
-
The items that were not attempted.