PHPackages                             yaelliethy/wildqueue - 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. yaelliethy/wildqueue

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

yaelliethy/wildqueue
====================

A Laravel package for dynamically managing queue workers.

1.0.0(10mo ago)14MITPHPPHP ^8.1

Since Jul 15Pushed 10mo agoCompare

[ Source](https://github.com/yaelliethy/wildqueue)[ Packagist](https://packagist.org/packages/yaelliethy/wildqueue)[ RSS](/packages/yaelliethy-wildqueue/feed)WikiDiscussions main Synced 1mo ago

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

WildQueue - Dynamic Laravel Queue Worker Management
===================================================

[](#wildqueue---dynamic-laravel-queue-worker-management)

A Laravel package that automatically manages workers for dynamically named queues without Redis or Horizon.

Features
--------

[](#features)

- 🧠 **Dynamic Worker Spawning**: Automatically spawns workers when jobs are dispatched to new queues
- 📊 **Database Tracking**: Tracks all workers and their status in the database
- ⚡ **Optimized Performance**: Uses caching to avoid repetitive database/process checks
- 🔄 **Automatic Pruning**: Uses Laravel's scheduler to automatically clean up idle workers
- 📈 **Activity Tracking**: Monitors job processing to determine worker idle time
- ⚙️ **Rich CLI Commands**: Complete set of management commands
- 🎯 **Regex Pattern Matching**: Filter which queues should have workers spawned using regex patterns

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

[](#installation)

1. Add the package to your project:

```
composer require yaelliethy/wildqueue
```

2. Publish the configuration:

```
php artisan vendor:publish --provider="WildQueue\WildQueueServiceProvider" --tag="config"
```

3. **Migration Setup**:

    **Option A (Automatic)** - The migration will be automatically available after installation:

    ```
    php artisan migrate
    ```

    **Option B (Manual)** - If the migration doesn't appear, publish it manually:

    ```
    php artisan vendor:publish --provider="WildQueue\WildQueueServiceProvider" --tag="migrations"
    php artisan migrate
    ```

Configuration
-------------

[](#configuration)

Edit `config/wildqueue.php`:

```
return [
    'enabled' => true,           // Enable/disable dynamic worker spawning
    'idle_timeout' => 300,       // Seconds before a worker is considered idle (5 minutes)
    'auto_prune' => true,        // Automatically register pruning with Laravel scheduler
    'cache_duration' => 30,      // How long to cache worker status (seconds)

    // Define regex patterns for queues that should have workers spawned
    'queue_patterns' => [
        '/^emails:.*/',          // Match all queues starting with 'emails:'
        '/^notifications:.*/',   // Match all queues starting with 'notifications:'
        '/^tenant:\w+:.*/',      // Match tenant-specific queues
    ],

    // Define regex patterns for queues that should NOT have workers spawned
    'excluded_patterns' => [
        '/^system:.*/',          // Exclude system queues
        '/.*:internal$/',        // Exclude internal queues
    ],
];
```

### Cache Duration

[](#cache-duration)

The `cache_duration` setting controls how long WildQueue caches the status of workers to avoid repetitive database queries and process checks. This significantly improves performance during job bursts but may delay detection of dead workers.

**Configuration Options:**

```
// In config/wildqueue.php
'cache_duration' => 30,  // Cache for 30 seconds (default)
```

```
# Or via environment variable in .env
WILDQUEUE_CACHE_DURATION=15
```

**Use Cases:**

- **Default (30 seconds)**: Good balance for most applications
- **High-frequency jobs (60 seconds)**: Better performance for applications with many rapid job dispatches
- **Critical responsiveness (10-15 seconds)**: Faster worker respawn detection for time-sensitive applications
- **Development/testing (0 seconds)**: Disables caching for immediate feedback (not recommended for production)

**Example:**

```
# For faster worker recovery in production
WILDQUEUE_CACHE_DURATION=15

# For high-throughput systems
WILDQUEUE_CACHE_DURATION=60

# For development (immediate worker detection)
WILDQUEUE_CACHE_DURATION=0
```

### Pattern Matching Examples

[](#pattern-matching-examples)

```
// Match all email queues
'/^emails:.*/' → matches: emails:user-123, emails:newsletter, emails:welcome

// Match tenant-specific queues
'/^tenant:\w+:.*/' → matches: tenant:abc:notifications, tenant:xyz:reports

// Match user-specific queues
'/.*:user-\d+$/' → matches: emails:user-123, notifications:user-456

// Exclude system queues
'/^system:.*/' → excludes: system:cleanup, system:maintenance
```

Usage
-----

[](#usage)

### Assigning Queue Names

[](#assigning-queue-names)

You can assign queue names to your jobs using any standard Laravel method. WildQueue will automatically detect the resolved queue name and manage workers accordingly. Supported methods include:

- **Using `onQueue()` method** (most common): ```
    dispatch(new SendEmailJob($user))->onQueue('emails:user-' . $user->id);
    ```
- **Setting the `$queue` property in the constructor**: ```
    class SendEmailJob implements ShouldQueue {
        use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
        public function __construct($user) {
            $this->queue = 'emails:user-' . $user->id;
        }
    }
    ```
- **Modifying the `$queue` property after instantiation**: ```
    $job = new SendEmailJob($user);
    $job->queue = 'emails:user-' . $user->id;
    dispatch($job);
    ```
- **Using `onQueue()` in the constructor**: ```
    class SendEmailJob implements ShouldQueue {
        public function __construct($user) {
            $this->onQueue('emails:user-' . $user->id);
        }
    }
    ```
- **Dynamic assignment with a method**: ```
    class SendEmailJob implements ShouldQueue {
        public function __construct($user) {
            $this->queue = $this->generateQueueName($user);
        }
        private function generateQueueName($user) {
            return 'emails:user-' . $user->id;
        }
    }
    ```

**WildQueue will work with all of these methods.**

#### Priority

[](#priority)

- The `onQueue()` method always takes precedence over property assignments.
- Laravel resolves the final queue name before the `JobQueued` event, which WildQueue listens to.

### Pattern-Based Worker Spawning

[](#pattern-based-worker-spawning)

With the configuration above:

- ✅ `emails:user-123` - Worker spawned (matches `/^emails:.*/`)
- ✅ `notifications:welcome` - Worker spawned (matches `/^notifications:.*/`)
- ❌ `system:cleanup` - No worker spawned (excluded by `/^system:.*/`)

### Automatic Pruning

[](#automatic-pruning)

The package automatically registers a scheduled task to prune idle workers every minute when `auto_prune` is enabled (default).

Make sure your Laravel scheduler is running:

```
php artisan schedule:run
```

Or add this to your crontab:

```
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
```

### Custom Pruning Schedule

[](#custom-pruning-schedule)

If you want to customize the pruning schedule, set `auto_prune` to `false` and add your own schedule in `app/Console/Kernel.php`:

```
protected function schedule(Schedule $schedule)
{
    $schedule->command('wildqueue:prune')
        ->everyFiveMinutes()
        ->withoutOverlapping();
}
```

### CLI Commands

[](#cli-commands)

- `wildqueue:list` - Show all tracked workers and their status
- `wildqueue:stop {queue}` - Stop a specific worker
- `wildqueue:prune` - Manually prune idle workers
- `wildqueue:work {queue}` - Start a tracked worker for a specific queue
- `wildqueue:debug:dispatch` - Dispatch a test job to a random queue

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

[](#how-it-works)

1. **Job Dispatch**: When you dispatch a job with `->onQueue('queue-name')`, the `JobQueued` event is triggered
2. **Pattern Matching**: The package checks if the queue matches any configured patterns
3. **Cache Check**: If patterns match, checks if a worker for that queue is cached as active (30-second cache)
4. **Worker Spawn**: If no cached worker exists, checks the database and spawns a new worker if needed
5. **Activity Tracking**: The `JobProcessed` event updates the `last_job_at` timestamp for the queue
6. **Automatic Pruning**: Laravel's scheduler runs `wildqueue:prune` every minute to clean up idle workers

Performance Optimizations
-------------------------

[](#performance-optimizations)

- **Caching**: Active workers are cached for 30 seconds to avoid repetitive database queries (time is configurable)
- **Persistent Workers**: Workers don't exit after processing jobs, they continue running
- **Scheduler-Based Pruning**: Uses Laravel's native scheduler for reliable, efficient cleanup
- **Pattern Filtering**: Only spawn workers for queues that match your business logic

Testing
-------

[](#testing)

Test pattern matching:

```
# This should spawn a worker (if emails pattern is enabled)
php artisan tinker --execute="dispatch(new App\Jobs\TestJob())->onQueue('emails:user-123');"

# This should NOT spawn a worker (if system pattern is excluded)
php artisan tinker --execute="dispatch(new App\Jobs\TestJob())->onQueue('system:cleanup');"
```

View active workers:

```
php artisan wildqueue:list
```

Manually prune idle workers:

```
php artisan wildqueue:prune
```

Best Practices
--------------

[](#best-practices)

- Use `onQueue()` for one-off queue assignments
- Use constructor property assignment for consistent queue logic
- Use dynamic methods when queue names depend on model properties or complex logic
- Ensure queue names match your configured patterns in `wildqueue.php`

☕ Support
---------

[](#--support)

To support this project (and my studies) please consider buying a coffee:

[![Buy Me A Coffee](https://camo.githubusercontent.com/c856920e4a7b1cc860a1237dda48a83d7dac5dbeeb9c886c64deed5bed6e7aca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4275792532304d6525323041253230436f666665652d2532334646444430303f7374796c653d666f722d7468652d6261646765266c6f676f3d6275792d6d652d612d636f66666565266c6f676f436f6c6f723d626c61636b)](https://www.buymeacoffee.com/yaelliethy)

License
-------

[](#license)

MIT

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance55

Moderate activity, may be stable

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

308d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2a470f0daa663358bde6553b236eebd49cd3bd8cbb9fada3581057a2c5afb20d?d=identicon)[yaelliethy](/maintainers/yaelliethy)

---

Top Contributors

[![yaelliethy](https://avatars.githubusercontent.com/u/19614722?v=4)](https://github.com/yaelliethy "yaelliethy (12 commits)")

### Embed Badge

![Health badge](/badges/yaelliethy-wildqueue/health.svg)

```
[![Health](https://phpackages.com/badges/yaelliethy-wildqueue/health.svg)](https://phpackages.com/packages/yaelliethy-wildqueue)
```

###  Alternatives

[illuminate/queue

The Illuminate Queue package.

20331.4M1.2k](/packages/illuminate-queue)[spatie/laravel-health

Monitor the health of a Laravel application

86910.0M83](/packages/spatie-laravel-health)[yadahan/laravel-authentication-log

Laravel Authentication Log provides authentication logger and notification for Laravel.

416632.8k5](/packages/yadahan-laravel-authentication-log)[fumeapp/modeltyper

Generate TypeScript interfaces from Laravel Models

196277.9k](/packages/fumeapp-modeltyper)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[palpalani/laravel-sqs-queue-json-reader

Custom SQS queue reader for Laravel

26109.8k](/packages/palpalani-laravel-sqs-queue-json-reader)

PHPackages © 2026

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