Sms Biuras Notifier Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the Package (via Composer):

   composer require symfony/sms-biuras-notifier
   

   Note: Since this is a Symfony package, ensure your Laravel app can handle Symfony dependencies (e.g., symfony/http-client). If conflicts arise, use symfony/http-client as a standalone package.

2. Configure the DSN in .env:

   SMSBIURAS_DSN=smsbiuras://YOUR_UID:YOUR_API_KEY@default?from=YourSender&test_mode=1
   

   • Replace YOUR_UID, YOUR_API_KEY, and YourSender with your SmsBiuras credentials.
   • Set test_mode=1 for sandbox testing (no charges).

3. Bind the Symfony Notifier Transport in config/app.php:

   'providers' => [
       // ...
       Symfony\Component\Notifier\Notifier::class,
       Symfony\Component\Notifier\Bridge\Sms\SmsBiurasNotifier::class,
   ],
   

   Alternative: Use a Laravel service provider to register the transport:

   use Symfony\Component\Notifier\Bridge\Sms\SmsBiurasNotifier;
   use Symfony\Component\Notifier\Transport\Dsn;
   
   public function register()
   {
       $this->app->singleton(SmsBiurasNotifier::class, function ($app) {
           $dsn = new Dsn(env('SMSBIURAS_DSN'));
           return new SmsBiurasNotifier($dsn);
       });
   }
   

4. First Use Case: Send an SMS Inject the SmsBiurasNotifier into a Laravel service/controller and use it like Symfony’s Notifier:

   use Symfony\Component\Notifier\Message\SmsMessage;
   use Symfony\Component\Notifier\Notification\Notification;
   
   public function sendWelcomeSms()
   {
       $notifier = app(SmsBiurasNotifier::class);
       $message = new SmsMessage('Welcome! Your code is: 12345');
       $notification = new Notification('Welcome', $message);
   
       $notifier->send($notification->forPhoneNumber('+37061234567'));
   }
   

Implementation Patterns

Workflow: Transactional SMS Notifications

1. Trigger SMS from Business Logic: Use Laravel events or services to dispatch SMS notifications. Example:

   // In a service or event listener
   event(new OrderPlaced($order));
   
   // Listener
   public function handle(OrderPlaced $event)
   {
       $notifier = app(SmsBiurasNotifier::class);
       $message = new SmsMessage("Order #{$event->order->id} confirmed!");
       $notifier->send($message->forPhoneNumber($event->order->customer_phone));
   }
   

2. Async Delivery with Laravel Queues: Wrap the notifier in a job to avoid blocking HTTP requests:

   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   use Illuminate\Foundation\Bus\Dispatchable;
   
   class SendSmsJob implements ShouldQueue
   {
       use Dispatchable, Queueable;
   
       public function __construct(
           private string $phone,
           private string $message
       ) {}
   
       public function handle()
       {
           $notifier = app(SmsBiurasNotifier::class);
           $notifier->send(new SmsMessage($this->message)->forPhoneNumber($this->phone));
       }
   }
   

   Dispatch the job from your business logic:

   SendSmsJob::dispatch($phone, 'Your message here');
   

3. Template-Based SMS: Use Laravel’s Blade or a templating service to generate dynamic SMS content:

   $message = new SmsMessage(view('sms.templates.welcome', ['code' => $otp])->render());
   

Integration Tips

• Laravel-Symfony DI Bridge: Register Symfony services in a Laravel provider to avoid conflicts:

  public function register()
  {
      $this->app->bind(
          \Symfony\Component\Notifier\Notifier::class,
          function ($app) {
              return new \Symfony\Component\Notifier\Notifier([
                  $app->make(SmsBiurasNotifier::class),
              ]);
          }
      );
  }
  

• Environment-Specific Config: Use Laravel’s config() helper to dynamically set DSN options:

  $dsn = new Dsn(env('SMSBIURAS_DSN'));
  $dsn->setOption('from', config('services.smsbiuras.sender'));
  

• Logging: Extend Symfony’s logger to Laravel’s logging system:

  use Psr\Log\LoggerInterface;
  use Symfony\Component\Notifier\Bridge\Sms\SmsBiurasNotifier;
  
  class LaravelSmsBiurasNotifier extends SmsBiurasNotifier
  {
      public function __construct(Dsn $dsn, private LoggerInterface $logger)
      {
          parent::__construct($dsn);
      }
  
      protected function doSend(SmsMessage $message): void
      {
          try {
              parent::doSend($message);
          } catch (\Exception $e) {
              $this->logger->error("SMS failed: {$e->getMessage()}");
              throw $e;
          }
      }
  }
  

• Testing: Use Laravel’s Mockery or PHPUnit to mock the notifier:

  $notifier = Mockery::mock(SmsBiurasNotifier::class);
  $notifier->shouldReceive('send')->once();
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency Conflicts:

   • The package may pull in Symfony components (e.g., symfony/http-client, symfony/options-resolver) that conflict with Laravel’s versions.
   • Fix: Use composer require symfony/http-client explicitly and resolve conflicts via composer.json overrides or platform-check.

2. DSN Configuration Quirks:

   • The from sender in the DSN must match SmsBiuras’ registered sender IDs/numbers. Invalid senders will cause silent failures.
   • Debug: Enable test_mode=1 and check SmsBiuras’ sandbox logs for validation errors.

3. Async Delivery Gaps:

   • Symfony’s Messenger (used internally) lacks Laravel’s queue retries/failed jobs out of the box.
   • Workaround: Implement a custom queue listener or use Laravel’s ShouldQueue with a fallback to Symfony’s retry logic.

4. Character Limits:

   • SmsBiuras enforces a ~160-character limit per SMS. Longer messages auto-split but may incur higher costs.
   • Tip: Use SmsMessage::split() to handle long texts explicitly:

     $message = new SmsMessage($longText);
     $message->split();
     

5. Rate Limiting:

   • SmsBiuras may throttle requests during peak hours. Laravel’s queue system won’t auto-retry failed SMS jobs by default.
   • Solution: Add a retry policy in your job:

     public function retryUntil()
     {
         return now()->addMinutes(5); // Retry for 5 minutes
     }
     

Debugging Tips

1. Enable Verbose Logging: Configure Laravel’s logging to capture Symfony’s debug output:

   'logging' => [
       'default' => 'single',
       'channels' => [
           'single' => [
               'driver' => 'single',
               'level' => 'debug', // Capture debug logs
           ],
       ],
   ],
   

2. Check SmsBiuras API Responses: The package may not expose raw API responses. Extend the notifier to log them:

   class DebugSmsBiurasNotifier extends SmsBiurasNotifier
   {
       protected function doSend(SmsMessage $message): void
       {
           $response = $this->client->send($message);
           \Log::debug('SmsBiuras API Response', ['response' => $response]);
       }
   }
   

3. Test Mode Validation: Always test with test_mode=1 first. Real SMS (test_mode=0) may fail silently if:

   • The from sender is unregistered.
   • The API key is invalid.
   • The phone number is malformed (e.g., missing country code).

4. Phone Number Formatting: SmsBiuras expects E.164 format (e.g., +37061234567). Laravel’s Str::of($phone)->start('+') can help normalize numbers:

   $phone = Str::of($user->phone)->start('+')->__toString();
   

Extension Points

1. Custom Transport: Extend SmsBiurasNotifier to add features like:
   • Message Templates: Predefined SMS templates stored in the database.
   • Webhooks: Trigger events on SMS delivery/failure.

   class CustomSmsBiurasNotifier extends SmsBi