🎯 درباره پکیج

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

📦 پیش‌نیازها

برای استفاده از این پکیج، ابتدا مطمئن شوید که محیط شما شرایط زیر را دارد:

• نسخه هشت یا بالاتر از پی‌اچ‌پی روی سرور نصب باشد.

• از لاراول نسخه نُه، ده یا یازده استفاده می‌کنید.

• افزونه سی‌یوآر‌ال روی سرور فعال باشد که معمولاً به‌صورت پیش‌فرض فعال است.

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

⚙️ مراحل نصب و راه‌اندازی

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

bash

composer require pishropayamak/sms

bash

php artisan vendor:publish --tag=pishropayamak-config

گام سوم: تنظیم متغیرهای محیطی
فایل env را در ریشه پروژه خود باز کنید و سه متغیر زیر را به آن اضافه نمایید:

PISHROPAYAMAK_TOKEN=your_token_here
PISHROPAYAMAK_FROM=9444xxxxxx
PISHROPAYAMAK_TYPE=0

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

متغیر دوم برای شماره خط اختصاصی شماست که در صورت تنظیم، به‌عنوان فرستنده پیش‌فرض استفاده می‌شود.

متغیر سوم برای تعیین نوع پیام است که مقدار صفر به معنای پیامک معمولی و مقدار یک به معنای پیامک فلش می‌باشد.

توجه داشته باشید که اگر شماره فرستنده را در فایل env تنظیم نکنید، باید در هر بار ارسال پیامک، شماره را به متد ارسال پاس دهید.

🚀 نحوه استفاده از پکیج

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

use PishroPayamak\Sms\Facades\PishroPayamak;
$response = PishroPayamak::sendSms('9444xxxxxx',['09121234567', '09129876543'],متن پیام شما',0');

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

متد ارسال پیامک چهار پارامتر ورودی دارد که به شرح زیر هستند:

• پارامتر اول، شماره خط اختصاصی شما به‌عنوان فرستنده است که مقدار آن ضروری می‌باشد.

• پارامتر دوم، لیستی از شماره موبایل گیرندگان است که باید به‌صورت یک آرایه ارسال شود و مقدار آن ضروری می‌باشد.

• پارامتر سوم، متن پیامک است که حداکثر طول آن هزار کاراکتر بوده و مقدار آن ضروری می‌باشد.

• پارامتر چهارم، نوع پیام است که مقدار صفر برای معمولی و مقدار یک برای فلش می‌باشد و در صورت عدم تعیین، به‌صورت پیش‌فرض روی صفر تنظیم می‌شود.

📤 خروجی متد ارسال پیامک

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

در صورت موفقیت، آرایه شامل دو کلید موفقیت با مقدار درست و آی‌دی با مقدار عددی کد پیگیری خواهد بود.

💡 مثال‌های عملی ا کاربرد پکیج

برای آشنایی بیشتر با کاربرد این پکیج، چند مثال عملی را مرور می‌کنیم.

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

ارسال گروهی: با قرار دادن چندین شماره در لیست گیرندگان، به‌راحتی پیام خود را به تمام آنها به‌صورت یکجا ارسال می‌نمایید.

ارسال پیام فلش: با تنظیم نوع پیام بر روی عدد یک، پیامک شما به‌صورت فلش (نمایشی) برای گیرنده ارسال می‌شود.

استفاده از شماره فرستنده پیش‌فرض: در صورتی که شماره فرستنده را در فایل env تنظیم کرده باشید، می‌توانید از همان شماره به‌عنوان فرستنده پیش‌فرض استفاده کنید و نیازی به وارد کردن مجدد آن نداشته باشید.

🔒 نکات امنیتی مهم

برای حفظ امنیت پروژه خود، حتماً به نکات زیر توجه کنید:

• هرگز توکن را به‌صورت مستقیم در کدهای برنامه قرار ندهید و همیشه از فایل env برای ذخیره آن استفاده کنید.

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

• توکن‌ها ممکن است دارای تاریخ انقضا باشند، بنابراین به‌طور دوره‌ای آنها را بررسی و در صورت نیاز تمدید کنید.

• در صورت پایان کار یا تغییر پروژه، توکن را از پنل کاربری باطل کنید تا از سوءاستفاده احتمالی جلوگیری شود.

🧪 عیب‌یابی مشکلات رایج

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

مشکل دوم: خطای گواهی اس‌اس‌ال
در محیط توسعه، ممکن است با خطای گواهی اس‌اس‌ال مواجه شوید که در این صورت می‌توانید برای تست، تأیید گواهی را به‌صورت موقت غیرفعال کنید.

مشکل سوم: پیامک ارسال نمی‌شود اما خطایی نمایش داده نمی‌شود
در این حالت، ابتدا صحت توکن را بررسی کنید. سپس مطمئن شوید که حساب کاربری شما اعتبار کافی برای ارسال پیامک دارد. در نهایت، شماره فرستنده باید در پنل کاربری شما ثبت شده باشد.

📚 منابع و مستندات بیشتر

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

• وب‌سایت رسمی پیشرو پیامک

• ایمیل پشتیبانی

• مخزن گیت‌هاب پکیج

📄 مجوز و مشارکت

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

📚 مستندات بیشتر

- وب‌سایت رسمی: https://pishropayamak.ir
- پشتیبانی: mr.rezarahpeyma@gmail.com
- مخزن گیت‌هاب: https://github.com/MohammadrezaRahpeyma/pishropayamak-sms

📄 مجوز

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

🙏 مشارکت

اگر مشکلی پیدا کردید یا پیشنهادی برای بهبود دارید، خوشحال می‌شویم که در گیت‌هاب ایجاد Issue کنید یا Pull Request ارسال کنید.

ساخته شده توسط پیشرو پیامک