ارسال پیامک لاراول؛ از سرویس کوچک تا نوتیفیکیشن، صف و تست خودکار
ارسال پیامک لاراول را میشود با یک خط Http::post شروع کرد، ولی در یک پروژهی واقعی چند پرسش زود پیدا میشود: کلید کجا بماند، پیامک بیرون از درخواست کاربر چطور فرستاده شود، اگر سرویسدهنده خطا داد چه کنیم و بدون خرج پیامک واقعی چطور آزمایشش کنیم. لاراول برای هر کدام ابزار آماده دارد: فایل config، Http facade، سیستم نوتیفیکیشن، صف، RateLimiter و Http::fake. این صفحه آنها را کنار هم میگذارد تا یک مسیر تمیز بسازید. قالب درخواست هر شرکت پیامکی فرق دارد، پس نشانی و فیلدها جانشیناند و باید طبق مستندات سرویسدهندهی خودتان عوض شوند.
بروزرسانی: · زمان مطالعه حدود ۱۱ دقیقه · نوشتهی تیم فنی فینگت
برای ارسال پیامک لاراول دو راه رایج هست. راه اول یک پکیج آماده است؛ فهرستی از آنها در مخزنهای عمومی پیدا میشود و بسته به سرویسدهندهی شما ممکن است درایور مناسب داشته باشد. راه دوم نوشتن یک کلاس کوچک روی Http facade است که فقط به سرویسدهندهی خودتان وصل میشود. اگر پکیج پیامک لاراول مناسب و نگهداریشدهای برای شرکت خودتان دیدید، استفاده از آن منطقی است؛ در غیر این صورت کلاس خودتان کوتاهتر و قابل فهمتر است.
در این صفحه راه دوم را میرویم، چون اصول آن برای هر پکیجی هم لازم است. چهار قطعه میسازیم: تنظیمات، سرویس ارسال، کانال نوتیفیکیشن که پیامک را مثل ایمیل و اعلان دیگر لاراول رفتار میدهد، و صف که ارسال را از درخواست کاربر جدا میکند. وب سرویس پیامک پسزمینهی این کار را توضیح داده است.
فرقش با نسخهی سادهی PHP
اگر پروژهی شما لاراولی نیست، همان مفهوم را با ابزار خود PHP در ارسال پیامک با php ببینید. در لاراول، چون چارچوب تنظیمات، صف و آزمون را آماده میدهد، کار اصلی چیدن درست آنهاست نه نوشتن دوبارهی آنها.
لاراول رسیدن پیامک را قطعی نمیکند. کد شما فقط درخواست را به شرکت پیامکی تحویل میدهد؛ مسیر بعدی در دست سرویسدهنده و اپراتور است.
تنظیمات؛ کلید را در config بگذارید نه در کد
اولین قاعدهی لاراول برای هر راز این است: مقدار در فایل .env، خواندن آن فقط در فایل config. اگر در لایهی برنامه مستقیم env صدا بزنید، بعد از اجرای دستور config:cache مقدار null برمیگردد و پیامکها بیصدا از کار میافتند؛ این از شایعترین دلیلهای «در سرور کار نمیکند» است.
نمونهی زیر سه مقدار را تعریف میکند و در config/services.php مثل تنظیمهای ایمیل و سرویسهای دیگر قرار میدهد.
فایل .env نباید وارد مخزن کد شود؛ فایل .env.example را با مقدارهای خالی نگه دارید تا همتیمیها بدانند کدام تنظیمها لازم است. برای آزمایش و تولید کلیدهای جداگانه بگیرید.
کلاس سرویس با Http facade
حالا یک کلاس کوچک میسازیم که تنها کارش گفتگو با وبسرویس است. بقیهی برنامه فقط این کلاس را میشناسد؛ اگر روزی شرکت پیامکی عوض شد، فقط همین یک فایل تغییر میکند.
در Http facade متد timeout و connectTimeout از همان ابتدا گذاشته شدهاند، و متد throw اگر پاسخ خطا بود استثنا پرتاب میکند. این استثنا را بعداً صف میگیرد و تلاش مجدد را خودش انجام میدهد.
app/Services/Sms/SmsGateway.php
<?php
namespace App\Services\Sms;
use Illuminate\Support\Facades\Http;
use InvalidArgumentException;
class SmsGateway
{
public function __construct(
private string $endpoint,
private string $key,
private string $sender,
private int $timeout = 8,
) {}
/** شماره را به قالب 09xxxxxxxxx برمیگرداند یا استثنا پرتاب میکند */
public static function normalize(string $raw): string
{
$raw = strtr($raw, ['۰'=>'0','۱'=>'1','۲'=>'2','۳'=>'3','۴'=>'4','۵'=>'5','۶'=>'6','۷'=>'7','۸'=>'8','۹'=>'9']);
$digits = preg_replace('/\D+/', '', $raw);
if (str_starts_with($digits, '98')) {
$digits = '0'.substr($digits, 2);
}
if (! preg_match('/^09\d{9}$/', $digits)) {
throw new InvalidArgumentException('شمارهی موبایل نامعتبر است');
}
return $digits;
}
/** پیامک را به وبسرویس تحویل میدهد؛ در خطا RequestException یا ConnectionException پرتاب میشود */
public function send(string $phone, string $text): array
{
$response = Http::withToken($this->key)
->acceptJson()
->asJson()
->connectTimeout(3)
->timeout($this->timeout)
->post($this->endpoint, [
'to' => self::normalize($phone),
'from' => $this->sender,
'message' => $text,
])
->throw(); // کد 4xx و 5xx را به استثنا تبدیل میکند
return $response->json() ?? [];
}
}
app/Providers/AppServiceProvider.php؛ ثبت در کانتینر
<?php
namespace App\Providers;
use App\Services\Sms\SmsGateway;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->app->singleton(SmsGateway::class, fn () => new SmsGateway(
config('services.sms.endpoint'),
config('services.sms.key'),
config('services.sms.sender'),
(int) config('services.sms.timeout', 8),
));
}
}
با ثبت در کانتینر، هر کلاسی در لاراول میتواند SmsGateway را در سازندهاش بخواهد و لاراول خودش آن را بدهد. در آزمون هم میتوان آن را با یک نسخهی ساختگی عوض کرد.
کانال نوتیفیکیشن پیامک؛ مثل ایمیل، فقط برای موبایل
لاراول یک سیستم نوتیفیکیشن دارد که یک رویداد را از کانالهای مختلف میفرستد: ایمیل، پایگاهداده، اسلک و غیره. کانال پیامک ما چیزی است که خودمان مینویسیم و بعد کنار بقیه به کار میگیریم. مزیتش این است که منطق «چه کسی چه پیامی بگیرد» از «چطور بفرستیم» جداست.
کانال متن را از متد toSms خود نوتیفیکیشن میگیرد و شماره را از متد routeNotificationForSms روی مدل کاربر.
app/Channels/SmsChannel.php
<?php
namespace App\Channels;
use App\Services\Sms\SmsGateway;
use Illuminate\Notifications\Notification;
class SmsChannel
{
public function __construct(private SmsGateway $gateway) {}
public function send(object $notifiable, Notification $notification): void
{
$phone = $notifiable->routeNotificationFor('sms', $notification);
if (! $phone) {
return; // کاربر شماره ندارد؛ بیسروصدا رد میشویم
}
$this->gateway->send($phone, $notification->toSms($notifiable));
}
}
<?php
namespace App\Notifications;
use App\Channels\SmsChannel;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;
class OrderPlaced extends Notification implements ShouldQueue
{
use Queueable;
public int $tries = 3;
public function __construct(private int $orderId) {}
public function via(object $notifiable): array
{
return [SmsChannel::class];
}
/** بین تلاشها ده ثانیه و بعد یک دقیقه صبر کن */
public function backoff(): array
{
return [10, 60];
}
public function toSms(object $notifiable): string
{
return "سفارش شماره {$this->orderId} ثبت شد. ممنون از خرید شما.";
}
}
app/Models/User.php؛ فقط یک متد اضافه
// داخل کلاس User، که از ویژگی Notifiable استفاده میکند:
public function routeNotificationForSms($notification = null): ?string
{
return $this->phone; // ستون شمارهی موبایل شما
}
// استفاده در هر جا:
// $user->notify(new \App\Notifications\OrderPlaced($order->id));
چون OrderPlaced صفدار است، $user->notify فوراً برمیگردد و ارسال واقعی در یک کارگر صف انجام میشود. اگر کارگر را اجرا نکرده باشید (php artisan queue:work)، پیامکها در صف میمانند؛ این هم از شایعترین دلیلهای «ارسال نمیشود» است.
صف پیامک در لاراول؛ چرا و چطور؟
ارسال پیامک یک تماس شبکهای است و شبکه گاهی کند یا قطع میشود. اگر این تماس در همان درخواست کاربر انجام شود، هر کندی سرویسدهنده مستقیم به صفحهی کاربر میرسد. صف پیامک در لاراول این وابستگی را میشکند و چند مزیت دیگر هم دارد.
پاسخ سریع به کاربر
درخواست کاربر بعد از ثبت سفارش بلافاصله تمام میشود و پیامک چند ثانیه بعد توسط کارگر صف فرستاده میشود.
تلاش مجدد خودکار
با tries و backoff نوتیفیکیشن بعد از خطای شبکه دوباره امتحان میشود، بدون اینکه کدی بنویسید.
جدا شدن خطا
اگر وبسرویس چند دقیقه از دسترس خارج شد، سفارشها خراب نمیشوند؛ فقط کار پیامک در صف عقب میافتد.
صفهای جدا
پیامک کد تأیید را در صف جداگانهی با اولویت بالا بگذارید تا پشت پیامکهای دستهای نماند.
ثبت شکست
کارهای ناموفق در جدول failed_jobs میمانند و بعداً میتوان آنها را مرور یا دوباره اجرا کرد.
هزینهی کمتر
با تلاشهای محدود، یک خطای دائمی (مثل شمارهی نامعتبر) بیانتها دوباره فرستاده نمیشود.
برای کد تأیید که چند ثانیه بعد بیارزش میشود، تلاش مجدد با فاصلهی طولانی بیمعناست. در آن حالت بهتر است tries را کم کنید یا با متد retryUntil زمان پایان بگذارید.
سقف نرخ؛ دکمهی ارسال را به ابزار حمله تبدیل نکنید
هر مسیری که به پیامک منتهی میشود، مثلاً «ارسال کد ورود»، برای رباتها شیرین است چون هر درخواست برای شما هزینه دارد. لاراول با RateLimiter و middleware throttle این را ساده میکند.
نمونهی زیر دو سقف همزمان میگذارد: یکی برای هر شماره و یکی برای هر IP. جزئیات بیشتر این حمله و راههای مقابله در جلوگیری از sms bombing آمده است.
app/Providers/AppServiceProvider.php؛ تعریف سقف در boot
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
public function boot(): void
{
RateLimiter::for('sms-code', function (Request $request) {
$phone = (string) $request->input('phone');
return [
Limit::perMinute(1)->by('phone:'.$phone), // یک پیامک در دقیقه برای هر شماره
Limit::perHour(5)->by('phone-hour:'.$phone),
Limit::perHour(20)->by('ip:'.$request->ip()),
];
});
}
routes/web.php؛ استفاده در مسیر
use App\Http\Controllers\SmsCodeController;
use Illuminate\Support\Facades\Route;
Route::post('/sms/request-code', [SmsCodeController::class, 'request'])
->middleware('throttle:sms-code');
اگر سایت شما پشت یک پروکسی یا CDN است، مطمئن شوید لاراول IP واقعی کاربر را میبیند؛ وگرنه همهی کاربران یک IP دارند و سقف بر اساس IP همه را با هم میبندد. برای این کار TrustProxies را درست تنظیم کنید.
آزمون با Http::fake؛ بدون خرج پیامک واقعی
بزرگترین مزیت لاراول برای این کار، Http::fake است. با آن، هیچ درخواستی به سرویسدهنده نمیرود و جواب را خودتان تعیین میکنید. میتوانید هم موفقیت، هم خطا را بسازید و هم ببینید درخواست دقیقاً با چه محتوایی ساخته شد.
tests/Feature/SmsGatewayTest.php
<?php
namespace Tests\Feature;
use App\Services\Sms\SmsGateway;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;
class SmsGatewayTest extends TestCase
{
private function gateway(): SmsGateway
{
return new SmsGateway('https://sms.example.test/api/send', 'test-key', '3000XXXX');
}
public function test_it_sends_normalized_phone_and_token(): void
{
Http::fake(['sms.example.test/*' => Http::response(['ok' => true], 200)]);
$this->gateway()->send('۰۹۱۲۰۰۰۰۰۰۰', 'سلام');
Http::assertSent(fn ($request) =>
$request['to'] === '09120000000'
&& $request['message'] === 'سلام'
&& $request->hasHeader('Authorization', 'Bearer test-key')
);
}
public function test_server_error_throws(): void
{
Http::fake(['sms.example.test/*' => Http::response(['error' => 'x'], 500)]);
$this->expectException(RequestException::class);
$this->gateway()->send('09120000000', 'سلام');
}
public function test_invalid_phone_never_calls_api(): void
{
Http::fake();
$this->expectException(\InvalidArgumentException::class);
try {
$this->gateway()->send('123', 'سلام');
} finally {
Http::assertNothingSent();
}
}
}
آزمون سوم کوچک ولی مهم است: ثابت میکند شمارهی نامعتبر اصلاً به سرویسدهنده نمیرسد و هزینهای نمیسازد. با Notification::fake هم میتوانید در آزمونهای بالاتر فقط بسنجید که نوتیفیکیشن درست فرستاده شد و ارسال واقعی را دور بزنید.
مسیر یک پیامک از ثبت سفارش تا گوشی
برای اینکه تصویر کامل شود، مسیر یک پیامک را در پروژهی بالا قدم به قدم دنبال میکنیم. هر مرحله جایی است که ممکن است چیزی خراب شود و باید بدانید کجا را نگاه کنید. در جستوجوی عبارت laravel sms بیشتر نمونهها همین مسیر را بدون این جزئیات نشان میدهند.
۱
ثبت سفارش
کنترلر سفارش را در پایگاهداده ذخیره میکند و بلافاصله notify را صدا میزند. این مرحله نباید به شبکهی بیرونی وابسته باشد.
۲
قرار گرفتن در صف
چون نوتیفیکیشن صفدار است، فقط یک رکورد در صف نوشته میشود و پاسخ به کاربر برمیگردد. اگر صف خالی نمیشود، اولین جای بررسی کارگر صف است.
۳
برداشتن توسط کارگر
کارگر کار را برمیدارد و via را میخواند. اینجا کانال پیامک انتخاب میشود و شماره از routeNotificationForSms گرفته میشود.
۴
درخواست به وبسرویس
SmsGateway شماره را نرمال میکند، درخواست را با timeout میفرستد و در صورت خطا استثنا پرتاب میکند.
۵
تلاش مجدد یا شکست
اگر استثنا آمد، صف طبق backoff دوباره امتحان میکند. بعد از سومین شکست کار در failed_jobs میماند تا کسی ببیند.
۶
تحویل به شرکت پیامکی
اگر جواب موفق بود، کار تمام است. از اینجا به بعد مسیر در دست شرکت پیامکی و اپراتور است و کد شما دیگر نمیبیند چه میشود.
نمونهای از رفتار با خطا در یک شب پرکار
این یک نمونهی فرضی برای دیدن اثر صف و سقف نرخ است و ماجرای واقعی یک مشتری نیست.
سناریوی نمونه
نمونه: فروشگاه آنلاین لوازم ورزشی در روز تخفیف
فروشگاه فرضی «ورزشآباد» در یک روز تخفیف چند دههزار بازدید دارد. اگر پیامک سفارش در همان درخواست فرستاده میشد، هر وقفهی چند ثانیهای وبسرویس مستقیماً صفحهی پرداخت را کند میکرد. با نوتیفیکیشن صفدار، صفحهی پرداخت همیشه سریع است و اگر وبسرویس ده دقیقه خطا بدهد، پیامکها در صف عقب میافتند و بعد با همان backoff دوباره امتحان میشوند. در همان روز، یک ربات هم دکمهی «ارسال کد» را چند صد بار میزند؛ سقف یک پیامک در دقیقه برای هر شماره و بیست ارسال در ساعت برای هر IP جلوی خالی شدن اعتبار پنل را میگیرد. در پایان روز، تیم فقط جدول failed_jobs را مرور میکند تا ببیند چه پیامکهایی واقعاً نرفتهاند.
واژههای این صفحه
اگر با اصطلاحهای لاراولی آشنا نیستید، این چند مورد برای دنبال کردن بقیهی صفحه کافی است.
Http facade
ابزار داخلی لاراول برای درخواست HTTP؛ روی Guzzle ساخته شده و timeout، توکن و خطا را ساده میکند.
Notification
سیستم لاراول برای فرستادن یک پیام از چند کانال؛ هر نوتیفیکیشن یک کلاس جدا دارد.
صف (Queue)
جایی که کارهای کند، مثل ارسال پیامک، برای اجرا در پسزمینه گذاشته میشوند تا درخواست کاربر معطل نماند.
backoff
فاصلهی انتظار بین تلاشهای مجدد یک کار ناموفق.
RateLimiter
ابزار لاراول برای محدود کردن تعداد درخواست در بازهی زمانی، بر اساس شماره، IP یا هر کلید دیگر.
کی ارسال پیامک لاراول را به کار بگیریم و کی کنار بگذاریم؟
هر نوتیفیکیشن پیامکی خرج دارد؛ پس پیش از اتصال رویدادها به کانال پیامک بسنجید کدام باید واقعاً روی شمارهی تلفن برسند.
پیامک مناسب است وقتی
مخاطب اپ ندارد یا عضو سایت نیست و فقط شمارهاش را دارید.
پیام باید در هر حال روی شمارهی تلفن برسد، مثل یادآوری قرار یا هشدار مهم.
خط، مجوز و محتوا را از سرویسدهندهی خود تأیید کردهاید.
کانال دیگر کافی است وقتی
کاربر شما حساب و اعلان فعال دارد و فقط میخواهید وضعیت سفارش را بدهید.
هدف فقط ورود کاربر است و میتوان بدون کد پیامکی تأییدش کرد.
پیام اطلاعرسانی ساده است و تأخیر چند دقیقهای مهم نیست.
لاراول اجازه میدهد یک نوتیفیکیشن را از چند کانال بفرستید؛ پس میتوانید «اول اعلان، اگر نه، پیامک» را در via پیاده کنید. ورود بدون رمز ورود با پیامک در لاراول هم با همین کانال کار میکند و اگر میخواهید هزینهی کد ورود را کم کنید، ورود بدون رمز عبور را هم ببینید.
اشتباههای رایج در پروژههای لاراولی
همهی این اشتباهها را در پروژههای واقعی میشود دید؛ هیچکدام سخت نیست، فقط باید قبل از انتشار به آنها فکر کرد.
خواندن env در کنترلر یا سرویس
بعد از config:cache مقدار تهی میشود. env را فقط در فایل config بخوانید و از config() استفاده کنید.
اجرا نکردن کارگر صف
نوتیفیکیشن صفدار بدون queue:work (یا Supervisor در تولید) هرگز فرستاده نمیشود. وضعیت کارگر را پایش کنید.
نداشتن timeout
Http در لاراول بهطور پیشفرض ۳۰ ثانیه صبر میکند. برای پیامک عدد کوتاهتر بگذارید.
لاگ کردن متن پیام
پیامک کد تأیید یا شمارهی کامل در لاگ نماند؛ فقط شناسه و علت.
تلاش مجدد بیپایان
اگر خطای دائمی (شمارهی نامعتبر، کلید باطل) هم مجدداً امتحان شود، فقط خرج و شلوغی میسازد. tries را محدود و خطاهای دائمی را جدا کنید.
فراموش کردن سقف نرخ
مسیر درخواست کد بدون throttle با چند اسکریپت ساده میتواند اعتبار پنل را خالی کند.
اعتماد به «موفق»
پاسخ موفق یعنی تحویل به شرکت پیامکی؛ برای بررسی نرسیدنها به پیامک تحویل داده نمیشود نگاه کنید.
فهرست بررسی پیش از انتشار
پیش از وصل کردن کد به پنل واقعی، این موارد را یک بار بررسی کنید.
config:cache امتحان شده بعد از اجرای config:cache، ارسال هنوز کار میکند و هیچ env مستقیمی باقی نیست.
کارگر صف زنده است در تولید با Supervisor یا ابزار مشابه اجرا و پس از هر استقرار دوباره راهاندازی میشود (queue:restart).
آزمونها میگذرند حالت موفق، خطای سرور و شمارهی نامعتبر با Http::fake پوشش داده شدهاند.
سقف نرخ فعال است مسیر درخواست کد هم per phone و هم per IP محدود است.
لاگ امن در لاگ فقط شناسهی سفارش یا کاربر و علت خطا هست.
پایش اعتبار اعتبار پنل را پایش میکنید؛ برای دیدن عدد منطقی هزینهی پنل پیامک را مرور کنید.
پرسشهای متداول درباره ارسال پیامک لاراول
برای ارسال پیامک لاراول حتماً پکیج لازم است؟
نه. با Http facade و یک کلاس کوچک میتوان به هر وبسرویسی وصل شد. پکیج پیامک لاراول وقتی ارزش دارد که برای سرویسدهندهی شما درایور نگهداریشده داشته باشد.
چرا بعد از config:cache پیامک نمیرود؟
چون کد از env() مستقیم میخواند. بعد از کش کردن config، env خارج از فایلهای config مقدار null میدهد. مقدار را در config/services.php بخوانید و با config() استفاده کنید.
پیامک را از طریق صف بفرستم یا همزمان؟
برای هر چیزی که نباید کاربر را منتظر بگذارد، صف بهتر است. فقط کارگر صف باید همیشه زنده باشد و برای کد تأیید، تعداد تلاش و زمان پایان را کوتاه بگیرید.
چطور بدون ارسال واقعی آزمایش کنم؟
با Http::fake میتوانید جواب موفق یا خطا بسازید و با Http::assertSent محتوای درخواست را بسنجید. برای سطح بالاتر هم Notification::fake هست.
کانال سفارشی نوتیفیکیشن چه فایدهای دارد؟
منطق «چه کسی چه پیامی بگیرد» را از «چطور ارسال شود» جدا میکند و پیامک را مثل ایمیل و اعلان در یک سیستم قرار میدهد. تغییر سرویسدهنده هم فقط به یک کلاس نیاز دارد.
آیا فینگت وبسرویس پیامک دارد؟
نه. فینگت پنل یا خط پیامکی نمیفروشد. برای سایتها ورود بدون رمز با تأیید روی گوشی دارد که ممکن است بخشی از پیامکهای ورود را بینیاز کند.