Laravel Melipayamak Sms Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add the package via Composer:

     composer require ems-spot/laravel-melipayamak-sms
     

   • Publish the config file:

     php artisan vendor:publish --provider="EmsSpot\Melipayamak\MelipayamakServiceProvider"
     

   • Configure .env with your Melipayamak credentials:

     MELIPAYAMAK_USERNAME=your_username
     MELIPAYAMAK_PASSWORD=your_password
     MELIPAYAMAK_FROM=your_sender_id
     MELIPAYAMAK_DEBUG=false
     MELIPAYAMAK_DEBUG_RECIPIENT=test_phone
     

2. First Use Case:

   • Extend Laravel's Notifiable trait in your user model:

     use Notifiable;
     use EmsSpot\Melipayamak\SMS;
     

   • Implement the via() and toSms() methods in your notifiable class (e.g., User):

     public function via($notifiable)
     {
         return ['EmsSpot\Melipayamak\SMS'];
     }
     
     public function toSms($notifiable)
     {
         return (new SMS)
             ->text('Your activation code is: ' . $this->activation_code)
             ->to($notifiable->phone)
             ->sendText();
     }
     

   • Trigger the notification:

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

Implementation Patterns

Usage Patterns

1. Basic SMS Notification:

   • Use the SMS facade or class directly in your notifiable classes:

     (new SMS)
         ->text('Hello, this is a test message.')
         ->to('+905551234567')
         ->sendText();
     

2. Dynamic Content:

   • Pass dynamic values to the SMS text using Laravel's translation or string interpolation:

     public function toSms($notifiable)
     {
         return (new SMS)
             ->text(__('sms.welcome', ['name' => $notifiable->name]))
             ->to($notifiable->phone)
             ->sendText();
     }
     

3. Debugging Mode:

   • Enable debug mode in .env to test messages without sending:

     MELIPAYAMAK_DEBUG=true
     MELIPAYAMAK_DEBUG_RECIPIENT=+905551234567
     

4. Batch Sending:

   • Loop through a collection of users and send SMS notifications:

     foreach ($users as $user) {
         $user->notify(new YourNotificationClass());
     }
     

5. Customizing the SMS Class:

   • Extend the EmsSpot\Melipayamak\SMS class to add custom methods or logic:

     class CustomSMS extends SMS
     {
         public function withPriority($priority)
         {
             $this->priority = $priority;
             return $this;
         }
     }
     

Workflows

1. User Activation:

   • Send an activation code via SMS when a user registers:

     $user->activation_code = Str::random(6);
     $user->notify(new ActivationNotification($user));
     

2. Password Reset:

   • Send a password reset link via SMS:

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

3. Transactional Alerts:

   • Notify users about order status changes, payment confirmations, etc.:

     $order->user->notify(new OrderStatusUpdatedNotification($order));
     

Integration Tips

1. Queue Notifications:

   • Use Laravel's queue system to avoid timeouts for bulk SMS sending:

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

2. Logging:

   • Log SMS responses for debugging or auditing:

     use Illuminate\Support\Facades\Log;
     
     public function toSms($notifiable)
     {
         $sms = (new SMS)
             ->text('Your message.')
             ->to($notifiable->phone);
     
         $response = $sms->sendText();
         Log::info('SMS sent to ' . $notifiable->phone, ['response' => $response]);
     
         return $sms;
     }
     

3. Testing:

   • Use Laravel's mocking features to test SMS notifications:

     $this->mock(EmsSpot\Melipayamak\SMS::class)
         ->shouldReceive('sendText')
         ->once()
         ->andReturn(true);
     

Gotchas and Tips

Pitfalls

1. Environment Configuration:

   • Forgetting to set MELIPAYAMAK_FROM (sender ID) will cause the SMS to fail silently. Always validate this field.

2. Phone Number Format:

   • Melipayamak expects phone numbers in a specific format (e.g., +905551234567). Ensure your database stores numbers in this format or normalize them before sending:

     $phone = '+90' . str_replace('0', '', $notifiable->phone);
     

3. Debug Mode Misuse:

   • Debug mode sends messages to MELIPAYAMAK_DEBUG_RECIPIENT instead of the intended recipient. Remember to disable it (MELIPAYAMAK_DEBUG=false) before production.

4. Rate Limits:

   • Melipayamak may have rate limits. Handle potential MelipayamakException in your code:

     try {
         $sms->sendText();
     } catch (\Exception $e) {
         Log::error('Failed to send SMS: ' . $e->getMessage());
         // Retry or notify admin
     }
     

5. Character Limits:

   • SMS messages are typically limited to 160 characters. Longer messages may be split or truncated. Test your messages to ensure they fit.

Debugging

1. Check Response:

   • The sendText() method returns a response object. Inspect it for errors:

     $response = $sms->sendText();
     if ($response->success === false) {
         // Handle error
     }
     

2. Enable Debug Logging:

   • Set MELIPAYAMAK_DEBUG=true and check Laravel logs for debug messages.

3. Test with Known Working Credentials:

   • If messages aren’t sending, verify your MELIPAYAMAK_USERNAME and MELIPAYAMak_PASSWORD are correct.

Config Quirks

1. Config File Location:

   • The published config file is located at config/melipayamak.php. Customize it as needed:

     'default' => [
         'username' => env('MELIPAYAMAK_USERNAME'),
         'password' => env('MELIPAYAMAK_PASSWORD'),
         'from' => env('MELIPAYAMAK_FROM'),
         'debug' => env('MELIPAYAMAK_DEBUG', false),
         'debug_recipient' => env('MELIPAYAMAK_DEBUG_RECIPIENT'),
     ],
     

2. Multiple Configurations:

   • The package supports multiple configurations (e.g., for different environments or clients). Use the config() helper to switch:

     $sms = (new SMS)->setConfig('client2');
     

Extension Points

1. Custom SMS Class:

   • Override the EmsSpot\Melipayamak\SMS class in your AppServiceProvider:

     public function register()
     {
         $this->app->bind('EmsSpot\Melipayamak\SMS', function () {
             return new App\Services\CustomSMS();
         });
     }
     

2. Add Custom Methods:

   • Extend the SMS class to add features like scheduling or priority:

     class CustomSMS extends SMS
     {
         public function schedule(\Carbon\Carbon $time)
         {
             $this->scheduledAt = $time;
             return $this;
         }
     }
     

3. Event Listeners:

   • Listen for SMS events (e.g., SMSSent) to log or process responses:

     Event::listen('EmsSpot\Melipayamak\Events\SMSSent', function ($event) {
         Log::info('SMS sent to ' . $event->phone, ['message' => $event->message]);
     });
     

4. Middleware:

   • Add middleware to validate phone numbers or check user permissions before sending:

     $sms->through(function ($notifiable, $sms) {
         if (!$notifiable->canReceiveSMS()) {
             throw new \Exception('User cannot receive SMS.');
         }
         return $sms;
     });