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 & Workers](/categories/queues) 4. / 5. philiprehberger/php-background-jobs ActiveLibrary[Queues & Workers](/categories/queues) philiprehberger/php-background-jobs =================================== Lightweight background job queue with file-based driver v1.1.0(4mo ago)168MITPHPPHP ^8.2CI passing Since Mar 13Pushed 1mo agoCompare [ 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 1w ago READMEChangelogDependencies (6)Versions (5)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)[![Last updated](https://camo.githubusercontent.com/461265dc37d58b6eabc854139ca9fb101c6808344f03e4c3289e0b72572d3f73/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f7068696c69707265686265726765722f7068702d6261636b67726f756e642d6a6f6273)](https://github.com/philiprehberger/php-background-jobs/commits/main) 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 { /* ... */ } } ``` ### Lifecycle Hooks [](#lifecycle-hooks) Register callbacks that fire when a job succeeds or fails: ``` use PhilipRehberger\BackgroundJobs\BaseJob; class SendEmailJob extends BaseJob { public function __construct( private readonly string $to, ) {} public function handle(): void { // Send the email... } } $job = new SendEmailJob('user@example.com'); $job->onSuccess(function ($job) { echo "Job completed after {$job->getAttempts()} attempt(s)."; }); $job->onFailure(function ($job, \Throwable $e) { echo "Job failed: {$e->getMessage()}"; }); $queue->push($job); ``` ### 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`Queue``pending(): array`Get all pending job payloads`Worker``processNext(Queue $queue, int $maxAttempts = 3): bool`Process next job`BaseJob``onSuccess(callable $callback): self`Register a success lifecycle hook`BaseJob``onFailure(callable $callback): self`Register a failure lifecycle hook`BaseJob``getAttempts(): int`Get the number of attempts`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 ``` Support ------- [](#support) If you find this project useful: ⭐ [Star the repo](https://github.com/philiprehberger/php-background-jobs) 🐛 [Report issues](https://github.com/philiprehberger/php-background-jobs/issues?q=is%3Aissue+is%3Aopen+label%3Abug) 💡 [Suggest features](https://github.com/philiprehberger/php-background-jobs/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) ❤️ [Sponsor development](https://github.com/sponsors/philiprehberger) 🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages) 💻 [GitHub Profile](https://github.com/philiprehberger) 🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger) License ------- [](#license) [MIT](LICENSE) ### Health Score 40 — FairBetter than 86% of packages Maintenance83 Actively maintained with recent releases Popularity10 Limited adoption so far Community8 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 88.9% 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 ~3 days Total 4 Last Release 141d 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 (16 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 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 [dereuromark/cakephp-queue The Queue plugin for CakePHP provides deferred task execution. 308995.7k27](/packages/dereuromark-cakephp-queue)[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 144840.7k4](/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)