Laravel Atlasm SMS (پنل پیامک اطلس ام)

پکیج لاراول برای ارسال پیامک، دریافت اعتبار پنل و پیگیری وضعیت تحویل از طریق وب‌سرویس SOAP پنل پیامکی اطلس ام.

امکانات

• ارسال پیامک با متن مشترک به یک یا چند گیرنده (send)
• ارسال پیامک‌های متفاوت به گیرندگان مختلف (sendMulti)
• دریافت اعتبار پنل (getCredit)
• دریافت وضعیت تحویل پیامک‌ها (getStatus)
• Auto-Discovery، Facade و فایل کانفیگ قابل انتشار
• پیام خطای فارسی برای کدهای خطای سرویس

نیازمندی‌ها

• PHP 8.1 یا بالاتر
• افزونه‌ی PHP به نام soap (ext-soap)
• لاراول 10، 11، 12 یا 13

نصب

composer require saeedmohsenii/laravel-atlasm-sms

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

برای انتشار فایل کانفیگ (اختیاری):

php artisan vendor:publish --tag=atlasm-sms-config

تنظیمات

مقادیر زیر را در فایل .env قرار دهید:

ATLASM_SMS_WSDL=https://panel.atlasm.ir/webservice/send.php?wsdl
TLASM_SMS_USERNAME=your-username
ATLASM_SMS_PASSWORD=your-password
ATLASM_SMS_SENDER=3000xxxx

# اختیاری
ATLASM_SMS_PASSWORD_MD5=false
ATLASM_SMS_TIMEOUT=20
ATLASM_SMS_VERIFY_SSL=true

استفاده

با Facade

use Atlasm\Sms\Facades\AtlasmSms;

// یک گیرنده
$result = AtlasmSms::send('09120000000', 'سلام، این یک پیامک آزمایشی است.');

// چند گیرنده با متن مشترک (حداکثر ۱۵۰ نفر)
$result = AtlasmSms::send(['09120000000', '09130000000'], 'متن پیامک');

// پیامک فلش (type = 1) و شماره فرستنده‌ی دلخواه
$result = AtlasmSms::send('09120000000', 'متن پیامک', 1, '3000xxxx');

if ($result['success']) {
    // ...
}

ارسال پیامک‌های متفاوت (SendMultiSMS)

هر چهار آرایه باید هم‌اندازه باشند (حداکثر ۶۰ مورد):

AtlasmSms::sendMulti(
    ['3000xxxx', '3000xxxx'],            // فرستنده‌ها
    ['09120000000', '09130000000'],      // گیرنده‌ها
    ['متن اول', 'متن دوم'],              // متن‌ها
    [0, 0],                              // نوع‌ها: 0 معمولی، 1 فلش
);

اعتبار و وضعیت

$credit = AtlasmSms::getCredit();
// ['success' => true, 'credit' => 1500.0, ...]

$status = AtlasmSms::getStatus(['شناسه۱', 'شناسه۲']); // حداکثر ۵۰ شناسه

با تزریق وابستگی

use Atlasm\Sms\SmsService;

class OtpController
{
    public function send(SmsService $sms)
    {
        $result = $sms->send('09120000000', 'کد تایید شما: 12345');

        return response()->json($result, $result['success'] ? 200 : 422);
    }
}

ساختار پاسخ

همه‌ی متدها یک آرایه برمی‌گردانند.

موفق:

[
    'success' => true,
    'method'  => 'SendSMS',
    'message' => 'پاسخ از سرویس دریافت شد.',
    'data'    => [...],   // پاسخ خام سرویس
]

خطای سرویس (کد خطای مستندات):

[
    'success'    => false,
    'method'     => 'SendSMS',
    'error_code' => '1',
    'message'    => 'اعتبار پنل برای ارسال کافی نیست.',
    'data'       => [...],
]

خطای ارتباط:

جزئیات خطاهای ارتباطی در لاگ لاراول ثبت می‌شود (نام کاربری و رمز عبور هرگز لاگ نمی‌شوند).

استثناها (Exceptions)

خطاهای ارتباطی و خطاهای سرویس به‌صورت آرایه برمی‌گردند، اما خطاهای برنامه‌نویسی Exception پرتاب می‌کنند:

• InvalidArgumentException: ورودی نامعتبر (متن خالی، گیرنده‌ی خالی، بیش از حد مجاز، نوع پیامک نامعتبر، ...)
• Atlasm\Sms\Exceptions\ConfigurationException (زیرکلاس InvalidArgumentException): تنظیمات ناقص (WSDL، نام کاربری، رمز عبور یا شماره‌ی فرستنده)

کدهای خطا

ارسال (send / sendMulti)

اعتبار (getCredit): ۰ (نام کاربری/رمز اشتباه)، ۵ (پنل غیرفعال)، ۶ (پنل منقضی)

وضعیت (getStatus): ۱۴ (شناسه نامعتبر)، ۱۵ (نام کاربری/رمز اشتباه)، ۱۶ (تعداد شناسه‌ها بیش از حد مجاز)، ۱۷ (پنل غیرفعال)، ۱۸ (پنل منقضی)

نکته‌ی مهم درباره‌ی getCredit

اگر سرویس مقدار اعتبار و کد خطا را هر دو به‌صورت یک عدد ساده برگرداند (مثلاً 0 یا 5)، تشخیص «اعتبار صفر» از «خطای ۰» ممکن نیست؛ در این حالت عدد به‌عنوان اعتبار تفسیر می‌شود. خطاها فقط وقتی شناسایی می‌شوند که پاسخ در ساختار Return یا آرایه برگردد.

تست

composer install
composer test

مجوز

این پکیج تحت مجوز MIT منتشر شده است.