Laravel Sms Gateway Laravel Package

Getting Started

Minimal Setup

1. Install Core & Driver

   composer require misaf/laravel-sms-gateway misaf/laravel-sms-gateway-{provider}
   

   (Replace {provider} with your gateway, e.g., kavenegar.)

2. Publish Config

   php artisan vendor:publish --tag=sms-gateway-config
   

   Configure credentials in config/sms-gateway.php (e.g., API keys, endpoints).

3. First SMS Send

   use Misaf\SmsGateway\Facades\SmsGateway;
   
   $response = SmsGateway::send('+989123456789', 'Hello from Laravel!');
   

   Check $response for provider-specific data (e.g., success, messageId).

First Use Case: Otp Verification

// Generate and send OTP
$otp = Str::random(6);
SmsGateway::send('+989123456789', "Your OTP is: {$otp}");

// Store OTP in session/DB for validation

Implementation Patterns

1. Driver Switching Per Request

Override the default driver dynamically:

// Use a specific driver for this request
SmsGateway::useDriver('kavenegar')->send('+989123456789', 'Test');

// Reset to default after
SmsGateway::useDefaultDriver();

2. Event Listeners for SMS Logs

Publish the event class and listen for SmsSent:

// config/sms-gateway.php
'events' => [
    'enabled' => true,
],

// Listen in EventServiceProvider
protected $listen = [
    \Misaf\SmsGateway\Events\SmsSent::class => [
        \App\Listeners\LogSms::class,
    ],
];

Listener Example:

public function handle(SmsSent $event) {
    Log::info('SMS Sent', [
        'to' => $event->to,
        'message' => $event->message,
        'response' => $event->response,
    ]);
}

3. HTTP Client Customization

Extend the default HTTP client (e.g., for retries or headers):

// config/sms-gateway.php
'http' => [
    'timeout' => 30,
    'headers' => [
        'X-Custom-Header' => 'value',
    ],
],

4. Bulk SMS

Use the sendBulk method (if supported by the driver):

$recipients = ['+989123456789', '+98999999999'];
$response = SmsGateway::sendBulk($recipients, 'Bulk message');

5. Fallback Drivers

Configure a fallback driver in config/sms-gateway.php:

'drivers' => [
    'primary' => 'kavenegar',
    'fallback' => 'ghasedak',
],

The package will auto-switch if the primary fails.

Gotchas and Tips

Pitfalls

1. Driver-Specific Quirks

   • Some drivers (e.g., kavenegar) require Unicode support for Persian/Arabic text. Enable it:

     SmsGateway::useDriver('kavenegar')->setUnicode(true)->send(...);
     

   • Rate Limits: Providers like messagebird throttle requests. Implement exponential backoff in listeners.

2. Event Data Mismatch

   • The SmsSent event’s response field varies by driver. Check the driver’s docs for structure (e.g., kavenegar returns token, while plivo returns message_uuid).

3. Configuration Overrides

   • Driver-specific configs (e.g., kavenegar’s sandbox mode) must be set in the driver’s package config, not the main sms-gateway.php.

4. Testing Without Real SMS

   • Use the mock driver for testing (if available) or stub the SmsGateway facade:

     SmsGateway::shouldReceive('send')->andReturn(['success' => true]);
     

Debugging Tips

• Enable Logging:

  SmsGateway::setDebug(true); // Logs raw HTTP requests/responses
  

• Check Provider-Specific Errors:
  • Example: kavenegar returns error_code in the response. Handle it:

    $response = SmsGateway::send(...);
    if ($response['success'] === false && $response['error_code'] === 100) {
        // Handle "Invalid API Key" error
    }
    

Extension Points

1. Custom Drivers Create a new driver by implementing Misaf\SmsGateway\Contracts\Driver:

   namespace App\Providers;
   
   use Misaf\SmsGateway\Contracts\Driver;
   
   class CustomDriver implements Driver {
       public function send($to, $message) {
           // Your logic here
       }
   }
   

   Register it in config/sms-gateway.php:

   'drivers' => [
       'custom' => \App\Providers\CustomDriver::class,
   ],
   

2. Middleware for SMS Add middleware to validate recipients or log before sending:

   SmsGateway::extend(function ($gateway) {
       $gateway->beforeSend(function ($to, $message) {
           if (!preg_match('/^\+989\d{9}$/', $to)) {
               throw new \Exception('Invalid Iranian number');
           }
       });
   });
   

3. Queue SMS for Async Delivery Dispatch a job instead of sending immediately:

   SendSmsJob::dispatch('+989123456789', 'Hello')->onQueue('sms');
   

   Job Example:

   use Misaf\SmsGateway\Facades\SmsGateway;
   
   class SendSmsJob implements ShouldQueue {
       public function handle() {
           SmsGateway::send($this->to, $this->message);
       }
   }
   

Performance Tips

• Batch Processing: Use sendBulk for >10 recipients to reduce API calls.
• Caching: Cache API responses if your provider supports it (e.g., plivo’s message_uuid can be cached for retries).