PHPackages                             michel/pqueue - 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. [Queues & Workers](/categories/queues)
4. /
5. michel/pqueue

ActiveLibrary[Queues & Workers](/categories/queues)

michel/pqueue
=============

PQueue is a minimalist PHP library for processing background messages using a single persistent CLI (managed via systemd) or periodic execution (via cron), covering 90% of use cases without external dependencies or complex worker management.

0.0.1-alpha(1mo ago)001MPL-2.0PHPPHP >=7.4

Since Jul 3Pushed 1mo agoCompare

[ Source](https://github.com/michelphp/pqueue)[ Packagist](https://packagist.org/packages/michel/pqueue)[ RSS](/packages/michel-pqueue/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (6)Versions (2)Used By (1)

PQueue - Simple PHP Queue Library
=================================

[](#pqueue---simple-php-queue-library)

PQueue is a lightweight, framework-agnostic library for handling background jobs and messages with persistent queues.

Features
--------

[](#features)

- **Multiple Transports**: Comes with `SQLite` and `Filesystem` transports.
- **DI-Friendly**: Designed to integrate cleanly with any PSR-11 dependency injection container.
- **Configurable Worker**: The queue worker can be configured with memory limits, time limits, retry strategies, and more.
- **Automatic Handler Discovery**: Scans specified directories to find your message handlers automatically.

Installation
------------

[](#installation)

```
composer require michel/pqueue
```

Basic Usage (Without a Framework)
---------------------------------

[](#basic-usage-without-a-framework)

This example shows how to use the library in a simple PHP script.

**1. Create a Message and a Handler**

```
// src/Messages/MyMessage.php
namespace App\Messages;
class MyMessage {
    public string $text;
    public function __construct(string $text) { $this->text = $text; }
}

// src/Handlers/MyMessageHandler.php
namespace App\Handlers;
use App\Messages\MyMessage;
class MyMessageHandler {
    public function __invoke(MyMessage $message) {
        echo "Processing message: " . $message->text . "\n";
    }
}
```

**2. Dispatch a Message**

```
// send_message.php
require 'vendor/autoload.php';

use Michel\PQueue\Transport\SQLiteTransport;
use Michel\PQueue\PQueueDispatcher;
use App\Messages\MyMessage;

// 1. Create a transport
$transport = SQLiteTransport::create(['db_path' => __DIR__ . '/pqueue.sqlite']);

// 2. Create a dispatcher
$dispatcher = new PQueueDispatcher($transport);

// 3. Dispatch your message
$dispatcher->dispatch(new MyMessage('Hello, World!'));

echo "Message dispatched!\n";
```

**3. Run the Worker**

The worker needs a `HandlerResolver` to get handler instances. For this simple example, we'll create a basic one.

```
// worker.php
require 'vendor/autoload.php';

use Michel\PQueue\PQueueConsumerFactory;
use Michel\PQueue\PQueueWorker;
use Michel\PQueue\HandlerResolver\HandlerResolverInterface;
use Michel\PQueue\Transport\SQLiteTransport;
use App\Handlers\MyMessageHandler; // Import the handler class

// 1. Create a simple handler resolver for the example
$handlerResolver = new class implements HandlerResolverInterface {
    private array $handlers = [];
    public function getHandler(string $className): object {
        if (!isset($this->handlers[$className])) {
            $this->handlers[$className] = new $className();
        }
        return $this->handlers[$className];
    }
    public function hasHandler(string $className): bool {
        return class_exists($className);
    }
};

// 2. Create the transport
$transport = SQLiteTransport::create(['db_path' => __DIR__ . '/pqueue.sqlite']);

// 3. Use the factory to build the consumer
$factory = new PQueueConsumerFactory(
    $handlerResolver,
    [
        MyMessageHandler::class,  // You can add handler classes directly
        __DIR__ . '/src/Handlers' // And also scan directories
    ],
    __DIR__ . '/cache'            // Cache directory for handler discovery
);
$consumer = $factory->createConsumer();

// 4. Create and run the worker
$worker = new PQueueWorker($transport, $consumer, [
    'stopWhenEmpty' => true, // Stop after processing all messages
]);
$worker->run();

echo "Worker finished.\n";
```

Worker Callbacks
----------------

[](#worker-callbacks)

You can hook into the worker lifecycle using the following methods:

- `onConsume(callable $callback)`: Executed after a message is successfully consumed.
- `onFailure(callable $callback)`: Executed when a message fails processing.
- `onStop(callable $callback)`: Executed when the worker stops (due to memory limit, time limit, or empty queue).

```
$worker->onConsume(function ($message) {
    echo "Message processed!\n";
});

$worker->onFailure(function ($message, $exception) {
    echo "Message failed: " . $exception->getMessage() . "\n";
});

$worker->onStop(function () {
    echo "Worker stopped.\n";
});
```

###  Health Score

30

—

LowBetter than 61% of packages

Maintenance91

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity19

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/909a078010ad44ff35146af8288451a3b6fd26f81cb198cbea776a92553c9b8a?d=identicon)[F.Michel](/maintainers/F.Michel)

---

Top Contributors

[![michelphp](https://avatars.githubusercontent.com/u/26349908?v=4)](https://github.com/michelphp "michelphp (1 commits)")

### Embed Badge

![Health badge](/badges/michel-pqueue/health.svg)

```
[![Health](https://phpackages.com/badges/michel-pqueue/health.svg)](https://phpackages.com/packages/michel-pqueue)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

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

The Laravel Framework.

34.9k556.2M21.5k](/packages/laravel-framework)[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)[kimai/kimai

Kimai - Time Tracking

4.8k9.4k1](/packages/kimai-kimai)

PHPackages © 2026

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