Laravel Dreamsms Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dreamsms/laravel-dreamsms
   php artisan vendor:publish --provider="DreamSms\LaravelDreamSms\DreamSmsServiceProvider" --tag=config
   

   Add credentials to .env:

   DREAMSMS_BASE_URL=https://www.dreams.sa/index.php/api
   DREAMSMS_USER=your_username
   DREAMSMS_SECRET_KEY=your_api_key
   DREAMSMS_SENDER_NAME=YourSenderID
   

2. First Use Case: Send a test SMS via Tinker:

   use DreamSms\LaravelDreamSms\Facades\DreamSms;
   DreamSms::send('+966123456789', 'Hello from Laravel!');
   

Key Entry Points

• Facade: DreamSms (global access)
• Service Container: app(DreamSms::class)
• Config: config('dreamsms')

Implementation Patterns

Core Workflows

1. Sending SMS

   • Single recipient:

     DreamSms::send('+966123456789', 'Your OTP is 1234');
     

   • Bulk recipients:

     $recipients = ['+966123456789', '+966987654321'];
     DreamSms::sendMultiple($recipients, 'Hello all!');
     

2. OTP Management

   • Generate and send OTP:

     $otp = DreamSms::generateOtp();
     DreamSms::sendOtp('+966123456789', $otp);
     

3. Balance & Account

   • Check balance:

     $balance = DreamSms::getBalance();
     

Integration Tips

• Queue Jobs: Wrap SMS sends in jobs for async processing:

  use DreamSms\Jobs\SendSmsJob;
  
  SendSmsJob::dispatch('+966123456789', 'Delayed message');
  

• Events: Listen for SMS events (e.g., SmsSent):

  DreamSms::send('+966123456789', 'Event-triggered');
  

• Custom Senders: Override sender name dynamically:

  DreamSms::setSender('CustomSender')->send('+966123456789', 'Message');
  

Gotchas and Tips

Common Pitfalls

1. Authentication Failures

   • Ensure DREAMSMS_SECRET_KEY matches the API key from your DreamSMS dashboard.
   • Verify DREAMSMS_BASE_URL is correct (some accounts use https://api.dreams.sa).

2. Sender Name Restrictions

   • Saudi Arabia’s CITC requires pre-approved sender IDs. Use the exact registered name (e.g., YourBrand not yourbrand).
   • Test with a generic sender (e.g., DreamSMS) before submitting for approval.

3. Rate Limits

   • Default limit: 1 SMS/sec. Exceeding this may return 429 Too Many Requests.
   • Solution: Implement exponential backoff in retries:

     try {
         DreamSms::send($number, $message);
     } catch (\DreamSms\Exceptions\RateLimitException $e) {
         sleep(2); // Wait before retry
         retry();
     }
     

4. OTP Length

   • DreamSMS enforces 4–6 digit OTPs. Validate server-side:

     $otp = str_pad(rand(0, 999999), 6, '0', STR_PAD_LEFT);
     

Debugging Tips

• Enable Logging: Add to config/dreamsms.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs appear in storage/logs/laravel.log.

• API Response Inspection: Use the getLastResponse() method to debug raw API calls:

  DreamSms::send('+966123456789', 'Test');
  dd(DreamSms::getLastResponse());
  

Extension Points

1. Custom HTTP Client Override the default Guzzle client in a service provider:

   $this->app->singleton(DreamSms::class, function ($app) {
       $client = new \GuzzleHttp\Client(['timeout' => 30]);
       return new \DreamSms\LaravelDreamSms\DreamSms($client, $app['config']['dreamsms']);
   });
   

2. Event Customization Extend the SmsSent event to add metadata:

   DreamSms::extend(function ($sms) {
       $sms->onSent(function ($event) {
           \Log::info('Custom event', ['message' => $event->message]);
       });
   });
   

3. Fallback for Failures Implement a fallback sender (e.g., Twilio) if DreamSMS fails:

   try {
       DreamSms::send($number, $message);
   } catch (\Exception $e) {
       \Log::error('DreamSMS failed: ' . $e->getMessage());
       // Fallback to Twilio or email
   }