Sms Biuras Notifier Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Dependency: The package is a Symfony Notifier bridge, requiring Laravel to either:
  • Adopt Symfony components (e.g., symfony/notifier, symfony/messenger) or
  • Abstract Symfony-specific logic (e.g., DSN parsing, transport factories) into Laravel-compatible layers.
  • Risk: High if the Laravel app lacks Symfony integration; moderate if using Symfony components (e.g., via vlucas/phpdotenv + manual DI).
• Notification Workflow: Fits Laravel’s event/queue systems if SMS is treated as a channel (e.g., Notification::route('sms', $user)). However, Laravel’s Illuminate\Notifications lacks native Symfony Notifier compatibility, requiring a custom channel or facade.
• Biuras-Specificity: Hardcodes Biuras API logic (e.g., DSN format, endpoint URLs). Multi-provider support would need a wrapper layer (e.g., abstract SmsProviderInterface).

Integration Feasibility

• DSN Configuration:
  • Laravel’s .env can replace Symfony’s DSN (e.g., SMSBIURAS_UID=xxx), but validation (e.g., required fields) must be manually implemented.
  • Example:

    $dsn = sprintf('smsbiuras://%s:%s@default?from=%s&test_mode=%d',
        config('services.smsbiuras.uid'),
        config('services.smsbiuras.api_key'),
        config('services.smsbiuras.from'),
        config('services.smsbiuras.test_mode')
    );
    

• Symfony Notifier in Laravel:
  • Requires bootstrapping Symfony’s Notifier and TransportFactory in a Laravel service provider.
  • Example:

    $this->app->singleton(NotifierInterface::class, function ($app) {
        return new Notifier([
            new SmsBiurasTransport($app->make(BiurasClient::class), $dsn),
        ]);
    });
    

• Async Delivery:
  • Symfony Messenger’s transports can be mapped to Laravel queues via a custom QueueTransport or by dispatching Laravel events from Symfony’s MessageBus.

Technical Risk

• Breaking Changes: The package’s minimal changelog suggests stability, but Symfony 8+ requires PHP 8.4+. Laravel’s PHP version must align (e.g., Laravel 10+ for PHP 8.4).
• Testing Gaps:
  • No Laravel-specific tests; integration tests would need to mock Symfony services (e.g., TransportFactory).
  • Test Mode: Biuras’ test_mode=1 may not align with Laravel’s queue testing (e.g., Queue::fake()).
• Error Handling:
  • Symfony’s NotificationFailedException must be caught and translated to Laravel’s Exception or logged via Log::error().
  • Retry Logic: Symfony Messenger’s retries may conflict with Laravel’s queue retries (e.g., maxAttempts).

Key Questions

1. Symfony Adoption:
   • Is the team open to adding Symfony components, or must this be a pure Laravel solution?
2. Provider Flexibility:
   • Will Biuras remain the sole provider, or is a multi-provider adapter needed (e.g., SmsBiurasTransport, TwilioTransport interfaces)?
3. Async Strategy:
   • Should SMS use Laravel’s queues (simpler) or Symfony Messenger (more features like retries)?
4. Configuration:
   • How will .env/config/services.php map to Symfony’s DSN format?
5. Monitoring:
   • Are delivery metrics (e.g., sms_sent, sms_failed) needed in Laravel’s monitoring (e.g., Horizon, Datadog)?

Integration Approach

Stack Fit

• Option 1: Lightweight Laravel Wrapper (Recommended for minimal risk):
  • Create a Laravel service (SmsBiurasClient) that wraps Biuras’ API directly (no Symfony dependency).
  • Use Laravel’s Notification channel or a custom SmsBiurasChannel.
  • Pros: No Symfony overhead, full control over error handling/retries.
  • Cons: Reimplements DSN parsing, transport logic.
