Download the PHP package tudorr89/phpqdrv without Composer

phpqdrv

A small, dependency-light queue system for PHP with interchangeable backends.

Features

• Five drivers: Redis, MariaDB/MySQL, PostgreSQL, SQLite, Beanstalkd
• Nothing is silently lost: reserved jobs are recovered if a worker dies
• Real retries: failed jobs are released with exponential backoff, then parked in a dead letter store
• Atomic claims: no two workers can ever handle the same job (Lua scripts for Redis, SKIP LOCKED / guarded updates for SQL databases)
• Delayed jobs (push($queue, $payload, $delay))
• Optional dependencies: predis and Pheanstalk are suggest-ed; the package itself only needs ext-pdo + psr/log
• PSR-3 logging, graceful SIGTERM/SIGINT shutdown, static analysis clean at PHPStan level 8

Requirements

• PHP 8.1+
• ext-pdo and the matching PDO driver (pdo_sqlite, pdo_mysql, pdo_pgsql)
• ext-pcntl (optional, for graceful shutdown)

Installation

Then install the client for the backend you actually use:

Quick start

SQLite

Redis

PostgreSQL / MariaDB

Beanstalkd

Queue API

Job::getAttempts() reports the number of deliveries including the current one: a freshly pushed job reports 0, the first delivery reports 1.

Worker

work() is a daemon loop: it keeps polling forever (until maxJobs jobs were processed or stop() is called). For cron-style runs use processNext() in your own bounded loop.

Failure policy:

1. The processor throws \Throwable → job is logged and release()d with a backoff of 1s, 2s, 4s… (capped at 300s).
2. Once getAttempts() >= maxAttempts → fail() parks the job in the dead letter store.
3. Infrastructure errors (queue unreachable) are logged and retried; the worker never dies.

Graceful shutdown: SIGTERM/SIGINT (when ext-pcntl is available) finish the in-flight job, then the loop returns. Call $worker->stop() from your processor to stop after the current job.

Reliability model

A job handed to a worker is reserved, not deleted:

Each driver takes a visibilityTimeout (default 300s) in its constructor. Set it slightly above your slowest job. Workers sweep every 30 seconds automatically.

fail() writes to a dead letter store per backend: a failed status for SQL, a {prefix}:{queue}:failed list for Redis, a {queue}.failed tube for Beanstalkd.

Payloads

Payloads are arrays encoded as JSON with strict error handling:

• invalid UTF-8 or resources → InvalidPayloadException on push
• corrupt stored payloads → InvalidPayloadException on pop
• floats keep their zero fraction (3.0 stays 3.0)

Payloads are stored as opaque JSON text on every backend, so they round-trip exactly. (PostgreSQL's JSONB would normalise key order; subclass PostgreSQLQueue and override payloadSelectExpression()/payloadParameter() if you want that trade-off.)

Schema

Drivers create their table/index on construction (ensureSchema()), idempotently. For production, pass ensureSchema: false and apply the DDL yourself:

All timestamps are integer microseconds since the epoch. status is one of pending, processing, completed, failed.

The underlying PDO is switched to ERRMODE_EXCEPTION — a queue that fails silently is worse than one that throws.

Running the tests

Redis, MariaDB and PostgreSQL tests are skipped unless their DSN is provided:

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Add tests and run composer check
4. Open a Pull Request

License

MIT — see LICENSE.md.