Smsapi Notifier Laravel Package

Getting Started

Minimal Setup

1. Install the Package:

   composer require symfony/smsapi-notifier
   

   If using Laravel with Symfony Notifier (e.g., via spatie/laravel-notifier), ensure symfony/notifier is also installed:

   composer require symfony/notifier spatie/laravel-notifier
   

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

   SMSAPI_DSN=smsapi://YOUR_API_TOKEN@default?from=YOUR_SENDER&fast=0&test=0
   

   For smsapi.com, use:

   SMSAPI_DSN=smsapi://YOUR_API_TOKEN@api.smsapi.com?from=YOUR_SENDER
   

3. First Use Case: Send an SMS via Symfony Notifier (if integrated):

   use Symfony\Component\Notifier\Message\SmsMessage;
   use Symfony\Component\Notifier\NotifierInterface;
   
   $notifier = new NotifierInterface(); // Assume bound to Laravel's container
   $message = new SmsMessage('Hello via SMSAPI!', 'recipient@example.com');
   $notifier->send($message);
   

   For Laravel without Symfony Notifier, wrap the DSN in a custom transport:

   use Symfony\Component\Notifier\Transport\Dsn;
   use Symfony\Component\Notifier\Transport\SmsapiTransport;
   
   $dsn = new Dsn('smsapi://TOKEN@default?from=SENDER');
   $transport = new SmsapiTransport($dsn);
   $transport->send(new SmsMessage('Test', '123456789'));
   

Implementation Patterns

Core Workflows

1. Sending SMS Notifications:

   • Symfony Notifier Integration: Use SmsMessage with Symfony’s NotifierInterface:

     $notifier->send(
         new SmsMessage('Your OTP: 1234', 'user@example.com')
     );
     

   • Laravel Facade (Recommended): Create a facade to abstract Symfony Notifier:

     // app/Facades/SmsNotifier.php
     namespace App\Facades;
     
     use Illuminate\Support\Facades\Facade;
     
     class SmsNotifier extends Facade {
         protected static function getFacadeAccessor() { return 'sms.notifier'; }
     }
     

     Bind the notifier in AppServiceProvider:

     $this->app->singleton('sms.notifier', function ($app) {
         return new NotifierInterface([new SmsapiTransport(new Dsn(env('SMSAPI_DSN')))]);
     });
     

     Usage:

     SmsNotifier::send(new SmsMessage('Hello', 'user@example.com'));
     

2. Environment-Specific Config: Use Laravel’s .env for DSN variations:

   SMSAPI_DSN_PROD=smsapi://PROD_TOKEN@api.smsapi.com?from=PROD_SENDER&fast=1
   SMSAPI_DSN_STAGING=smsapi://STAGING_TOKEN@default?test=1
   

   Dynamically resolve in AppServiceProvider:

   $dsn = new Dsn(env('SMSAPI_DSN_' . config('app.env')));
   

3. Async Delivery with Queues: Dispatch SMS jobs via Laravel Queues:

   use App\Jobs\SendSmsJob;
   
   SendSmsJob::dispatch('Hello', 'user@example.com');
   

   Job implementation:

   // app/Jobs/SendSmsJob.php
   namespace App\Jobs;
   
   use Illuminate\Bus\Queueable;
   use Symfony\Component\Notifier\Message\SmsMessage;
   use Symfony\Component\Notifier\NotifierInterface;
   
   class SendSmsJob {
       use Queueable;
   
       public function handle(NotifierInterface $notifier) {
           $notifier->send(new SmsMessage($this->message, $this->recipient));
       }
   }
   

4. Event-Driven Extensions: Listen to SmsMessageSent events for analytics or retries:

   // app/Listeners/SmsSentListener.php
   namespace App\Listeners;
   
   use Symfony\Component\Notifier\EventListener\SmsMessageSent;
   use Symfony\Component\Notifier\Message\SentMessage;
   
   class SmsSentListener {
       public function onSmsSent(SmsMessageSent $event) {
           $sentMessage = $event->getSentMessage();
           if ($sentMessage instanceof SentMessage) {
               logger()->info('SMS sent', [
                   'message_id' => $sentMessage->getMessageId(),
                   'recipient' => $sentMessage->getRecipient(),
               ]);
           }
       }
   }
   

   Register the listener in EventServiceProvider:

   protected $listeners = [
       SmsMessageSent::class => [
           SmsSentListener::class,
       ],
   ];
   

Integration Tips

1. Laravel-Symfony Bridge: Use spatie/laravel-symfony-messenger to integrate Symfony Messenger with Laravel:

   composer require spatie/laravel-symfony-messenger
   

   Configure in config/services.php:

   'messenger' => [
       'transports' => [
           'smsapi' => [
               'dsn' => env('SMSAPI_DSN'),
           ],
       ],
   ],
   

2. Testing: Mock the transport in PHPUnit:

   use Symfony\Component\Notifier\Transport\MockTransport;
   
   $transport = new MockTransport();
   $notifier = new NotifierInterface([$transport]);
   $notifier->send(new SmsMessage('Test', '123'));
   $this->assertCount(1, $transport->getSentMessages());
   

3. Fallback Mechanisms: Combine with other transports (e.g., email) for multi-channel notifications:

   $notifier->send(
       new SmsMessage('SMS fallback: Email sent', 'user@example.com'),
       new EmailMessage('Primary email', 'user@example.com', 'user@example.com')
   );
   

4. Rate Limiting: Use Laravel’s throttle middleware or spatie/laravel-circuit-breaker:

   use Spatie\CircuitBreaker\CircuitBreaker;
   
   CircuitBreaker::new('smsapi', 5, 60)->run(function () {
       $notifier->send(new SmsMessage('Rate-limited test', '123'));
   });
   

Gotchas and Tips

Pitfalls

1. DSN Misconfiguration:

   • Issue: Forgetting from= or test= parameters in the DSN.
   • Fix: Validate the DSN format and test in sandbox mode (test=1).
   • Debug: Check SMSAPI’s API response for validation errors.

2. Symfony Notifier Dependency Conflicts:

   • Issue: Version mismatches between symfony/notifier and symfony/smsapi-notifier.
   • Fix: Pin versions in composer.json:

     "symfony/notifier": "^6.0",
     "symfony/smsapi-notifier": "^6.0"
     

3. Missing messageId in SentMessage:

   • Issue: Older versions (<7.3.0) may not populate messageId in SentMessage.
   • Fix: Upgrade to symfony/smsapi-notifier:^7.3.0 or manually set it:

     $sentMessage->setMessageId($response['messageId']);
     

4. Laravel’s env() Caching:

   • Issue: .env changes not reflected due to Laravel’s cached config.
   • Fix: Clear config cache:

     php artisan config:clear
     

5. SMSAPI API Rate Limits:

   • Issue: Unhandled 429 Too Many Requests responses.
   • Fix: Implement exponential backoff in a custom transport:

     use Symfony\Component\Notifier\Exception\TransportException;
     use Symfony\Component\Notifier\Transport\TransportInterface;
     
     class RetryableSmsapiTransport implements TransportInterface {
         public function send(SmsMessage $message) {
             $retries = 3;
             while ($retries--) {
                 try {
                     $this->transport->send($message);
                     break;
                 } catch (TransportException $e) {
                     if ($retries === 0) throw $e;
                     sleep(2 ** $retries);
                 }
             }
         }
     }
     

Debugging Tips

1. Enable Symfony Notifier Debug: Set the NOTIFIER_DEBUG env var:

   NOTIFIER_DEBUG=1
   

   Logs will include transport details.

2. Inspect Raw API Responses: Extend the transport to log requests/responses:

   class