PHPackages                             fardadev/kavenegar-for-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. fardadev/kavenegar-for-laravel

ActiveLibrary[Mail & Notifications](/categories/mail)

fardadev/kavenegar-for-laravel
==============================

Modern Laravel 11+ package for Kavenegar SMS API integration with full type safety and comprehensive testing

v1.0.0-beta.1(5mo ago)316[1 issues](https://github.com/FardaDev/kavenegar-for-laravel/issues)[1 PRs](https://github.com/FardaDev/kavenegar-for-laravel/pulls)MITPHPPHP ^8.3CI passing

Since Nov 17Pushed 1mo agoCompare

[ Source](https://github.com/FardaDev/kavenegar-for-laravel)[ Packagist](https://packagist.org/packages/fardadev/kavenegar-for-laravel)[ Docs](https://github.com/FardaDev/kavenegar-for-laravel)[ GitHub Sponsors](https://github.com/FardaDev)[ RSS](/packages/fardadev-kavenegar-for-laravel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (13)Versions (5)Used By (0)

Kavenegar Laravel Package
=========================

[](#kavenegar-laravel-package)

[![Latest Version on Packagist](https://camo.githubusercontent.com/fb4a51300c96c71a944020080486a1a771057016573e2e1c5f6f720c793828bc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f66617264616465762f6b6176656e656761722d666f722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/fardadev/kavenegar-for-laravel)[![Total Downloads](https://camo.githubusercontent.com/3a7662f4a2376cc227504d01a68f097b841fdc35f5d02351dd24159fefad1159/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f66617264616465762f6b6176656e656761722d666f722d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/fardadev/kavenegar-for-laravel)

Modern Laravel 11+ package for [Kavenegar](https://kavenegar.com) SMS API integration with full type safety, comprehensive testing, and Laravel best practices.

Features
--------

[](#features)

- ✅ **Laravel 11+ Compatible** - Built for modern Laravel with PHP 8.3+
- ✅ **Full Type Safety** - Strongly typed with readonly DTOs and return types
- ✅ **Auto-Discovery** - Automatic service provider and facade registration
- ✅ **Comprehensive API Coverage** - All Kavenegar endpoints supported
- ✅ **Exception Handling** - Typed exceptions for different error scenarios
- ✅ **Helper Methods** - Convenient helpers for common use cases
- ✅ **Environment Aware** - Skip SMS in development/testing environments
- ✅ **Fully Tested** - Comprehensive test coverage with Pest
- ✅ **Well Documented** - Complete API documentation and examples

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Laravel 11.0 or 12.0
- Kavenegar API Key ([Get one here](https://panel.kavenegar.com/client/setting/account))

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require fardadev/kavenegar-for-laravel
```

The package will automatically register itself thanks to Laravel's auto-discovery feature.

### Publish Configuration

[](#publish-configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=kavenegar-config
```

This will create a `config/kavenegar.php` file in your application.

### Environment Variables

[](#environment-variables)

Add your Kavenegar credentials to your `.env` file:

```
KAVENEGAR_API_KEY=your-api-key-here
KAVENEGAR_SENDER=your-sender-number
KAVENEGAR_TIMEOUT=30
KAVENEGAR_SKIP_IN_DEV=true

# Optional: Template names for verification codes
KAVENEGAR_TEMPLATE_LOGIN=login-verify
KAVENEGAR_TEMPLATE_EMAIL_PASS=email-pass
KAVENEGAR_TEMPLATE_2FA=email-2fa
```

Configuration
-------------

[](#configuration)

The `config/kavenegar.php` file contains all package configuration options:

```
return [
    // Your Kavenegar API key (required)
    'api_key' => env('KAVENEGAR_API_KEY', ''),

    // Default sender line number (optional)
    'sender' => env('KAVENEGAR_SENDER', null),

    // HTTP request timeout in seconds
    'timeout' => env('KAVENEGAR_TIMEOUT', 30),

    // Skip SMS sending in local/dev environments
    'skip_in_development' => env('KAVENEGAR_SKIP_IN_DEV', true),

    // Test phone numbers (SMS skipped in testing environment)
    'test_phone_numbers' => [
        '09112223344',
    ],

    // Verification templates (must be created in Kavenegar panel)
    'templates' => [
        'login' => env('KAVENEGAR_TEMPLATE_LOGIN', 'login-verify'),
        'email_password' => env('KAVENEGAR_TEMPLATE_EMAIL_PASS', 'email-pass'),
        'two_factor' => env('KAVENEGAR_TEMPLATE_2FA', 'email-2fa'),
    ],
];
```

### Configuration Options

[](#configuration-options)

OptionTypeDefaultDescription`api_key`string-Your Kavenegar API key (required)`sender`string|nullnullDefault sender line number`timeout`int30HTTP request timeout in seconds`skip_in_development`booltrueSkip SMS in local/dev environments`test_phone_numbers`array\[\]Phone numbers treated as test numbers`templates`array\[\]Template names for verification codesUsage
-----

[](#usage)

### Basic SMS Sending

[](#basic-sms-sending)

#### Using Facade

[](#using-facade)

```
use FardaDev\Kavenegar\Facades\Kavenegar;

// Send to single recipient
$result = Kavenegar::send(
    receptor: '09123456789',
    message: 'Hello from Kavenegar!'
);

// Send to multiple recipients
$result = Kavenegar::send(
    receptor: ['09123456789', '09987654321'],
    message: 'Hello everyone!'
);

// Send with all options
$result = Kavenegar::send(
    receptor: '09123456789',
    message: 'Scheduled message',
    sender: '10004346',
    date: time() + 3600, // Send in 1 hour
    type: 1, // Save to phone memory
    localid: [123], // For duplicate prevention
    hide: 1, // Hide receptor in logs
    tag: 'marketing',
    policy: 'custom-flow'
);

// Check result
foreach ($result as $response) {
    echo "Message ID: {$response->messageid}\n";
    echo "Status: {$response->statustext}\n";
    echo "Cost: {$response->cost} Rials\n";

    if ($response->isDelivered()) {
        echo "Message delivered!\n";
    } elseif ($response->isPending()) {
        echo "Message is pending...\n";
    }
}
```

#### Using Dependency Injection

[](#using-dependency-injection)

```
use FardaDev\Kavenegar\Client\KavenegarClient;

class NotificationService
{
    public function __construct(private KavenegarClient $kavenegar) {}

    public function sendWelcomeSMS(string $phone): void
    {
        $this->kavenegar->send(
            receptor: $phone,
            message: 'Welcome to our service!'
        );
    }
}
```

### Bulk SMS Sending

[](#bulk-sms-sending)

Send different messages to different recipients from different senders:

```
$result = Kavenegar::sendArray(
    senders: ['10004346', '10004347', '10004348'],
    receptors: ['09123456789', '09987654321', '09111111111'],
    messages: ['Message 1', 'Message 2', 'Message 3']
);
```

### Verification Codes

[](#verification-codes)

#### Using verifyLookup

[](#using-verifylookup)

```
// Simple verification code
$result = Kavenegar::verifyLookup(
    receptor: '09123456789',
    template: 'login-verify',
    token: '123456'
);

// With multiple tokens
$result = Kavenegar::verifyLookup(
    receptor: '09123456789',
    template: 'email-pass',
    token: '123456',
    token2: 'user@example.com'
);

// With all token parameters
$result = Kavenegar::verifyLookup(
    receptor: '09123456789',
    template: 'custom-template',
    token: 'value1',
    token2: 'value2',
    token3: 'value3',
    token10: 'value10',
    token20: 'value20'
);
```

#### Using Helper Methods

[](#using-helper-methods)

The package includes a `KavenegarHelper` class with convenient methods for common verification scenarios. This helper automatically handles development environment skipping and token normalization.

```
use FardaDev\Kavenegar\Helpers\KavenegarHelper;

$helper = app(KavenegarHelper::class);

// Send login code
$result = $helper->sendLoginCode('09123456789', '123456');

// Send email + password code
$result = $helper->sendEmailPasswordCode(
    '09123456789',
    '123456',
    'user@example.com'
);

// Send 2FA code
$result = $helper->sendTwoFactorCode(
    '09123456789',
    '654321',
    'user@example.com'
);
```

**Note:** The `KavenegarHelper` is a convenience implementation for common use cases. You can create your own custom helper class by injecting `KavenegarClient` and implementing logic specific to your application's needs.

### Checking Message Status

[](#checking-message-status)

```
// Check by message ID
$status = Kavenegar::status('8792343');

// Check multiple messages
$status = Kavenegar::status(['8792343', '8792344']);

// Check by local ID
$status = Kavenegar::statusLocalMessageId('123');

// Check by receptor and date range
$status = Kavenegar::statusByReceptor(
    receptor: '09123456789',
    startdate: strtotime('-1 day'),
    enddate: time()
);

foreach ($status as $s) {
    echo "Message {$s->messageid}: {$s->statustext}\n";

    if ($s->isDelivered()) {
        echo "Delivered successfully!\n";
    }
}
```

### Message History and Selection

[](#message-history-and-selection)

```
// Get full message details
$messages = Kavenegar::select('8792343');

// Get messages in date range
$messages = Kavenegar::selectOutbox(
    startdate: strtotime('-1 day'),
    enddate: time(),
    sender: '10004346' // Optional filter
);

// Get latest messages
$messages = Kavenegar::latestOutbox(
    pagesize: 100,
    sender: '10004346' // Optional filter
);

// Count messages
$count = Kavenegar::countOutbox(
    startdate: strtotime('-1 day'),
    enddate: time(),
    status: 10 // Optional: only delivered messages
);
```

### Cancelling Messages

[](#cancelling-messages)

```
// Cancel scheduled message
$result = Kavenegar::cancel('8792343');

// Cancel multiple messages
$result = Kavenegar::cancel(['8792343', '8792344']);
```

### Voice Calls (TTS)

[](#voice-calls-tts)

```
// Send text-to-speech call
$result = Kavenegar::makeTTS(
    receptor: '09123456789',
    message: 'Your verification code is 1 2 3 4 5 6'
);

// Scheduled TTS call
$result = Kavenegar::makeTTS(
    receptor: '09123456789',
    message: 'Reminder message',
    date: time() + 3600 // Call in 1 hour
);
```

### Account Information

[](#account-information)

```
// Get account info
$info = Kavenegar::info();

echo "Credit: {$info->remaincredit} Rials\n";
echo "Expiry: " . $info->getExpiryDate()->format('Y-m-d') . "\n";

if ($info->hasCredit()) {
    echo "Account has credit\n";
}

if ($info->isExpired()) {
    echo "Account is expired!\n";
}

// Get account configuration
$config = Kavenegar::config();

if ($config->hasApiLogsEnabled()) {
    echo "API logs are enabled\n";
}
```

Advanced Features
-----------------

[](#advanced-features)

### Creating Custom Helpers

[](#creating-custom-helpers)

While the package includes `KavenegarHelper` for common scenarios, you can create your own custom helper tailored to your application's specific needs:

```