Sms Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require dotsmart/sms-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Belyas\DotSmartSmsBundle\BelyasDotSmartSmsBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config and adjust config/packages/dotsmart_sms.yaml:

   dotsmart_sms:
       api_key: 'your_dot_smart_api_key'
       sender_id: 'your_sender_id'
       timeout: 30
   

3. First Use Case Inject the DotSmartSmsService into a controller or service:

   use Belyas\DotSmartSmsBundle\Service\DotSmartSmsService;
   
   public function sendSms(DotSmartSmsService $smsService)
   {
       $response = $smsService->sendSms(
           '+212612345678', // Recipient
           'Test message',  // Message
           'YOUR_SENDER_ID' // Optional: Override sender_id
       );
       return new JsonResponse($response);
   }
   

Implementation Patterns

Common Workflows

1. Sending SMS Use the service in controllers, commands, or event listeners:

   $smsService->sendSms($phoneNumber, $message, $senderId = null);
   

   • Bulk SMS: Loop through recipients (handle rate limits manually).

2. Async Processing Dispatch a Symfony Message via a queue (e.g., Symfony Messenger):

   $message = new SendSmsMessage($phone, $text, $senderId);
   $bus->dispatch($message);
   

   Configure a handler to use DotSmartSmsService.

3. Validation Validate phone numbers before sending (e.g., with libphonenumber):

   use libphonenumber\PhoneNumberUtil;
   $phoneUtil = PhoneNumberUtil::getInstance();
   $phone = $phoneUtil->parse($phoneNumber);
   if (!$phoneUtil->isValidNumber($phone)) {
       throw new \InvalidArgumentException('Invalid phone number');
   }
   

4. Logging Responses Extend the service to log responses (e.g., using Monolog):

   $logger->info('SMS sent', ['recipient' => $phone, 'response' => $response]);
   

Integration Tips

• Symfony Forms: Add a SmsType form field for user-submitted messages.
• APIs: Use the service in API controllers to send OTPs or notifications.
• Events: Trigger SMS on user actions (e.g., UserRegisteredEvent).

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never commit api_key to version control. Use environment variables:

     # .env
     DOTSMART_API_KEY=your_key_here
     

   • Override config in config/packages/dev/dotsmart_sms.yaml for local testing.

2. Rate Limits

   • DotSmart may throttle requests. Implement exponential backoff in retries:

     $attempts = 0;
     while ($attempts < 3) {
         try {
             $response = $smsService->sendSms(...);
             break;
         } catch (\Exception $e) {
             $attempts++;
             sleep(2 ** $attempts); // Exponential delay
         }
     }
     

3. Character Limits

   • SMS messages are typically limited to 160 characters. Use Unicode conversion:

     $message = mb_strimwidth($message, 0, 160, '...', 'UTF-8');
     

4. Sender ID Restrictions

   • Some countries require pre-approved sender IDs. Test with a sandbox API key first.

Debugging

• Enable Debug Mode: Set debug: true in config to log raw API responses.
• Check HTTP Status Codes: Wrap calls in a try-catch to handle:
  • 401: Invalid API key.
  • 429: Rate limit exceeded.
  • 500: Server error (retry or notify admin).

Extension Points

1. Custom Responses Extend DotSmartSmsService to transform responses:

   class CustomSmsService extends DotSmartSmsService {
       public function sendSms($phone, $message, $senderId = null) {
           $response = parent::sendSms($phone, $message, $senderId);
           return ['success' => $response['status'] === 'success', 'data' => $response];
       }
   }
   

2. Template Engine Use Twig to render SMS templates:

   {# templates/sms/welcome.txt.twig #}
   Hello {{ user.name }},
   Welcome to our service!
   

   $message = $twig->render('sms/welcome.txt.twig', ['user' => $user]);
   $smsService->sendSms($user->phone, $message);
   

3. Webhook Validation If DotSmart supports webhooks, validate signatures:

   $expectedSignature = hash_hmac('sha256', $payload, config('dotsmart_sms.webhook_secret'));
   if (!hash_equals($expectedSignature, $_SERVER['HTTP_X_SIGNATURE'])) {
       throw new \RuntimeException('Invalid webhook signature');
   }