mrgear/laravel-smsir

sms.ir version 2 laravel package

1.0.0 2023-09-30 10:09 UTC

Requires (Dev)

• orchestra/testbench: ^7.0

MIT

• mahdi rashidi

• sms
• notification
• laravel
• laravel sms
• sms.ir
• MRW

README

پکیج ارسال اس ام اس sms.ir v2 برای لاراول

این پکیج برای ارسال اس ام اس از طریق API پنل sms.ir ورژن ۲ در طراحی شده است.

لیست محتوا

• نصب
• فایل کانفیگ و env.
• طریقه استفاده
  • متودها
  • چند مثال
    • ارسال تکی
    • ارسال گروهی
    • ارسال نظیر به نظیر
    • ارسال وریفای (سریع)
• نوتیفیکیشن
• Facade and Helper function

نصب

composer require mrgear/laravel-smsir

smsir.php , .env

برای تنظیم کلیدهای شماره خط، لینک پایه (base_url)، شناسه قالب پیش فرض در فایل env. از کلیدهای زیر استفاده کنید

SMSIR_BASE_URL=https://api.sms.ir/v1/send/
SMSIR_API_KEY=Your api key
SMSIR_LINE_NUMBER=Your pannel line number
SMSIR_TEMPLATE_ID=Default template id

فایل کانفیگ smsir.php شامل اطلاعات کلید api، شماره خط، لینک پایه (base_url)، شناسه قالب پیش فرض میباشد که از فایل env. دریافت میکند.

برای تغییر فایل کانفیگ از دستور زیر استفاده کنید تا فایل Config/smsir.php درون دایرکتوری تنظیمات لاراول قرار بگیرد.

php artisan vendor:publish --provider=MRGear\SMSIR\Providers\SMSIRServiceProvider --tag=config

طریقه استفاده

با استفاده از کلاس SMSIR میتوانیم پروسه ارسال اس ام اس را انجام دهیم.

متودها

$smsir_instance = new \MRGear\SMSIR\SMSIR();

//تعیین شماره تلفن همراه بصورت تکی (برای استفاده در اسلا تکی و وریفای)
$smsir_instance->phoneNumber('09xx');

//تعیین شماره تلفن همراه بصورت گروهی (برای استفاده در ارسال نظیر به نظیر و گروهی)
$smsir_instance->phoneNumbers(['09xx' , '09xx']);

//تعیین پیام مورد نظر برای ارسال (برای در ارسال گروهی و تکی)
$smsir_instance->message(['09xx1' , '09xx2' , '09xx3']);

//تعیین پیام بصورت گروهی (برای استفاده در ارسال نظیر به نظیر)
$smsir_instance->messages(['message 1' , 'message 2' , 'message 3']);

//تعیین شناسه قالب بصورت دستی (برای استفاده در ارسال وریفای) 
$smsir_instance->templateId('123xx');
//تعیین پارامترهای ارسال وریفای بصورت دستی (برای استفاده در ارسال وریفای) 
$smsir_instance->parameters(['name' => 'VERIFICATION_CODE' , 'value' => '12345']);
// یا
$smsir_instance->parameters(['parameter_mame' , 'parameter_value']);
// یا
$smsir_instance->parameters([ 'parameter_value' , 'parameter_mame']);

// آماده سازی برای ارسال تکی
$smsir_instance->single();

// آماده سازی برای ارسال گروهی
$smsir_instance->multiple();

// آماده سازی برای ارسال نظیر به نظیر
$smsir_instance->p2p();

// آماده سازی برای ارسال وریفای
$smsir_instance->fast();

//ارسال
$smsir_instance->send();

چند مثال

برای ارسال اس ام اس باید پارامترهای مورد نیاز و متود مورد نظر تعیین شود.

در پنل sms.ir سه روش ارسال گروهی، وریفای و نظیر به نظیر تعریف شده است که در زیر مثالی از هرکدام را بررسی میکنیم.

روش ارسال تکی:

$smsir_instance = new \MRGear\SMSIR\SMSIR();
$smsir_instance->message('پیام مورد نظر')->phoneNumber('09xx')->single()->send();
//یا
$smsir_instance->phoneNumber('09xx');
$smsir_instance->message('پیام مورد نظر');
$smsir_instance->single()->send();

روش ارسال گروهی:

$smsir_instance = new \MRGear\SMSIR\SMSIR();
$smsir_instance->message('پیام مورد نظر')->phoneNumbers(['0912xxx' , '0935xxx'])->multiple()->send();
//یا
$smsir_instance->phoneNumbers(['0912xxx' , '0935xxx']);
$smsir_instance->message('پیام مورد نظر');
$smsir_instance->multiple()->send();

