Sqs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require async-aws/sqs
   

   Ensure aws/aws-sdk-php is installed (dependency).

2. Basic Configuration: Add AWS credentials to .env:

   AWS_ACCESS_KEY_ID=your_key
   AWS_SECRET_ACCESS_KEY=your_secret
   AWS_DEFAULT_REGION=us-east-1
   

3. First Use Case: Send a message to a queue:

   use AsyncAws\Sqs\SqsClient;
   
   $client = new SqsClient();
   $result = $client->sendMessage([
       'QueueUrl' => 'https://sqs.us-east-1.amazonaws.com/1234567890/my-queue',
       'MessageBody' => 'Hello, SQS!',
   ]);
   

4. Where to Look First:

   • Package Docs (if available).
   • AsyncAws\Sqs\SqsClient class for core methods.
   • config/sqs.php (if provided) for default configurations.

Implementation Patterns

Core Workflows

1. Sending Messages:

   $client->sendMessage([
       'QueueUrl' => '...',
       'MessageBody' => '...',
       'MessageAttributes' => [ // Optional
           'Author' => ['StringValue' => 'John Doe', 'DataType' => 'String'],
       ],
   ]);
   

2. Receiving Messages:

   $messages = $client->receiveMessage([
       'QueueUrl' => '...',
       'MaxNumberOfMessages' => 10,
       'WaitTimeSeconds' => 20, // Long polling
   ]);
   

3. Batch Operations:

   $client->sendMessageBatch([
       'QueueUrl' => '...',
       'Entries' => [
           ['Id' => '1', 'MessageBody' => 'Batch Message 1'],
           ['Id' => '2', 'MessageBody' => 'Batch Message 2'],
       ],
   ]);
   

4. Queue Management:

   // Create queue
   $client->createQueue(['QueueName' => 'my-new-queue']);
   
   // Delete queue
   $client->deleteQueue(['QueueUrl' => '...']);
   

Integration Tips

• Laravel Service Provider: Bind the client in AppServiceProvider for dependency injection:

  $this->app->singleton(SqsClient::class, function () {
      return new SqsClient();
  });
  

• Queue Workers: Use with Laravel's queue system for async processing:

  $client->receiveMessage(['QueueUrl' => '...'])->then(function ($messages) {
      foreach ($messages['Messages'] as $message) {
          // Process message
          $client->deleteMessage([
              'QueueUrl' => '...',
              'ReceiptHandle' => $message['ReceiptHandle'],
          ]);
      }
  });
  

• Error Handling: Wrap calls in try-catch for AWS-specific exceptions:

  try {
      $client->sendMessage(...);
  } catch (\AsyncAws\Core\Exception\AwsException $e) {
      Log::error('SQS Error: ' . $e->getAwsErrorMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Visibility Timeout:

   • If not handled, messages may reappear in the queue after VisibilityTimeout expires.
   • Always delete messages after processing:

     $client->deleteMessage(['QueueUrl' => '...', 'ReceiptHandle' => $handle]);
     

2. Long Polling:

   • WaitTimeSeconds must be between 1 and 20 seconds. Default is 0 (short polling).
   • Long polling reduces empty responses but increases latency.

3. Message Size Limits:

   • SQS enforces a 256 KB message size limit. For larger payloads, use S3 or compress data.

4. Queue URLs:

   • URLs are region-specific. Ensure AWS_DEFAULT_REGION matches the queue's region.

5. Batch Failures:

   • If any entry in a batch fails, the entire batch is rejected. Handle failures gracefully:

     $result = $client->sendMessageBatch(...);
     if (isset($result['Failed'])) {
         Log::error('Batch failures:', $result['Failed']);
     }
     

Debugging

• Enable Debugging: Configure the AWS SDK for verbose logging:

  $client = new SqsClient([
      'debug' => true,
      'logger' => new \Monolog\Logger('sqs'),
  ]);
  

• Check IAM Permissions: Ensure the IAM role/user has:

  • sqs:SendMessage
  • sqs:ReceiveMessage
  • sqs:DeleteMessage
  • sqs:GetQueueUrl (if creating queues dynamically).

Extension Points

1. Custom Middleware: Extend the client with middleware for logging, retries, or transformations:

   $client = new SqsClient();
   $client->getMiddlewareStack()->push(function ($handler) {
       return function ($request) {
           // Pre-process request
           $response = $handler($request);
           // Post-process response
           return $response;
       };
   });
   

2. Queue Factories: Create a factory class to abstract queue URLs and configurations:

   class SqsQueueFactory {
       public static function getQueueUrl(string $name): string {
           return "https://sqs.{region}.amazonaws.com/{account-id}/{$name}";
       }
   }
   

3. Event Dispatching: Trigger Laravel events on SQS actions (e.g., MessageSent, MessageProcessed):

   event(new MessageSent($message));