Getting Started

Minimal Setup

Install the Package:
```
composer require kavenegar/php
```
Ensure your composer.json includes "kavenegar/php": "^x.x" (replace with the latest version).
Retrieve API Key: Sign up at Kavenegar Panel and grab your API key from Settings.

First Use Case: Send an SMS in a Laravel controller or service:

use Kavenegar\KavenegarApi;

$api = new KavenegarApi(env('KAVENEGAR_API_KEY'));
$sender = env('KAVENEGAR_SENDER'); // e.g., "10004346"
$receptors = ['09123456789', '09367891011'];
$message = "Your verification code is: 123456";

try {
    $result = $api->Send($sender, $receptors, $message);
    // Handle response (see Implementation Patterns)
} catch (\Kavenegar\Exceptions\ApiException $e) {
    Log::error('Kavenegar API Error: ' . $e->errorMessage());
}

Store Config in .env:

KAVENEGAR_API_KEY=your_api_key_here
KAVENEGAR_SENDER=10004346

Implementation Patterns

Core Workflows

Sending SMS:

Single Recipient:

$result = $api->Send($sender, ['09123456789'], $message);

Bulk SMS:

$result = $api->Send($sender, ['09123456789', '09367891011'], $message);

Async Handling: Use Laravel's queue to defer SMS sending (e.g., for user notifications):
```
Queue::push(new SendSmsJob($api, $sender, $receptors, $message));
```

Response Handling:

Check status (200 = success) and iterate over entries:

if ($result && $result['status'] === 200) {
    foreach ($result['entries'] as $entry) {
        Log::info("Sent to {$entry->receptor}: {$entry->statustext}");
    }
}

Verification Codes:

Generate and send codes dynamically:

$code = Str::random(6);
$message = "Your code is: {$code}";
$api->Send($sender, [$user->phone], $message);

Error Handling:

API Errors (e.g., invalid API key):

catch (\Kavenegar\Exceptions\ApiException $e) {
    // Log and retry or notify admin
}

HTTP Errors (e.g., network issues):

catch (\Kavenegar\Exceptions\HttpException $e) {
    // Implement retry logic with exponential backoff
}

Integration Tips

Laravel Service Provider: Bind the API client to the container for dependency injection:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(KavenegarApi::class, function () {
        return new KavenegarApi(env('KAVENEGAR_API_KEY'));
    });
}

Usage in controllers:

public function __construct(private KavenegarApi $kavenegar) {}

Queue Jobs: Create a job for async SMS sending:

// app/Jobs/SendSmsJob.php
public function handle()
{
    $this->kavenegar->Send($this->sender, $this->receptors, $this->message);
}

Logging: Log all SMS attempts (success/failure) for auditing:

Log::channel('sms')->info('Sent to ' . $receptor, ['status' => $entry->status]);

Testing: Use Laravel's Mockery to stub the API in tests:

$mock = Mockery::mock(KavenegarApi::class);
$mock->shouldReceive('Send')->andReturn(['status' => 200, 'entries' => []]);
$this->app->instance(KavenegarApi::class, $mock);

Rate Limiting: Implement Laravel's throttle middleware for API calls:

Route::middleware(['throttle:10,1'])->group(function () {
    // Routes using Kavenegar
});

Gotchas and Tips

Pitfalls

API Key Exposure:

Never hardcode the API key. Use Laravel's .env and validate it:

if (empty(env('KAVENEGAR_API_KEY'))) {
    throw new \RuntimeException('Kavenegar API key not configured.');
}

Phone Number Validation:

Kavenegar expects 09xx format for Iranian numbers. Validate before sending:

$phone = preg_replace('/[^0-9]/', '', $phone);
if (!preg_match('/^09[0-9]{9}$/', $phone)) {
    throw new \InvalidArgumentException('Invalid phone number.');
}

Cost Tracking:

Monitor cost in responses to track SMS expenses. Log costs for billing:

$totalCost = collect($result['entries'])->sum('cost');
Log::info("Total SMS cost: {$totalCost} rials");

Status Codes:
- Common status values:
  - 1: "در صف ارسال" (Queued)
  - 2: "ارسال شد" (Sent)
  - 3: "ناموفق" (Failed)
- Handle failures gracefully (e.g., retry or notify user).

Character Limits:

Kavenegar enforces a 300-character limit per SMS. Split long messages:

$chunks = array_chunk(str_split($message, 300), 300);
foreach ($chunks as $chunk) {
    $api->Send($sender, $receptors, implode('', $chunk));
}

Debugging Tips

Enable Debugging:
- Check raw API responses by inspecting $result:
```
dd($result); // Debug full response structure
```
HTTP Errors:
- For HttpException, verify:
  - Internet connectivity.
  - Kavenegar's API status (status.kavenegar.com).
  - No firewall/proxy blocking requests.
API Quotas:
- Monitor your Kavenegar Panel for quota limits. Upgrade if needed.

Timeouts:

Increase Laravel's HTTP timeout if responses are slow:

$client = new \GuzzleHttp\Client(['timeout' => 30]);
// Inject custom client if the package allows (check source).

Extension Points

Custom Response Handling:

Extend the package by creating a decorator:

class EnhancedKavenegarApi extends KavenegarApi {
    public function Send(...$args) {
        $result = parent::Send(...$args);
        // Add custom logic (e.g., translate status codes)
        return $this->processResponse($result);
    }
}

Webhook Integration:

Use Kavenegar's webhook to receive delivery reports:

Route::post('/kavenegar-webhook', function (Request $request) {
    Log::info('Webhook received:', $request->all());
});

Fallback Mechanism:

Implement a fallback to another SMS provider if Kavenegar fails:

try {
    $api->Send($sender, $receptors, $message);
} catch (\Exception $e) {
    $fallbackApi->Send($sender, $receptors, $message);
}

Local Testing:

Mock the API for local development:

$mock = Mockery::mock(KavenegarApi::class);
$mock->shouldReceive('Send')->andReturn(['status' => 200, 'entries' => []]);
$this->app->instance(KavenegarApi::class, $mock);

**Configuration

Kavenegar Php Laravel Package