PHPackages                             oeltimacreation/php-simplequeue - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. oeltimacreation/php-simplequeue

ActiveLibrary[Caching](/categories/caching)

oeltimacreation/php-simplequeue
===============================

A lightweight, framework-agnostic background job queue system for PHP with Redis and database drivers

v1.7.0(2w ago)2356MITPHPPHP ^8.2CI passing

Since Jan 7Pushed 2w agoCompare

[ Source](https://github.com/oeltimacreation/php-simplequeue)[ Packagist](https://packagist.org/packages/oeltimacreation/php-simplequeue)[ Docs](https://github.com/oeltimacreation/php-simplequeue)[ RSS](/packages/oeltimacreation-php-simplequeue/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (9)Dependencies (24)Versions (21)Used By (0)

OeltimaCreation PHP SimpleQueue
===============================

[](#oeltimacreation-php-simplequeue)

A small, framework-agnostic PHP queue for durable background jobs. Job data is stored in a database; Redis or database polling delivers work to workers.

It supports retries with backoff, delayed retries, scheduled first dispatch, progress reporting, lease-based job ownership, graceful shutdown, and bounded queue repair.

Requirements
------------

[](#requirements)

- PHP 8.2 or later
- PDO and a supported database for durable jobs
- Redis 7+ or Valkey 8+ with `predis/predis:^3` for Redis delivery (optional)

Install
-------

[](#install)

```
composer require oeltimacreation/php-simplequeue
composer require predis/predis # only when using the Redis driver
```

Create the `background_jobs` table using the schema for your database in [the database guide](docs/database.md).

Quick start
-----------

[](#quick-start)

The in-memory sample has no services to configure and is the fastest way to see the complete dispatch → process → inspect flow:

```
php examples/basic/in-memory.php
```

For a durable Redis setup, configure the environment variables shown in [the Redis example](examples/redis/README.md), then run the worker and dispatcher in separate terminals.

```
use Oeltima\SimpleQueue\Contract\JobHandlerInterface;
use Oeltima\SimpleQueue\Driver\InMemoryQueueDriver;
use Oeltima\SimpleQueue\JobDispatcher;
use Oeltima\SimpleQueue\JobRegistry;
use Oeltima\SimpleQueue\QueueManager;
use Oeltima\SimpleQueue\Storage\InMemoryJobStorage;
use Oeltima\SimpleQueue\Worker;

final class WelcomeEmail implements JobHandlerInterface
{
    public function handle(int $jobId, array $payload, ?callable $progress = null): mixed
    {
        if ($progress !== null) {
            $progress(100, 'Email sent');
        }

        return ['recipient' => $payload['email']];
    }
}

$storage = new InMemoryJobStorage();
$queues = new QueueManager(new InMemoryQueueDriver());
$registry = new JobRegistry();
$registry->register('email.welcome', WelcomeEmail::class);
$dispatcher = new JobDispatcher($storage, $queues);

$jobId = $dispatcher->dispatch('email.welcome', ['email' => 'ada@example.test']);
(new Worker($storage, $queues, $registry, queue: 'default', options: ['lock_file' => null]))->processOne();

echo $dispatcher->getStatus($jobId)?->status->value; // completed
```

Scheduled dispatch
------------------

[](#scheduled-dispatch)

Delay a job's first availability with `dispatchAfter()`, `dispatchAt()`, or the optional `$availableAt` parameter on `dispatch()` / `dispatchBatch()`:

```
$jobId = $dispatcher->dispatchAfter(300, 'email.welcome', ['email' => 'ada@example.test']);

$jobId = $dispatcher->dispatch(
    'email.welcome',
    ['email' => 'ada@example.test'],
    availableAt: strtotime('tomorrow 09:00'),
);
```

Past or present timestamps dispatch immediately; non-positive timestamps and negative delays are rejected. With Redis/In-Memory the notification is delayed and promoted when due; with database polling claims already gate on the stored `available_at`.

Documentation
-------------

[](#documentation)

- [Getting started](docs/getting-started.md) — durable setup and first worker
- [Configuration](docs/configuration.md) — drivers and worker options
- [Database guide](docs/database.md) — schemas, indexes, and idempotency
- [Operations](docs/operations.md) — deployment, repair, retention, monitoring
- [Architecture](docs/architecture.md) — delivery and ownership model
- [Extending](docs/extending.md) — custom handlers, storage, and drivers
- [Upgrading](docs/upgrading.md) — supported upgrade paths
- [Examples](examples/README.md) — runnable sample catalogue

Important delivery rule
-----------------------

[](#important-delivery-rule)

SimpleQueue provides **at-least-once delivery**. A job can run more than once if a worker completes a side effect and stops before its acknowledgement is stored. Make every handler idempotent: use transaction IDs, unique database constraints, or provider idempotency keys for external side effects.

`dispatchIdempotent()` prevents duplicate *active* jobs for one request ID. For cross-process safety with `PdoJobStorage`, keep the conditional/generated active-request-ID unique index from the database guide.

Development
-----------

[](#development)

```
composer check        # tests, PHPStan, and coding style
composer test
composer phpstan
composer cs-check
composer test-coverage
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution details, [SECURITY.md](SECURITY.md) for vulnerability reporting, and [LICENSE](LICENSE)for license terms.

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance97

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~22 days

Recently: every ~4 days

Total

10

Last Release

17d ago

PHP version history (2 changes)1.0.0PHP ^8.1

1.4.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/95e17b76fa658e837eab72c99699b56c6daa946b1910c58eed306ea3401e8a63?d=identicon)[nerdv2](/maintainers/nerdv2)

---

Top Contributors

[![nerdv2](https://avatars.githubusercontent.com/u/12403857?v=4)](https://github.com/nerdv2 "nerdv2 (169 commits)")

---

Tags

phpqueueasyncschedulerredisqueuejobtaskbackgroundworker

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/oeltimacreation-php-simplequeue/health.svg)

```
[![Health](https://phpackages.com/badges/oeltimacreation-php-simplequeue/health.svg)](https://phpackages.com/packages/oeltimacreation-php-simplequeue)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k87.4M2.2k](/packages/symfony-symfony)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k21](/packages/tempest-framework)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

568591.1k63](/packages/ecotone-ecotone)[wikimedia/parsoid

Parsoid, a bidirectional parser between wikitext and HTML5

200569.1k3](/packages/wikimedia-parsoid)[mjphaynes/php-resque

Redis backed library for creating background jobs and processing them later.

228202.1k3](/packages/mjphaynes-php-resque)[javibravo/simpleue

Php package to manage queue tasks in a simple way

130353.9k1](/packages/javibravo-simpleue)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)