Allmysms Notifier Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require symfony/allmysms-notifier
   

2. Configure the DSN in your .env:

   ALLMYSMS_DSN=allmysms://LOGIN:APIKEY@default?from=SENDER_NUMBER
   

   Replace LOGIN, APIKEY, and SENDER_NUMBER with your AllMySms credentials.

3. Register the transport in config/services.php (Laravel):

   'notifier' => [
       'transports' => [
           'allmysms' => [
               'dsn' => env('ALLMYSMS_DSN'),
           ],
       ],
   ],
   

4. Send your first SMS in a Laravel job or controller:

   use Symfony\Component\Notifier\Notifier;
   use Symfony\Component\Notifier\Message\SmsMessage;
   
   $notifier = new Notifier([new AllMySmsTransport(env('ALLMYSMS_DSN'))]);
   $notifier->send(new SmsMessage('+1234567890', 'Hello from Laravel!'));
   

First Use Case: Transactional Alerts

Use the package to send OTPs or alerts with minimal boilerplate:

$sms = new SmsMessage('+1234567890', 'Your OTP is: ' . $otp);
$notifier->send($sms);

Implementation Patterns

Workflow: Queued SMS Delivery

Leverage Laravel’s queues to handle SMS asynchronously:

1. Dispatch a job:

   SendSmsJob::dispatch('+1234567890', 'Your order is confirmed!');
   

2. Handle the job:

   public function handle()
   {
       $notifier = app(Notifier::class);
       $notifier->send(new SmsMessage($this->phone, $this->message));
   }
   

Workflow: Customizing SMS Options

Attach AllMySmsOptions for advanced features like scheduling or campaigns:

$sms = new SmsMessage('+1234567890', 'Scheduled alert');
$sms->options((new AllMySmsOptions())
    ->date('2023-12-31 12:00:00') // Schedule for later
    ->campaignName('HolidayPromo') // Track in AllMySms dashboard
);

$notifier->send($sms);

Integration with Laravel Notifications

Extend Laravel’s Notification class to use AllMySms:

use Illuminate\Notifications\Notification;
use Symfony\Component\Notifier\Message\SmsMessage;

class SmsNotification extends Notification
{
    public function via($notifiable)
    {
        return ['sms'];
    }

    public function toSms($notifiable)
    {
        return (new SmsMessage($notifiable->phone, 'Hello, ' . $notifiable->name))
            ->options((new AllMySmsOptions())->campaignName('UserAlerts'));
    }
}

Testing Patterns

Mock the transport for unit tests:

$transport = $this->createMock(TransportInterface::class);
$transport->expects($this->once())
    ->method('send')
    ->with($this->isInstanceOf(SmsMessage::class));

$notifier = new Notifier([$transport]);
$notifier->send(new SmsMessage('+1234567890', 'Test'));

Gotchas and Tips

Pitfalls

1. DSN Format Sensitivity:

   • Ensure the DSN follows allmysms://LOGIN:APIKEY@default?from=SENDER exactly.
   • Missing default or from may cause silent failures.

2. Phone Number Validation:

   • AllMySms may reject malformed numbers (e.g., +123 instead of +1234567890).
   • Validate with Str::startsWith($phone, '+') before sending.

3. Rate Limits:

   • AllMySms may throttle requests. Use Laravel’s queues to distribute load:

     $this->dispatch(new SendSmsJob($phone, $message))->onQueue('sms');
     

4. Options Overrides:

   • Some AllMySmsOptions (e.g., simulate) may conflict with production use.
   • Test in a sandbox environment first.

Debugging

• Enable Verbose Logging:

  $options = (new AllMySmsOptions())->verbose(1);
  $sms->options($options);
  

  Check Laravel logs for detailed API responses.

• Check AllMySms Dashboard:

  • Monitor delivery status and errors in AllMySms API Dashboard.

Extension Points

1. Custom Transport: Extend AllMySmsTransport to add retries or fallback logic:

   class CustomAllMySmsTransport extends AllMySmsTransport
   {
       public function send(SmsMessage $message): SentMessage
       {
           try {
               return parent::send($message);
           } catch (TransportException $e) {
               // Fallback to email or retry
           }
       }
   }
   

2. Dynamic DSN: Load the DSN from a config file or environment variable dynamically:

   $dsn = config('services.allmysms.dsn');
   $transport = new AllMySmsTransport($dsn);
   

3. Event Listeners: Listen for sent/failed events to trigger analytics or retries:

   public function handle(SentMessage $message)
   {
       if ($message->failed()) {
           // Log or retry
       }
   }
   

Tips

• Use Laravel’s env() Helper: Avoid hardcoding credentials; use .env:

  $transport = new AllMySmsTransport(env('ALLMYSMS_DSN'));
  

• Batch Processing: For bulk SMS, use Laravel’s chunking:

  User::chunk(100, function ($users) {
      foreach ($users as $user) {
          $this->dispatch(new SendSmsJob($user->phone, 'Batch message'));
      }
  });
  

• Fallback Mechanism: Combine with another transport (e.g., Twilio) for redundancy:

  $notifier = new Notifier([
      new AllMySmsTransport(env('ALLMYSMS_DSN')),
      new TwilioTransport(env('TWILIO_DSN')),
  ]);