Rabbitmq Laravel Package

Getting Started

Read this first: almatar/rabbitmq is [DEPRECATED] and the repository is archived (4 stars, 0 dependents). The deprecation was formalised in v1.2.0 (PR "chore: deprecate package and add migration guide"), whose own description points you to vladimir-yuldashev/laravel-queue-rabbitmq. v1.2.0 ships an in-repo migration guide — read it before anything else in this assessment. Treat the rest of this page as "how the package was used day-to-day" and as a complement to that guide, not as a reason to start a new project on it.

1. Confirm you actually need it. If all you want is a RabbitMQ-backed Laravel queue driver (Queue::push, queue:work), the maintained successor is the right tool. This package is lower-level: it wraps php-amqplib so you can publish and consume arbitrary AMQP messages outside Laravel's queue abstraction.
2. Install (pin the version explicitly — releases are effectively frozen, and v1.2.0 is the last meaningful one):

   composer require almatar/rabbitmq:^1.2
   

   Pin ^1.2 rather than ^1.0 so you actually receive the deprecation notice and the bundled migration guide.
3. Read the migration guide that v1.2.0 added. It lives in the package repo (typically MIGRATION.md / docs/ — confirm the exact path against the v1.2.0 tag). This is now the most valuable artefact in the repository; skim it before writing code, because it tells you which of your intended usages are already solved by the successor package.
4. Publish the config so you have a local config/rabbitmq.php to inspect:

   php artisan vendor:publish --provider="Almatar\RabbitMQ\RabbitMQServiceProvider"
   

   Read the generated file end-to-end before writing code. It is the source of truth for connection keys (host, port, credentials, vhost) and exchange/queue names.
5. Wire credentials through env, never the config file:

   RABBITMQ_HOST=127.0.0.1
   RABBITMQ_PORT=5672
   RABBITMQ_USER=guest
   RABBITMQ_PASSWORD=guest
   RABBITMQ_VHOST=/
   

6. Register the provider. Recent Laravel versions may auto-discover it; Lumen requires manual registration in bootstrap/app.php:

   $app->register(Almatar\RabbitMQ\RabbitMQServiceProvider::class);
   

   If a facade is shipped, alias it in config/app.php (Laravel) or $app->withFacades() (Lumen). Verify the exact class names against the package source — even with the new migration guide, the general docs are thin.
7. First use case: publish a single message to a known exchange and confirm it with the RabbitMQ management UI before writing any consumer code. Getting publish working end-to-end first separates connection/auth problems from consumption problems.

Implementation Patterns

Fire-and-forget publishing from a service class. Inject or resolve the package's connection/facade and publish after your domain logic commits. Keep publishing out of controllers — wrap it in a small MessagePublisher service so the AMQP client doesn't leak across your codebase and so you have one place to swap in the successor package later.

Publish after commit, not inside the transaction. If you publish inside a DB transaction that later rolls back, downstream consumers act on data that never existed. Use DB::afterCommit(...) (or an event listener) to defer the publish.

Long-running consumers as Artisan commands. The idiomatic pattern is a custom command (php artisan rabbitmq:consume) that boots the connection once and loops over deliveries, dispatching to handlers. Register it in Kernel::$commands (Laravel) or $app->command() (Lumen), and run it under Supervisor with numprocs > 1 for throughput. This is where the package earns its keep: you get raw AMQP semantics — manual ack/nack, prefetch/QoS, dead-lettering — that the queue driver hides from you.

Handler-per-message-type. Map routing keys to small invokable handler classes rather than a switch inside the consumer. It keeps the consumer loop stable while message types evolve, and makes handlers trivially unit-testable with a plain array payload.

Integration with Laravel events. A clean seam is: consumer command receives a delivery → dispatches a domain event or job → Laravel's own queue/event system handles the rest. This lets you keep AMQP only at the system boundary (interop with other services) and use native Laravel tooling internally.

Topology declaration in one place. Declare exchanges, queues, and bindings in a bootstrap/setup command rather than lazily in consumers. Consumers that declare topology at runtime race each other and produce confusing PRECONDITION_FAILED errors when parameters differ.

Testing. Don't hit a broker in unit tests. Bind a fake publisher into the container and assert messages were "sent"; reserve a real broker (Testcontainers/docker-compose) for a thin integration suite covering publish→consume→ack.

Gotchas and Tips

• The biggest gotcha is the package's status — now explicit in v1.2.0. Archived + deprecated + 0 dependents means: no security patches, no compatibility work for new PHP/Laravel versions, and php-amqplib major-version bumps will eventually break it. Plan the migration to vladimir-yuldashev/laravel-queue-rabbitmq (or direct php-amqplib) as part of adoption, not as a later cleanup. If you must keep it, fork it and pin every transitive dependency.
• v1.2.0 is a docs-only release — nothing breaks, nothing improves. The changelog is a single chore: commit adding the deprecation notice and migration guide. Do not expect bug fixes, PHP/Laravel support bumps, or php-amqplib compatibility work in it. Budget zero time for "upgrade testing" and all of it for reading the guide.
• Use the new migration guide as your contract. Because v1.2.0 documents the intended successor path, map each of your usages to a line in that guide. Where the guide has no answer (usually raw consume loops with custom QoS/DLX), that is the code you will have to own — write it behind an adapter now.
• Config caching bites hard. php artisan config:cache freezes config/rabbitmq.php; env changes silently have no effect until you re-cache. This is the #1 cause of "it works locally, not in staging."
• Lumen needs explicit everything — provider, facade, and command registration. There is no auto-discovery. Budget time for this; most "package doesn't work" reports on small packages are Lumen wiring issues.
• Connection lifetime. php-amqplib connections are not automatically resilient. In long-running consumers, a broker restart or idle timeout leaves you with a dead socket and a process that appears healthy. Wrap the consume loop with reconnect-with-backoff, and set heartbeats/timeouts explicitly in config.
• Ack before you finish, and you lose messages. Ack only after the handler succeeds; nack (with requeue where appropriate) on exception. Without a dead-letter exchange configured, poison messages will loop forever — configure DLX/DLQ up front.
• Set prefetch/QoS. The default lets the broker push unlimited unacked messages to a consumer; one slow handler then starves the others. A small prefetch (e.g. 10) is almost always what you want.
• Idempotency is on you. AMQP is at-least-once. Design handlers to tolerate redelivery (dedupe keys, upserts), because they will see duplicates.
• Don't reuse a channel across threads/processes. One connection per process, one channel per consumer; sharing across forked workers corrupts framing and produces bizarre protocol errors.
• Debugging order of operations: (1) can php-amqplib connect at all with the same credentials outside Laravel? (2) does the exchange/queue exist with matching params in the management UI? (3) is config cached? (4) is the supervisor process running the current code (queue:restart-style restart after deploys)?
• Extension points are limited. With an archived package, treat it as glue you own: keep a thin adapter interface (publish, consume) in your app so the underlying library is swappable, and avoid letting the package's facade appear in domain code. Combined with the v1.2.0 migration guide, that single abstraction is what makes the eventual migration a one-file change rather than a refactor.