• Option 2: Symfony Notifier Bridge (For teams using Symfony components):
  • Integrate symfony/notifier via Composer, bootstrap in a Laravel service provider.
  • Map Symfony’s Notifier to Laravel’s Notification facade or events.
  • Pros: Leverages Symfony’s battle-tested transport system.
  • Cons: Adds Symfony as a dependency; complex async queue mapping.

Migration Path

1. Phase 1: Proof of Concept (1–2 weeks)
   • Implement a minimal SmsBiurasClient service in Laravel.
   • Test DSN parsing and API calls in test_mode=1.
   • Validate integration with Laravel’s Notification system.
2. Phase 2: Async Delivery (1 week)
   • Choose between:
     • Laravel Queues: Dispatch SendSms jobs with ShouldQueue.
     • Symfony Messenger: Bridge to Laravel queues via a custom transport.
3. Phase 3: Error Handling & Monitoring (1 week)
   • Implement retry logic (e.g., Illuminate\Bus\Queueable).
   • Log failures to Laravel’s failed_jobs table or a custom table.
   • Expose metrics via Laravel’s Log::channel('sms') or Prometheus.

Compatibility

• Laravel Versions:
  • PHP 8.4+ required for Symfony 8+ (Laravel 10+).
  • For older Laravel, use an older package version (e.g., 7.3.x for PHP 8.1).
• Biuras API:
  • Verify API compatibility (e.g., endpoints, rate limits) with Biuras’ current spec.
  • Test edge cases (e.g., invalid phone numbers, character limits).

Sequencing

1. Configure DSN:
   • Add .env keys:

     SMSBIURAS_UID=your_uid
     SMSBIURAS_API_KEY=your_key
     SMSBIURAS_FROM=YourBrand
     SMSBIURAS_TEST_MODE=true
     

2. Create Service:

   // app/Services/SmsBiurasClient.php
   class SmsBiurasClient {
       public function send(string $to, string $message): bool {
           $client = new \Symfony\Contracts\HttpClient\HttpClient();
           $response = $client->request('POST', 'https://api.smsbiuras.lt/send', [
               'auth_basic' => [env('SMSBIURAS_UID'), env('SMSBIURAS_API_KEY')],
               'json' => [
                   'to' => $to,
                   'text' => $message,
                   'from' => env('SMSBIURAS_FROM'),
               ],
           ]);
           return $response->getStatusCode() === 200;
       }
   }
   

3. Register in Laravel:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->singleton(SmsBiurasClient::class, function ($app) {
           return new SmsBiurasClient();
       });
   }
   

4. Create Notification Channel:

   // app/Notifications/Channels/SmsBiurasChannel.php
   class SmsBiurasChannel implements Channel {
       public function send(Notification $notification, Message $message) {
           $client = app(SmsBiurasClient::class);
           $client->send($message->to(), $notification->toSms($message));
       }
   }
   

5. Use in Notifications:

   // app/Notifications/OrderConfirmed.php
   public function via($notifiable) {
       return ['sms'];
   }
   
   public function toSms($notifiable) {
       return "Your order #{$this->order->id} is confirmed!";
   }
   

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Symfony Notifier for breaking changes (e.g., PHP 8.4+ requirements).
  • Mitigation: Use composer require symfony/notifier:^7.3 with strict version pinning.
• Biuras API Changes:
  • Biuras may deprecate endpoints or change rate limits.
  • Mitigation: Subscribe to Biuras’ API changelog; implement a feature flag for API versioning.

Support

• Debugging:
  • Symfony’s NotificationFailedException may not surface clearly in Laravel’s error pages.
  • Solution: Create a custom exception handler or log all SMS failures to storage/logs/sms.log.
• Community:
  • 4-star repo with no dependents; issues may go unanswered.
  • Solution: Fork the repo or create a Laravel-specific issue template.

Scaling

• Performance:
  • Biuras’ API rate limits (e.g., 100 SMS/min) may throttle high-volume apps.
  • Solution: Implement exponential backoff