Sms Biuras Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require symfony/sms-biuras-notifier
   

   Ensure your project uses Symfony 6.4+ or Laravel 10+ (via Symfony Bridge).

2. Configuration Add Biuras SMS credentials to your .env:

   SMS_BIURAS_API_KEY=your_api_key_here
   SMS_BIURAS_SENDER_ID=YourSender
   

3. First Use Case Send a basic SMS via a Laravel service:

   use Symfony\Component\Notifier\Notifier;
   use Symfony\Component\Notifier\Bridge\SmsBiuras\SmsBiurasTransport;
   
   $notifier = new Notifier([
       new SmsBiurasTransport('SMS_BIURAS_API_KEY', 'SMS_BIURAS_SENDER_ID'),
   ]);
   
   $notifier->send(
       new Notification('Welcome!', 'Your verification code: 12345')
   );
   

Key Files to Review

• config/services.php (Add Biuras SMS config if using Laravel’s service container).
• app/Providers/AppServiceProvider.php (Bind the transport to Laravel’s container).

Implementation Patterns

Workflows

1. Laravel Integration Bind the transport to Laravel’s container in AppServiceProvider:

   public function register()
   {
       $this->app->bind(\Symfony\Component\Notifier\Transport\Dsn::class, function ($app) {
           return new SmsBiurasTransport(
               config('services.sms_biuras.api_key'),
               config('services.sms_biuras.sender_id')
           );
       });
   }
   

2. Sending Notifications Use Laravel’s Notification facade or inject the Notifier:

   use App\Notifications\SmsVerification;
   
   // Option 1: Via Notification class
   $user->notify(new SmsVerification());
   
   // Option 2: Directly via Notifier
   $notifier->send(
       new Notification('Subject', 'Message'),
       new Recipient('+37061234567', 'user@example.com')
   );
   

3. Batch Sending Loop through users and send SMS in bulk (with rate-limiting):

   foreach ($users as $user) {
       $notifier->send(
           new Notification('Hello', "Hi {$user->name}!"),
           new Recipient($user->phone, $user->email)
       );
       sleep(1); // Avoid rate limits
   }
   

4. Event-Driven Notifications Trigger SMS on model events (e.g., created):

   class User extends Model
   {
       protected static function booted()
       {
           static::created(function ($user) {
               $user->notify(new SmsVerification());
           });
       }
   }
   

Integration Tips

• Laravel Queues: Dispatch notifications to queues for async processing:

  $user->notify(new SmsVerification())->onQueue('sms');
  

• Logging: Enable Symfony’s logger to track failed sends:

  $notifier = new Notifier([$transport], ['logger' => new SymfonyLogger()]);
  

• Fallbacks: Combine with other transports (e.g., email) for multi-channel notifications.

Gotchas and Tips

Pitfalls

1. Rate Limits

   • Biuras SMS may throttle requests. Implement exponential backoff or queue delays.
   • Fix: Use Laravel’s sleep() or queue retries with jitter.

2. Phone Number Formatting

   • Biuras expects E.164 format (+37061234567). Validate input:

   use Libphonenumber\PhoneNumberUtil;
   $phone = PhoneNumberUtil::getInstance()->parse($rawPhone, 'LT');
   $recipient = new Recipient($phone->getNumber(), $email);
   

3. API Key Security

   • Never hardcode keys. Use Laravel’s .env and validate in config:

   if (empty(config('services.sms_biuras.api_key'))) {
       throw new \RuntimeException('SMS_BIURAS_API_KEY not configured.');
   }
   

4. Character Limits

   • Biuras SMS supports ~160 chars per message. Split long messages:

   $chunks = array_chunk(str_split($longMessage, 150), 150);
   foreach ($chunks as $chunk) {
       $notifier->send(new Notification('Part', $chunk));
   }
   

5. Recipient Validation

   • Biuras rejects invalid numbers/emails. Validate before sending:

   if (!preg_match('/^\+370\d{8}$/', $phone)) {
       throw new \InvalidArgumentException('Invalid Lithuanian phone number.');
   }
   

Debugging

• Enable Debug Mode Set NOTIFIER_DEBUG=true in .env to log all requests/responses.
• Check HTTP Status Codes Biuras returns 429 for rate limits and 400 for invalid inputs. Handle in a custom transport wrapper:

  class BiurasTransport extends SmsBiurasTransport
  {
      public function __construct(string $apiKey, string $senderId)
      {
          parent::__construct($apiKey, $senderId);
          $this->setHttpClient(new \Symfony\Contracts\HttpClient\HttpClient([
              'timeout' => 10,
              'headers' => ['Accept' => 'application/json'],
          ]));
      }
  }
  

Extension Points

1. Custom Notification Classes Extend Symfony’s Notification to add metadata:

   class SmsVerification extends Notification
   {
       public function __construct(private string $code) {}
   
       public function asSms(SmsMessage $message): void
       {
           $message->subject('Verification Code');
           $message->text("Your code: {$this->code}");
       }
   }
   

2. Webhook Handling Use Laravel’s HandleIncomingWebhook to process Biuras delivery reports:

   Route::post('/sms-webhook', [SmsWebhookHandler::class, 'handle']);
   

3. Testing Mock the transport in PHPUnit:

   $mockTransport = $this->createMock(SmsBiurasTransport::class);
   $mockTransport->method('send')->willReturn(true);
   $notifier = new Notifier([$mockTransport]);
   

4. Local Development Use a local SMS gateway (e.g., symfony/notify-bundle’s null transport) to avoid hitting rate limits:

   $notifier = new Notifier([
       new NullTransport(), // For local testing
       new SmsBiurasTransport($apiKey, $senderId),
   ]);