پکیج ارسال پیامک مخصوص لاراول

چرا از وب‌سرویس مدیرپیامک در لاراول استفاده کنیم؟

فراموشی رمز عبور و پوشه‌های اسپم را به فراموشی بسپارید...

ارسال پیامک یکی از مهم‌ترین قابلیت‌های موردنیاز در سایت‌ها و نرم‌افزارهای تحت وب است. از ارسال کد ورود و رمز یک‌بارمصرف گرفته تا اطلاع‌رسانی سفارش، یادآوری پرداخت، اعلام وضعیت درخواست و ارسال پیام‌های خدماتی، همه این فرایندها را می‌توان در پروژه‌های Laravel به‌صورت خودکار اجرا کرد.

با اتصال لاراول به وب‌سرویس مدیرپیامک، دیگر نیازی نیست پیام‌ها را به‌صورت دستی از پنل ارسال کنید. کافی است رویداد موردنظر در سایت اتفاق بیفتد تا سیستم در همان لحظه پیامک مناسب را برای کاربر ارسال کند.

وب‌سرویس مدیرپیامک از API Key و درخواست‌های REST پشتیبانی می‌کند و امکاناتی مانند ارسال پیامک ساده، ارسال پیامک پترن، OTP، مدیریت مخاطبان و دریافت گزارش وضعیت ارسال را در اختیار توسعه‌دهندگان قرار می‌دهد. پیامک در Laravel چه کاربردی دارد؟

تقریباً در هر پروژه‌ای که با کاربران، مشتریان یا اعضای یک سازمان در ارتباط است، امکان ارسال پیامک می‌تواند تجربه کاربری را بهبود دهد.

مهم‌ترین کاربردهای ارسال پیامک در لاراول عبارت‌اند از:

* ارسال کد ورود و ثبت‌نام OTP
* تأیید شماره موبایل کاربران
* بازیابی رمز عبور
* اطلاع‌رسانی ثبت یا تغییر وضعیت سفارش
* ارسال شماره فاکتور و رسید پرداخت
* یادآوری سررسید اقساط
* اطلاع‌رسانی نوبت و رزرو
* اعلام پاسخ تیکت پشتیبانی
* ارسال پیامک‌های خدماتی و تراکنشی
* ارسال پیام‌های شخصی‌سازی‌شده بر اساس رفتار کاربران

در این روش، ارسال پیامک می‌تواند به رویدادهایی مانند ثبت سفارش، پرداخت موفق، ایجاد حساب کاربری یا تغییر وضعیت یک درخواست متصل شود.

چرا از وب‌سرویس مدیرپیامک در لاراول استفاده کنیم؟

وب‌سرویس مدیرپیامک امکان اتصال سایت، اپلیکیشن، CRM و نرم‌افزارهای مختلف به سامانه پیامکی را فراهم می‌کند. درخواست‌ها از طریق API ارسال می‌شوند و پاسخ سرویس نیز به‌صورت ساختاریافته در اختیار برنامه قرار می‌گیرد.

برخی از قابلیت‌های این سرویس عبارت‌اند از:

* دریافت API Key اختصاصی
* ارتباط امن از طریق HTTPS
* ارسال پیامک تکی و گروهی
* ارسال پیامک بر اساس پترن
* ارسال رمز یک‌بارمصرف و کد فعال‌سازی
* دریافت گزارش تحویل پیامک
* دسترسی به خطوط خدماتی
* امکان ارسال پیامک به شماره‌های مسدودشده تبلیغاتی در سرویس‌های مجاز
* مشاهده وضعیت پیام‌های ارسال‌شده
* استفاده در سایت، اپلیکیشن و نرم‌افزارهای اختصاصی

مدیرپیامک همچنین مستندات API و مخزن رسمی SDK را در اختیار توسعه‌دهندگان قرار داده است تا اتصال پروژه‌های برنامه‌نویسی با سرعت بیشتری انجام شود. یازهای اتصال لاراول به پنل پیامکی

برای شروع به موارد زیر نیاز دارید:

1. یک حساب فعال در مدیرپیامک
2. دریافت API Key از بخش تنظیمات وب‌سرویس
3. دسترسی به خط ارسال‌کننده
4. نصب Composer روی پروژه
5. دسترسی به فایل `.env`
6. اطلاعات پترن، در صورت استفاده از پیامک الگو یا OTP

اطلاعات API نباید مستقیماً داخل Controller یا سایر فایل‌های پروژه نوشته شود. بهتر است کلید دسترسی را در فایل `.env` نگهداری کنید تا هم امنیت پروژه افزایش پیدا کند و هم تغییر تنظیمات در محیط توسعه و سرور اصلی ساده‌تر باشد.

نصب پکیج ارسال پیامک در Laravel

