Requirements
Requirements
Before installing Queue Autoscale for Laravel, ensure your environment meets these prerequisites.
Runtime
| Requirement | Version |
|---|---|
| PHP | 8.4 or 8.5 |
| Laravel | 12.0+ or 13.0+ |
| Composer | Latest version recommended |
PHP Extensions
| Extension | Required | Why |
|---|---|---|
ext-pcntl |
Yes | The manager installs signal handlers so it can shut down gracefully instead of orphaning its workers. |
ext-posix |
Yes | Worker termination and the manager process lock deliver signals by PID. |
ext-mbstring |
Yes | Worker output is truncated on a character boundary, so a multibyte character straddling the cap cannot put invalid UTF-8 into the log channel. |
phpredis or predis/predis |
Cluster mode only | Redis connectivity for leader election and cross-host coordination. |
Both required extensions are enforced by Composer. They are present in most PHP CLI builds but are commonly absent from the official php:*-fpm and Alpine Docker images — build them in, or the manager will fail to start.
Package Dependencies
These are installed automatically via Composer:
| Package | Version | Purpose |
|---|---|---|
cboxdk/laravel-queue-metrics |
^3.0 | Queue discovery and metrics collection |
cboxdk/system-metrics |
^3.0 (via queue-metrics) | CPU and memory monitoring for resource-aware scaling |
symfony/process |
^7.0 | ^8.0 | Worker process spawning and management |
spatie/laravel-package-tools |
^1.16 | Service provider conventions |
Infrastructure
Redis (optional)
Redis is not required for single-host autoscaling. The package works with any Laravel-supported queue driver (database, sqs, redis, etc.).
redis, database and sqs are covered by tests. The SQS specs run against
ElasticMQ, which speaks the SQS wire protocol, and cover
depth reading through the metrics facade end to end:
docker run -d --name autoscale-elasticmq -p 9324:9324 softwaremill/elasticmq-native:1.6.11
They skip when it is not running, so the default suite needs nothing installed.
Redis is required when:
- Cluster mode is enabled (multi-host coordination, leader election, heartbeats)
- You want Redis-backed predictive signals on a single host (pickup-time percentiles, spawn-latency tracking)
See Installation for deployment shape options.
Process Supervisor (production)
In production, use Supervisor or systemd to keep the php artisan queue:autoscale manager process running and to restart it on failure. The autoscale manager replaces manual queue:work process management — you do not need Supervisor entries for individual queue workers.
See Deployment for platform-specific setup.
SLA Timing Floor
The autoscaler operates within the timing constraints of Laravel's queue worker internals. There is a hard floor on how fast jobs can be picked up:
~3-5 seconds minimum pickup time — even with a running worker, Laravel's queue:work command has an internal sleep/poll loop (sleep_seconds, default 3s) plus job pickup overhead. SLA targets below 5 seconds will produce flaky breach events. This is expected behaviour, not a bug.
~8-12 seconds from zero — profiles with workers.min = 0 add the evaluation interval (default 5s) and worker spawn latency on top of the poll floor.
Setting sla.target_seconds below 5 is not recommended. See Understanding SLA Timing for the full explanation.
Next Steps
Ready to install? Follow the Installation guide.