Amqp Rabbit Laravel Queue Laravel Package

Getting Started

This package hooks into Laravel's queue worker lifecycle to give you a first-class Worker::registerTimeoutHandler entry point, so jobs that exceed --timeout are handed to your callback (log, alert, cleanup, mark failed) instead of the worker silently dying.

Minimal steps:

1. composer require <vendor>/<package> — Laravel package auto-discovery registers the service provider; only add it to config/app.php if you have discovery disabled.
2. php artisan vendor:publish --tag=<package>-config (check php artisan vendor:publish for the exact tag) and skim the resulting config file — that file and the provider's boot() method are the two places to look first. The boot() method is where Worker::registerTimeoutHandler is called, which is the single most important line in the package.
3. First use case: register a handler in AppServiceProvider::boot() that logs the job class and queue, then run a deliberately slow job (sleep(120) with --timeout=10) on a local queue and confirm your callback fires.

Sanity-check the installed version against your framework: 2.11.1 fixed the Worker::registerTimeoutHandler call signature for Laravel >=13.31. If you are pinned to an older Laravel, stay on 2.11.0 until you upgrade; if you are on 13.31+, 2.11.1 is the minimum you should run.

Implementation Patterns

Central handler registration. Keep exactly one registration in a service provider rather than per-command, so queue:work, queue:listen, Horizon, and any custom worker command all inherit the same behavior:

// AppServiceProvider::boot()
Worker::registerTimeoutHandler(function ($connectionName, $job) {
    Log::warning('queue.timeout', [
        'connection' => $connectionName,
        'job' => $job->resolveName(),
        'queue' => $job->getQueue(),
        'attempts' => $job->attempts(),
    ]);
});

Treat the handler as an observability seam, not a retry mechanism. The idiomatic use is to push to your alerting path (Sentry/Slack/PagerDuty) and to release side resources (locks, temp files, open transactions). Retries belong to $tries/backoff, not to the timeout handler.

Per-environment behavior. Register nothing but a log line in local, and a real alert plus failed-job marking in production. Branch in the provider on app()->environment() rather than duplicating config across supervisor programs.

Horizon and custom worker commands. If you run Horizon, confirm the package's registration path is actually reached — Horizon constructs its own worker instance. Verify by triggering a timeout in staging and watching for your log line; if it is absent, that is your integration point to fix, not the package.

Testing. Add a feature test that boots the worker with a tiny --timeout, dispatches a job that blocks, and asserts your handler's side effect (a log spy or a fake alert transport). This is the cheapest regression guard you can have for a package whose whole surface is one call site.

Deployment order. Because the fix is a framework-version compatibility patch, roll Laravel and this package in the same deploy, or upgrade this package before crossing 13.31, never after.

Gotchas and Tips

• Version pinning is the real hazard here. 2.11.1 exists solely because the registerTimeoutHandler call changed shape in Laravel 13.31. Mixing Laravel 13.31+ with package 2.11.0 produces an argument/signature error at worker boot — which typically manifests as workers failing to start, not as a clean exception in your logs. Pin both, and check composer why-not when a worker misbehaves after a framework bump.
• retry_after must exceed timeout. This is a queue-level invariant the package cannot enforce for you; violating it causes jobs to be picked up by a second worker while the first is still running, and your timeout handler may never fire at all.
• The handler runs on a signal path. Keep it fast and non-throwing. Do not do I/O-heavy work, dispatch chained jobs, or open DB transactions inside it — an exception there can mask the original timeout and leave the worker in a bad state.
• PCNTL matters. Signal-based timeout handling requires ext-pcntl and a non-Windows host. If the handler appears to be a no-op on one environment but works elsewhere, check extensions and --timeout values before blaming the package.
• Horizon inherits, it does not mirror. Timeout values set in config/horizon.php supersede CLI flags; a handler that never fires is more often a Horizon config mismatch than a package bug.
• Config caching. Run php artisan config:clear after publishing or editing the config; config:cache during deploy is the usual culprit for "the handler ignores my settings."
• Debugging order: (1) composer show <vendor>/<package> to confirm 2.11.1, (2) php -m | grep pcntl, (3) queue:work -v with a blocking job, (4) grep your provider for the registration line, (5) check Horizon/supervisor overrides. That sequence resolves the overwhelming majority of timeout-handler reports.
• Extension points. If the package exposes a contract or event alongside the handler callback, prefer binding to that over subclassing the worker — subclassing breaks the moment Laravel touches the worker's timeout internals again, which is exactly what 2.11.1 was patching around.