fyre/queue

A Queue library.

v3.2.1 2025-04-02 12:21 UTC

Requires

• fyre/command: ^6.0
• fyre/config: ^4.0
• fyre/container: ^1.0
• fyre/event: ^4.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/filesystem: ^2.0
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^12

MIT

• elusivecodes

README

FyreQueue is a free, open-source queue library for PHP.

Table Of Contents

• Installation
• Basic Usage
• Methods
• Queues
  • Redis
• Workers
• Messages
• Commands
  • Stats
  • Worker

Installation

Using Composer

composer require fyre/queue

In PHP:

use Fyre\Queue\QueueManager;

Basic Usage

• $container is a Container.
• $config is a Config.

$queueManager = new QueueManager($container, $config);

Default configuration options will be resolved from the "Queue" key in the Config.

Autoloading

It is recommended to bind the QueueManager to the Container as a singleton.

$container->singleton(QueueManager::class);

Any dependencies will be injected automatically when loading from the Container.

$queueManager = $container->use(QueueManager::class);

Methods

Build

Build a Queue.

• $options is an array containing configuration options.

$queue = $queueManager->build($options);

Queue dependencies will be resolved automatically from the Container.

Clear

Clear all instances and configs.

$queueManager->clear();

Get Config

Set a Queue config.

• $key is a string representing the Queue key.

$config = $queueManager->getConfig($key);

Alternatively, if the $key argument is omitted an array containing all configurations will be returned.

$config = $queueManager->getConfig();

Has Config

Determine whether a Queue config exists.

• $key is a string representing the Queue key, and will default to QueueManager::DEFAULT.

$hasConfig = $queueManager->hasConfig($key);

Is Loaded

Determine whether a Queue instance is loaded.

• $key is a string representing the Queue key, and will default to QueueManager::DEFAULT.

$isLoaded = $queueManager->isLoaded($key);

Push

Push a job to a Queue.

• $className is a string representing the job class.
• $arguments is an array containing arguments that will be passed to the job.
• $options is an array containing options for the Message.
  • config is a string representing the configuration key, and will default to QueueManager::DEFAULT.
  • queue is a string representing the queue name, and will default to QueueManager::DEFAULT.
  • method is a string representing the class method, and will default to "run".
  • delay is a number representing the number of seconds before the job should run, and will default to 0.
  • expires is a number representing the number of seconds after which the job will expire, and will default to 0.
  • retry is a boolean indicating whether the job should be retried if it fails, and will default to true.
  • maxRetries is a number indicating the maximum number of times the job should be retried, and will default to 5.
  • unique is a boolean indicating whether the job should be unique, and will default to false.

$queueManager->push($className, $arguments, $options);

Job dependencies will be resolved automatically from the Container.

Set Config

Set the Queue config.

• $key is a string representing the Queue key.
• $options is an array containing configuration options.

$queueManager->setConfig($key, $options);

Unload

Unload a Queue.

• $key is a string representing the Queue key, and will default to QueueManager::DEFAULT.

$queueManager->unload($key);

Use

Load a shared Queue instance.

• $key is a string representing the Queue key, and will default to "default".

$queue = $queueManager->use($key);

Queue dependencies will be resolved automatically from the Container.

Queues

You can load a specific queue by specifying the className option of the $options variable above.

Custom queues can be created by extending \Fyre\Queue\Queue, ensuring all below methods are implemented.

Clear

Clear all items from the queue.

• $queueName is a string representing the queue name, and will default to QueueManager::DEFAULT.

$queue->clear($queueName);

Complete

Mark a job as completed.

• $message is a Message.

$queue->complete($message);

Fail

Mark a job as failed.

• $message is a Message.

$queue->fail($message);

Pop

Pop the last item off the queue.

• $queueName is a string representing the queue name.

$message = $queue->pop($queueName);

Push

Push a job onto the queue.

• $message is a Message.

$queue->push($message);

Queues

Get all the active queues.

$queues = $queue->queues();

Reset

Reset the queue statistics.

• $queueName is a string representing the queue name, and will default to QueueManager::DEFAULT.

$queue->reset($queueName);

Stats

