Laravel Infobip Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digitonic/laravel-infobip
   

   Publish the config file:

   php artisan vendor:publish --provider="Digitonic\Infobip\InfobipServiceProvider"
   

2. Configuration Edit .env with your Infobip credentials:

   INFOBIP_USERNAME=your_username
   INFOBIP_PASSWORD=your_password
   INFOBIP_BASE_URL=https://api.infobip.com
   

3. First Use Case: Sending an SMS

   use Digitonic\Infobip\Facades\Infobip;
   
   Infobip::sms()->send([
       'from' => 'YourBrand',
       'to' => '441234567890',
       'text' => 'Hello from Laravel!'
   ]);
   

Key Files to Review

• config/infobip.php (API endpoints, default settings)
• app/Providers/InfobipServiceProvider.php (Service binding)
• vendor/digitonic/laravel-infobip/src/Facades/Infobip.php (Facade usage)

Implementation Patterns

Core Workflows

1. SMS Messaging

   // Basic SMS
   Infobip::sms()->send(['to' => '1234567890', 'text' => 'Test']);
   
   // Bulk SMS
   Infobip::sms()->bulkSend([
       'messages' => [
           ['to' => '1234567890', 'text' => 'Hello 1'],
           ['to' => '0987654321', 'text' => 'Hello 2']
       ]
   ]);
   

2. Email Campaigns

   Infobip::email()->send([
       'from' => 'noreply@example.com',
       'to' => ['user@example.com'],
       'subject' => 'Welcome',
       'html' => '<p>Hello!</p>'
   ]);
   

3. Two-Way SMS (Callback Handling) Configure a webhook route:

   Route::post('/infobip/webhook', [InfobipWebhookController::class, 'handle']);
   

   Then implement InfobipWebhookController to parse incoming SMS replies.

4. Template-Based Messaging

   Infobip::sms()->sendTemplate([
       'from' => 'Brand',
       'to' => '1234567890',
       'text' => 'Welcome {{name}}!',
       'vars' => ['name' => 'John']
   ]);
   

Integration Tips

• Queue Jobs for Async Sending Wrap Infobip calls in Laravel queues to avoid timeouts:

  use Illuminate\Support\Facades\Queue;
  
  Queue::push(function () {
      Infobip::sms()->send(['to' => '1234567890', 'text' => 'Delayed message']);
  });
  

• Logging Responses Extend the service to log API responses:

  Infobip::extend(function ($infobip) {
      $infobip->afterSend(function ($response) {
          \Log::info('Infobip Response', $response->toArray());
      });
  });
  

• Fallback Mechanisms Combine with other providers (e.g., Twilio) for redundancy:

  try {
      Infobip::sms()->send(['to' => '1234567890', 'text' => 'Fallback test']);
  } catch (\Exception $e) {
      // Fallback to Twilio
  }
  

Gotchas and Tips

Common Pitfalls

1. Authentication Failures

   • Ensure .env credentials match Infobip’s application username/password (not user credentials).
   • Test with the Infobip API Tester first.

2. Rate Limits

   • Infobip enforces rate limits. Cache responses or use exponential backoff:

     try {
         Infobip::sms()->send(...);
     } catch (\Digitonic\Infobip\Exceptions\RateLimitExceeded $e) {
         sleep(10); // Retry after delay
     }
     

3. Webhook Delays

   • Infobip may delay webhook deliveries. Use idempotency keys to avoid duplicate processing:

     Infobip::sms()->send(['to' => '1234567890', 'text' => 'Test', 'idempotencyKey' => uniqid()]);
     

4. Character Limits

   • SMS: 70 chars per segment (concatenated SMS auto-handled by Infobip, but budget for extra segments).
   • Email: HTML emails may hit size limits (~10MB). Compress attachments or use base64 encoding.

Debugging Tips

• Enable Debug Mode

  Infobip::setDebug(true); // Logs raw API requests/responses
  

• Validate Payloads Use Infobip::validate() to check request data before sending:

  $validated = Infobip::validate([
      'to' => '1234567890',
      'text' => 'Test'
  ]);
  

Extension Points

1. Custom API Endpoints Override the base URL in config or dynamically:

   Infobip::setBaseUrl('https://custom.infobip.com');
   

2. Add New Features Extend the facade to support unsupported endpoints (e.g., WhatsApp API):

   Infobip::extend(function ($infobip) {
       $infobip->whatsapp = new WhatsAppService($infobip->client);
   });
   

3. Mocking for Tests Use Laravel’s mocking to test without hitting Infobip:

   $this->mock(\Digitonic\Infobip\Infobip::class, function ($mock) {
       $mock->shouldReceive('send')->andReturn(['success' => true]);
   });
   

Configuration Quirks

• Default "From" Sender Set a global default in config/infobip.php:

  'defaults' => [
      'from' => 'YourBrandName',
  ],
  

• Timeouts Adjust Guzzle timeout in config (default: 30s):

  'timeout' => 60, // seconds