Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require kavenegar/laravel
   

   Add to config/app.php:

   'providers' => [
       // ...
       Kavenegar\Laravel\ServiceProvider::class,
   ],
   'aliases' => [
       'Kavenegar' => Kavenegar\Laravel\Facade::class,
   ]
   

   Publish config:

   php artisan vendor:publish --provider="Kavenegar\Laravel\ServiceProvider"
   

2. Configure API Key: Edit .env or config/kavenegar.php:

   KAVENEGAR_API_KEY=your_api_key_here
   

3. First Use Case: Send a basic SMS:

   use Kavenegar\Facades\Kavenegar;
   
   Kavenegar::send('1234567890', 'Hello from Laravel!');
   

Implementation Patterns

Core Workflows

1. Sending SMS:

   • Basic:

     Kavenegar::send($receiver, $message);
     

   • With Options:

     Kavenegar::send($receiver, $message, [
         'type' => 'sms', // or 'dlr'
         'line' => '1234567890', // sender number
     ]);
     

2. Verification Codes:

   $code = Kavenegar::sendVerificationCode($receiver, [
       'template' => 'verify_code',
       'token' => '123456',
       'callback' => 'http://example.com/callback',
   ]);
   

3. Async Sending:

   Kavenegar::sendAsync($receiver, $message);
   

4. Queue Integration:

   // Dispatch a job
   SendSmsJob::dispatch($receiver, $message);
   

   Define job:

   use Kavenegar\Facades\Kavenegar;
   use Illuminate\Bus\Queueable;
   
   class SendSmsJob implements ShouldQueue {
       use Queueable;
   
       public function handle() {
           Kavenegar::send($this->receiver, $this->message);
       }
   }
   

Common Integrations

1. User Registration/Reset:

   // In UserController@register
   $code = Kavenegar::sendVerificationCode($user->phone, [
       'template' => 'register_code',
       'token' => $user->verification_token,
   ]);
   

2. Two-Factor Auth:

   $code = Kavenegar::send($user->phone, "Your 2FA code: {$user->two_factor_code}");
   

3. Notifications: Extend Laravel's Notification class:

   class SmsNotification extends Notification {
       public function via($notifiable) {
           return ['kavenegar'];
       }
   
       public function toKavenegar($notifiable) {
           return [
               'message' => 'Your notification message',
               'template' => 'notification_template',
           ];
       }
   }
   

Gotchas and Tips

Pitfalls

1. API Key Security:

   • Never commit .env or hardcode keys in config files.
   • Use Laravel's .env or a secure secrets manager.

2. Rate Limits:

   • Kavenegar enforces rate limits (~1 SMS/sec by default). Handle KavenegarException for throttling:

     try {
         Kavenegar::send($receiver, $message);
     } catch (\Kavenegar\Exceptions\KavenegarException $e) {
         if ($e->getCode() === 429) {
             // Retry logic or notify admin
         }
     }
     

3. Template Dependencies:

   • Ensure templates (e.g., verify_code) are pre-registered in Kavenegar Panel.
   • Use type: 'dlr' for delivery reports, but templates must support it.

4. Queue Stuck Jobs:

   • Monitor failed_jobs table for stuck SMS jobs. Implement a retry mechanism:

     $job->retryAfter(5); // Retry after 5 seconds
     

Debugging

1. Enable Logging: Add to config/kavenegar.php:

   'log' => true,
   

   Check storage/logs/laravel.log for API responses/errors.

2. Mocking for Tests: Use a mock service provider in config/app.php during testing:

   'providers' => [
       // ...
       Kavenegar\Laravel\Testing\ServiceProvider::class, // Replace with mock provider
   ],
   

Extension Points

1. Custom Responses: Override the facade or service container binding:

   $this->app->bind(KavenegarManager::class, function () {
       return new CustomKavenegarManager();
   });
   

2. Webhook Handling: Validate Kavenegar webhooks (e.g., DLR) in a route:

   Route::post('/kavenegar-webhook', function (Request $request) {
       $validator = Validator::make($request->all(), [
           'token' => 'required|string',
           'message' => 'required',
       ]);
       // Process valid webhook
   });
   

3. Fallback Mechanisms: Implement a fallback for failed sends:

   try {
       Kavenegar::send($receiver, $message);
   } catch (Exception $e) {
       Log::error("Kavenegar failed: {$e->getMessage()}");
       // Fallback to email or another SMS provider
   }
   

Configuration Quirks

1. Line Number Validation: Kavenegar validates sender numbers (line). Ensure your config/kavenegar.php line is registered in their panel.

2. Async vs Sync:

   • sendAsync uses a queue but may not guarantee order. Use send for critical, synchronous messages.

3. Character Limits:

   • SMS: 300 chars (UTF-8). Use type: 'dlr' for longer messages (split internally by Kavenegar).