Sms Sender Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to your composer.json:

   "require": {
       "avtonom/sms-sender-bundle": "^1.6"
   }
   

   Run composer update.

2. Enable the Bundle Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Avtonom\SmsSenderBundle\AvtonomSmsSenderBundle::class => ['all' => true],
   

3. Configure SMS Provider Define your SMS provider in config/packages/avtonom_sms_sender.yaml (Symfony 4+) or app/config/config.yml (Symfony 2/3):

   avtonom_sms_sender:
       provider: 'your_provider' # e.g., 'clickatell', 'twilio', 'custom'
       options:
           api_key: '%env(SMS_API_KEY)%'
           # Other provider-specific options
   

4. First Use Case: Send a Test SMS Inject the SmsSender service and send a message:

   use Avtonom\SmsSenderBundle\SmsSender;
   
   class SomeController
   {
       public function sendTestSms(SmsSender $smsSender)
       {
           $smsSender->send([
               'to' => '1234567890',
               'message' => 'Hello from Laravel!',
           ]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Provider Abstraction Use the bundle’s SmsSender service to switch providers without changing business logic:

   $smsSender->send([
       'to'      => 'recipient_number',
       'message' => 'Your OTP is 1234',
       'from'    => 'YourBrand', // Optional sender ID
   ]);
   

2. Batch Sending Send SMS to multiple recipients efficiently:

   $smsSender->sendBatch([
       ['to' => '1234567890', 'message' => 'Hello 1'],
       ['to' => '0987654321', 'message' => 'Hello 2'],
   ]);
   

3. Async Sending (Symfony Messenger) Integrate with Symfony Messenger for background processing:

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               sms:
                   dsn: 'avtonom_sms_sender://'
           routing:
               'Avtonom\SmsSenderBundle\Message\SendSmsMessage': sms
   

4. Event Listeners Hook into SMS lifecycle events (e.g., SmsSentEvent):

   use Avtonom\SmsSenderBundle\Event\SmsSentEvent;
   
   class SmsLoggerSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               SmsSentEvent::class => 'logSms',
           ];
       }
   
       public function logSms(SmsSentEvent $event)
       {
           // Log or process sent SMS data
       }
   }
   

Integration Tips

• Laravel-Specific: Use Symfony’s HttpKernel bridge to integrate with Laravel’s service container:

  $kernel = new AppKernel('prod', false);
  $container = $kernel->getContainer();
  $smsSender = $container->get('avtonom_sms_sender.sms_sender');
  

• Validation: Validate phone numbers before sending:

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

• Fallback Providers: Configure multiple providers for redundancy:

  avtonom_sms_sender:
      providers:
          primary: 'clickatell'
          fallback: 'twilio'
  

Gotchas and Tips

Common Pitfalls

1. Provider-Specific Quirks

   • Clickatell: Requires username and password in options, not api_key.
   • Twilio: Needs account_sid and auth_token.
   • Custom Providers: Ensure the SmsSender library’s provider class is properly implemented (see SmsSender docs).

2. Phone Number Formatting

   • Always prepend + and country code (e.g., +1234567890). Some providers (e.g., Twilio) may reject malformed numbers.

3. Rate Limits

   • Providers like Twilio enforce rate limits. Handle SmsSenderException gracefully:

     try {
         $smsSender->send([...]);
     } catch (\Avtonom\SmsSender\Exception\SmsSenderException $e) {
         $this->handleRateLimit($e);
     }
     

4. Web Profiler Overhead

   • The bundle integrates with Symfony’s Web Profiler, which adds minor overhead. Disable in production if needed:

     avtonom_sms_sender:
         profiler: false
     

Debugging Tips

• Enable Debug Mode Add to config/packages/dev/avtonom_sms_sender.yaml:

  avtonom_sms_sender:
      debug: true
  

  This logs raw API responses for troubleshooting.

• Check Profiler Tab The Web Profiler tab (/profiler) shows SMS sent/received data, including:

  • Recipient numbers
  • Message content
  • Response statuses
  • Timestamps

• Log Provider Responses Extend the SmsSender service to log raw responses:

  use Psr\Log\LoggerInterface;
  
  class CustomSmsSender extends \Avtonom\SmsSender\SmsSender
  {
      public function __construct(LoggerInterface $logger, array $providers)
      {
          parent::__construct($providers);
          $this->logger = $logger;
      }
  
      protected function sendSms($message, $providerName)
      {
          $response = parent::sendSms($message, $providerName);
          $this->logger->debug('SMS Response', ['provider' => $providerName, 'response' => $response]);
          return $response;
      }
  }
  

Extension Points

1. Custom Providers Implement a new provider by extending Avtonom\SmsSender\Provider\ProviderInterface:

   class CustomProvider implements ProviderInterface
   {
       public function send(SmsMessage $message)
       {
           // Custom logic to send via your API
           return new SmsResponse($success, $data);
       }
   }
   

   Register it in config:

   avtonom_sms_sender:
       providers:
           custom: 'App\Provider\CustomProvider'
   

2. Override Default Services Use Symfony’s compiler pass or Laravel’s service binding to replace the default SmsSender:

   // In a compiler pass or service provider
   $container->set('avtonom_sms_sender.sms_sender', $this->createCustomSmsSender());
   

3. Add Metadata to SMS Extend the SmsMessage class to include custom fields (e.g., campaign_id):

   class ExtendedSmsMessage extends \Avtonom\SmsSender\SmsMessage
   {
       protected $campaignId;
   
       public function setCampaignId($campaignId)
       {
           $this->campaignId = $campaignId;
           return $this;
       }
   }
   

   Update the provider to handle the new field.