برای اتصال لاراول به زیرساخت وب‌سرویس مدیرپیامک می‌توانید از SDK رسمی IPPanel استفاده کنید. ابتدا دستور زیر را در ترمینال پروژه اجرا کنید:

“`bash
composer require ippanelcom/laravel-sdk
“`

این پکیج برای اتصال پروژه‌های Laravel به API پیامکی طراحی شده و امکان ارسال پیامک ساده، پیامک پترن و رمز یک‌بارمصرف صوتی را فراهم می‌کند. های جدید لاراول، Service Provider معمولاً به‌صورت خودکار شناسایی می‌شود. در پروژه‌هایی که قابلیت Auto Discovery غیرفعال است، باید Provider و Alias پکیج را به فایل تنظیمات برنامه اضافه کنید.

## انتشار فایل تنظیمات پکیج

پس از نصب، دستور زیر را اجرا کنید:

“`bash
php artisan vendor:publish –provider=”Ippanel\IppanelServiceProvider” –tag=”config”
“`

با اجرای این دستور، فایل تنظیمات پکیج در مسیر زیر ایجاد می‌شود:

“`text
config/ippanel.php
“`

سپس API Key دریافتی از مدیرپیامک را در فایل `.env` قرار دهید:

“`env
IPPANEL_API_KEY=YOUR_API_KEY
“`

به‌جای عبارت `YOUR_API_KEY` کلید واقعی وب‌سرویس خود را وارد کنید. API Key باید محرمانه باقی بماند و نباید در مخزن عمومی GitHub یا فایل‌های قابل‌دسترسی کاربران قرار گیرد.

## نمونه کد ارسال پیامک ساده در لاراول

برای ارسال پیامک عادی می‌توانید Client پکیج را در Controller تزریق و متد ارسال وب‌سرویس را فراخوانی کنید:

“`php
<?php

namespace App\Http\Controllers;

use Ippanel\Client;

class SmsController extends Controller
{
public function send(Client $sms)
{
$message = ‘سفارش شما با موفقیت ثبت شد.’;
$sender = ‘+981000XXXX’;
$recipients = [‘+989121234567’];

$response = $sms->sendWebservice(
$message,
$sender,
$recipients
);

if ($response->isSuccessful()) {
return response()->json([
‘success’ => true,
‘message’ => ‘پیامک با موفقیت ارسال شد.’,
‘data’ => $response->getData(),
]);
}

return response()->json([
‘success’ => false,
‘message’ => $response->getMessage(),
], 422);
}
}
“`

در این کد:

* متغیر `$message` شامل متن پیامک است.
* متغیر `$sender` شماره ارسال‌کننده را مشخص می‌کند.
* آرایه `$recipients` شماره گیرندگان را در بر می‌گیرد.
* متد `isSuccessful()` موفق یا ناموفق بودن درخواست را بررسی می‌کند.
* متد `getData()` اطلاعات پاسخ وب‌سرویس را برمی‌گرداند.
* متد `getMessage()` متن خطای احتمالی را دریافت می‌کند.

ساختار پاسخ SDK به توسعه‌دهنده اجازه می‌دهد وضعیت درخواست، داده‌های ارسال و پیام خطا را به‌شکل کنترل‌شده مدیریت کند. پیامک پترن و OTP در Laravel

برای پیام‌هایی مانند کد ورود، بازیابی رمز، اطلاع‌رسانی پرداخت یا تأیید سفارش، بهتر است از پیامک پترن استفاده کنید.

پترن یک متن از پیش تأییدشده است که بخش‌هایی از آن به‌صورت متغیر تعریف می‌شوند. برای مثال:

“`text
کاربر عزیز، کد ورود شما %code% است.
“`

در زمان ارسال، مقدار متغیر `code` از سمت پروژه لاراول ارسال می‌شود.

نمونه کد ارسال پیامک پترن:

“`php
<?php

use Ippanel\Client;

public function sendOtp(Client $sms)
{
$patternCode = ‘YOUR_PATTERN_CODE’;
$sender = ‘+981000XXXX’;
$recipient = ‘+989121234567’;

$parameters = [
‘name’ => ‘علی’,
‘code’ => ‘45821’,
];

$response = $sms->sendPattern(
$patternCode,
$sender,
$recipient,
$parameters
);

if (!$response->isSuccessful()) {
report($response->getMessage());

return response()->json([
‘success’ => false,
‘message’ => ‘ارسال کد با خطا مواجه شد.’,
], 422);
}

return response()->json([
‘success’ => true,
‘message’ => ‘کد تأیید ارسال شد.’,
]);
}
“`

پترن‌ها قالب‌های از پیش تأییدشده‌ای هستند که متغیرهای موردنیاز هنگام ارسال در آن‌ها جای‌گذاری می‌شود. این روش برای ارسال OTP، پیام‌های استاندارد و اطلاع‌رسانی‌های تراکنشی مناسب است. امنیتی ارسال کد OTP

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

