ارسال پیامک با php؛ یک کلاینت کوچک، امن و قابل آزمایش با cURL
ارسال پیامک با php در سادهترین شکل یک درخواست HTTP است: آدرس وبسرویس، کلید دسترسی، شماره و متن. نوشتن همین درخواست ده دقیقه کار دارد، اما بیشتر پروژهها بعدها بهخاطر چیزهایی که در همان ده دقیقه جا افتاده دردسر میکشند: نبودن timeout، لو رفتن کلید در مخزن کد، لاگ شدن متن کد تأیید و نبودن راهی برای آزمایش بدون خرج پیامک واقعی. این صفحه یک کلاینت کوچک میسازد که این چهار مشکل را از همان ابتدا ندارد. چون هر شرکت پیامکی قالب درخواست خودش را دارد، نشانی و نام فیلدها در نمونهها جانشیناند و باید از مستندات سرویسدهندهی شما برداشته شوند.
بروزرسانی: · زمان مطالعه حدود ۱۱ دقیقه · نوشتهی تیم فنی فینگت
وقتی میگوییم ارسال پیامک با php، منظور این نیست که PHP خودش پیامک میفرستد. PHP فقط یک درخواست اینترنتی به وبسرویس شرکت پیامکی میفرستد و آن شرکت پیامک را از مسیر خود به اپراتور میرساند. اگر هنوز با این ایده آشنا نیستید، صفحهی وب سرویس پیامک تصویر کلی آن را توضیح داده است.
به همین دلیل اتصال php به وب سرویس پیامک بیشتر یک کار مهندسی دقیق است تا برنامهنویسی پیچیده.
پس سهم کد شما کوچک است: ساختن درخواست درست، منتظر ماندن به اندازه، فهمیدن جواب و رفتار درست در برابر خطا. سهم بزرگتر، یعنی رساندن پیامک، در دست سرویسدهنده و اپراتور است و هیچ کدی از سمت شما نمیتواند رسیدن را قطعی کند. هر کجا ادعایی دربارهی رسیدن دیدید، یادتان باشد که درستش «تحویل به شرکت پیامکی» است و نه «دیدن پیامک روی گوشی».
سه مسیر برای نوشتن آن
در PHP سه راه رایج هست: تابع file_get_contents با context، کتابخانهی Guzzle، و افزونهی cURL. برای یک درخواست ساده، cURL بینیاز از نصب چیزی است و روی تقریباً هر میزبانی فعال است؛ به همین دلیل نمونههای این صفحه با ارسال پیامک با curl نوشته شدهاند. اگر پروژهی شما لاراولی است، ارسال پیامک لاراول همین کار را با ابزار خود چارچوب نشان میدهد.
اگر فقط کد تأیید ورود میفرستید، منطق ساخت و بررسی کد را در ورود با موبایل php ببینید. این صفحه فقط لایهی ارسال را میسازد و عمداً به آن منطق کاری ندارد.
پیش از نوشتن کد چهار چیز را از سرویسدهنده بگیرید
بدون این چهار مورد هر نمونهکدی فقط حدس است. پیش از شروع، آنها را از پنل یا مستندات شرکت پیامکی بردارید و جایی امن یادداشت کنید.
نشانی دقیق وبسرویس نشانی ارسال، روش درخواست (معمولاً POST) و قالب بدنه که JSON است یا فرم. حدسزدن این بخش، شایعترین دلیل خطای اولیه است.
شیوهی احراز هویت کلید در سرآیند میآید یا در بدنه، یا نام کاربری و گذرواژه است. در هر سه حالت، آن را مثل رمز عبور بانک نگه دارید.
خط و نوع پیام شمارهی خطی که مجوز ارسال دارد و فرق خط خدماتی با تبلیغاتی. برای آشنایی، خط خدماتی و پیامک خدماتی و تبلیغاتی را بخوانید.
قالب جواب و کدهای خطا جواب موفق چه شکلی است، خطای اعتبار کم یا شمارهی نامعتبر چه کدی دارد. بدون آن، کد شما فقط میتواند بگوید «کار نکرد».
کد ارسال پیامک php؛ سادهترین نمونه با cURL
نمونهی زیر را فقط برای فهمیدن ساختار ببینید. نشانی، نام فیلدها و قالب سرآیند جانشیناند و باید طبق مستندات سرویسدهندهی خودتان عوض شوند. کد را نمیشود روی یک سرویسدهندهی مشخص «همینطور» اجرا کرد.
دو چیز در همین نمونهی کوتاه مهم است. اول CURLOPT_TIMEOUT که اگر نباشد، کند شدن سرویسدهنده صفحهی شما را هم میخواباند. دوم CURLOPT_RETURNTRANSFER که بدون آن جواب چاپ میشود و به متغیر نمیرسد.
تابع ارسال پیامک در php؛ کلاینتی که خطا را جدی میگیرد
نمونهی بالا اگر شبکه قطع شود یا سرویسدهنده جواب نادرست بدهد، چیزی نمیگوید و برنامه را ادامه میدهد. کلاس زیر همان کار را درستتر انجام میدهد: خطای شبکه را از خطای سرویسدهنده جدا میکند، استثنای مشخص پرتاب میکند و کلید را از متغیر محیطی میخواند.
ساختار عمداً کوچک است. اگر روزی سرویسدهنده را عوض کنید، فقط بدنهی متد send تغییر میکند و بقیهی برنامه که فقط SmsClient را صدا میزند دست نمیخورد؛ همین جدایی هزینهی تغییر را کم میکند.
SmsClient.php؛ کلاینت با استثنای مشخص
<?php
declare(strict_types=1);
final class SmsException extends RuntimeException {}
final class SmsClient
{
public function __construct(
private string $endpoint,
private string $apiKey,
private string $sender,
private int $timeout = 8,
) {}
public static function fromEnv(): self
{
$key = getenv('SMS_API_KEY');
$url = getenv('SMS_ENDPOINT');
$from = getenv('SMS_SENDER');
if (!$key || !$url || !$from) {
throw new SmsException('تنظیمات پیامک کامل نیست');
}
return new self($url, $key, $from);
}
/** شماره را به قالب 09xxxxxxxxx برمیگرداند یا استثنا پرتاب میکند */
public static function normalize(string $raw): string
{
$raw = strtr($raw, ['۰'=>'0','۱'=>'1','۲'=>'2','۳'=>'3','۴'=>'4','۵'=>'5','۶'=>'6','۷'=>'7','۸'=>'8','۹'=>'9']);
$d = preg_replace('/\D+/', '', $raw);
if (str_starts_with($d, '98')) { $d = '0' . substr($d, 2); }
if (!preg_match('/^09\d{9}$/', $d)) { throw new SmsException('شمارهی موبایل نامعتبر است'); }
return $d;
}
/** پیامک را به وبسرویس تحویل میدهد؛ خروجی جواب رمزگشاییشدهی سرویسدهنده است */
public function send(string $phone, string $text): array
{
$payload = json_encode(
['to' => self::normalize($phone), 'from' => $this->sender, 'message' => $text],
JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
);
$ch = curl_init($this->endpoint);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json; charset=utf-8',
'Authorization: Bearer ' . $this->apiKey,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 3,
CURLOPT_TIMEOUT => $this->timeout,
]);
$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$err = curl_error($ch);
curl_close($ch);
if ($body === false) {
throw new SmsException('خطای شبکه: ' . $err); // قطع اینترنت، DNS، timeout
}
$data = json_decode($body, true);
if ($status < 200 || $status >= 300 || !is_array($data)) {
throw new SmsException("پاسخ نامعتبر از سرویسدهنده (HTTP $status)");
}
return $data;
}
}
در این کلاس شماره پیش از ارسال نرمال میشود. کاربر ایرانی ممکن است شماره را با رقم فارسی، با پیششمارهی ۹۸ یا با فاصله بنویسد؛ اگر این را همانجا یکدست نکنید، بخشی از پیامکها با «شمارهی نامعتبر» رد میشوند و علتش را دیر میفهمید.
پیامک سفارش در php؛ صدا زدن کلاینت از جای درست
کلاینت آماده است و حالا باید از جایی صدایش بزنیم. نمونهی ما پیامک «سفارش ثبت شد» است. دو اصل دارد: خطای پیامک نباید ثبت سفارش را خراب کند، و کسی که پیامک را میخواهد باید بتواند بعدها بفهمد چه شد، بیآنکه متن پیام یا شمارهی کامل در لاگ بماند.
order-sms.php؛ ارسال بعد از ثبت سفارش
<?php
declare(strict_types=1);
require __DIR__ . '/SmsClient.php';
function maskPhone(string $phone): string
{
// فقط سه رقم آخر در لاگ میماند
return str_repeat('*', max(0, strlen($phone) - 3)) . substr($phone, -3);
}
function notifyOrderPlaced(string $phone, int $orderId): bool
{
try {
$sms = SmsClient::fromEnv();
$sms->send($phone, "سفارش شماره $orderId ثبت شد. ممنون از خرید شما.");
return true;
} catch (SmsException $e) {
// متن پیام و شمارهی کامل را لاگ نکنید؛ فقط علت و شناسهی سفارش
error_log(sprintf('[sms] order=%d phone=%s error=%s', $orderId, maskPhone($phone), $e->getMessage()));
return false; // سفارش بهخاطر پیامک شکست نمیخورد
}
}
// در جایی که سفارش با موفقیت ذخیره شد:
// $ok = notifyOrderPlaced($order['phone'], $order['id']);
// اگر $ok نادرست بود، فقط یک وضعیت «پیامک ارسال نشد» روی سفارش بگذارید.
اگر ارسال پیامک سفارش در سایت شما زیاد است، ارسال همزمان در همان درخواست کاربر کند میشود. راه بهتر این است که ارسال را در یک صف یا کار زمانبندیشده انجام دهید تا صفحهی تأیید سفارش منتظر شبکه نماند. صفحهی افزونهی اعلان سفارش نمونهای از همین فکر است.
جواب سرویسدهنده را چطور بخوانیم؟
قالب دقیق جواب هر سرویسدهنده فرق میکند؛ ولی دستهبندی کلی خطاها در همه جا مشابه است. جدول زیر یک راهنمای عمومی است، نه مرجع کدهای یک شرکت مشخص.
وضعیتی که میبینید
معنی محتمل
کار درست
خطای شبکه یا timeout
اینترنت سرور، DNS یا کندی سرویسدهنده؛ معلوم نیست پیامک رفته یا نه
یک بار با فاصله دوباره امتحان کنید و برای کد تأیید، به کاربر بگویید «کد تازه بخواهد».
کد 401 یا 403
کلید اشتباه، منقضی یا بدون دسترسی
تنظیم کلید را بررسی کنید؛ تکرار خودکار فایده ندارد.
کد 400 یا پیام «شماره نامعتبر»
قالب شماره یا فیلد اشتباه است
نرمالسازی شماره و نام فیلدها را با مستندات بسنجید.
خطای اعتبار کم
شارژ پنل تمام شده
هشدار داخلی بفرستید و شارژ را زودتر پایش کنید.
کد 429
سقف تعداد درخواست رد شده
ارسال را کندتر کنید یا صف بگذارید.
کد 5xx
مشکل سمت سرویسدهنده
تلاش مجدد با فاصلهی فزاینده و ثبت خطا.
موفق با شناسهی پیام
پیام به شرکت پیامکی تحویل شد
شناسه را ذخیره کنید؛ در پیگیریهای بعدی به کارتان میآید.
نکتهی مهم این است که «موفق» در جواب سرویسدهنده معمولاً یعنی درخواست پذیرفته شده، نه اینکه پیامک به دست مخاطب رسیده است. اگر مشتری میگوید پیامک نرسیده، علتهای پشت آن در پیامک تحویل داده نمیشود جداگانه بررسی شدهاند.
مثال ساده برای سنجیدن کلاینت بدون ارسال واقعی
هر بار که کلاینت را آزمایش میکنید، پیامک واقعی و پول خرج نکنید. راه ساده این است که یک سرور محلی کوچک شبیه سرویسدهنده راه بیندازید و نشانی آن را در متغیر محیطی بگذارید. PHP خودش سرور داخلی دارد و برای این کار کافی است.
با همین سرور میتوانید حالتهای خطا را هم بسازید؛ مثلاً کلید را عمداً اشتباه بدهید تا ببینید کلاینت پیام درست پرتاب میکند، یا پاسخ را با sleep کند کنید تا timeout را امتحان کنید. این آزمونها پیش از اولین ارسال واقعی به پنل ارزانترین راه پیدا کردن اشتباهها هستند.
نمونهی یک روز پرتراکم در فروشگاه
این یک نمونهی فرضی است و دادهی واقعی مشتری نیست؛ فقط برای دیدن چند خطا کنار هم.
سناریوی نمونه
نمونه: شب یلدا در فروشگاه لوازمخانگی
فروشگاه فرضی «آرنیک» در یک شب شلوغ دهها سفارش دریافت میکند. تابع ارسال پیامک در همان درخواست ثبت سفارش صدا زده شده و timeout ندارد. وقتی وبسرویس پیامک چند دقیقه کند میشود، هر سفارش چند ده ثانیه منتظر میماند، کاربران دکمه را دوباره میزنند و چند سفارش تکراری ثبت میشود. ماجرا با سه تغییر درمان میشود: timeout هشتثانیهای در کلاینت، ارسال بعد از ذخیرهی سفارش و بیرون از مسیر پاسخ به کاربر، و ثبت وضعیت «پیامک ارسال نشد» روی سفارشهایی که خطا خوردهاند تا پشتیبانی بتواند بعداً پیگیری کند.
اشتباههای رایج در ارسال پیامک با curl و php
اکثر ایرادهای محیط تولید از همین چند اشتباه ساده میآیند. هیچکدام نیاز به دانش خاص ندارد؛ فقط باید به آنها فکر کنید.
نوشتن کلید در کد
کلید ثابت درون فایل PHP دیر یا زود با مخزن کد، پشتیبان یا اسکرینشات لو میرود. آن را در متغیر محیطی یا فایل تنظیمات خارج از ریشهی وب بگذارید.
غیرفعال کردن بررسی گواهی
گذاشتن CURLOPT_SSL_VERIFYPEER برابر false برای «رفع خطای SSL» اتصال را به حملهی واسط باز میکند. بهجای آن، گواهیهای سرور را درست کنید.
نبودن timeout
cURL بهطور پیشفرض بسیار صبور است. بدون timeout یک سرویس کند، کل سایت را کند میکند.
لاگ کردن متن پیام
کد تأیید یا اطلاعات سفارش در فایل لاگ میماند. فقط شناسه و علت خطا کافی است.
باز گذاشتن دکمهی ارسال برای همه
هر فرمی که پیامک میفرستد باید سقف تعداد داشته باشد، وگرنه ربات پنل شما را خالی میکند. جلوگیری از sms bombing این خطر را توضیح داده است.
باور به «موفق» بهعنوان رسیدن
پذیرفته شدن درخواست با رسیدن پیامک یکی نیست. برای پیامهای حساس راه جایگزین بگذارید.
نادیده گرفتن کدگذاری
متن فارسی را با JSON_UNESCAPED_UNICODE و UTF-8 بفرستید و اگر سرویسدهنده قالب دیگری خواسته، همان را رعایت کنید.
کی باید از ارسال پیامک خودتان صرفنظر کنید؟
هر پیامک هزینه دارد و هر وبسرویس نگهداری میخواهد. پیش از وصل کردن همهی رویدادها به پیامک، بسنجید کدام واقعاً به آن نیاز دارند.
ارسال پیامک با php مناسب است وقتی
مخاطب شما اپ یا حساب فعال ندارد و فقط شمارهاش را دارید.
پیام باید حتماً روی شمارهی تلفن برسد، مثل یادآوری قرار ملاقات یا هشدار حساس.
حجم و محتوای پیام را میشناسید و خط و مجوز لازم را دارید.
کمخرجتر است راه دیگری بروید وقتی
فقط میخواهید کاربری که از قبل عضو سایت است را از پیشرفت سفارش باخبر کنید.
مخاطبانتان اپ را نصب کردهاند و میتوانند اعلان بگیرند.
هدف فقط ورود کاربر است و کد پیامکی هزینهی تکراری دارد.
فینگت یک وبسرویس پیامک نیست و خط یا پنل پیامکی نمیفروشد؛ برنامهی تماس رایگان است و برای سایتها ورود بدون رمز با تأیید روی گوشی دارد. اگر بخشی از پیامکهای شما فقط برای ورود است، ورود بدون رمز عبور میتواند آن بخش را بینیاز از پیامک کند. بقیهی پیامکها همانطور که هستند باقی میمانند.
فهرست بررسی پیش از انتشار
پیش از اتصال کد به یک پنل واقعی این فهرست را یک بار مرور کنید. هر مورد با چند دقیقه کار انجام میشود و جلوی شکایتهای پرهزینهی بعدی را میگیرد.
کلید و نشانی در تنظیمات هیچکدام درون کد یا مخزن نیست و کلید جدا برای محیط آزمایش و تولید دارید.
timeout و خطا تست کردهاید قطع اینترنت و کندی سرویسدهنده، سایت را از کار نمیاندازد.
نرمالسازی شماره رقم فارسی، پیششمارهی ۹۸ و فاصله درست پردازش میشود.
لاگ امن در لاگ فقط شناسه، شمارهی ماسکشده و علت خطا هست.
سقف ارسال برای هر شماره و هر IP سقف دارید و فرم ارسال بدون بررسی باز نیست.
پایش اعتبار اگر اعتبار پنل از حدی کمتر شد، کسی خبردار میشود. دیدن هزینهی پنل پیامک به تعیین این حد کمک میکند.
برنامهی جایگزین برای وقتی پیامک نمیرسد، راه دیگری مثل پشتیبانی یا ورود با روش دیگر هست.
واژههای این صفحه
اگر با اصطلاحهای زیر آشنا نیستید، همین چند خط برای دنبال کردن بقیهی صفحه کافی است.
cURL
افزونه و ابزاری که درخواست HTTP میفرستد؛ در PHP با توابع curl_init و curl_exec استفاده میشود.
timeout
حداکثر زمانی که برنامه حاضر است برای جواب صبر کند. بدون آن، یک سرویس کند میتواند سایت را معطل کند.
متغیر محیطی
مقداری که خارج از کد، در تنظیمات سرور یا فایل مخفی نگهداری میشود؛ جای مناسب کلید دسترسی.
نرمالسازی شماره
تبدیل همهی شکلهای نوشتن شماره به یک قالب ثابت، مثلاً 09xxxxxxxxx.
استثنا
سازوکار PHP برای گزارش خطا که اجازه میدهد خطا را در یک نقطه بگیرید و جلوی خرابی کل برنامه را بگیرید.
پرسشهای متداول درباره ارسال پیامک با php
ارسال پیامک با php به چه چیزهایی نیاز دارد؟
به PHP با افزونهی curl، یک وبسرویس پیامک از یک شرکت پیامکی، کلید دسترسی، خطی که مجوز ارسال دارد و اعتبار در پنل. قالب دقیق درخواست را مستندات همان شرکت تعیین میکند.
آیا میتوانم بدون cURL پیامک بفرستم؟
بله، با file_get_contents و context یا کتابخانهی Guzzle. ولی cURL تقریباً در همهی میزبانها فعال است و کنترل بهتری روی timeout و خطا میدهد.
کلید دسترسی را کجا نگه دارم؟
در متغیر محیطی یا فایل تنظیمات خارج از ریشهی وب. هرگز آن را درون فایل PHP یا مخزن کد نگذارید و برای آزمایش و تولید دو کلید جدا داشته باشید.
چرا درخواست موفق است ولی پیامک نمیرسد؟
موفق بودن معمولاً یعنی شرکت پیامکی درخواست را پذیرفته است. رسیدن به گوشی به خط، محتوا، فیلتر و اپراتور هم بستگی دارد و باید جداگانه بررسی شود.
چطور بدون خرج پیامک واقعی آزمایش کنم؟
یک سرور آزمایشی ساده با php -S بسازید که شبیه وبسرویس جواب بدهد و نشانی آن را در تنظیمات بگذارید. همینطور حالتهای خطا را هم میتوانید شبیهسازی کنید.
برای کد تأیید ورود هم از همین کلاینت استفاده کنم؟
میتوانید، ولی منطق کد، انقضا و سقف تلاش را جدا بنویسید. ورود با موبایل php همین بخش را کامل نشان میدهد و از این کلاینت بهجای sendSms استفاده میکند.
فینگت برای ارسال پیامک چه نقشی دارد؟
فینگت پنل یا خط پیامکی ندارد و پیامک نمیفرستد. برای سایتها ورود بدون رمز با تأیید روی گوشی کاربر دارد که میتواند بخشی از پیامکهای ورود را کم کند.