README

A Laravel-first RabbitMQ wrapper that auto-configures dead-letter retry queues so you can focus on writing your handlers—no boilerplate required! 🎉

🚀 Installation

# 1️⃣ Install via Composer
composer require howincodes/laravel-rabbitmq

# 2️⃣ Publish the default config
php artisan vendor:publish \
  --provider="HowinCodes\RabbitMQ\RabbitMQServiceProvider" \
  --tag="config"

This publishes config/rabbitmq.php into your app.

⚙️ Configuration

Open config/rabbitmq.php and you’ll see:

return [

    // 🖥️ Broker Connection
    'host'     => env('RABBITMQ_HOST', '127.0.0.1'),
    'port'     => env('RABBITMQ_PORT', 5672),
    'user'     => env('RABBITMQ_USER', 'guest'),
    'password' => env('RABBITMQ_PASSWORD', 'guest'),
    'vhost'    => env('RABBITMQ_VHOST', '/'),

    // 🔄 Base exchanges
    'exchanges' => [
        'tasks' => [
            'type'    => 'topic',
            'durable' => true,
        ],
        // add your own exchanges here...
    ],

    // 📬 Queues + Retry settings
    'queues' => [
        'tasks' => [
            'exchange'     => 'tasks',
            'routing_keys' => ['task.created'],
            'durable'      => true,
            'consume'      => true,

            // ⚙️ Enable retry logic
            'retry'        => [
                'enabled'      => true,
                'max_attempts' => 5,      # total tries before giving up
                'interval'     => 15000,  # wait 15s before retry (ms)
            ],
        ],
        // `tasks.retry` auto-generated by the package
    ],

    // 🛠️ Map queue names → handler classes
    'queue_handlers' => [
        'tasks'       => HowinCodes\RabbitMQ\Handlers\GenericHandler::class,
        'tasks.retry' => HowinCodes\RabbitMQ\Handlers\GenericRetryHandler::class,
    ],
];

Tip: Feel free to rename tasks to anything—each base queue can have its own retry block!

📚 How It Works

1. Declare your base queue

   • One config block, no need to manually define DLX or retry queue.

2. Package auto-generates

   • <exchange>.retry exchange
   • <queue>.retry queue with TTL & DLX back to your base exchange

3. Handlers

   • GenericHandler processes the main queue.
   • GenericRetryHandler processes messages after they exceed retries.

🎨 Usage

1. Publishing a Message

use HowinCodes\RabbitMQ\Publisher;

app(Publisher::class)
    ->publish('tasks', 'task.created', [
        'id'      => 123,
        'payload' => ['foo' => 'bar'],
    ]);

💡 The tasks exchange is declared automatically.

2. Running the Consumer

php artisan rabbitmq:consume-queues

✔️ Listens on both tasks and tasks.retry queues 🛠️ Dispatches to GenericHandler & GenericRetryHandler

🧑‍🤝‍🧑 Examples

A. Tasks Queue (Default)

• Exchange: tasks

• Queue: tasks → retry to tasks.retry

• Handlers:

  • GenericHandler
  • GenericRetryHandler

// config/rabbitmq.php snippet:
'queues' => [
    'tasks' => [
        'exchange'     => 'tasks',
        'routing_keys' => ['task.created'],
        'retry'        => ['enabled'=>true,'max_attempts'=>5,'interval'=>15000],
    ],
],
'queue_handlers' => [
    'tasks'       => GenericHandler::class,
    'tasks.retry' => GenericRetryHandler::class,
],

B. User Events Queue

// config/rabbitmq.php snippet:
'exchanges' => [
    'users' => ['type'=>'topic','durable'=>true],
],
'queues' => [
    'users' => [
        'exchange'     => 'users',
        'routing_keys' => ['user.created','user.updated','user.deleted'],
        'retry'        => ['enabled'=>true,'max_attempts'=>3,'interval'=>10000],
    ],
],
'queue_handlers' => [
    'users'       => GenericHandler::class,
    'users.retry' => GenericRetryHandler::class,
],

Publishing:

app(Publisher::class)
    ->publish('users', 'user.created', [
        'id'    => 456,
        'name'  => 'Alice',
        'email' => 'alice@example.com',
    ]);

Consuming:

php artisan rabbitmq:consume-queues

🛠️ Customization & Advanced

• Custom Handlers: Swap GenericHandler and GenericRetryHandler for your own classes in config/rabbitmq.php.

• Custom DLX Names: Override 'exchange' or 'routing_key' in the retry block.

• Disable Retry: 'retry' => ['enabled' => false] or remove the retry block.

• Monitoring: Use Laravel logging, Sentry, or other APM to track dead-letter flows.

❤️ Thank You!

Thanks for choosing howincodes/laravel-rabbitmq! If you love it, ⭐ star the repo and share your feedback. Happy messaging! 🚀