PHPackages                             bunqueue/client - 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. bunqueue/client

Active

bunqueue/client
===============

00

Compare

[ Source](https://github.com/egeominotti/bunqueue-php)[ Packagist](https://packagist.org/packages/bunqueue/client)[ RSS](/packages/bunqueue-client/feed)WikiDiscussions Synced today

READMEChangelogDependenciesVersionsUsed By (0)

[ ![bunqueue logo](https://raw.githubusercontent.com/egeominotti/bunqueue/main/.github/logo.png)](https://bunqueue.dev)bunqueue/client (PHP)
=====================

[](#bunqueueclient-php)

**The official PHP client for [bunqueue](https://bunqueue.dev), the high performance job queue server.**

Native TCP protocol (msgpack, length-prefixed frames), one runtime dependency, verified certificate TLS. Producer-friendly for FPM, worker-friendly for CLI: `run()` for daemons, `runOnce()` for cron/request-scoped batches.

[![packagist](https://camo.githubusercontent.com/bbb92f736063308be0809a03ac3b92d26dd656b7094e586d2d182419d3aebdd9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62756e71756575652f636c69656e743f636f6c6f723d643331353664266c6162656c3d7061636b6167697374)](https://packagist.org/packages/bunqueue/client)[![downloads](https://camo.githubusercontent.com/d6746b384341b5e42a321930740fa3217f1f227fa8e4ee777dded89ced29601b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f62756e71756575652f636c69656e743f636f6c6f723d666634663966)](https://packagist.org/packages/bunqueue/client)[![license](https://camo.githubusercontent.com/dbf2969ae11e4c77d155bdefb7656936d4a196adbb463e4fa9efa1eec97ab792/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d316131613265)](https://github.com/egeominotti/bunqueue/blob/main/sdk/php/LICENSE)[![php](https://camo.githubusercontent.com/b8b9cebfbb14fd712c90f70bb94b700e82709815d0de15d3d14cf81a66ab4bdd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312532422d326561343466)](https://github.com/egeominotti/bunqueue/tree/main/sdk/php)[![conformance](https://camo.githubusercontent.com/49b0d1fccdaccc15bb346f5771b8aa418d6bdd32cd0522daa2f2e846eb96b9d0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f70726f746f636f6c2d636f6e666f726d616e74253230313725324631372d643331353664)](https://github.com/egeominotti/bunqueue/tree/main/sdk/conformance)

[Documentation](https://bunqueue.dev/guide/sdks/) · [Protocol spec](https://github.com/egeominotti/bunqueue/blob/main/docs/protocol.md) · [Server](https://github.com/egeominotti/bunqueue) · [Changelog](https://github.com/egeominotti/bunqueue/blob/main/sdk/php/CHANGELOG.md)

---

The bunqueue server runs on Bun, distributed as a binary or a Docker image. This client lets any PHP service produce and consume jobs against it: one queue, any language.

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

[](#installation)

```
composer require bunqueue/client
```

Requires PHP 8.1+. Single dependency: `rybakit/msgpack` (pure PHP, no extension needed).

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

[](#quick-start)

Start a server (`bunx bunqueue start` or the Docker image), then:

```
use Bunqueue\Queue;
use Bunqueue\Worker;

// Producer (an API endpoint, a controller, anywhere)
$queue = new Queue('emails', ['host' => 'localhost', 'port' => 6789]);
$job = $queue->add('welcome', ['to' => 'user@example.com'], ['attempts' => 3]);

// Worker (a CLI process: php worker.php)
$worker = new Worker('emails', function (Bunqueue\Job $job) {
    sendEmail($job->data()['to']);
    return ['sent' => true];
}, ['host' => 'localhost', 'port' => 6789]);

$worker->on('completed', fn ($job, $result) => printf("done %s\n", $job->id()));
$worker->on('error', fn ($e) => error_log($e->getMessage()));
$worker->installSignalHandlers();   // SIGTERM/SIGINT -> graceful stop
$worker->run();                     // blocking loop
```

### Request-scoped consumption (FPM, cron)

[](#request-scoped-consumption-fpm-cron)

PHP often cannot run a blocking daemon. `runOnce()` pulls and processes one batch, then returns — perfect for a cron tick or a protected endpoint:

```
$handled = $worker->runOnce();   // returns how many jobs were processed
```

Failure semantics
-----------------

[](#failure-semantics)

```
use Bunqueue\UnrecoverableError;

$worker = new Worker('orders', function ($job) {
    if (!isValid($job->data())) {
        throw new UnrecoverableError('malformed order');  // no retries -> DLQ
    }
    throw new \RuntimeException('transient');  // retried per attempts/backoff
});
```

Retries, backoff, priorities, delays, stall detection and the dead letter queue all live in the server; the failure's message and stack (throw site first) are persisted with the job.

Long job? The PHP worker is single-threaded, so renew the lease from inside the processor: `$job->extendLock(60_000);`

API surface
-----------

[](#api-surface)

AreaMethodsProduce`add`, `addBulk` (custom ids preserved), full wire job options (`priority`, `delay`, `attempts`, `backoff`, `jobId`, `deduplication`, `dependsOn`, `lifo`, `durable`, ...)Query`getJob`, `getJobByCustomId`, `getJobs`, `getState`, `getResult`, `getProgress`, `waitForJob`, `getJobCounts`, `count`, `getJobLogs`, `getChildrenValues`Control`pause`, `resume`, `isPaused`, `drain`, `clean`, `obliterate`, `remove`, `discard`, `promote`, `retryJob`, `changePriority`, `changeDelay`, `updateJobData`, `moveJobToFailed`DLQ`getDlq`, `retryDlq`, `purgeDlq`Schedulers`upsertJobScheduler` (cron pattern or `every`, execution `limit`), `getJobScheduler`, `getJobSchedulers`, `removeJobScheduler`Adminwebhooks, `setRateLimit(limit, durationMs, ttlMs)`, `getWorkers`, `getStats`, `listQueues`, `ping`Flows`FlowProducer`: parent/child trees, `addChain`, `getFlow`, automatic rollbackTLS: `['tls' => true]` (system CAs, verified) or `['tls' => ['caFile' => './ca.pem']]`. Auth: `['token' => '...']`.

### Telemetry

[](#telemetry)

Pass an optional payload-free callback to `Queue`, `Worker` or `Connection`:

```
$queue = new Queue('emails', [
    'onEvent' => function (array $event): void {
        error_log(sprintf(
            '%s command=%s duration=%.2fms error=%s',
            $event['type'],
            $event['command'] ?? '',
            $event['durationMs'] ?? 0,
            $event['error'] ?? '',
        ));
    },
]);
```

It receives `connected`, `reconnect`, `auth`, `command`, `timeout`, `error`and `close` events without tokens or command payloads. Callback exceptions are isolated from queue correctness.

Quality assurance
-----------------

[](#quality-assurance)

Every change runs the e2e suite (a real server spawned per run) and the cross-language [conformance suite](https://github.com/egeominotti/bunqueue/tree/main/sdk/conformance):

```
composer install
php tests/run-e2e.php                                # 48 e2e tests
BUNQUEUE_SDK_SOAK_SECONDS=3600 php tests/soak.php   # sustained profile
cd ../conformance && bun runner.ts --driver "php drivers/php.php"   # 17/17
cd ../.. && bun run test:sandbox:sdk
```

The native suite includes multi-process custom-id and single-lease races, fixed-seed generated payloads, malformed depth fuzzing, a 512-job spike, and SIGKILL/reconnect durability. The soak profile reuses one connection; adjust `BUNQUEUE_SDK_SOAK_BATCH` for stress diagnostics.

License
-------

[](#license)

MIT. See the [LICENSE](https://github.com/egeominotti/bunqueue/blob/main/sdk/php/LICENSE) file. Documentation: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/). Issues and feature requests: [GitHub issues](https://github.com/egeominotti/bunqueue/issues).

###  Health Score

8

—

LowBetter than 0% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity8

Early-stage or recently created project

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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/4ff81a45461fecf3cc03f5a3468bd13912f3540df23ef9acd0fd0e87aa17bf16?d=identicon)[egeominotti](/maintainers/egeominotti)

### Embed Badge

![Health badge](/badges/bunqueue-client/health.svg)

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

PHPackages © 2026

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