robuust / laravel-heroku-queue-listener
Laravel package to autoscale Heroku queue workers based on queue events
Package info
github.com/robuust/laravel-heroku-queue-listener
pkg:composer/robuust/laravel-heroku-queue-listener
Requires
- php: ^8.2
- ext-pcntl: *
- illuminate/cache: ^10.0|^11.0|^12.0|^13.0
- illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
- illuminate/events: ^10.0|^11.0|^12.0|^13.0
- illuminate/queue: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
- php-heroku-client/php-heroku-client: ^4.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.0
- dev-feature/monitor-worker-queues
- dev-feature/fix-cached-worker-count
- dev-feature/heroku-control
- dev-feature/release-1-3-0
- dev-fix/require-pcntl
- dev-feature/release-1-2-1
- dev-feature/graceful-worker-shutdown
- dev-feature/add-scaling-based-on-available-jobs
- dev-codex/add-laravel-10-support
This package is auto-updated.
Last update: 2026-11-17 13:47:37 UTC
README
Autoscale Heroku worker dynos based on Laravel queue events.
Installation
composer require robuust/laravel-heroku-queue-listener
The package uses Laravel package auto-discovery.
PCNTL is required for Laravel's queue:work daemon to handle POSIX signals and enforce job timeouts. Heroku's PHP buildpack enables extensions required by dependencies from the application's committed composer.lock on the next build.
If a shell script launches the worker, use exec php artisan queue:work as its final command to replace the shell with PHP. Heroku sends SIGTERM to all processes in a dyno; exec removes the extra shell process.
Configuration
For Heroku Control, set the following environment variables:
HEROKU_CONTROL_URL(the HTTPS gateway base URL)HEROKU_CONTROL_TOKEN(the app or review-pipeline worker credential)HEROKU_APP_NAME
The gateway URL and token must be configured together. Partial or invalid gateway configuration raises a configuration error and never falls back to a legacy credential. Redirects are disabled for gateway requests. Only the worker formation endpoint is used; this package does not request deployment permission.
Existing applications can continue to use HEROKU_API_KEY and HEROKU_APP_NAME
when neither gateway setting is configured. Gateway tokens must not be placed in
HEROKU_API_KEY. To migrate, provision a scoped worker credential outside the
application, configure the gateway pair, and remove HEROKU_API_KEY from that
application after the gateway path is verified. Do not revoke a shared legacy
credential while other applications still use it.
Laravel merges the new heroku_control_url and heroku_control_token defaults
even when an application has an older published configuration file. Republishing
is optional; add those keys from the package's config if you manage them there.
Rebuild Laravel's configuration cache after updating the package and settings
with php artisan config:cache. The listener reads Laravel configuration and
does not access environment variables directly.
Optional:
QUEUE_AUTOSCALER_RELEASE_EVENT(defaults toApp\\Events\\AppReleased)QUEUE_AUTOSCALER_CACHE_KEY(defaults toqueue-autoscaler:current-dynos)QUEUE_AUTOSCALER_CACHE_TTL_SECONDS(defaults to3600)
Publish config if needed:
php artisan vendor:publish --tag=queue-autoscaler-config
Worker queues
The queue-autoscaler.queues setting accepts an array containing queue names and/or null.
It defaults to [null], which monitors the default queue of Laravel's default
queue connection and preserves the existing single-queue behavior. Laravel
merges this default even when an older published configuration omits the key.
Set the list to exactly the queues consumed by your worker. For example, a
worker started with php artisan queue:work --queue=high,default needs:
'queues' => ['high', 'default'],
On the configured release event, the listener requests a worker when any listed
queue has jobs. It stops the worker and scales to zero only when every listed
queue is empty. Queue sizes include reserved and delayed jobs for Laravel's
database and Redis drivers, so those jobs keep the worker alive. The list does
not change the worker's queue priority; set that with queue:work --queue.
Normal JobQueued events continue to request a worker as before. Rebuild the
application's configuration cache after changing the list.
HTTP failures and retries
Each scaling attempt has a 2-second connection timeout. Direct Heroku requests have a 5-second total timeout; gateway requests have a 35-second total timeout, longer than the gateway's 30-second execution limit. The cache lock expires five seconds after the selected request timeout. Redirects are treated as failed requests. There are no sleeps or immediate HTTP retries in the queue event listener. A non-blocking cache lock allows only one scaling request per app at a time. Each event requests its own worker count; concurrent events that cannot acquire the lock return immediately without queuing another request.
Failed requests set a shared exponential cooldown (30, 60, 120, 240, then
300 seconds, with up to 25% jitter, capped at
300 seconds). A valid Retry-After in seconds or HTTP-date format can extend
that cooldown beyond 300 seconds. Success clears the failure count. A later
queue or configured application release event may try again after the cooldown.
A failed request invalidates the cached worker count because a timed-out PATCH
may already have reached Heroku.
The package registers no scheduled tasks and starts no background retry process. It makes requests only in response to existing queue or application release events. Cooldown expiry alone does not trigger a request. If a worker startup fails and no subsequent event occurs after the cooldown, queued work remains waiting until another event retries the scaling request. Likewise, a request skipped because another request holds the lock requires a subsequent event.
The listener requests one worker when jobs are queued and zero when all configured queues are empty, regardless of queue depth.
Use a shared persistent cache supporting atomic locks (for example Redis) across all application dynos. Local file or array caches do not coordinate requests between dynos. State keys are scoped by Heroku app name, under the configured cache key; the previous unscoped cached count is ignored.
Failures log the HTTP status, Request-Id, RateLimit-Remaining, Retry-After
and the retry delay when a response is available. Authenticated requests and
raw exception messages are not included. A timeout by itself does not establish
rate limiting: Heroku documents that as HTTP 429 with the rate_limit error ID.
The Platform API documents RateLimit-Remaining, but does not promise a
Retry-After or rate-limit reset header, so retries also work without them.
References: Heroku Platform API and HTTP Retry-After.