وب سرویس پیامک لاراول و PHP | ارسال OTP و پیامک انبوه در Laravel

لاراول محبوب‌ترین فریم‌ورک PHP در میان توسعه‌دهندگان وب است. ارسال پیامک‌های اعتبارسنجی ورود دو مرحله‌ای (OTP)، تایید ثبت سفارش، نوتیفیکیشن‌های سیستم و پیامک‌های تراکنشی هسته اصلی هر اپلیکیشن لاراولی مدرن به شمار می‌روند.

در این راهنما، نحوه پیاده‌سازی سرویس پیامک فری اس ام اس در لاراول ۱۰ و ۱۱ را به صورت ماژولار با معماری تمیز (Clean Architecture)، کانال نوتیفیکیشن اختصاصی (`Custom Notification Channel`) و صف‌های پس‌زمینه (`Queues`) آموزش می‌دهیم.

۱. تنظیمات محیطی (.env) و کانفیگ لاراول

ابتدا کلید وب‌سرویس و پیش‌شماره ارسالی را در فایل .env پروژه خود قرار دهید:

FREE_SMS_API_KEY=your_secret_api_key_here
FREE_SMS_BASE_URL=https://api.free-sms.ir
FREE_SMS_SENDER=50004000

سپس در فایل config/services.php تنظیمات سرویس را اضافه کنید:

<?php
return [
    // سایر کانفیگ‌ها...
    'freesms' => [
        'api_key'  => env('FREE_SMS_API_KEY'),
        'base_url' => env('FREE_SMS_BASE_URL', 'https://api.free-sms.ir'),
        'sender'   => env('FREE_SMS_SENDER'),
    ],
];

۲. ایجاد کلاس سرویس ارسال پیامک (FreeSmsService)

یک کلاس سرویس در مسیر app/Services/FreeSmsService.php ایجاد کنید. ما از کلاینت استاندارد Illuminate\Support\Facades\Http با مکانیزم Retry خودکار استفاده می‌کنیم:

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Exception;

class FreeSmsService
{
    protected string $apiKey;
    protected string $baseUrl;
    protected ?string $sender;

    public function __construct()
    {
        $this->apiKey  = config('services.freesms.api_key');
        $this->baseUrl = config('services.freesms.base_url');
        $this->sender  = config('services.freesms.sender');
    }

    /**
     * ارسال سریع کد اعتبارسنجی OTP با پترن خدماتی
     */
    public function sendOtpPattern(string $mobile, string $patternCode, array $variables): array
    {
        try {
            $response = Http::withHeaders([
                'Authorization' => 'Bearer ' . $this->apiKey,
                'Content-Type'  => 'application/json',
            ])->timeout(4)->retry(2, 100)->post("{$this->baseUrl}/api/v1/send/pattern", [
                'recipient'    => $mobile,
                'pattern_code' => $patternCode,
                'variables'    => $variables,
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('FreeSMS OTP Error: ' . $response->body());
            throw new Exception('خطا در ارسال پیامک: ' . $response->status());
        } catch (Exception $e) {
            Log::critical('FreeSMS Connection Exception: ' . $e->getMessage());
            throw $e;
        }
    }
}

۳. ساخت کانال نوتیفیکیشن اختصاصی لاراول (Custom SmsChannel)

یکی از زیبایی‌های لاراول، سیستم یکپارچه Notifications آن است. برای ایجاد کانال پیامک سفارشی، فایل app/Notifications/Channels/SmsChannel.php را ایجاد کنید:

<?php

namespace App\Notifications\Channels;

use Illuminate\Notifications\Notification;
use App\Services\FreeSmsService;

class SmsChannel
{
    protected FreeSmsService $smsService;

    public function __construct(FreeSmsService $smsService)
    {
        $this->smsService = $smsService;
    }

    public function send($notifiable, Notification $notification)
    {
        if (!method_exists($notification, 'toSms')) {
            return;
        }

        $messageData = $notification->toSms($notifiable);
        $mobile = $notifiable->routeNotificationFor('sms', $notification);

        if (!$mobile) {
            $mobile = $notifiable->mobile ?? $notifiable->phone;
        }

        return $this->smsService->sendOtpPattern(
            $mobile,
            $messageData['pattern_code'],
            $messageData['variables']
        );
    }
}

۴. ارسال نوتیفیکیشن از طریق صف (Laravel Queues)

اکنون هر کلاسی که از Notification ارث‌بری می‌کند می‌تواند با افزودن implements ShouldQueue پیامک را بدون بلاک کردن درخواست کاربر ارسال کند:

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;
use App\Notifications\Channels\SmsChannel;

class OrderConfirmedNotification extends Notification implements ShouldQueue
{
    use Queueable;

    protected $order;

    public function __construct($order)
    {
        $this->order = $order;
    }

    public function via($notifiable): array
    {
        return [SmsChannel::class];
    }

    public function toSms($notifiable): array
    {
        return [
            'pattern_code' => 'order-confirm',
            'variables'    => [
                'name'     => $notifiable->name,
                'order_id' => (string) $this->order->id,
                'amount'   => number_format($this->order->total),
            ],
        ];
    }
}

۵. دریافت گزارش دلیوری با وب‌هوک لاراول (Webhook Controller)

هنگامی که وضعیت تحویل پیامک از سمت مخابرات مشخص می‌شود، فری اس ام اس آن را به وب‌هوک شما مخابره می‌کند:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class SmsWebhookController extends Controller
{
    public function handleDelivery(Request $request)
    {
        $messageId = $request->input('message_id');
        $status    = $request->input('status'); // DELIVERED, FAILED, BLACKLIST
        $deliveredAt = $request->input('delivered_at');

        Log::info("SMS {$messageId} updated to {$status} at {$deliveredAt}");

        return response()->json(['status' => 'acknowledged']);
    }
}

جدول کدهای وضعیت و خطاهای وب‌سرویس

سوالات متداول برنامه‌نویسان لاراول