Laravel Rabbitmq Laravel Package

Getting Started

This package provides a RabbitMQ queue driver for Laravel, letting you swap the built-in database/redis queue for a broker-backed one without changing your job classes. v1.4.0 is an additive release (new Filament action + optional batch consumption), so it's a drop-in upgrade from v1.3.x.

Minimal path:

1. composer require lettermint/laravel-rabbitmq and publish the config (php artisan vendor:publish --tag="rabbitmq-config" — check the README for the exact tag).
2. Set the connection environment variables (RABBITMQ_HOST, RABBITMQ_PORT, RABBITMQ_USER, RABBITMQ_PASSWORD, RABBITMQ_VHOST) and point Laravel at the driver: QUEUE_CONNECTION=rabbitmq.
3. Register the connection in config/queue.php as a rabbitmq driver entry if the package doesn't auto-inject it.
4. Start a worker: php artisan queue:work rabbitmq.

Where to look first, in order: config/rabbitmq.php (exchange/queue naming, declaration flags, prefetch, DLQ settings), then the package README for the supported connection options, then the test suite — the tests are the most reliable specification of how exchanges, bindings, and dead-lettering are actually wired.

Best first use case: move a single high-throughput or long-running queue (image processing, webhooks, report generation) onto RabbitMQ while leaving the rest of your app on the default driver. Configure a second connection and dispatch with ->onConnection('rabbitmq') so you can compare behaviour before committing.

Implementation Patterns

Per-queue connections, not one global switch. Define several entries in config/queue.php (rabbitmq, rabbitmq-priority, rabbitmq-bulk) that each map to a distinct queue/exchange. This keeps prefetch and retry semantics tunable per workload instead of forcing one global setting.

Routing explicit, not implicit. Always dispatch with onQueue('name') and be deliberate about which exchange/binding the config declares. RabbitMQ's default exchange routes by queue name, which is convenient, but once you introduce a topic or fanout exchange you want that visible in the job dispatch site, not buried in config.

Dead-letter queues as your failure path. Configure the DLX/DLQ in config/rabbitmq.php and let poison messages land there rather than looping. This is the pattern v1.4.0's Filament action is built for: in v1.3.x you inspected and re-queued DLQ messages by hand (or wrote your own Artisan command); in v1.4.0 the Filament resource exposes a retry all action. Day-to-day workflow: watch the DLQ resource, triage the failure, ship the fix, restart workers, then hit retry all to replay the batch.

Retry-all is a replay, so make consumers idempotent. Re-queued messages carry the original payload. Any handler that isn't idempotent (charging a card, sending an email, incrementing a counter) needs a dedupe key or an already_processed guard before you use the bulk retry button in anger.

Batch consumption (v1.4.0) for bulk workloads. The new optional batch consumption mode is aimed at high-volume queues where per-message round-trips dominate. Use it for jobs that are cheap individually and safe to process in a group (indexing, syncs, analytics writes). Leave it off for long-running or memory-hungry jobs — batching amplifies the blast radius of a single failure and changes how acknowledgements are grouped, so a mid-batch exception can redeliver work you already did. Tune the batch size against worker memory, and benchmark before enabling it in production.

Filament integration is opt-in. The retry-all action lives in a Filament panel. Register the package's plugin/resource in your PanelProvider (per the v1.4.0 docs) rather than assuming it appears automatically, and gate the resource behind an authorization policy — it's an operational tool that can replay production messages.

Testing. Use Queue::fake() for dispatch assertions as usual; for driver-specific behaviour (dead-lettering, ack semantics) write integration tests against a real container via Docker or Testcontainers, since the fake bypasses the broker entirely.

Gotchas and Tips

• Prefetch vs. long jobs. A high prefetch count combined with slow jobs starves other workers — messages get pulled into one worker's buffer and sit unacked. Start with a low prefetch and raise it only after watching queue depth and worker utilisation.
• queue:restart after every deploy. Workers hold the old code in memory; RabbitMQ will happily redeliver to a stale consumer. Put the restart in your deploy script, not on a manual checklist.
• Message size limits. RabbitMQ has a practical payload ceiling and Laravel serialises the whole job — avoid SerializesModels on huge graphs and never put file blobs in a payload. Store big artefacts externally and pass an ID.
• Connection lifecycle on idle workers. Long-idle workers can hit broker-side heartbeats/timeouts and die silently. Configure heartbeat and keepalive, and supervise with systemd/Supervisor so a dropped connection restarts the consumer rather than leaving a zombie.
• Declaration is not free. If queue/exchange declaration is enabled in config, mismatched arguments (e.g. changing x-dead-letter-exchange or durability) against an already-declared queue throws PRECONDITION_FAILED. Either delete and redeclare during a maintenance window, or manage topology out-of-band and turn declaration off in production.
• Vhost and permissions. / is not always the vhost in managed offerings (CloudAMQP, Amazon MQ). Permission errors surface as opaque ACCESS_REFUSED — verify the user has configure/write/read on the specific vhost, not just the broker.
• DLQ growth is invisible by default. Without an alert on DLQ depth, failures accumulate silently until someone opens the Filament panel. Add a depth check to your monitoring; the new retry-all button is a recovery tool, not a detection one.
• Two retry mechanisms coexist. Laravel's failed_jobs table and the broker's DLQ are separate stores. Decide which is authoritative per connection — mixing them makes "where did the failed job go?" a genuinely hard question at 3am.
• Debugging tip: when a message vanishes, check exchange bindings before touching application code. rabbitmqctl list_bindings and list_queues name messages_ready messages_unacknowledged will tell you in seconds whether the problem is routing or consumption.
• Extension points: the driver's connector and the queue/job classes are the natural seams for custom behaviour (custom ack handling, correlation-ID propagation for tracing). Prefer wrapping dispatches in a helper over forking the package.