Kavenegar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sayadaazami/kavenegar
   

2. Publish Config:

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

   (Laravel 5/6: Use --provider="Kavenegar\Laravel\ServiceProviderLaravel5/6")

   • Config file: config/kavenegar.php
   • Set api_key from Kavenegar Panel.

3. First Use Case: Send a basic SMS:

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

Key Files to Review

• config/kavenegar.php: API key, sandbox mode, and default settings.
• Kavenegar facade: Primary entry point for all SMS operations.

Implementation Patterns

Core Workflows

1. Sending SMS:

   // Basic
   Kavenegar::send($receiver, $message);
   
   // With options (e.g., line number, type)
   Kavenegar::send($receiver, $message, [
       'line' => '1234567890', // Sender line
       'type' => 'sms',       // 'sms' or 'voice'
   ]);
   

2. Verification Codes:

   $code = Kavenegar::sendVerificationCode($receiver, $templateId);
   // Store $code in DB for later validation.
   

3. Batch Sending:

   $receivers = ['09123456789', '09987654321'];
   Kavenegar::batchSend($receivers, 'Your message here');
   

4. Async Sending (Queue):

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

   • Create a job:

     php artisan make:job SendSmsJob
     

     // app/Jobs/SendSmsJob.php
     public function handle() {
         Kavenegar::send($this->receiver, $this->message);
     }
     

5. Templates:

   • Use predefined templates from Kavenegar Panel.
   • Replace placeholders:

     Kavenegar::sendTemplate($receiver, $templateId, ['name' => 'John']);
     

Integration Tips

• Events: Trigger SMS on model events (e.g., created):

  // User.php
  protected static function boot() {
      static::created(function ($user) {
          Kavenegar::send($user->phone, "Welcome, {$user->name}!");
      });
  }
  

• Middleware: Send notifications via middleware:

  // app/Http/Middleware/SendWelcomeSms.php
  public function handle($request, Closure $next) {
      if (auth()->check() && auth()->user()->shouldSendWelcomeSms()) {
          Kavenegar::send(auth()->user()->phone, 'Welcome!');
      }
      return $next($request);
  }
  

• Notifications: Extend Laravel’s Notification class:

  // app/Notifications/SmsNotification.php
  public function via($notifiable) {
      return ['kavenegar'];
  }
  
  public function toKavenegar($notifiable) {
      return (string) $this->message;
  }
  

  • Register the channel in config/notifications.php.

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never commit config/kavenegar.php to version control.
   • Use environment variables:

     // .env
     KAVENEGAR_API_KEY=your_key_here
     

     Update config file:

     'api_key' => env('KAVENEGAR_API_KEY'),
     

2. Sandbox Mode:

   • Enable in config ('sandbox' => true) for testing.
   • Sandbox receivers are hardcoded (e.g., 1000000000). Use real numbers in production.

3. Rate Limits:

   • Kavenegar enforces rate limits (e.g., 1 SMS/sec for free tier).
   • Implement retries with exponential backoff:

     try {
         Kavenegar::send($receiver, $message);
     } catch (\Exception $e) {
         if ($e->getCode() === 429) { // Rate limited
             sleep(2);
             retry();
         }
     }
     

4. Character Limits:

   • SMS: Max 300 characters (70 chars per segment; extra segments cost more).
   • Voice: Max 60 seconds.
   • Trim messages or split them:

     $message = Str::limit($longMessage, 300);
     

5. Error Handling:

   • Common errors:
     • 401: Invalid API key.
     • 400: Invalid receiver/format.
     • 429: Rate limited.
   • Log errors:

     try {
         Kavenegar::send($receiver, $message);
     } catch (\Exception $e) {
         Log::error("Kavenegar SMS failed: {$e->getMessage()}");
     }
     

Debugging Tips

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

   'debug' => true,
   

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

2. Test with Sandbox:

   • Set 'sandbox' => true in config.
   • Use sandbox receiver (1000000000) to verify messages.

3. API Response Inspection: Access raw responses via:

   $response = Kavenegar::send($receiver, $message, [], true);
   // $response contains full API reply (e.g., status, message ID).
   

Extension Points

1. Custom HTTP Client: Override the default Guzzle client in ServiceProvider:

   // app/Providers/KavenegarServiceProvider.php
   public function register() {
       $this->app->singleton('kavenegar', function ($app) {
           $client = new \GuzzleHttp\Client([
               'timeout' => 30,
               'headers' => ['User-Agent' => 'MyApp/1.0'],
           ]);
           return new Kavenegar\Kavenegar($app['config']['kavenegar'], $client);
       });
   }
   

2. Add New Methods: Extend the facade or service class:

   // app/Extensions/KavenegarExtension.php
   namespace App\Extensions;
   
   use Kavenegar\Kavenegar as BaseKavenegar;
   
   class KavenegarExtension extends BaseKavenegar {
       public function sendWithRetry($receiver, $message, $retries = 3) {
           for ($i = 0; $i < $retries; $i++) {
               try {
                   return parent::send($receiver, $message);
               } catch (\Exception $e) {
                   if ($i === $retries - 1) throw $e;
                   sleep(2 ** $i);
               }
           }
       }
   }
   

   Bind it in a service provider:

   $this->app->bind('kavenegar', function ($app) {
       return new KavenegarExtension($app['config']['kavenegar']);
   });
   

3. Queue Failures: Handle failed jobs in FailedJob handler:

   // app/Listeners/HandleFailedSmsJob.php
   public function handle(FailedJob $event) {
       if ($event->job instanceof \App\Jobs\SendSmsJob) {
           Log::error("Failed to send SMS to {$event->job->receiver}");
           // Retry logic or notify admin
       }
   }