- What does mxl/laravel-queue-rate-limit actually do?
- It adds per-queue rate limiting to Laravel's queue worker, capping how many jobs from a given queue are processed within a configured time window. Limits are defined in your queue configuration, so you can give each queue its own throughput ceiling. The goal is to stop job bursts from overwhelming external APIs or downstream services.
- How do I install and configure the package in Laravel?
- Install it with Composer, typically via composer require mxl/laravel-queue-rate-limit, then add rate limit settings to your queue configuration file for each queue you want to throttle. The package hooks into the standard queue worker lifecycle, so you keep using queue:work as usual. Check the repository README for the exact config keys and supported versions before wiring it into production.
- Which queue drivers and rate limiter backends are supported?
- The package targets the standard Laravel queue stack and relies on a shared rate-limiter store such as Redis or the cache backend. It is commonly used with Redis, database, and SQS-style queues. Before adopting it, confirm your specific Laravel version, PHP version, driver, and limiter store are inside the package's supported matrix.
- Which Laravel and PHP versions does the package support?
- Support depends on the release line, so verify the composer.json constraints in the repository against your application's Laravel and PHP versions. The 3.6.1 release is a patch-level change with no new configuration or public API surface. Always confirm the compatibility matrix before upgrading in a production project.
- How does it interact with queue:work --stop-when-empty?
- In version 3.6.1, a worker started with --stop-when-empty no longer exits when the only remaining jobs are held behind an active rate-limit window. Instead it waits for the nearest window and then retries the job. Empty-queue exit behavior and multi-queue processing order are explicitly preserved. This matters for cron drains, CI jobs, and Kubernetes Jobs that previously assumed prompt process exit.
- Will upgrading to 3.6.1 change worker runtime behavior in production?
- Yes, potentially. The upgrade is a drop-in Composer bump with no migrations or config publishing, but the semantic fix means workers can live longer than before when jobs are rate limited. Any orchestration that expects fast exit, such as Supervisor stopwaitsecs, deploy scripts, or CI steps, should be re-validated in staging first. Reproduce a rate-limited pending-queue scenario and confirm the worker waits and then drains.
- Can a worker block indefinitely while waiting on a rate limit window?
- The documented change waits for the nearest rate-limit window and then retries, and the wait is bounded by that window in normal operation. However, if the limiter never releases, a worker could sit longer than your orchestration expects. Test how the wait interacts with --max-time, --timeout, --sleep, and --tries, and add your own guard where scripts previously assumed a quick exit.
- Is the new wait behavior configurable or opt-out?
- Based on the 3.6.1 release notes, the wait behavior is the corrected default rather than an opt-in flag, and no new configuration options are introduced. Treat it as unconditional for that version line. If you need the old exit semantics, the practical rollback is pinning back to the previous 3.6.x release.
- Does it work with Laravel Horizon and custom queue workers?
- Confirm this with the package maintainers or source, since Horizon manages workers differently from raw queue:work and may or may not exercise the same code path. Custom commands or packages that decorate queue:work, such as tenancy-aware queue packages or orchestration shims parsing exit codes, are the most likely source of indirect incompatibility. Test Horizon-managed workers separately before rolling out.
- How should I test and roll out an upgrade safely?
- Inventory every invocation of queue:work --stop-when-empty across cron, CI, deploy scripts, and Kubernetes Jobs. Upgrade in staging, reproduce a rate-limited pending-queue scenario, and verify the worker waits and drains rather than exiting. Update runbooks and deployment scripts to tolerate longer-lived workers, then roll out during a low-traffic window and monitor worker lifetime and drain latency for one cycle. Rollback is a simple version pin.