Skip to content

message-status.md

Latest commit

 

History

History
89 lines (58 loc) · 2.73 KB

message-status.md

File metadata and controls

89 lines (58 loc) · 2.73 KB

Message status

Yii Queue can report the status of a message by its ID.

The API surface is:

  • QueueInterface::status(string|int $id): MessageStatus
  • AdapterInterface::status(string|int $id): MessageStatus

Status tracking support depends on the adapter. If an adapter doesn't support status tracking or can't find the message by ID, it returns MessageStatus::NOT_FOUND.

Getting a message ID

QueueInterface::push() returns a MessageInterface. When the adapter supports IDs, the returned message is typically wrapped into an IdEnvelope, which stores the ID in message metadata.

To read the ID:

use Yiisoft\Queue\Message\IdEnvelope;

$pushedMessage = $queue->push($message);
$id = $pushedMessage->getMetadata()[IdEnvelope::MESSAGE_ID_KEY] ?? null;

If $id is null, the current adapter didn't provide an ID and you can't query a status.

The ID type (string or int) and how long it stays queryable are adapter-specific.

Statuses

Statuses are represented by the Yiisoft\Queue\MessageStatus enum:

  • MessageStatus::NOT_FOUND The message is not known to the queue, or the adapter doesn't support status tracking.

  • MessageStatus::WAITING The message is in the queue and has not been picked up yet.

  • MessageStatus::RESERVED A worker has taken the message and is handling it.

  • MessageStatus::DONE The message has been handled.

In addition to enum cases, MessageStatus provides a string key via MessageStatus::key():

$statusKey = $status->key(); // "not-found", "waiting", "reserved" or "done"

Querying a status

use Yiisoft\Queue\MessageStatus;
use Yiisoft\Queue\Message\IdEnvelope;

$pushedMessage = $queue->push($message);
$id = $pushedMessage->getMetadata()[IdEnvelope::MESSAGE_ID_KEY] ?? null;

if ($id === null) {
    throw new \RuntimeException('The adapter did not provide a message ID, status tracking is unavailable.');
}

$status = $queue->status($id);

if ($status === MessageStatus::WAITING) {
    // The message is waiting to be handled.
}

if ($status === MessageStatus::RESERVED) {
    // A worker is currently handling the message.
}

if ($status === MessageStatus::DONE) {
    // The message has been handled.
}

Edge cases

  • Unknown ID or unsupported tracking If an adapter doesn't support status tracking or can't find the message by ID, it returns MessageStatus::NOT_FOUND.

  • Timing RESERVED can be short-lived and difficult to observe: depending on the adapter, a message may move from WAITING to RESERVED and then to DONE quickly.

  • Failures / retries Failures and retries are handled by the worker and middleware pipelines, described in Errors and retryable messages. How failures affect the status is adapter-specific.