PHPackages                             yangusik/laravel-balanced-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. [Caching](/categories/caching)
4. /
5. yangusik/laravel-balanced-queue

ActiveLibrary[Caching](/categories/caching)

yangusik/laravel-balanced-queue
===============================

Laravel queue management with load balancing between partitions (user groups)

v1.2.0(2mo ago)786.4k↑51%6MITPHPPHP ^8.1CI passing

Since Jan 15Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/YanGusik/laravel-balanced-queue)[ Packagist](https://packagist.org/packages/yangusik/laravel-balanced-queue)[ RSS](/packages/yangusik-laravel-balanced-queue/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (14)Versions (11)Used By (0)

Laravel Balanced Queue
======================

[](#laravel-balanced-queue)

A Laravel package for queue management with load balancing between partitions (user groups). Perfect for scenarios where you need fair job distribution and concurrency control per user/tenant.

Problem Solved
--------------

[](#problem-solved)

Imagine you have an AI generation service where users can submit unlimited tasks. Without balanced queuing:

- One user can flood the queue and block everyone else
- No control over how many concurrent tasks a single user can run
- Resource-heavy users can exhaust API rate limits

**Laravel Balanced Queue** solves this by:

- Distributing jobs fairly across all users (round-robin)
- Limiting concurrent jobs per user (e.g., max 2 AI generations per user)
- Never rejecting jobs - they queue up and execute eventually
- Preventing single users from monopolizing workers

How It Works
------------

[](#how-it-works)

### The Problem

[](#the-problem)

```
Standard Laravel Queue (FIFO):

Queue: [A1][A2][A3][A4][A5][A6][A7][A8][B1][B2][C1][C2]
        ─────────────────────────────→ time

Execution order: A1 → A2 → A3 → A4 → A5 → A6 → A7 → A8 → B1 → B2 → C1 → C2

User A submitted 8 tasks first.
User B and C must wait until ALL of User A's tasks complete!

```

### The Solution

[](#the-solution)

Balanced Queue partitions jobs by user and rotates between them:

```
Balanced Queue (partitioned):

Partition A: [A1][A2][A3][A4][A5][A6][A7][A8]
Partition B: [B1][B2]
Partition C: [C1][C2]

Execution order: A1 → B1 → C1 → A2 → B2 → C2 → A3 → A4 → A5...

Everyone gets fair turns! User B doesn't wait for all 8 of User A's tasks.

```

### Strategy Comparison

[](#strategy-comparison)

**Round-Robin Strategy** (recommended) — strict rotation:

```
Partitions:  [A: 5 jobs] [B: 2 jobs] [C: 2 jobs]

Worker 1:    A1 ──────── B1 ──────── C1 ──────── A2 ──────── B2 ────────
Worker 2:       ──────── A3 ──────── C2 ──────── A4 ──────── A5 ────────

Order: A → B → C → A → B → C → A → A → A
       └── cycles through all partitions equally

```

**Random Strategy** — unpredictable but fast:

```
Partitions:  [A: 5 jobs] [B: 2 jobs] [C: 2 jobs]

Worker 1:    A1 ──────── A2 ──────── B1 ──────── C1 ──────── A3 ────────
Worker 2:       ──────── C2 ──────── A4 ──────── B2 ──────── A5 ────────

Order: Random selection each time (stateless, good for high load)

```

**Smart Strategy** — prioritizes smaller queues:

```
Partitions:  [A: 50 jobs] [B: 3 jobs] [C: 2 jobs]
                  │            │           │
             (deprioritized)  (boost)    (boost)

Worker 1:    B1 ──────── C1 ──────── B2 ──────── C2 ──────── B3 ────────
Worker 2:       ──────── A1 ──────── A2 ──────── A3 ──────── A4 ────────

Small queues (B, C) get processed faster, preventing starvation.
User A's 50 jobs won't block users with just a few tasks.

```

### Concurrency Limiting

[](#concurrency-limiting)

With `max_concurrent: 2` per partition:

```
Partition A: [A1][A2][A3][A4][A5] waiting
                 │   │
             ┌───┴───┴───┐
             │  Active   │
             │  A1  A2   │ ← max 2 running simultaneously
             └───────────┘

A3, A4, A5 wait until A1 or A2 completes.
Other partitions (B, C) can still run their jobs!

```

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

[](#installation)

```
composer require yangusik/laravel-balanced-queue
```

Publish the configuration:

```
php artisan vendor:publish --tag=balanced-queue-config
```

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

[](#quick-start)

### Step 1: Add Queue Connection

[](#step-1-add-queue-connection)

Add to `config/queue.php`:

```
'connections' => [
    // ... your existing connections

    'balanced' => [
        'driver' => 'balanced',
        'connection' => 'default', // Redis connection from database.php
        'queue' => 'default',
        'retry_after' => 90,
    ],
],
```

### Step 2: Create a Job

[](#step-2-create-a-job)

```