PHPackages                             danil-kashin/file-queue - 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. danil-kashin/file-queue

ActiveLibrary

danil-kashin/file-queue
=======================

A simple, file-based FIFO queue that keeps messages in order across restarts.

v1.0.0(1mo ago)00BSD-3-ClausePHPPHP >=8.1

Since Mar 30Pushed 1mo agoCompare

[ Source](https://github.com/KashinDanil/FileQueue)[ Packagist](https://packagist.org/packages/danil-kashin/file-queue)[ RSS](/packages/danil-kashin-file-queue/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (2)Used By (0)

FileQueue
=========

[](#filequeue)

A simple, file-based FIFO queue for PHP. Messages are persisted to disk using an append-only log with exclusive file locking, so the queue survives process restarts and is safe to use across multiple processes.

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

[](#requirements)

- PHP 8.1+
- Extension: `json`

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

[](#installation)

```
composer require danil-kashin/file-queue
```

Usage
-----

[](#usage)

### 1. Create a worker

[](#1-create-a-worker)

Extend `FileQueueWorker` and implement `processMessage()`. Return `true` on success, `false` on failure. Failed messages are dequeued and not retried automatically.

The worker scans a directory for queue files and processes each discovered queue on every tick, up to **10 messages per queue**. This ensures equal resource distribution across queues and avoids the noisy-neighbor problem. It handles `SIGTERM`/`SIGINT` for graceful shutdown.

```
use DanilKashin\FileQueue\Queue\QueueMessage;
use DanilKashin\FileQueue\Workers\FileQueueWorker;

class OrderWorker extends FileQueueWorker
{
    protected function processMessage(QueueMessage $message): bool
    {
        return handleOrder($message->payload);
    }
}
```

For each processed message the worker prints `+` (success) or `-` (failure) to stdout.

### 2. Run the worker

[](#2-run-the-worker)

The worker is a long-running process — run it in the background so your application keeps responding. Progress is written to stdout (`+` / `-` per message and `.` per tick); errors go to stderr.

```
vendor/bin/run_worker "App\Workers\OrderWorker" --queuesDir=/var/queues > worker.log 2>&1 &
```

### 3. Enqueue messages

[](#3-enqueue-messages)

Messages can be enqueued from anywhere in your application as long as they share the same `baseDir`. No running worker is required at enqueue time; messages will be picked up on the next tick.

```
use DanilKashin\FileQueue\Queue\FileQueue;
use DanilKashin\FileQueue\Queue\QueueMessage;

$queue = new FileQueue(queueName: 'orders', baseDir: '/var/queues');
$queue->enqueue(new QueueMessage(['order_id' => 42, 'status' => 'pending']));
```

Architecture
------------

[](#architecture)

 ```
flowchart LR
    App["Your App"] -->|"enqueue(QueueMessage)"| FileQueue
    FileQueue -->|"dequeue()"| FileQueueWorker
    FileQueueWorker -->|"processMessage(QueueMessage)"| YourWorker["Your Worker"]
```

      Loading If you need to supply queues from a custom source (e.g. a database-backed list of queue names), extend `QueueWorker` directly and implement both `getQueues()` and `processMessage()`.

Queue API
---------

[](#queue-api)

```
$queue = new FileQueue(queueName: 'orders', baseDir: '/var/queues');

// Write
$queue->enqueue(new QueueMessage(['order_id' => 42]));

// Read
$message = $queue->dequeue(); // QueueMessage|null
if ($message !== null) {
    $payload = $message->payload; // ['order_id' => 42]
}

// Inspect
$queue->isEmpty(); // bool
$queue->size();    // int — counts remaining (unconsumed) messages

// Compact the queue file
$queue->compact();
```

### Compaction

[](#compaction)

Over time the data file grows as messages are appended and consumed. `compact()` rewrites the file to contain only unread messages, reclaiming disk space.

No need to call it regularly if your `FileQueueWorker` runs all the time. When the last message is dequeued, all associated files are removed automatically, so no manual cleanup is needed.

How it works
------------

[](#how-it-works)

Each queue is backed by three files:

FilePurpose`{name}.queue.data`Append-only binary log of framed records`{name}.queue.pointer`Read offset — tracks the next unread message`{name}.queue.lock`Exclusive lock file — guards all mutationsRecords are size-prefixed with a 4-byte big-endian length header followed by the JSON payload. Reads advance the pointer without touching the data file. `compact()` rewrites the data file to drop consumed records. All mutations are guarded by an exclusive lock.

Exceptions
----------

[](#exceptions)

ClassWhen thrown`QueueException`I/O failure (unreadable file, write error, …)`CorruptedQueueException`Truncated or structurally invalid record`CorruptedQueueException` extends `QueueException`, so catching `QueueException` covers both.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

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

Unknown

Total

1

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/808cc658e54eb99caa9573723ab97993e9fcd90d2b6cd0940a1ba7eb8950f8cf?d=identicon)[KashinDanil](/maintainers/KashinDanil)

---

Top Contributors

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

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/danil-kashin-file-queue/health.svg)

```
[![Health](https://phpackages.com/badges/danil-kashin-file-queue/health.svg)](https://phpackages.com/packages/danil-kashin-file-queue)
```

PHPackages © 2026

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