Laravel Rabbitmq Laravel Package

Getting Started

1. Install and publish config — require the package, then publish its config (php artisan vendor:publish) and review the connection, exchange, queue, and consumer settings first. The config file is the primary source of truth for how consumers bind and run.
2. Locate the consumer command — most day-to-day work flows through BaseConsumerCommand. Your application should extend it (or use the provided command) rather than calling the underlying AMQP library directly. Look at how it resolves exchanges, queues, and message processors before writing new consumers.
3. Create a first message processor — implement the processor/handler interface the package expects for a single routing key or queue, register it in config, and run the consumer locally with php artisan <consumer-command> to confirm binding and message flow.
4. First real use case — start with a low-risk queue (e.g. notifications or audit events) and a single processor. Verify:
   • the exchange and queue are declared/bound,
   • a test message is consumed,
   • failures appear in storage/logs/laravel.log, not just the terminal.

As of v0.5.1, setup failures such as an inability to bind to an exchange are re-thrown by BaseConsumerCommand, so Laravel’s exception handler and logging stack can report them. That makes the first local run a better smoke test for misconfigured exchanges and credentials.

Implementation Patterns

• Extend BaseConsumerCommand for each consumer group. Keep command classes thin: define which queue/exchange to consume and which processors to register, then delegate business logic to dedicated processor classes.
• One processor per message type or routing key. This keeps retry/failure behaviour predictable and makes it easy to unit test processors without running a full consumer.
• Let setup exceptions bubble. Since v0.5.1, BaseConsumerCommand re-throws exceptions raised before a message processor runs. Do not wrap parent::handle() in a broad try/catch that swallows binding or connection errors; otherwise you recreate the old CLI-only visibility problem in your own command.
• Supervisor-friendly deployment. Run consumers under Supervisor/systemd with stdout/stderr suppressed or rotated. Rely on Laravel’s logging for operational errors, but keep supervisor logs for process crashes. With v0.5.1, binding failures reach Laravel’s log channel, so your monitoring/alerting on laravel.log will catch exchange/queue misconfiguration even when supervisor captures nothing useful.
• Separate local CLI from production supervision. Locally, run php artisan <consumer> in the foreground and watch both terminal output and laravel.log. In production, configure the same command with --no-interaction-style flags where available and verify that a deliberately bad exchange name produces a Laravel log entry.
• Processor-level error handling. Catch only expected domain exceptions inside processors; allow unexpected exceptions to propagate so the package/queue can decide whether to reject, requeue, or fail the message. Log with context (queue, routing key, message id) inside the processor.
• Bind configuration to environments. Keep exchange/queue names in config or env vars, especially if staging and production share a broker. Test binding failures in staging by pointing at a non-existent exchange; v0.5.1 should surface that in Laravel’s logs.

Gotchas and Tips

• v0.5.1 behaviour change: setup exceptions are re-thrown. Previously, failures before a message processor (for example, failing to bind to an exchange) were only visible in CLI output. Under a supervisor that suppresses logs, those errors were effectively silent. Now they fall back to Laravel’s exception handler and logging. Ensure your logging.php channels and ExceptionHandler are configured for the consumer environment.
• Watch for duplicate reporting. If you already catch and report exceptions in your own command or processor, the re-thrown setup exception may now be logged twice. Remove broad catches around parent::handle() and let Laravel report setup errors.
• Supervisor log suppression is no longer a blind spot for setup failures. Do not “fix” missing logs by adding 2>&1 to Supervisor and calling it done; use Laravel’s log stack. But keep supervisor stderr capture for fatal PHP errors and process-level crashes.
• Debugging binding failures: check broker credentials, vhost, exchange name, exchange type, queue name, routing key, and whether the exchange is declared elsewhere. A typo in any of these can now appear in laravel.log as a thrown exception, so search there first.
• Local versus supervised execution: a command that looks fine in the terminal may still fail under Supervisor due to environment variables, working directory, or user permissions. Reproduce with the same user and env as Supervisor before assuming a code issue.
• Extension point: if you need custom reporting for setup failures, override the relevant hook in your command subclass or configure Laravel’s exception handler/reporting rather than catching exceptions in the consumer loop. Keep the re-throw behaviour intact.
• Don’t treat v0.5.1 as a retry/requeue change. It improves error visibility for pre-processor failures; message-level failures and queue semantics are still governed by your processor and package configuration.