Kavenegar Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require h-o-sein/kavenegar-laravel
   

   Ensure your composer.json includes the dependency (though the package appears to be a wrapper for kavenegar/php, not a standalone package).

2. Publish Config Publish the package config to customize API settings:

   php artisan vendor:publish --provider="Hosein\Kavenegar\KavenegarServiceProvider"
   

   Edit .env or config/kavenegar.php with your API key and default sender:

   KAVENEGAR_API_KEY=your_api_key_here
   KAVENEGAR_SENDER=10004346
   

3. First Use Case: Send an SMS Use the facade in a controller or service:

   use Hosein\Kavenegar\Facades\Kavenegar;
   
   $result = Kavenegar::send('09123456789', 'Your verification code is 12345');
   

   Or with multiple recipients:

   $result = Kavenegar::send(['09123456789', '09367891011'], 'Hello!');
   

Implementation Patterns

Core Workflows

1. Sending SMS

   • Single Recipient:

     Kavenegar::send('09123456789', 'Hello!');
     

   • Multiple Recipients:

     Kavenegar::send(['09123456789', '09367891011'], 'Broadcast message');
     

   • Custom Sender:

     Kavenegar::send('09123456789', 'Hello!', ['sender' => '10001234']);
     

2. Verification Codes Integrate with Laravel's Illuminate\Auth\Events\Registered or custom events:

   use Hosein\Kavenegar\Facades\Kavenegar;
   
   event(new Registered($user));
   Kavenegar::send($user->phone, "Your code: {$user->verification_code}");
   

3. Async Processing Use Laravel Queues to avoid blocking requests:

   use Hosein\Kavenegar\Facades\Kavenegar;
   use Illuminate\Support\Facades\Queue;
   
   Queue::push(function () {
       Kavenegar::send('09123456789', 'Delayed message');
   });
   

4. Response Handling Parse responses in middleware or services:

   $result = Kavenegar::send('09123456789', 'Test');
   if ($result->status === 'success') {
       // Success logic
   } else {
       Log::error('Kavenegar error: ' . $result->statustext);
   }
   

Integration Tips

• Validation: Sanitize phone numbers before sending (e.g., remove + or 00 prefixes).
• Rate Limiting: Implement Laravel's throttle middleware for API calls.
• Logging: Log responses for debugging:

  Log::debug('Kavenegar response', ['data' => $result]);
  

• Testing: Mock the facade in PHPUnit:

  $this->mock(Hosein\Kavenegar\Facades\Kavenegar::class)->shouldReceive('send')->once();
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode the API key in source files. Use Laravel's .env and validate it exists in AppServiceProvider:

     if (!config('kavenegar.api_key')) {
         throw new \RuntimeException('Kavenegar API key not configured.');
     }
     

2. Phone Number Formatting

   • Kavenegar expects 0912... format (no + or 00). Strip prefixes:

     $phone = Str::replace(['+', '00'], '', $user->phone);
     

3. Rate Limits

   • Kavenegar enforces rate limits. Handle 429 Too Many Requests:

     try {
         $result = Kavenegar::send(...);
     } catch (\Kavenegar\Exceptions\ApiException $e) {
         if ($e->getCode() === 429) {
             sleep(5); // Retry after delay
             retry();
         }
     }
     

4. Deprecated Methods

   • The package is outdated (last release: 2020). Check for breaking changes in the underlying kavenegar/php library.

5. No Queue Support

   • The package lacks built-in queueing. Use Laravel Queues manually (as shown above).

Debugging

• Enable Debug Mode: Set debug: true in config/kavenegar.php to log raw API responses.
• Check HTTP Status: Wrap calls in try-catch to catch ApiException for non-200 responses.
• Test with Sandbox: Use Kavenegar's sandbox API for testing:

  config(['kavenegar.api_key' => env('KAVENEGAR_SANDBOX_KEY')]);
  

Extension Points

1. Custom Responses Extend the facade to add methods:

   // app/Providers/AppServiceProvider.php
   Kavenegar::macro('verify', function ($phone, $code) {
       return $this->send($phone, "Code: {$code}");
   });
   

   Usage:

   Kavenegar::verify('09123456789', '12345');
   

2. Event Dispatching Trigger events after sending:

   // app/Providers/KavenegarServiceProvider.php
   Kavenegar::extend(function ($api) {
       $api->afterSend(function ($result) {
           event(new SmsSent($result));
       });
   });
   

3. Override API Client Replace the underlying KavenegarApi instance for custom logic:

   $api = new \Kavenegar\KavenegarApi(config('kavenegar.api_key'));
   $api->setCustomOption('timeout', 10); // Example
   Kavenegar::setApi($api);