PHPackages                             philiprehberger/php-background-jobs - 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 &amp; Workers](/categories/queues)
4. /
5. philiprehberger/php-background-jobs

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

philiprehberger/php-background-jobs
===================================

Lightweight background job queue with file-based driver

v1.0.2(4d ago)11MITPHPPHP ^8.2CI passing

Since Mar 13Pushed yesterdayCompare

[ Source](https://github.com/philiprehberger/php-background-jobs)[ Packagist](https://packagist.org/packages/philiprehberger/php-background-jobs)[ Docs](https://github.com/philiprehberger/php-background-jobs)[ RSS](/packages/philiprehberger-php-background-jobs/feed)WikiDiscussions main Synced today

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

PHP Background Jobs
===================

[](#php-background-jobs)

[![Tests](https://github.com/philiprehberger/php-background-jobs/actions/workflows/tests.yml/badge.svg)](https://github.com/philiprehberger/php-background-jobs/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/2ac7451491a79e18eaaef46b9d2abf59d87637d2be86a5de619797c0b98db4d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69707265686265726765722f7068702d6261636b67726f756e642d6a6f62732e737667)](https://packagist.org/packages/philiprehberger/php-background-jobs)[![License](https://camo.githubusercontent.com/0ad854280f91dce1b3e7380ace477809067fef82a8a1634a5883730581581b97/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7068696c69707265686265726765722f7068702d6261636b67726f756e642d6a6f6273)](LICENSE)

Lightweight background job queue with file-based driver.

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

[](#requirements)

- PHP 8.2+

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

[](#installation)

```
composer require philiprehberger/php-background-jobs
```

Usage
-----

[](#usage)

### Define a Job

[](#define-a-job)

Implement the `Job` interface:

```
use PhilipRehberger\BackgroundJobs\Contracts\Job;

class SendEmailJob implements Job
{
    public function __construct(
        private readonly string $to,
        private readonly string $subject,
    ) {}

    public function handle(): void
    {
        // Send the email...
    }
}
```

### Create a Queue

[](#create-a-queue)

Use the built-in `FileDriver` to store jobs as JSON files:

```
use PhilipRehberger\BackgroundJobs\Drivers\FileDriver;
use PhilipRehberger\BackgroundJobs\Queue;

$driver = new FileDriver('/path/to/storage/queue');
$queue = new Queue($driver);
```

### Push Jobs

[](#push-jobs)

```
// Push a job for immediate processing
$id = $queue->push(new SendEmailJob('user@example.com', 'Welcome!'));

// Push a job with a delay (in seconds)
$id = $queue->later(new SendEmailJob('user@example.com', 'Reminder'), 3600);
```

### Process Jobs with the Worker

[](#process-jobs-with-the-worker)

```
use PhilipRehberger\BackgroundJobs\Worker;

// Process the next available job
$processed = Worker::processNext($queue);

// Process with a custom max attempts limit
$processed = Worker::processNext($queue, maxAttempts: 5);
```

### Queue Management

[](#queue-management)

```
// Get the number of pending jobs
$count = $queue->size();

// Clear all jobs
$queue->clear();

// Pop a job manually
$payload = $queue->pop();
if ($payload !== null) {
    $job = $payload->resolveJob();
    $job->handle();
}
```

### Custom Queue Driver

[](#custom-queue-driver)

Implement the `QueueDriver` interface to use a different storage backend:

```
use PhilipRehberger\BackgroundJobs\Contracts\QueueDriver;
use PhilipRehberger\BackgroundJobs\JobPayload;

class RedisDriver implements QueueDriver
{
    public function push(JobPayload $payload): void { /* ... */ }
    public function pop(): ?JobPayload { /* ... */ }
    public function size(): int { /* ... */ }
    public function clear(): void { /* ... */ }
}
```

### Error Handling

[](#error-handling)

Failed jobs throw a `JobFailedException`:

```
use PhilipRehberger\BackgroundJobs\Exceptions\JobFailedException;

try {
    Worker::processNext($queue);
} catch (JobFailedException $e) {
    echo $e->getMessage();
    echo $e->payload->id;        // Job ID
    echo $e->payload->jobClass;  // Original job class
    echo $e->payload->attempts;  // Number of attempts
}
```

API
---

[](#api)

ClassMethodDescription`Queue``push(Job $job): string`Push a job, returns job ID`Queue``later(Job $job, int $delaySeconds): string`Push a delayed job`Queue``pop(): ?JobPayload`Pop the next available job`Queue``size(): int`Get pending job count`Queue``clear(): void`Remove all jobs`Worker``processNext(Queue $queue, int $maxAttempts = 3): bool`Process next job`JobPayload``resolveJob(): Job`Deserialize the job instance`JobPayload``isAvailable(): bool`Check if job is ready to process`JobPayload``withIncrementedAttempts(): self`Clone with incremented attempts`JobPayload``toArray(): array`Serialize to array`JobPayload``fromArray(array $data): self`Restore from arrayDevelopment
-----------

[](#development)

```
composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse
```

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance100

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

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 ~2 days

Total

3

Last Release

4d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfd7d24cbbf32400fa13ce0bbe7a31edd2d66a6d4488eafdb3d64c5337bf0435?d=identicon)[philiprehberger](/maintainers/philiprehberger)

---

Top Contributors

[![philiprehberger](https://avatars.githubusercontent.com/u/8218077?v=4)](https://github.com/philiprehberger "philiprehberger (9 commits)")

---

Tags

asyncqueuebackgroundjobsworker

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/philiprehberger-php-background-jobs/health.svg)

```
[![Health](https://phpackages.com/badges/philiprehberger-php-background-jobs/health.svg)](https://phpackages.com/packages/philiprehberger-php-background-jobs)
```

###  Alternatives

[clue/mq-react

Mini Queue, the lightweight in-memory message queue to concurrently do many (but not too many) things at once, built on top of ReactPHP

145660.2k4](/packages/clue-mq-react)[rcrowe/raven

Raven client for Sentry that supports background processing through multiple providers.

3467.0k](/packages/rcrowe-raven)

PHPackages © 2026

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