WebFiori Queue

Table of Contents

Supported PHP Versions

Features

Installation

composer require webfiori/queue

Usage

Define a Job

use WebFiori\Queue\Job;

class SendEmailJob implements Job {
    public function __construct(
        private string $to,
        private string $subject
    ) {}

    public function handle(): void {
        // Send the email
        mail($this->to, $this->subject, 'Hello!');
    }

    public function getMaxAttempts(): int {
        return 3;
    }

    public function getRetryDelaySeconds(): int {
        return 60; // wait 60s × attempt number before retry
    }
}

Dispatch and Process

use WebFiori\Queue\FileQueueStorage;
use WebFiori\Queue\Queue;

$queue = new Queue(new FileQueueStorage('/path/to/storage'));

// Dispatch jobs
$queue->dispatch(new SendEmailJob('[email protected]', 'Welcome!'));
$queue->dispatch(new SendEmailJob('[email protected]', 'Priority!'), priority: 10);
$queue->dispatch(new SendEmailJob('[email protected]', 'Delayed'), delaySeconds: 300);

// Process pending jobs (call this from a scheduler or worker)
$processed = $queue->process(limit: 50);

Static Facade

use WebFiori\Queue\QueueFacade;

QueueFacade::dispatch(new SendEmailJob('[email protected]', 'Hello'));
QueueFacade::process();

Failed Jobs

// View failed jobs (each is a QueuedJob)
$failed = $queue->getFailed();

// Retry a specific failed job
$queue->retry($failed[0]->getId());

// Clear all failed jobs
$queue->flush();

Observing Failures

$queue->setOnError(function (?Job $job, \Throwable $e, int $attempts, bool $willRetry): void {
    // $job is null if the stored payload was not a valid Job instance.
    error_log(sprintf(
        '[queue] %s failed on attempt %d (%s): %s',
        $job !== null ? get_class($job) : 'invalid-payload',
        $attempts,
        $willRetry ? 'will retry' : 'terminal',
        $e->getMessage()
    ));
});

Inspecting Pending Jobs

// List all pending jobs (including delayed ones not yet available)
$pending = $queue->getPending();

foreach ($pending as $queuedJob) {
    echo sprintf(
        "ID: %s | Priority: %d | Attempts: %d | Available: %s\n",
        $queuedJob->getId(),
        $queuedJob->getPriority(),
        $queuedJob->getAttempts(),
        date('Y-m-d H:i:s', $queuedJob->getAvailableAt())
    );
}

// Quick count (works with any storage backend)
$count = $queue->getPendingCount();

API

Job (interface)

Queue

QueueStorage (interface)

ListableQueueStorage (interface, extends QueueStorage)

QueueFacade

Testing

composer test

Examples

Contributing

License

Support

Changelog