Iqsms Notifier Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require symfony/iqsms-notifier
   

2. Configure the DSN Add the DSN to your .env file:

   IQSMS_DSN=iqsms://LOGIN:PASSWORD@default?from=SENDER_NAME
   

   Replace LOGIN, PASSWORD, and SENDER_NAME with your IQSMS credentials and sender ID.

3. First Use Case: Sending an SMS Use Symfony's Notifier component to send an SMS:

   use Symfony\Component\Notifier\NotifierInterface;
   use Symfony\Component\Notifier\Message\SmsMessage;
   
   $notifier = new Notifier([new IqsmsTransport($dsn)]);
   $notifier->send(new SmsMessage('Hello, this is a test SMS!', '71234567890'));
   

Where to Look First

• DSN Configuration: Focus on the .env setup and DSN format.
• Notifier Integration: Review Symfony's Notifier documentation for message types and transports.
• Error Handling: Check the Symfony Notifier docs for handling failures.

Implementation Patterns

Common Workflows

1. Sending SMS Messages

   $notifier->send(new SmsMessage('Your verification code is 12345', $phoneNumber));
   

2. Using Different Senders Configure multiple DSNs in .env and switch between them dynamically:

   IQSMS_DSN_DEFAULT=iqsms://login:pass@default?from=Sender1
   IQSMS_DSN_ALTERNATE=iqsms://login:pass@alternate?from=Sender2
   

   $notifier = new Notifier([
       new IqsmsTransport($_ENV['IQSMS_DSN_DEFAULT']),
       new IqsmsTransport($_ENV['IQSMS_DSN_ALTERNATE']),
   ]);
   

3. Bulk SMS with Retries Use Symfony's RetryStrategy for transient failures:

   use Symfony\Component\Notifier\Retry\RetryStrategy;
   
   $notifier = new Notifier([
       new IqsmsTransport($dsn, new RetryStrategy(3, 1000)),
   ]);
   

4. Event-Driven Notifications Trigger SMS notifications from Laravel events:

   use Illuminate\Support\Facades\Bus;
   use App\Jobs\SendSmsNotification;
   
   Bus::dispatch(new SendSmsNotification($user->phone, 'Welcome!'));
   

Integration Tips

• Laravel Service Provider Bind the notifier to Laravel's container for easy access:

  use Symfony\Component\Notifier\NotifierInterface;
  use Symfony\Component\Notifier\Transport\IqsmsTransport;
  
  public function register()
  {
      $this->app->singleton(NotifierInterface::class, function ($app) {
          return new Notifier([new IqsmsTransport(config('services.iqsms.dsn'))]);
      });
  }
  

• Configuration in config/services.php

  'iqsms' => [
      'dsn' => env('IQSMS_DSN'),
      'from' => env('IQSMS_FROM', 'DefaultSender'),
  ],
  

• Logging Failures Extend the transport to log failed messages:

  use Psr\Log\LoggerInterface;
  
  $transport = new IqsmsTransport($dsn, null, new LoggerInterface());
  

Gotchas and Tips

Pitfalls

1. DSN Format Sensitivity

   • Ensure the DSN follows the exact format: iqsms://LOGIN:PASSWORD@default?from=SENDER.
   • Missing ?from= or incorrect sender format will cause failures.

2. Character Limits

   • IQSMS may enforce message length limits (e.g., 70 characters per segment). Split long messages:

     use Symfony\Component\Notifier\Message\SmsMessage;
     $message = new SmsMessage(str_split('Your long message here...', 70));
     

3. Rate Limiting

   • IQSMS may throttle requests. Implement exponential backoff in your retry strategy:

     new RetryStrategy(5, 2000, 2) // 5 retries, 2s delay, multiplier of 2
     

4. Sender ID Restrictions

   • Some regions require approved sender IDs. Test with a sandbox account first.

Debugging

• Enable Debug Mode Symfony Notifier logs transport interactions. Enable debug in config/logging.php:

  'channels' => [
      'notifier' => [
          'driver' => 'single',
          'path' => storage_path('logs/notifier.log'),
          'level' => 'debug',
      ],
  ],
  

• Check IQSMS API Responses Wrap the transport in a custom class to inspect raw responses:

  use Symfony\Component\Notifier\Transport\IqsmsTransport;
  use Symfony\Component\Notifier\Exception\TransportException;
  
  class CustomIqsmsTransport extends IqsmsTransport
  {
      public function __send(SmsMessage $message): void
      {
          try {
              parent::__send($message);
          } catch (TransportException $e) {
              \Log::error('IQSMS Error: ' . $e->getMessage());
              throw $e;
          }
      }
  }
  

Extension Points

1. Custom Message Formatting Override the transport to modify messages before sending:

   class CustomIqsmsTransport extends IqsmsTransport
   {
       protected function __send(SmsMessage $message): void
       {
           $message->text = "[Your Brand] " . $message->text;
           parent::__send($message);
       }
   }
   

2. Webhook Integration Use IQSMS's webhook API to track delivery status. Extend the transport to fetch status updates:

   $transport->getDeliveryStatus($messageId);
   

3. Fallback Transports Combine IQSMS with other transports (e.g., Twilio) for redundancy:

   $notifier = new Notifier([
       new IqsmsTransport($iqsmsDsn),
       new TwilioTransport($twilioDsn),
   ]);
   

Configuration Quirks

• Environment Variables Ensure .env variables are loaded before instantiating the transport. Use Laravel's config() helper:

  $dsn = config('services.iqsms.dsn');
  

• Caching the Transport Instantiate the transport once and reuse it (Symfony Notifier is thread-safe):

  $transport = new IqsmsTransport($dsn);
  $notifier = new Notifier([$transport]);
  

• Testing Use Symfony's TransportFactoryTestCase for unit tests:

  use Symfony\Component\Notifier\Test\TransportFactoryTestCase;
  
  class IqsmsTransportTest extends TransportFactoryTestCase
  {
      protected function createTransport(): IqsmsTransport
      {
          return new IqsmsTransport('iqsms://test:test@default?from=Test');
      }
  }