* برای هر کد، زمان انقضای کوتاه تعیین کنید.
* تعداد درخواست‌های ارسال کد را محدود کنید.
* کد قبلی را پس از صدور کد جدید غیرفعال کنید.
* پس از تأیید موفق، کد را مصرف‌شده در نظر بگیرید.
* تعداد دفعات وارد کردن کد اشتباه را محدود کنید.
* اطلاعات API را فقط در فایل `.env` نگهداری کنید.
* شماره موبایل را پیش از ارسال اعتبارسنجی و یکسان‌سازی کنید.
* خطاهای سرویس را بدون نمایش اطلاعات محرمانه ثبت کنید.

بهتر است برای جلوگیری از درخواست‌های مکرر، فاصله مشخصی میان دو بار ارسال OTP تعریف شود.

استفاده از Queue برای ارسال پیامک در لاراول

تماس با یک API خارجی ممکن است زمان پاسخ درخواست کاربر را افزایش دهد. برای پیامک‌هایی که لازم نیست دقیقاً در همان لحظه ارسال شوند، می‌توانید عملیات ارسال را داخل Queue قرار دهید.

لاراول امکان اجرای وظایف زمان‌بر در صف را فراهم می‌کند تا پاسخ صفحه یا API بدون انتظار برای پایان عملیات خارجی به کاربر بازگردانده شود. Queueها می‌توانند از Database، Redis یا سرویس‌هایی مانند Amazon SQS استفاده کنند. اد Job می‌توانید دستور زیر را اجرا کنید:

“`bash
php artisan make:job SendSmsJob
“`

سپس ارسال پیامک را داخل متد `handle` قرار دهید:

“`php
public function handle(Client $sms): void
{
$response = $sms->sendWebservice(
$this->message,
$this->sender,
[$this->mobile]
);

if (!$response->isSuccessful()) {
throw new \RuntimeException($response->getMessage());
}
}
“`

Job را نیز به این صورت اجرا کنید:

“`php
SendSmsJob::dispatch(
$mobile,
$message,
$sender
);
“`

برای پیامک ورود یا OTP که سرعت اهمیت زیادی دارد، می‌توان ارسال را مستقیم انجام داد؛ اما پیامک‌هایی مانند اطلاع‌رسانی سفارش، یادآوری یا کمپین‌های گروهی بهتر است از طریق Queue پردازش شوند.

مدیریت خطا و گزارش ارسال پیامک

یکی از اشتباهات رایج در اتصال لاراول به پنل پیامکی این است که برنامه‌نویس پس از ارسال درخواست، پاسخ وب‌سرویس را بررسی نمی‌کند.

در یک پیاده‌سازی حرفه‌ای بهتر است موارد زیر ذخیره شوند:

* شماره گیرنده
* نوع پیامک
* زمان ارسال
* شناسه پیام یا ارسال
* وضعیت درخواست
* متن خطای احتمالی
* تعداد تلاش‌های ارسال
* نام پترن استفاده‌شده

وب‌سرویس مدیرپیامک امکان دریافت گزارش وضعیت پیام‌هایی مانند ارسال موفق، در صف، نرسیده یا فیلترشده را فراهم می‌کند. بنابراین می‌توانید وضعیت نهایی پیامک را در پنل مدیریتی سایت یا نرم‌افزار خود نمایش دهید. مستقیم با HTTP Client لاراول

در پروژه‌هایی که نمی‌خواهید از پکیج استفاده کنید، امکان ارسال مستقیم درخواست به REST API نیز وجود دارد.

لاراول یک HTTP Client داخلی برای برقراری ارتباط با سرویس‌های خارجی ارائه می‌دهد که از قابلیت‌هایی مانند Header، Timeout، Retry، مدیریت خطا و تست پاسخ پشتیبانی می‌کند. لی یک درخواست مستقیم می‌تواند به‌شکل زیر باشد:

“`php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
‘Authorization’ => config(‘services.sms.api_key’),
‘Accept’ => ‘application/json’,
])->timeout(10)
->retry(2, 500)
->post(‘API_ENDPOINT’, [
‘sending_type’ => ‘webservice’,
‘from_number’ => ‘+981000XXXX’,
‘message’ => ‘پیام آزمایشی مدیرپیامک’,
‘params’ => [
‘recipients’ => [‘+989121234567’],
],
]);

if ($response->failed()) {
logger()->error(‘SMS API Error’, [
‘status’ => $response->status(),
‘response’ => $response->json(),
]);
}
“`

آدرس Endpoint و پارامترهای هر متد باید مطابق آخرین مستندات API مدیرپیامک تنظیم شوند. در مستندات فعلی، درخواست‌های ارسال پیامک با احراز هویت و بدنه JSON پردازش می‌شوند. آماده بهتر است یا اتصال مستقیم به API؟

