Laravel Web2Sms Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require daika7ana/laravel-web2sms
   

   Publish the config file:

   php artisan vendor:publish --provider="Daika7ana\Web2Sms\Web2SmsServiceProvider"
   

2. Configuration Edit .env with your Web2SMS credentials:

   WEB2SMS_USERNAME=your_username
   WEB2SMS_PASSWORD=your_password
   WEB2SMS_API_URL=https://api.web2sms.com
   

3. First Use Case Send a test SMS in a controller:

   use Daika7ana\Web2Sms\Facades\Web2Sms;
   
   public function sendTestSms()
   {
       $response = Web2Sms::send([
           'to' => '254712345678', // Format: CountryCode + PhoneNumber
           'message' => 'Hello from Laravel!',
       ]);
   
       return $response->success() ? 'SMS sent!' : 'Failed: ' . $response->message();
   }
   

Implementation Patterns

Core Workflows

1. Basic SMS Sending

   Web2Sms::send([
       'to' => '254712345678',
       'message' => 'Your OTP is 12345',
   ]);
   

2. Bulk SMS with Recipients

   $recipients = ['254712345678', '254798765432'];
   foreach ($recipients as $phone) {
       Web2Sms::send(['to' => $phone, 'message' => 'Bulk message']);
   }
   

3. Sending with Custom Headers

   Web2Sms::send([
       'to' => '254712345678',
       'message' => 'Custom header test',
       'headers' => ['X-Custom-Header' => 'value'],
   ]);
   

4. Handling Responses

   $response = Web2Sms::send([...]);
   if ($response->success()) {
       $messageId = $response->messageId(); // Unique ID for tracking
   } else {
       Log::error('SMS failed: ' . $response->message());
   }
   

Integration Tips

• Queue SMS Jobs Use Laravel queues to avoid timeouts for bulk SMS:

  dispatch(new SendSmsJob($phone, $message));
  

  Job class:

  class SendSmsJob implements ShouldQueue
  {
      public function handle()
      {
          Web2Sms::send(['to' => $this->phone, 'message' => $this->message]);
      }
  }
  

• Logging Failed SMS Extend the package to log failures:

  Web2Sms::extend(function ($builder) {
      $builder->afterSend(function ($response) {
          if (!$response->success()) {
              Log::error('Web2SMS Error', [
                  'phone' => $response->to(),
                  'message' => $response->message(),
                  'code' => $response->code(),
              ]);
          }
      });
  });
  

• Rate Limiting Use Laravel’s throttle middleware to limit SMS bursts:

  Route::middleware(['throttle:10,1'])->group(function () {
      Route::post('/send-sms', [SmsController::class, 'send']);
  });
  

Gotchas and Tips

Common Pitfalls

1. Phone Number Format

   • Issue: SMS fails if the phone number isn’t in CountryCodePhoneNumber format (e.g., 254712345678 for Kenya).
   • Fix: Validate input with:

     $phone = preg_replace('/[^0-9]/', '', $phone); // Remove non-digits
     if (strlen($phone) < 10) {
         throw new \InvalidArgumentException('Invalid phone number');
     }
     

2. API URL Hardcoding

   • Issue: The package defaults to https://api.web2sms.com, but some providers use custom URLs (e.g., https://yourprovider.com/api).
   • Fix: Override in .env or config:

     WEB2SMS_API_URL=https://yourprovider.com/api
     

3. No Retry Mechanism

   • Issue: Temporary failures (e.g., network issues) aren’t retried.
   • Fix: Implement a retry decorator:

     Web2Sms::extend(function ($builder) {
         $builder->setRetryPolicy(new RetryPolicy(3)); // Retry 3 times
     });
     

4. No Transactional Support

   • Issue: The package doesn’t support transactional SMS (e.g., for OTPs with expiry).
   • Workaround: Manually track SMS delivery statuses in a database table:

     $sms = Sms::create(['phone' => $phone, 'message' => $message]);
     $response = Web2Sms::send(['to' => $phone, 'message' => $message]);
     if ($response->success()) {
         $sms->update(['status' => 'sent', 'message_id' => $response->messageId()]);
     }
     

5. No Webhook Support

   • Issue: The package doesn’t listen for delivery reports.
   • Fix: Poll the API periodically or set up a webhook endpoint to check status:

     $status = Web2Sms::checkStatus($messageId);
     

Debugging Tips

• Enable Debug Mode Add to .env:

  WEB2SMS_DEBUG=true
  

  This logs the raw API response for troubleshooting.

• Check HTTP Status Codes The response object includes the HTTP status code:

  if ($response->code() === 401) {
      // Unauthorized (check credentials)
  }
  

• Test with a Sandbox Use a Web2SMS sandbox environment (if available) to avoid hitting rate limits during development.

Extension Points

1. Custom Response Handling Extend the Daika7ana\Web2Sms\Response class to add custom methods:

   Web2Sms::extend(function ($builder) {
       $builder->addResponseMethod('isDelivered', function () {
           return $this->status() === 'delivered';
       });
   });
   

2. Add Templates Support SMS templates for consistency:

   Web2Sms::sendTemplate('otp', ['code' => '12345'], '254712345678');
   

   (Requires modifying the package or creating a wrapper.)

3. Support for Unicode If sending non-ASCII messages (e.g., emojis), ensure the API supports UTF-8:

   Web2Sms::send([
       'to' => '254712345678',
       'message' => 'Hello 🌍!', // Unicode character
       'encoding' => 'UTF-8',
   ]);