Get the statistics for a queue.

• $queueName is a string representing the queue name, and will default to QueueManager::DEFAULT.

$stats = $queue->stats($queueName);

Redis

The Redis queue can be loaded using custom configuration.

• $options is an array containing configuration options.
  • className must be set to \Fyre\Queue\Handlers\RedisQueue.
  • host is a string representing the Redis host, and will default to "127.0.0.1".
  • password is a string representing the Redis password
  • port is a number indicating the Redis port, and will default to 6379.
  • database is a string representing the Redis database.
  • timeout is a number indicating the connection timeout.
  • persist is a boolean indicating whether to use a persistent connection, and will default to true.
  • tls is a boolean indicating whether to use a tls connection, and will default to true.
  • ssl is an array containing SSL options.
    • key is a string representing the path to the key file.
    • cert is a string representing the path to the certificate file.
    • ca is a string representing the path to the certificate authority file.

$container->use(Config::class)->set('Queue.redis', $options);

Workers

Workers are long running tasks that will consume and execute jobs from the queue.

use Fyre\Queue\Worker;

• $container is a Container.
• $queueManager is a QueueManager.
• $eventManager is an EventManager.
• $options is an array containing configuration options.
  • config is a string representing the configuration key, and will default to QueueManager::DEFAULT.
  • queue is a string representing the queue name, and will default to QueueManager::DEFAULT.
  • maxJobs is a number representing the maximum number of jobs to execute, and will default to 0.
  • maxRuntime is a number representing the maximum number of seconds the worker should run, and will default to 0.
  • rest is a number representing the number of microseconds to rest after processing a job, and will default to 10000.
  • sleep is a number representing the number of microseconds to sleep if no jobs are in the queue, and will default to 100000.

$worker = new Worker($container, $queueManager, $eventManager, $options);

Run

Run the worker.

$worker->run();

Messages

Messages are used internally to pass data between the Queue and Worker.

use Fyre\Queue\Message;

• $options is an array containing options for the message.
  • className is a string representing the job class.
  • arguments is an array containing arguments that will be passed to the job.
  • config is a string representing the configuration key, and will default to QueueManager::DEFAULT.
  • queue is a string representing the queue name, and will default to QueueManager::DEFAULT.
  • method is a string representing the class method, and will default to "run".
  • delay is a number representing the number of seconds before the job should run, and will default to 0.
  • expires is a number representing the number of seconds after which the job will expire, and will default to 0.
  • retry is a boolean indicating whether the job should be retried if it fails, and will default to true.
  • maxRetries is a number indicating the maximum number of times the job should be retried, and will default to 5.
  • unique is a boolean indicating whether the job should be unique, and will default to false.

$message = new Message($options);

Get After

Get the timestamp when the message can be sent.

$after = $message->getTimestamp();

Get Config

Get the message config.

$config = $message->getConfig();

Get Hash

Get the message hash.

$hash = $message->getHash();

Get Queue

Get the message queue.

$queueName = $message->getQueue();

Is Expired

Determine whether the message has expired.

$isExpired = $message->isExpired();

Is Ready

Determine whether the message is ready.

$isReady = $message->isReady();

Is Unique

Determine whether the message is unique.

$isUnique = $message->isUnique();

Is Valid

Determine whether the message is valid.

$isValid = $message->isValid();

Should Retry

Determine whether the message should be retried.

$shouldretry = $message->shouldRetry();

Commands

Stats

Display stats for the queue.

• --config is a the configuration key, and will default to QueueManager::DEFAULT.
• --queue is a the queue name, and will default to QueueManager::DEFAULT.

$commandRunner->run('queue:stats', ['--config', 'default', '--queue', 'default']);

Worker

Start a background queue worker.

• --config is a the configuration key, and will default to QueueManager::DEFAULT.
• --queue is a the queue name, and will default to QueueManager::DEFAULT.
• --max-jobs is the maximum number of jobs to execute, and will default to 0.
• --max-runtime is the maximum number of seconds the worker should run, and will default to 0.

$commandRunner->run('queue:worker', ['--config', 'default', '--queue', 'default', '--max-jobs', '99', '--max-runtime', '60']);