Custom SMS & OTP Drivers
- Introduction
- SMS Manager & Driver Architecture
- Built-in SMS Providers
- Implementing a Custom SMS Driver
- Pattern-Based Fast OTP Dispatching
- Anti-Brute-Force & Rate Limiting
- Testing SMS Drivers
Introduction
Reliable SMS delivery is the primary lifeline for customer authentication (One-Time Password / OTP), order status updates, and shipping notifications in Iranian e-commerce.
Reyhan Commerce features an enterprise multi-driver SMS notification engine accessible via the Sms facade. The engine abstracts away third-party vendor differences and guarantees instant OTP dispatching using Pattern-Based Fast SMS APIs (ارسال بر اساس پترن / وبسرویس خدماتی).
SMS Manager & Driver Architecture
All outgoing SMS messages and verification tokens are dispatched via the Sms facade. Under the hood, SmsManager resolves the configured driver and normalizes Iranian phone numbers (converting Persian/Arabic digits, formatting with +98, and removing leading zeros) automatically.
use Reyhan\Core\Facades\Sms;
// Pattern-based OTP dispatch
Sms::driver('kavenegar')->sendOtp(
mobile: '09123456789',
token: '748291',
template: 'verify-login'
);Built-in SMS Providers
Reyhan includes pre-tested drivers for leading SMS gateways:
| Provider Key | Gateway | Supported Features |
|---|---|---|
'kavenegar' | Kavenegar (کاوهنگار) | Fast Lookup Pattern OTP, Standard Bulk SMS, Delivery Reports |
'farazsms' | FarazSMS / IPPanel (فراز اساماس) | Shared Pattern Dispatch, Edge Node Acceleration |
'ghasedak' | Ghasedak (قاصدک) | OTP Template Service, Line Selection |
'log' | Local Log Driver | Outputs SMS content directly to storage/logs/laravel.log (Ideal for local testing) |
Implementing a Custom SMS Driver
Let's implement a custom driver for MeliPayamak (ملیپیامک).
Step 1: Implementing SmsGatewayContract
Create app/Services/Sms/MeliPayamakDriver.php:
<?php
declare(strict_types=1);
namespace App\Services\Sms;
use Illuminate\Http\Client\Factory as HttpFactory;
use Reyhan\Core\Contracts\Sms\SmsGatewayContract;
use Reyhan\Core\DTOs\SmsDispatchResult;
use Reyhan\Core\Exceptions\SmsDeliveryException;
final class MeliPayamakDriver implements SmsGatewayContract
{
public function __construct(
private readonly HttpFactory $http,
private readonly string $username,
private readonly string $password,
) {}
/**
* Send instant OTP using shared service patterns (وبسرویس خدماتی اشتراکی).
*/
public function sendOtp(string $mobile, string $token, string $template): SmsDispatchResult
{
$response = $this->http->post('https://rest.payamak-panel.com/api/SendSMS/BaseServiceNumber', [
'username' => $this->username,
'password' => $this->password,
'text' => [$token],
'to' => $mobile,
'bodyId' => (int) $template,
]);
if (! $response->successful() || (int) $response->json('RetStatus') !== 1) {
throw new SmsDeliveryException(
'Failed to send OTP via MeliPayamak: '.$response->body()
);
}
return new SmsDispatchResult(
successful: true,
messageId: (string) $response->json('Value'),
provider: 'melipayamak'
);
}
/**
* Send standard transactional or promotional text message.
*/
public function sendText(string $mobile, string $message): SmsDispatchResult
{
$response = $this->http->post('https://rest.payamak-panel.com/api/SendSMS/SendSMS', [
'username' => $this->username,
'password' => $this->password,
'to' => $mobile,
'from' => '50004...',
'text' => $message,
'isflash' => false,
]);
if (! $response->successful() || (int) $response->json('RetStatus') !== 1) {
throw new SmsDeliveryException('Failed to dispatch SMS: '.$response->body());
}
return new SmsDispatchResult(
successful: true,
messageId: (string) $response->json('Value'),
provider: 'melipayamak'
);
}
}Step 2: Registering the Driver
Register the custom driver in app/Providers/AppServiceProvider.php:
<?php
declare(strict_types=1);
namespace App\Providers;
use App\Services\Sms\MeliPayamakDriver;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;
use Reyhan\Core\Facades\Sms;
class AppServiceProvider extends ServiceProvider
{
public function boot(): void
{
Sms::extend('melipayamak', function (Application $app) {
return new MeliPayamakDriver(
http: $app->make('http'),
username: (string) config('sms.drivers.melipayamak.username'),
password: (string) config('sms.drivers.melipayamak.password')
);
});
}
}Step 3: Configuring Credentials
Update config/sms.php:
// config/sms.php
return [
'default' => env('SMS_DEFAULT_DRIVER', 'kavenegar'),
'drivers' => [
'melipayamak' => [
'username' => env('MELIPAYAMAK_USERNAME'),
'password' => env('MELIPAYAMAK_PASSWORD'),
],
// Other drivers...
],
'templates' => [
'otp' => env('SMS_OTP_TEMPLATE', '12345'),
'order_confirmed' => env('SMS_ORDER_CONFIRMED_TEMPLATE', '67890'),
],
];Pattern-Based Fast OTP Dispatching
IMPORTANT
Regular promotional lines in Iran block recipients with active blacklists (DND / لیست سیاه). For OTP authentication, always configure a pattern template that routes through verified telecommunication service lines (خطوط خدماتی).
Anti-Brute-Force & Rate Limiting
Reyhan's built-in VerifyOtpAction and SendOtpAction enforce strict security throttling out of the box:
- 120-Second Resend Window: Customers can only request a new code every 2 minutes.
- Maximum 5 Verification Attempts: Exceeding 5 incorrect attempts permanently burns the OTP token and triggers a 15-minute cooldown.
Testing SMS Drivers
In local testing or CI pipelines, use the log driver or fake HTTP requests:
<?php
declare(strict_types=1);
use Illuminate\Support\Facades\Http;
use Reyhan\Core\Facades\Sms;
it('dispatches otp code through melipayamak driver', function () {
Http::fake([
'https://rest.payamak-panel.com/api/SendSMS/BaseServiceNumber' => Http::response([
'RetStatus' => 1,
'Value' => '987654321',
], 200),
]);
$result = Sms::driver('melipayamak')->sendOtp(
mobile: '09121112233',
token: '123456',
template: '9988'
);
expect($result->successful)->toBeTrue()
->and($result->messageId)->toBe('987654321');
});