PHPackages                             mahdi-hejazi/laravel-ghasedak-sms - 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. mahdi-hejazi/laravel-ghasedak-sms

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

mahdi-hejazi/laravel-ghasedak-sms
=================================

Modern Laravel package for Ghasedak SMS API with template and simple SMS support

1.0.0(9mo ago)13MITPHPPHP ^8.1|^8.2|^8.3

Since Jul 28Pushed 9mo agoCompare

[ Source](https://github.com/mahdi-hejazi/laravel-ghasedak-sms)[ Packagist](https://packagist.org/packages/mahdi-hejazi/laravel-ghasedak-sms)[ RSS](/packages/mahdi-hejazi-laravel-ghasedak-sms/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (2)Versions (3)Used By (0)

Laravel Ghasedak SMS
====================

[](#laravel-ghasedak-sms)

Modern Laravel package for Ghasedak SMS API with template and simple SMS support.

packagist url:

Features
--------

[](#features)

- ✅ **Template-based SMS** (OTP, verification codes, etc.)
- ✅ **Simple SMS** (free text messages)
- ✅ **Queue support** with Laravel notifications
- ✅ **Persian error messages**
- ✅ **Configurable templates**
- ✅ **Logging support**

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

[](#installation)

### Requirements

[](#requirements)

- PHP 8.1, 8.2, or 8.3
- Laravel 9, 10, 11, or 12
- Composer

### Install via Composer

[](#install-via-composer)

```
composer require mahdi-hejazi/laravel-ghasedak-sms
```

### Publish Configuration

[](#publish-configuration)

```
php artisan vendor:publish --provider="MahdiHejazi\LaravelGhasedakSms\GhasedakSmsServiceProvider" --tag="ghasedak-config"
```

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

[](#configuration)

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

```
GHASEDAK_API_KEY=your_api_key_here
GHASEDAK_SENDER=10008566
GHASEDAK_TEMPLATE_VERIFY_CODE=your_template_name
```

Usage
-----

[](#usage)

OTP SMS Usage Examples
======================

[](#otp-sms-usage-examples)

New OTP API Features
--------------------

[](#new-otp-api-features)

The new OTP API endpoint supports:

- ✅ **Named parameters** (instead of positional param1, param2, etc.)
- ✅ **Multiple recipients** in single request
- ✅ **Client reference IDs** for tracking
- ✅ **Scheduled sending**
- ✅ **Voice messages**
- ✅ **Better response format** with cost information

Basic Usage
-----------

[](#basic-usage)

### 0. Add template to Laravel Config

[](#0-add-template-to-laravel-config)

```
// config/ghasedak.php
'templates' => [
    'phoneVerifyCode' => 'phoneVerifyCode',
    'loginCode' => 'loginCode',
    'appointmentReminder' => 'appointmentReminder',
    'orderConfirmed' => 'orderConfirmed',
],
```

### 1. Single OTP with Named Parameters

[](#1-single-otp-with-named-parameters)

```
use MahdiHejazi\LaravelGhasedakSms\Facades\GhasedakSms;

// Send verification code using new OTP API
$response = GhasedakSms::sendOtp('09123456789', 'phoneVerifyCode', [
    'Code' => '1234'
]);

// Send login code with user name
$response = GhasedakSms::sendOtp('09123456789', 'loginCode', [
    'Code' => '5678',
    'Name' => 'احمد رضایی'
]);
```

### 2. Using Notification Classes

[](#2-using-notification-classes)

```
use MahdiHejazi\LaravelGhasedakSms\Notifications\OtpSmsNotification;

// Single verification code
$user->notify(OtpSmsNotification::verificationCode('09123456789', '1234'));

// Appointment reminder
$user->notify(OtpSmsNotification::appointmentReminder(
    '09123456789',
    'دکتر احمدی',
    '1403/10/15',
    '14:30'
));

// Order confirmation
$user->notify(OtpSmsNotification::orderConfirmation(
    '09123456789',
    'ORD-12345',
    '250000 تومان'
));

// Welcome message
$user->notify(OtpSmsNotification::welcome('09123456789', 'علی احمدی'));

// Password reset
$user->notify(OtpSmsNotification::passwordReset('09123456789', 'RESET123'));
```

### 3. Advanced Features

[](#3-advanced-features)

#### Scheduled OTP

[](#scheduled-otp)

```
// Send OTP at specific time (ISO 8601 format)
$sendDate = '2024-12-25T14:30:00Z';
$response = GhasedakSms::sendScheduledOtp(
    '09123456789',
    'phoneVerifyCode',
    ['Code' => '1234'],
    $sendDate
);

// Using notification
$user->notify(OtpSmsNotification::scheduledVerificationCode(
    '09123456789',
    '1234',
    '2024-12-25T14:30:00Z'
));
```

#### Voice OTP

[](#voice-otp)

```
// Send voice verification code
$response = GhasedakSms::sendVoiceOtp('09123456789', 'phoneVerifyCode', [
    'Code' => '1234'
]);

// Using notification
$user->notify(OtpSmsNotification::voiceVerificationCode('09123456789', '1234'));
```

#### Custom Client Reference ID

[](#custom-client-reference-id)

```
// Track your OTP with custom reference ID
$clientRefId = 'USER_123_VERIFY_' . time();
$response = GhasedakSms::sendOtpVerificationCode('09123456789', '1234', $clientRefId);

// Later, you can use this reference ID to check status
```

Template Configuration (old version of OTP)
-------------------------------------------

[](#template-configuration-old-version-of-otp)

### 1. Create Templates in Ghasedak Panel

[](#1-create-templates-in-ghasedak-panel)

Create templates at [ghasedak.me](https://ghasedak.me) with named parameters:

**Example Templates:**

```
Template Name: phoneVerifyCode
Template Text: کد تایید شما: {{Code}}

Template Name: loginCode
Template Text: سلام {{Name}}، کد ورود شما: {{Code}}

Template Name: appointmentReminder
Template Text: یادآوری قرار ملاقات با {{Doctor}} در تاریخ {{Date}} ساعت {{Time}}

Template Name: orderConfirmed
Template Text: سفارش {{OrderNumber}} به مبلغ {{Amount}} تایید شد

```

### 2. Add to Laravel Config

[](#2-add-to-laravel-config)

```
// config/ghasedak.php
'templates' => [
    'phoneVerifyCode' => 'phoneVerifyCode',
    'loginCode' => 'loginCode',
    'appointmentReminder' => 'appointmentReminder',
    'orderConfirmed' => 'orderConfirmed',
],
```

Response Format
---------------

[](#response-format)

The new OTP API returns detailed response:

```
$response = [
    'isSuccess' => true,
    'statusCode' => 200,
    'message' => 'با موفقیت انجام شد',
    'data' => [
        'items' => [
            [
                'messageBody' => 'کد تایید شما: 1234',
                'receptor' => '09123456789',
                'cost' => 850,
                'messageId' => '23304980',
                'clientReferenceId' => 'USER_123_VERIFY_1703497185',
                'sendDate' => '2024-12-25T09:59:45.599126+03:30'
            ]
        ],
        'totalCost' => 850
    ]
];
```

Error Handling
--------------

[](#error-handling)

```
use MahdiHejazi\LaravelGhasedakSms\Exceptions\GhasedakSmsException;

try {
    $response = GhasedakSms::sendOtpVerificationCode('09123456789', '1234');

    // Check response
    if ($response['isSuccess']) {
        $messageId = $response['data']['items'][0]['messageId'];
        $cost = $response['data']['totalCost'];
        echo "SMS sent successfully! ID: {$messageId}, Cost: {$cost}";
    }

} catch (GhasedakSmsException $e) {
    echo "Error: " . $e->getMessage();
    echo "Code: " . $e->getErrorCode();
}
```

Migration from Old API
----------------------

[](#migration-from-old-api)

### Before (Old Template API):

[](#before-old-template-api)

```
// Old way with positional parameters
GhasedakSms::sendTemplate('09123456789', 'phoneVerifyCode', ['1234']);
```

### After (New OTP API):

[](#after-new-otp-api)

```
// New way with named parameters
GhasedakSms::sendOtp('09123456789', 'phoneVerifyCode', ['Code' => '1234']);

// Or using the convenience method
GhasedakSms::sendOtpVerificationCode('09123456789', '1234');
```

Best Practices
--------------

[](#best-practices)

1. **Use meaningful client reference IDs** for tracking
2. **Test templates** in Ghasedak panel before using in code
3. **Handle errors gracefully** with try-catch blocks
4. **Monitor costs** using the totalCost field in responses
5. **Use bulk methods** for multiple recipients to reduce API calls
6. **Clean parameter values** - avoid special characters
7. **Use scheduled sending** for time-sensitive messages

### Available Factory Methods

[](#available-factory-methods)

```
// Built-in template SMS factory methods
SendSmsNotification::verificationCode($code, $phone);
SendSmsNotification::orderConfirmed($phone, $orderId, $amount, $date);
SendSmsNotification::thankYou($phone, $customerName);
SendSmsNotification::passwordReset($phone, $resetCode);
SendSmsNotification::welcome($phone, $userName);

// Simple SMS factory methods
SimpleSmsNotification::create($phone, $message, $sender);
SimpleSmsNotification::scheduled($phone, $message, $sendDate, $sender);
```

### Adding Custom Factory Methods

[](#adding-custom-factory-methods)

You can extend the notification classes to add your own factory methods:

#### Method 1: Extend the Notification Class

[](#method-1-extend-the-notification-class)

```