Infobip Notifier Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require symfony/notifier symfony/infobip-notifier
   

2. Configure DSN in .env:

   INFOBIP_DSN=infobip://YOUR_AUTH_TOKEN@api.infobip.com?from=YourSenderName
   

   • Replace YOUR_AUTH_TOKEN with your Infobip API token.
   • Replace api.infobip.com with your Infobip host (e.g., api.sandbox.infobip.com for testing).
   • from is the sender ID (e.g., YourApp).

3. First Use Case: Send an SMS

   use Symfony\Component\Notifier\Notifier;
   use Symfony\Component\Notifier\Bridge\Infobip\InfobipTransportFactory;
   use Symfony\Component\Notifier\Message\SmsMessage;
   
   $notifier = new Notifier([
       new InfobipTransportFactory($_ENV['INFOBIP_DSN']),
   ]);
   
   $message = new SmsMessage('Hello from Laravel!');
   $message->to('+1234567890');
   
   $notifier->send($message);
   

Where to Look First

• DSN Configuration: Focus on .env setup and Infobip’s DSN documentation.
• Symfony Notifier Docs: Symfony Notifier Overview for message types (SMS, email, etc.).
• Infobip API Limits: Check Infobip’s rate limits to avoid throttling.

Implementation Patterns

Core Workflows

1. Basic Notification Dispatch

• Pattern: Use Symfony Notifier’s Notifier class with the Infobip transport.
• Example:

  $notifier = app(Notifier::class); // If using Laravel's service container
  $notifier->send(new SmsMessage('Your OTP: 123456')->to('+1234567890'));
  

2. Laravel Event Integration

• Pattern: Trigger notifications via Laravel events (e.g., Registered).
• Example:

  // app/Listeners/SendWelcomeSms.php
  public function handle(Registered $event) {
      $notifier = app(Notifier::class);
      $notifier->send(new SmsMessage('Welcome!')->to($event->user->phone));
  }
  

3. Queue-Based Async Sending

• Pattern: Wrap notifications in a Laravel job to avoid blocking HTTP requests.
• Example:

  // app/Jobs/SendInfobipNotification.php
  public function handle() {
      $notifier = app(Notifier::class);
      $notifier->send($this->message);
  }
  

4. Dynamic Sender/Recipient Logic

• Pattern: Use Symfony’s Message classes to dynamically set recipients/senders.
• Example:

  $message = new SmsMessage('Custom message');
  $message->to('+1234567890')->from('DynamicSender');
  

Integration Tips

Laravel Service Container

• Register the Notifier as a singleton in AppServiceProvider:

  public function register() {
      $this->app->singleton(Notifier::class, function ($app) {
          return new Notifier([
              new InfobipTransportFactory($_ENV['INFOBIP_DSN']),
          ]);
      });
  }
  

Fallback Mechanisms

• Pattern: Use multiple transports (e.g., fallback to email if SMS fails).
• Example:

  $notifier = new Notifier([
      new InfobipTransportFactory($_ENV['INFOBIP_DSN']),
      new MailTransport($_ENV['MAILER_DSN']), // Fallback
  ]);
  

Testing

• Mock the Transport: Use Symfony’s TransportTestCase for unit tests:

  use Symfony\Component\Notifier\Test\TransportTestCase;
  
  class InfobipTransportTest extends TransportTestCase {
      protected function createTransport(): InfobipTransport {
          return new InfobipTransport(new InfobipClient('token', 'host'));
      }
  }
  

Debugging

• Enable Symfony’s debug mode to log sent messages:

  $notifier = new Notifier([...], [
      'debug' => true,
  ]);
  

Gotchas and Tips

Pitfalls

1. DSN Format Sensitivity

   • Issue: Incorrect DSN format (e.g., missing from or malformed host) causes silent failures.
   • Fix: Validate DSN in .env:

     INFOBIP_DSN=infobip://TOKEN@HOST?from=Sender&scheme=https
     

   • Debug: Check Symfony’s logs for TransportException.

2. Infobip API Rate Limits

   • Issue: High-volume sends may hit Infobip’s rate limits.
   • Fix:
     • Implement exponential backoff in a custom transport decorator.
     • Use Infobip’s batch API for bulk sends.

3. Symfony Notifier Events

   • Issue: Laravel’s event system doesn’t automatically listen to Symfony’s MessageSentEvent.
   • Fix: Subscribe to Symfony events via a Laravel event listener:

     use Symfony\Component\Notifier\EventListener\MessageSentEvent;
     
     public function handle(MessageSentEvent $event) {
         event(new NotificationSent($event->getMessage()));
     }
     

4. Queue Job Failures

   • Issue: Failed queue jobs (e.g., SendInfobipNotification) may not retry or log properly.
   • Fix: Use Laravel’s ShouldQueue and HandleFailures traits:

     use Illuminate\Bus\Queueable;
     use Illuminate\Queue\SerializesModels;
     use Illuminate\Queue\InteractsWithQueue;
     use Illuminate\Contracts\Queue\ShouldQueue;
     use Illuminate\Foundation\Bus\Dispatchable;
     use Illuminate\Bus\Queueable as QueueableTrait;
     
     class SendInfobipNotification implements ShouldQueue {
         use Dispatchable, InteractsWithQueue, QueueableTrait, SerializesModels;
     }
     

5. PHP Version Mismatches

   • Issue: Symfony 7+ requires PHP 8.1+. Laravel 10+ supports this, but older Laravel versions may conflict.
   • Fix: Pin Symfony dependencies explicitly:

     composer require symfony/notifier:^6.4 symfony/infobip-notifier:^6.4
     

Tips

1. Use Infobip’s Sandbox

   • Test with api.sandbox.infobip.com before going live to avoid costs.

2. Monitor Deliverability

   • Infobip provides delivery reports. Log these in Laravel:

     $notifier->send($message, function ($message, $transport, $failed) {
         if ($failed) {
             Log::error('Infobip send failed', ['message' => $message]);
         }
     });
     

3. Extend the Transport

   • Custom Headers: Decorate the transport to add headers:

     class CustomInfobipTransport extends InfobipTransport {
         public function __construct(InfobipClient $client, array $options = []) {
             parent::__construct($client, $options + ['headers' => ['X-Custom-Header' => 'value']]);
         }
     }
     

4. Laravel Notifications Facade

   • Tip: Create a facade for cleaner syntax:

     // app/Facades/Infobip.php
     public static function sendSms(string $message, string $to) {
         return app(Notifier::class)->send(new SmsMessage($message)->to($to));
     }
     

5. Environment-Specific DSNs

   • Use Laravel’s config('services.infobip.dsn') for environment-specific configs:

     // config/services.php
     'infobip' => [
         'dsn' => env('INFOBIP_DSN'),
         'sandbox' => env('APP_ENV') === 'local',
     ],
     

6. Handle Infobip API Errors

   • Tip: Catch InfobipApiException and map to Laravel’s HttpException:

     try {
         $notifier->send($message);
     } catch (InfobipApiException $e) {
         throw new HttpException(500, $e->getMessage());
     }
     

7. Avoid Hardcoding Tokens

   • Tip: Use