Laravel Sms Office Laravel Package

Getting Started

1. Installation:

   composer require nikajorjika/laravel-sms-office
   

   Publish the config file:

   php artisan vendor:publish --provider="Nikajorjika\SmsOffice\SmsOfficeServiceProvider" --tag="config"
   

2. Configure .env:

   SMS_OFFICE_DRIVER=sms-office
   SMS_OFFICE_KEY=your_api_key
   SMS_OFFICE_FROM=YourSenderName
   SMS_OFFICE_NOSMS=no_sms_code
   

3. First Use Case: Send an SMS via facade:

   use Nikajorjika\SmsOffice\Facades\SmsOffice;
   
   SmsOffice::message("Hello via SMS!")->to("995551234567")->send();
   

Implementation Patterns

Facade Usage

• Basic SMS Send:

  SmsOffice::message("Your OTP is 1234.")
      ->to("995551234567")
      ->urgent(true) // Optional: Mark as urgent
      ->send();
  

• Dynamic Messages:

  $phone = $user->phone_number;
  $message = "Welcome, {$user->name}! Your account is active.";
  SmsOffice::message($message)->to($phone)->send();
  

Notification Channel Integration

1. Extend Notification:

   use Nikajorjika\SmsOffice\SmsOfficeChannel;
   
   class AccountActivationNotification extends Notification
   {
       public function via($notifiable)
       {
           return [SmsOfficeChannel::class];
       }
   
       public function toSms($notifiable)
       {
           return "Hello {$notifiable->name}, your account is now active!";
       }
   }
   

2. Route SMS in Model:

   class User extends Authenticatable
   {
       public function routeNotificationForSms()
       {
           return $this->phone_number; // Must return valid phone (e.g., "995551234567")
       }
   }
   

3. Trigger Notification:

   $user->notify(new AccountActivationNotification());
   

Queueing SMS

• Use Laravel’s queue system for async sends:

  $user->notify(new AccountActivationNotification())->onQueue('sms');
  

Driver Switching

• Test with log driver (no API calls):

  SMS_OFFICE_DRIVER=log
  

  Logs will appear in storage/logs/laravel.log.

Gotchas and Tips

Common Pitfalls

1. Phone Number Format:

   • Must include country code (e.g., 995551234567).
   • Fix: Validate with Str::startsWith($phone, '995') or similar.

2. $urgent Parameter:

   • Gotcha: Must be a string ("true"/"false") or null.

     // ❌ Fails (PHP 8+ strict mode)
     SmsOffice::message("Hi")->urgent(false)->send();
     

   • Fix: Use "true"/"false" strings or omit:

     SmsOffice::message("Hi")->urgent("true")->send();
     

3. No-SMS Code:

   • If SMS_OFFICE_NOSMS is set, the package auto-appends [no_sms] to messages.
   • Disable: Set SMS_OFFICE_NOSMS=null in config.

4. Config Key Mismatch:

   • Old code might use "sender" instead of "from".
   • Fix: Update config or check for deprecated keys.

Debugging Tips

• Enable Logging: Switch to log driver to debug messages without API calls.
• API Errors: Check storage/logs/laravel.log for SMS Office API responses.
• Rate Limits: The package doesn’t handle retries. Implement a fallback queue job for failed sends.

Extension Points

1. Custom Drivers: Extend Nikajorjika\SmsOffice\Contracts\Driver to add new providers (e.g., Twilio).

   class CustomDriver implements Driver {
       public function send($message, $phone, $urgent = null) { ... }
   }
   

   Register in config/smsoffice.php:

   'supported_drivers' => ['sms-office', 'log', 'custom-driver'],
   

2. Message Formatting: Override the SmsOffice facade to preprocess messages:

   SmsOffice::extend(function ($app) {
       $facade = new SmsOffice($app);
       $facade->setFormatter(function ($message) {
           return "[Custom] " . $message;
       });
       return $facade;
   });
   

3. Webhook Validation: For production, validate SMS Office’s API responses (e.g., check for success: true in the response).

Performance Considerations

• Batch Sends: The package doesn’t support bulk sends. For high volumes, use the API directly or queue individual messages.
• Async Validation: Validate phone numbers/urgent flags before queuing to avoid failed jobs.

Testing

• Unit Tests: Mock the SmsOffice facade to test notifications:

  $this->mock(SmsOffice::class)->shouldReceive('send')->once();
  

• Feature Tests: Use the log driver to assert message content:

  $this->actingAs($user)->notify(new AccountActivationNotification());
  $this->assertLogContains("Hello {$user->name}...");