انتخاب روش مناسب به ساختار پروژه شما بستگی دارد.

استفاده از پکیج برای بیشتر پروژه‌های لاراولی سریع‌تر است، زیرا تنظیمات، ساخت درخواست و پردازش پاسخ‌ها در قالب کلاس‌ها و متدهای آماده انجام می‌شود.

اتصال مستقیم به API برای پروژه‌هایی مناسب است که:

* معماری اختصاصی دارند.
* نمی‌خواهند وابستگی جدیدی نصب کنند.
* به کنترل کامل درخواست‌ها نیاز دارند.
* از چند ارائه‌دهنده پیامکی استفاده می‌کنند.
* قصد دارند یک لایه مستقل برای تغییر سرویس‌دهنده ایجاد کنند.

در پروژه‌های بزرگ پیشنهاد می‌شود منطق ارسال پیامک داخل یک Service مجزا نوشته شود تا Controllerها مستقیماً به ارائه‌دهنده پیامکی وابسته نباشند.

چرا مدیرپیامک برای پروژه‌های Laravel مناسب است؟

مدیرپیامک تنها یک محیط برای ارسال دستی پیامک نیست. این سامانه امکان اتصال فرایندهای نرم‌افزاری به پنل پیامکی را فراهم می‌کند؛ بنابراین توسعه‌دهنده می‌تواند ارسال پیامک را بخشی از منطق اصلی برنامه قرار دهد.

وجود API Key، مستندات فنی، SDK لاراول، پیامک پترن، سرویس OTP و گزارش تحویل باعث می‌شود بتوانید از مدیرپیامک در فروشگاه اینترنتی، سامانه رزرو، CRM، نرم‌افزار حسابداری، اپلیکیشن خدماتی و سایر پروژه‌های اختصاصی استفاده کنید. ارسال پیامک در لاراول

برای راه‌اندازی ارسال پیامک در پروژه Laravel، ابتدا در مدیرپیامک ثبت‌نام کرده و API Key خود را دریافت کنید. سپس پکیج Laravel را با Composer نصب کرده، اطلاعات دسترسی را در فایل `.env` قرار دهید و متناسب با نیاز پروژه از ارسال عادی یا ارسال پترن استفاده کنید.

تیم پشتیبانی مدیرپیامک نیز در فرایند دریافت وب‌سرویس، انتخاب خط مناسب، ساخت پترن و اتصال پروژه همراه شما خواهد بود.

**همین حالا پنل پیامکی خود را فعال کنید و ارسال خودکار پیامک در پروژه لاراول را آغاز کنید.**

سؤالات متداول ارسال پیامک در لاراول

آیا برای ارسال پیامک در لاراول به پنل پیامکی نیاز داریم؟

بله. برای ارسال پیامک واقعی باید یک حساب فعال، اعتبار پیامکی، API Key و خط ارسال‌کننده داشته باشید.

API Key مدیرپیامک را کجا قرار دهیم؟

API Key را در فایل `.env` پروژه قرار دهید و از نوشتن مستقیم آن داخل Controller، Model یا فایل‌های قابل‌انتشار خودداری کنید.

آیا می‌توان از Laravel برای ارسال کد OTP استفاده کرد؟

بله. با استفاده از ارسال پترن می‌توانید کد ورود، تأیید شماره موبایل، بازیابی رمز عبور و ورود دومرحله‌ای را پیاده‌سازی کنید.

آیا امکان ارسال پیامک به چند شماره وجود دارد؟

بله. در ارسال وب‌سرویس می‌توانید آرایه‌ای از شماره‌های گیرنده را به متد ارسال بدهید. برای تعداد بالای پیامک بهتر است عملیات با Queue و پردازش مرحله‌ای انجام شود.

آیا امکان مشاهده وضعیت تحویل پیامک وجود دارد؟

بله. از طریق متدهای گزارش‌گیری وب‌سرویس می‌توانید وضعیت پیامک‌های ارسال‌شده را دریافت و در نرم‌افزار خود ذخیره کنید.

آیا ارسال پیامک در لاراول باید با پکیج انجام شود؟

خیر. علاوه بر SDK آماده، می‌توانید از HTTP Client داخلی Laravel برای فراخوانی مستقیم REST API استفاده کنید.

تفاوت پیامک ساده و پیامک پترن چیست؟

در پیامک ساده، متن کامل هنگام ارسال به وب‌سرویس داده می‌شود. در پیامک پترن، یک قالب از پیش تأییدشده دارید و تنها مقادیر متغیرهایی مانند نام، کد ورود یا شماره سفارش را ارسال می‌کنید.

نظرات

نام و نام خانوادگی*

شماره موبایل*