Sns Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require enqueue/sns
   

   Requires php-enqueue/amqp-ext or php-enqueue/amqp-lib for AWS SDK compatibility.

2. First Use Case: Sending a Message

   use Enqueue\Sns\SnsConnectionFactory;
   use Enqueue\Sns\SnsContext;
   
   $factory = new SnsConnectionFactory(
       new \Aws\Sns\SnsClient([
           'version' => 'latest',
           'region'  => 'us-east-1',
           'credentials' => [
               'key'    => 'YOUR_AWS_KEY',
               'secret' => 'YOUR_AWS_SECRET',
           ],
       ])
   );
   
   $connection = $factory->createContext();
   $producer = $connection->createProducer();
   
   $producer->send(new \Enqueue\Message\Message('Hello SNS!', ['topic' => 'my-topic']));
   

3. Key Files to Review

   • src/SnsConnectionFactory.php (Connection setup)
   • src/SnsContext.php (Context management)
   • src/SnsProducer.php (Message publishing)
   • src/SnsConsumer.php (Message consumption)

Implementation Patterns

Common Workflows

1. Producer Workflow

   $producer = $connection->createProducer();
   $producer->send(new Message('Data', [
       'topic' => 'my-topic',
       'attributes' => ['priority' => 'high']
   ]));
   

2. Consumer Workflow (Polling)

   $consumer = $connection->createConsumer('my-topic');
   $consumer->setMessageHandler(function ($message) {
       // Process message
       $message->ack();
   });
   $consumer->consume();
   

3. Batch Publishing

   $batchProducer = $connection->createBatchProducer();
   $batchProducer->sendBatch([
       new Message('Batch 1'),
       new Message('Batch 2'),
   ]);
   

Integration Tips

• Laravel Queue Integration Add to config/queue.php:

  'sns' => [
      'driver' => 'sns',
      'connection' => 'sns',
      'queue' => 'default',
      'options' => [
          'region' => env('AWS_REGION'),
          'credentials' => [
              'key' => env('AWS_KEY'),
              'secret' => env('AWS_SECRET'),
          ],
      ],
  ],
  

  Then bind in AppServiceProvider:

  Queue::extend('sns', function ($app) {
      $factory = new SnsConnectionFactory(
          new \Aws\Sns\SnsClient($app['config']['queue.sns.options'])
      );
      return $factory->createContext();
  });
  

• Retry Logic Use Enqueue\Retry\RetryContext for transient failures:

  $retryContext = new RetryContext($connection);
  $producer = $retryContext->createProducer();
  

• Message Serialization Customize serialization via MessageConverter:

  $converter = new \Enqueue\MessageConverter\JsonMessageConverter();
  $producer = $connection->createProducer($converter);
  

Gotchas and Tips

Pitfalls

1. AWS Credentials

   • Hardcoding credentials is unsafe. Use environment variables or AWS IAM roles.
   • Ensure the IAM user has SNS:Publish and SNS:Subscribe permissions.

2. Message Size Limits

   • SNS has a 256KB payload limit. For larger messages, use S3 or base64 encoding.

3. Consumer Lag

   • SNS consumers poll asynchronously. Use setDelay() to control polling intervals:

     $consumer->setDelay(1000); // 1 second delay
     

4. Message Visibility

   • SNS does not support visibility timeouts like SQS. Messages are immediately visible after publishing.

5. Topic vs. Queue Confusion

   • SNS is a pub/sub system, not a queue. Use FIFO topics for ordered delivery if needed.

Debugging

• Enable AWS SDK Debugging

  $client = new \Aws\Sns\SnsClient([
      'debug' => true,
      'logger' => new \Aws\Logger\StreamLogger('php://stdout'),
  ]);
  

• Check SNS Metrics Monitor NumberOfMessagesPublished and NumberOfNotificationsDelivered in AWS CloudWatch.

Extension Points

1. Custom Message Attributes Extend SnsMessage to add metadata:

   class CustomSnsMessage extends \Enqueue\Sns\SnsMessage {
       public function __construct($body, array $headers = [], array $attributes = []) {
           parent::__construct($body, $headers, array_merge($attributes, ['custom' => 'value']));
       }
   }
   

2. Middleware for Pre/Post Processing Use Enqueue\Client\Middleware to intercept messages:

   $producer = $connection->createProducer();
   $producer->withMiddleware(new class implements Middleware {
       public function handle($message, callable $next) {
           // Pre-process
           $result = $next($message);
           // Post-process
           return $result;
       }
   });
   

3. Dead Letter Queues (DLQ) Implement a fallback topic for failed messages:

   $producer->send(new Message('Data', [
       'topic' => 'my-topic',
       'attributes' => ['dlq-topic' => 'my-dlq-topic']
   ]));
   

Configuration Quirks

• Region-Specific Endpoints Ensure the AWS region matches your SNS topic’s region. Cross-region publishing requires additional configuration.

• HTTPS vs. HTTP The AWS SDK defaults to HTTPS. Force HTTP only if necessary (e.g., internal networks):

  'scheme' => 'http',
  

• Message Deduplication Use MessageDeduplicationId for idempotency:

  $producer->send(new Message('Data', [
      'topic' => 'my-topic',
      'attributes' => ['MessageDeduplicationId' => uniqid()]
  ]));