روش ارسال نظیر به نظیر:

$smsir_instance = new \MRGear\SMSIR\SMSIR();
$smsir_instance->phoneNumbers(['0912xxx' , '0935xxx'])->message(['message 1' , 'message 2'])->p2p()->send();
//یا
$smsir_instance->message(['message 1' , 'message 2']);
$smsir_instance->phoneNumbers(['0912xxx' , '0935xxx']);
$smsir_instance->p2p()->send();

روش ارسال وریفای:

$smsir_instance = new \MRGear\SMSIR\SMSIR();
$smsir_instance->parameters(['12454' , 'VERIFICATION_CODE'])->fast()->send();
//تعیین قالب بصورت دستی

$smsir_instance->templateId('123xx')->parameters(['VERIFICATION_CODE' , '12345'])->fast()->send();

نوتیفیکیشن

کلاس SMSIRNotification از سیستم نوتیفیکیشن لاراول بهره میبرد.

برای استفاده از سیستم نوتیفیکیشن در کلاسی که از تریت Notifiable استفاده میکند، نام فیلد شماره تلفن را باید از طریق متغیر smsir_phone_number$ ست کرد.

برای مثال اگر مدل User را که فیلد شماره تلفن همراه با نام phone_numberذخیره شده است را در نظر بگیریم، متغیر به شکل زیر خواهد بود

namespace App\Models;

use Illuminate\Notifications\Notifiable;

class User  
{
    use Notifiable;
    
    public $smsir_phone_number = 'phone_number';
}

کلاس نوتیفیکیشن تنها برای استفاده از دو حالت ارسال تکی و ارسال سریع (متود وریفای) استفاده میشود.

اگر ورودی کلاس بصورت رشته باشد، سیستم نوتیفیکیشن ارسال را تکی در نظر میگیرد و ورودی به عنوان پیام ارسال خواهد شد

برای ارسال وریفای میتوان پارامترهای ارسال وریفای را بصورت ارایه به ورودی کلاس داد.

نکته: جهت انتخاب دستی شناسه قالب میتوانید با کلید 'template_id' در آرایه‌ی ورودی، شناسه را تغییر دهید.

مثال

//ارسال تکی
$notification = new \MRGear\SMSIR\Notifications\SMSIRNotification('پیام مورد نظر');

//ارسال سریع ( وریفای )
$notification = new \MRGear\SMSIR\Notifications\SMSIRNotification(['VERIFICATION_CODE' , '12345']);

//ارسال سریع (وریفای) با تعیین شناسه قالب
$notification = new \MRGear\SMSIR\Notifications\SMSIRNotification(['VERIFICATION_CODE' , '12345' , 'template_id' => '12xx']);

$user = \App\Models\User::first();
$user->notify($notification);

Facade , Helper Function

برای دسترسی استاتیک و استفاده از قابلیت Facade لاراول میتوانید از کلاس MRGear\SMSIR\Facade\SMSIR\ استفاده کنید

متود کمکی smsir برای دسترسی به شکل زیر ایجاد شده است

smsir($message , $phone_number, $data = null , $template_id = null);

برای ارسال تکی

کافیست که متغیر اول و دوم را بصورت رشته ارسال کنیم

smsir('message text' , '09xx');

برای ارسال گروهی

در این حالت متغیر message$ را بصورت رشته و متغیر phone_number$ را بصورت آرایه‌ای از شماره‌ها ارسال می‌کنیم

smsir(smsir('message text' , ['09xx' , '09xx' , '09xx']);

برای ارسال نظیر به نظیر

در این حالت متغیر message$ را بصورت ارایه‌ی پیام‌ها و متغیر phone_number$ را بصورت آرایه‌ای از شماره‌ها ارسال می‌کنیم

smsir(['message text1' , 'message text2' , 'message text3' ] , ['09xx' , '09xx' , '09xx' ]);

برای ارسال وریفای (سریع)

در این حالت کافیست که بجای متغیر اول verify ( با حروف بزرگ یا کوچک)، یا v (کوچک یا بزرگ) ، fast (با حروف بزرگ یا کوچک) یا true جایگزاری کنیم.

در این حالت پارامتر‌های مورد نظر بجای متغیر سوم و درصورت نیاز شناسه قالب را بصورت دستی با متغیر چهارم ارسال میکنیم

smsir(true , '09x', ['VERIFICATION_CODE' , '123456']);
smsir('V' , '09x', ['VERIFICATION_CODE' , '123456'] , '12xx');
smsir('Verify' , '09x', ['123456' , 'VERIFICATION_CODE'] );
smsir('fast' , '09x', ['12456' , 'VERIFICATION_CODE'] , '12xxx');