PHPackages                             adamczykpiotr/laravel-balanced-queues - 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. adamczykpiotr/laravel-balanced-queues

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

adamczykpiotr/laravel-balanced-queues
=====================================

Laravel package designed to optimize the performance and efficiency of your application's queue usage

1.4.0(4d ago)1317[2 issues](https://github.com/adamczykpiotr/laravel-balanced-queues/issues)[1 PRs](https://github.com/adamczykpiotr/laravel-balanced-queues/pulls)MITPHPPHP ^8.3CI passing

Since Oct 12Pushed 2mo agoCompare

[ Source](https://github.com/adamczykpiotr/laravel-balanced-queues)[ Packagist](https://packagist.org/packages/adamczykpiotr/laravel-balanced-queues)[ Docs](https://github.com/adamczykpiotr/laravel-balanced-queues)[ GitHub Sponsors](https://github.com/AdamczykPiotr)[ RSS](/packages/adamczykpiotr-laravel-balanced-queues/feed)WikiDiscussions main Synced today

READMEChangelog (4)Dependencies (36)Versions (20)Used By (0)

Laravel Balanced Queues
=======================

[](#laravel-balanced-queues)

[![Latest Version on Packagist](https://camo.githubusercontent.com/722eaf5829af3e8ef32d176c3fbe4186f72a9562a18f346b4cc60f30430f8c89/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6164616d637a796b70696f74722f6c61726176656c2d62616c616e6365642d7175657565732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/adamczykpiotr/laravel-balanced-queues)[![GitHub Tests Action Status](https://camo.githubusercontent.com/25a70ba3984226b576f76e188f89e70c7578eacba678e58203069fa9988f5b2d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6164616d637a796b70696f74722f6c61726176656c2d62616c616e6365642d7175657565732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/adamczykpiotr/laravel-balanced-queues/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/8a1f270f82cb7f1af33523ad740190d3f0e21919a4acd3fab84c404bf75d06fd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6164616d637a796b70696f74722f6c61726176656c2d62616c616e6365642d7175657565732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/adamczykpiotr/laravel-balanced-queues/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/0e748044a66d97a1edbc1a66b2ca88bc5e86e20ed6c62243b70f005b2a9b9ba7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6164616d637a796b70696f74722f6c61726176656c2d62616c616e6365642d7175657565732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/adamczykpiotr/laravel-balanced-queues)

**Stop guessing how many queue workers you need.** This package automatically optimizes worker counts based on job type (CPU-intensive, API calls, file downloads) and your server's resources.

Why You Need This
-----------------

[](#why-you-need-this)

Running 10 workers for everything? **You're wasting resources or creating bottlenecks.**

- **Image downloads** saturate your network with too many workers
- **API calls** queue up with too few concurrent workers
- **CPU jobs** leave cores idle or cause context-switching overhead

Are you running your application on different machines? Different CPU core configurations, changing network bandwidth? **With this package you can optimize it automatically and fine tune it for best results.**

Quick Start
-----------

[](#quick-start)

```
composer require adamczykpiotr/laravel-balanced-queues
php artisan vendor:publish --tag="balanced-queues-config"
```

Tag your jobs with the right workload type using traits:

```
use AdamczykPiotr\LaravelBalancedQueues\Traits\HasBalancedQueues;

class ScrapeVideosJob implements ShouldQueue
{
    public function __construct() {
        $this->onHighNetworkBandwidthUsageQueu();
    }
}

class CallApiJob implements ShouldQueue
{
    public function __construct() {
        $this->onHighNetworkRequestUsageQueue();
    }
}

class ProcessBigDataJob implements ShouldQueue
{
    public function __construct() {
        $this->onHighCpuUsageQueue();
    }
}

class ProcessSmallerDataJob implements ShouldQueue
{
    public function __construct() {
        $this->onMediumCpuUsageQueue();
    }
}
```

Run your queues:

```
php artisan queue:run-balanced
```

**Done.** The package spawns all the queues with adjusted worker counts for each job type.

Available helpers
-----------------

[](#available-helpers)

Helper methodWorkload TypeUse Case`onHighCpuUsageQueue`CPU\_HIGHLarge file processing ~MB/GB`onMediumCpuUsageQueue`CPU\_MEDIUMPDF generation, smaller file parsing (~KB/MB)`onLowCpuUsageQueue`CPU\_LOWQuick background queries`onHighNetworkRequestUsageQueue`NETWORK\_HIGH\_BANDWIDTHLarge file downloads (~ >10MB)`onHighNetworkBandwidthUsageQueue`NETWORK\_HIGH\_REQUESTSAPI calls, webhooks`onFilesystemQueue`FILESYSTEMFilesystem operations (duh!)How It Works
------------

[](#how-it-works)

By default, `CPU_HIGH` usage assumes 100-50% CPU utilisation for a single job, ~50-25% for `CPU_MEDIUM` and ~10-20% for `CPU_LOW`. Jobs on `NETWORK_HIGH_BANDWIDTH` are best suited for downloading large files that completely saturate network bandwidth whereas `NETWORK_HIGH_REQUESTS` are in most cases are bottleneck by neither network nor cpu and are offloaded on a queue simply to improve UX. `FILESYSTEM` jobs are assumed to be bottlenecked by disk I/O.

If the default configuration doesn't fully utilize your machine, adjust the following default configuration in `config/balanced-queues.php`:

```
use AdamczykPiotr\LaravelBalancedQueues\Enums\JobWorkloadType;

$CPU_CORES = CpuCoreConfigurationResolver::CPU_CORES;

return [
    'queues' => [
        JobWorkloadType::DEFAULT->value => 1,

        JobWorkloadType::CPU_HIGH->value => $CPU_CORES,
        JobWorkloadType::CPU_MEDIUM->value => 2 * $CPU_CORES,
        JobWorkloadType::CPU_LOW->value => 4 * $CPU_CORES,

        JobWorkloadType::NETWORK_HIGH_BANDWIDTH->value => 5,
        JobWorkloadType::NETWORK_HIGH_REQUESTS->value => 50,

        JobWorkloadType::FILESYSTEM->value => 2,
    ],
];
```

The default configuration aims to ensure best results across wide range of cases. In order to get full benefits of this approach, it's *highly* recommended to fine-tune the configuration to *your*specific use-case. The clue to optimisation is to ensure a *single* queue can fully saturate the machine:

- Dispatching `CPU_CORES` jobs to `CPU_HIGH` queue should result in ~100% CPU usage
- Dispatching `2` \* `CPU_CORES` jobs to `CPU_MEDIUM` queue should result in ~100% CPU usage
- Dispatching `4` \* `CPU_CORES` jobs to `CPU_LOW` queue should result in ~100% CPU usage
- Dispatching `5` jobs to `NETWORK_HIGH_BANDWIDTH` queue should result in full network saturation
- Dispatching `50` jobs to `NETWORK_HIGH_REQUESTS` should result in jobs being finished as soon as possible (no real bottleneck)
- Dispatching `2` jobs to `FILESYSTEM` queue should result in full disk I/O saturation

In case more than one queue is fully saturated, OS scheduler will balance processes CPU time accordingly.

Advanced Configuration
----------------------

[](#advanced-configuration)

### Custom Queue Names

[](#custom-queue-names)

```
'queues' => [
    'ml-training' => 2 * $CPU_CORES,
    'notifications' => 10,
    'web-scraping' => 25,
],
```

### VM / Docker CPU Limits

[](#vm--docker-cpu-limits)

Override auto-detected CPU core count:

```
'package' => [
    'cpu_core_count' => 4,  // Override auto-detected core count
],
```

### Worker Options

[](#worker-options)

Add additional options to `artisan queue:work` command:

```
'worker_options' => [
    '--timeout' => 60,
    '--tries' => 3,
    '--sleep' => 3,
],
```

### Supervisor Configuration

[](#supervisor-configuration)

Customize the generated Supervisor configuration:

```
'supervisor' => [
    'header' => [
        'user' => 'www-data',
        'numprocs' => 1,
    ],
],
```

Commands
--------

[](#commands)

```
# Run queue workers
php artisan queue:run-balanced

# Run in background
php artisan queue:run-balanced --background

# Get path to generated config and run supervisor manually
php artisan queue:run-balanced --path-only
```

Docker container entrypoint example
-----------------------------------

[](#docker-container-entrypoint-example)

```
#!/bin/sh
set -e

SUPERVISORD_CONFIG_PATH=$(php artisan queue:run-balanced --path-only)
exec /usr/bin/supervisord -n -c "$SUPERVISORD_CONFIG_PATH"

```

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

[](#requirements)

- PHP 8.3+
- Laravel 11.x or 12.x
- Supervisor

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Piotr Adamczyk](https://github.com/adamczykpiotr)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance72

Regular maintenance activity

Popularity19

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 72.7% 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 ~65 days

Total

5

Last Release

4d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20736260?v=4)[Piotr Adamczyk](/maintainers/adamczykpiotr)[@adamczykpiotr](https://github.com/adamczykpiotr)

---

Top Contributors

[![adamczykpiotr](https://avatars.githubusercontent.com/u/20736260?v=4)](https://github.com/adamczykpiotr "adamczykpiotr (16 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

laraveladamczykpiotrlaravel-balanced-queues

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/adamczykpiotr-laravel-balanced-queues/health.svg)

```
[![Health](https://phpackages.com/badges/adamczykpiotr-laravel-balanced-queues/health.svg)](https://phpackages.com/packages/adamczykpiotr-laravel-balanced-queues)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k102.4M1.4k](/packages/spatie-laravel-permission)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M101](/packages/dedoc-scramble)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

44855.7k](/packages/harris21-laravel-fuse)[spatie/laravel-passkeys

Use passkeys in your Laravel app

471890.7k39](/packages/spatie-laravel-passkeys)[croustibat/filament-jobs-monitor

Background Jobs monitoring like Horizon for all drivers for FilamentPHP

274327.0k8](/packages/croustibat-filament-jobs-monitor)

PHPackages © 2026

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