Kavenegar Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beaumind/kavenegar-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Beaumind\KavenegarLaravel\KavenegarServiceProvider"
   

2. Configuration Edit .env with your Kavenegar API credentials:

   KAVENEGAR_API_KEY=your_api_key_here
   KAVENEGAR_API_URL=https://api.kavenegar.com/v1
   

3. First Use Case Send an SMS via a controller or command:

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

Where to Look First

• Facade: Beaumind\KavenegarLaravel\Facades\Kavenegar
• Config: config/kavenegar.php
• Service Provider: Beaumind\KavenegarLaravel\KavenegarServiceProvider

Implementation Patterns

Core Workflows

1. Basic SMS Sending

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

2. Sending with Custom Parameters

   Kavenegar::send([
       'receiver' => '1234567890',
       'message'  => 'Your verification code is {code}',
       'params'   => ['code' => '123456']
   ]);
   

3. Batch Sending

   $receivers = ['1234567890', '0987654321'];
   $message = 'Hello to all!';
   
   Kavenegar::sendBatch($receivers, $message);
   

4. Verification Codes

   $code = Kavenegar::generateCode(6); // Generates a 6-digit code
   Kavenegar::sendVerification('1234567890', $code);
   

Integration Tips

• Queue Jobs for Async Sending

  use Beaumind\KavenegarLaravel\Jobs\SendSmsJob;
  
  SendSmsJob::dispatch('1234567890', 'Hello!');
  

• Logging Responses Extend the service to log responses:

  Kavenegar::send($receiver, $message, ['log' => true]);
  

• Custom Exceptions Handle exceptions globally in App\Exceptions\Handler:

  catch (\Beaumind\KavenegarLaravel\Exceptions\KavenegarException $e) {
      Log::error($e->getMessage());
      return response()->json(['error' => 'SMS failed'], 500);
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits Kavenegar enforces rate limits. Monitor responses for 429 Too Many Requests and implement retries with exponential backoff.

2. Receiver Validation Ensure phone numbers are validated (e.g., using Str::startsWith($number, '09') for Iranian numbers).

3. Sandbox vs. Production Test in sandbox mode first (KAVENEGAR_SANDBOX=true in .env). Sandbox numbers are predefined.

4. Character Limits SMS messages are limited to 300 characters (including spaces). Longer messages require segmentation.

Debugging

• Enable Debug Mode

  KAVENEGAR_DEBUG=true
  

  Logs requests/responses to storage/logs/kavenegar.log.

• Check HTTP Status Codes Kavenegar returns:

  • 200: Success
  • 400: Bad request (e.g., invalid API key)
  • 403: Forbidden (e.g., insufficient balance)
  • 500: Server error

Extension Points

1. Customize HTTP Client Bind a custom Guzzle client in AppServiceProvider:

   $this->app->bind(\Beaumind\KavenegarLaravel\Contracts\KavenegarClient::class, function () {
       return new \Beaumind\KavenegarLaravel\Services\CustomKavenegarClient();
   });
   

2. Add Middleware Extend the Kavenegar facade to add middleware (e.g., logging, rate limiting):

   Kavenegar::extend(function ($app) {
       $client = $app->make(\Beaumind\KavenegarLaravel\Contracts\KavenegarClient::class);
       $client->addMiddleware(new \Your\Middleware\LogSmsMiddleware());
   });
   

3. Override Default Config Publish and modify config/kavenegar.php for custom timeouts, retries, or endpoints.

Pro Tips

• Use Events for Tracking Listen to sms.sent and sms.failed events:

  event(new \Beaumind\KavenegarLaravel\Events\SmsSent($smsData));
  

• Template-Based Messages Store reusable templates in the database and fetch them dynamically:

  $template = Template::find(1);
  Kavenegar::send($receiver, $template->message, $template->params);
  

• Fallback for Failures Implement a fallback mechanism (e.g., email) if SMS fails:

  try {
      Kavenegar::send($receiver, $message);
  } catch (\Exception $e) {
      Mail::to($receiver)->send(new SmsFallbackMail($message));
  }