Iron Mq Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require iron-io/iron_mq
   

   Add your IronMQ credentials to .env:

   IRONMQ_PROJECT_ID=your_project_id
   IRONMQ_TOKEN=your_token
   

2. First Use Case: Publishing a Message

   use IronMQ\IronMQ;
   
   $mq = new IronMQ(config('ironmq.project_id'), config('ironmq.token'));
   $mq->post('queue_name', 'Hello, IronMQ!');
   

3. Where to Look First

   • Official PHP Client Docs
   • examples/ in the GitHub repo for quick-start snippets
   • src/IronMQ.php for core class methods

Implementation Patterns

Core Workflows

1. Producer Pattern

   $mq = new IronMQ(config('ironmq.project_id'), config('ironmq.token'));
   $mq->post('orders', json_encode(['order_id' => 123, 'status' => 'pending']));
   

2. Consumer Pattern (Blocking)

   $mq = new IronMQ(config('ironmq.project_id'), config('ironmq.token'));
   $message = $mq->peek('orders'); // Non-blocking
   if ($message) {
       $mq->pop('orders', $message->id); // Remove from queue
       processOrder($message->body);
   }
   

3. Delayed Messages

   $mq->post('delayed_queue', 'Process later', 30); // Delay in seconds
   

4. Error Handling & Retries

   try {
       $mq->post('critical_queue', 'Important data');
   } catch (IronMQException $e) {
       // Log and retry with exponential backoff
       sleep(2 ** $attempt);
   }
   

Integration Tips

• Laravel Queue Integration Extend Illuminate\Queue\Queue to wrap IronMQ calls:

  class IronMQQueue extends Queue implements QueueContract {
      public function push($job, $data, $queue = null) {
          $mq = new IronMQ(config('ironmq.project_id'), config('ironmq.token'));
          $mq->post($queue ?: 'default', $data);
      }
  }
  

• Event-Driven Architecture Use IronMQ for async event publishing:

  event(new OrderCreated($order));
  // In a separate worker:
  $mq->peek('order_events')->then(function ($msg) {
      $event = json_decode($msg->body);
      // Handle event
  });
  

• Monitoring & Metrics Track queue stats via:

  $stats = $mq->stats('queue_name');
  logger()->info("Queue length: {$stats['messages']}");
  

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • IronMQ may throttle requests. Implement retry logic with jitter:

     $retryAfter = $e->getRetryAfter() ?: 1;
     sleep($retryAfter + rand(0, 100) / 100);
     

2. Message Size Limits

   • IronMQ enforces a 1MB payload limit. For larger data, use:
     • Base64 encoding + external storage (S3, etc.).
     • Chunking messages (e.g., split into part_1, part_2).

3. Visibility Timeouts

   • Messages are invisible to consumers for 60 seconds by default. Adjust with:

     $mq->pop('queue', $msgId, 300); // 5-minute visibility
     

4. Token Expiry

   • IronMQ tokens expire. Rotate them via:

     ironmq token create --project-id=your_id --description="PHP Worker Token"
     

Debugging

• Enable Debug Mode

  $mq = new IronMQ($projectId, $token, ['debug' => true]);
  

  Logs HTTP requests/responses to stderr.

• Common HTTP Errors

  Error Code	Cause	Fix
  401	Invalid token/project ID	Verify .env credentials
  404	Queue doesn’t exist	Create queue via dashboard
  429	Rate limited	Add delays between requests

Extension Points

1. Custom Middleware Add pre/post-processing to messages:

   $mq->setMiddleware(function ($msg) {
       $msg->body = gzdecode($msg->body); // Auto-decompress
   });
   

2. Webhook Integration Use IronMQ’s webhooks to trigger external actions:

   $mq->post('webhook_queue', 'Trigger webhook', 0, [
       'webhook_url' => 'https://your-app.com/hook'
   ]);
   

3. Queue Prioritization Simulate priority queues with suffixes:

   $mq->post('orders_high', $data); // High-priority
   $mq->post('orders_low', $data);  // Low-priority
   

4. Local Testing Use the IronMQ Sandbox for testing:

   IRONMQ_PROJECT_ID=sandbox
   IRONMQ_TOKEN=sandbox_token