Upgrading from v2 to v3

Version 3 is a ground-up redesign that introduces genuine forecasting, spawn-latency compensation, and p95-based SLA signals. This guide walks through the upgrade.

v3.3.0 — fractional CPU cores

v3.3.0 bumps cboxdk/laravel-queue-metrics to ^3.0 (which pulls cboxdk/system-metrics v3). Two type changes on ClusterManagerState:

• $cpuCores: int → float
• $cpuUsableCores: int → float (computed from total_cores - reserve_cores)
• $cpuReservedCores stays int — this is a user-configured whole-core reservation

If you read these fields directly (e.g. in a custom dashboard or event listener), update your type expectations. The cluster summary payload fields cpu_cores and cpu_usable_cores may now contain values like 0.5 in cgroup-constrained environments.

No config changes, no migration step.

Step 1 — Update the package

composer require cboxdk/laravel-queue-autoscale:^3.0

Step 2 — Migrate the config file

php artisan queue-autoscale:migrate-config

This writes config/queue-autoscale.v3.php next to your current file. Review and replace.

Step 3 — Update code references

Step 4 — Verify

Run your test suite. The package now uses p95 pickup time over a sliding window, compensated for measured worker spawn latency. You do not need to do anything to benefit from forecasting — it activates automatically when your arrival rate history has 5+ samples and a high enough R² under the configured policy.

What's New in v3

Three new topology capabilities, each additive and optional:

excluded — leave these queues alone

Use when Horizon or another supervisor already manages a queue, or for throwaway migration queues. Glob patterns via fnmatch.

'excluded' => ['horizon-managed', 'legacy-*'],

groups — multi-queue workers with strict priority

When several queues share a workload budget and you want idle workers in one to absorb bursts on another, declare a group. Each worker runs queue:work --queue=a,b,c with Laravel's per-poll priority semantics.

'groups' => [
    'notifications' => [
        'queues'  => ['email', 'sms', 'push'],
        'profile' => BalancedProfile::class,
    ],
],

A queue may appear in queues OR in a group's queues list — never both. Startup validation enforces this.

ExclusiveProfile — pinned single-threaded queues

For queues that must process jobs sequentially (customer integrations, non-thread-safe APIs), use the new profile. The package becomes a process supervisor for the queue: exactly one live worker, respawned on death, never scaled.

'queues' => [
    'legacy-integration' => ExclusiveProfile::class,
],

See Queue Topology for the conceptual model and decision guidance, and Configuration for the config reference.

Customising the pipeline

Every algorithm is class-replaceable. For example, to use your own forecaster:

// In AppServiceProvider::register()
$this->app->bind(
    \Cbox\LaravelQueueAutoscale\Contracts\ForecasterContract::class,
    \App\MyCustomForecaster::class,
);

See Custom Strategies for the public extension points.