README

A lightweight PHP task queue built on top of PDO.
Supports scheduled execution, retries, task expiration, indexed task types, automatic deletion of completed tasks, and optional process-level locking via LockGuard.

📦 Installation

composer require solophp/task-queue

📋 Requirements

• PHP: >= 8.2
• Extensions:
  • ext-json - for JSON payload handling
  • ext-pdo - for database operations
  • ext-posix - for LockGuard process locking (optional)

This package uses standard PHP extensions and has minimal external dependencies. No external database libraries required - works with any PDO-compatible database (MySQL, PostgreSQL, SQLite, etc.).

⚙️ Setup

use Solo\TaskQueue\TaskQueue;

$pdo = new PDO('mysql:host=localhost;dbname=test', 'username', 'password');
$queue = new TaskQueue($pdo, table: 'tasks', maxRetries: 5, deleteOnSuccess: true);
$queue->install(); // creates the tasks table if not exists

🚀 Usage

Add a task:

$taskId = $queue->addTask(
    'email_notification',
    ['type' => 'email_notification', 'user_id' => 123, 'template' => 'welcome'],
    new DateTimeImmutable('tomorrow') // optional, defaults to now
);

Process all tasks:

$queue->processPendingTasks(function (string $name, array $payload) {
    match ($name) {
        'email_notification' => sendEmail($payload),
        'push_notification' => sendPush($payload),
        default => throw new RuntimeException("Unknown task: $name")
    };
});

Process only specific type:

$queue->processPendingTasks(function (string $name, array $payload) {
    sendEmail($payload);
}, 20, 'email_notification'); // only tasks where payload_type column = 'email_notification'

🔒 Using LockGuard (optional)

use Solo\TaskQueue\LockGuard;

$lockFile = __DIR__ . '/storage/locks/my_worker.lock';
$lock = new LockGuard($lockFile); // path to lock file

if (!$lock->acquire()) {
    exit(0); // Another worker is already running
}

try {
    $queue->processPendingTasks(...);
} finally {
    $lock->release(); // Optional, auto-released on shutdown
}

🧰 Features

• Task Retries – Configurable max retry attempts before marking as failed
• Task Expiration – Automatic expiration via expires_at timestamp
• Indexed Task Types – Fast filtering by payload_type
• Row-Level Locking – Prevents concurrent execution of the same task
• Transactional Safety – All task operations are executed within a transaction
• Optional Process Locking – Prevent overlapping workers using LockGuard
• Optional Deletion on Success – Set deleteOnSuccess: true to automatically delete tasks after success

🔗 Integration with Event-Dispatcher

TaskQueue implements TaskQueueInterface and can be used as an async queue backend for SoloPHP Event-Dispatcher. The Event-Dispatcher library should contain a TaskQueueAdapter in its adapter collection that implements the integration.

For async event processing setup, refer to the Event-Dispatcher documentation.

🧪 API Methods

🧪 Testing

# Run tests
composer test

# Run code sniffer
composer cs

# Fix code style issues
composer cs-fix

📄 License

This project is open-sourced under the MIT license.