README

پکیج رسمی و کامل وب سرویس فراپیامک (ملی پیامک) برای لاراول

نویسنده: امیر رجب زاده
ایمیل: amir.irdev@gmail.com
وبسایت: https://amirrajabzadeh.ir
گیت‌هاب: amirrajabzadeh/farapayamak-laravel

✨ ویژگی‌ها

• ✅ پشتیبانی از تمام 8 وب سرویس فراپیامک
• ✅ متد SendOtp برای ارسال کد تأیید یکبارمصرف
• ✅ اضافه شدن خودکار "لغو11" به انتهای پیام (الزامی برای وب سرویس)
• ✅ ارسال پیامک ساده، پیشرفته، چندتایی و زماندار
• ✅ مدیریت کامل دفترچه تلفن و گروه‌ها
• ✅ دریافت پیامک‌های رسیده از صندوق ورودی
• ✅ دریافت اعتبار و وضعیت تحویل پیامک
• ✅ خروجی آرایه استاندارد با ساختار یکسان برای همه متدها
• ✅ بدون نیاز به دیتابیس
• ✅ کامنت‌گذاری کامل به فارسی
• ✅ پشتیبانی از لاراول 8 تا 12
• ✅ پشتیبانی از PHP 7.4 تا 8.4

📋 نیازمندی‌ها

• PHP نسخه 7.4 یا بالاتر (تا 8.4)
• لاراول نسخه 8.x، 9.x، 10.x، 11.x یا 12.x
• افزونه‌های PHP:
  • ext-soap (برای ارتباط با وب سرویس SOAP)
  • ext-json (برای پردازش JSON)

نکته: برای فعال کردن افزونه SOAP در فایل php.ini، خط extension=soap را از حالت کامنت خارج کنید.

📦 نصب

composer require amirrajabzadeh/farapayamak-laravel

⚙️ تنظیمات

1. افزودن متغیرهای محیطی در فایل .env

FARAPAYAMAK_USERNAME=نام_کاربری_شما
FARAPAYAMAK_PASSWORD=رمز_عبور_شما
FARAPAYAMAK_DEBUG=false

2. انتشار فایل کانفیگ (اختیاری)

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

فایل کانفیگ در config/farapayamak.php قرار می‌گیرد.

🚀 راهنمای استفاده

ساختار خروجی استاندارد

تمامی متدهای این پکیج یک آرایه استاندارد با ساختار زیر برمی‌گردانند:

[
    'success' => true,      // boolean: موفقیت یا خطا
    'message' => '...',     // string: پیام توضیحی فارسی
    'data' => mixed,        // mixed: داده اصلی (RecId, Credit, ...)
    'code' => null,         // int|null: کد خطا (در صورت موفقیت null)
    'raw' => mixed          // mixed: پاسخ خام وب سرویس (برای دیباگ)
]

1. ارسال پیامک ساده

<?php

namespace App\Http\Controllers;

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamak;

class SmsController extends Controller
{
    public function sendSms()
    {
        $result = FaraPayamak::sendSimpleSms(
            '09130908908',    // شماره گیرنده
            '5000xxxx',       // شماره فرستنده (ثبت شده در پنل)
            'سلام! این یک پیام آزمایشی است.'  // متن پیام (لغو11 خودکار اضافه می‌شود)
        );

        if ($result['success']) {
            return "✅ " . $result['message'] . " - RecId: " . $result['data'];
        }
        
        return "❌ خطا: " . $result['message'] . " (کد: " . $result['code'] . ")";
    }
}

2. ارسال OTP (کد تأیید)

<?php

namespace App\Http\Controllers;

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamak;
use Illuminate\Http\Request;

class OtpController extends Controller
{
    public function sendOtp(Request $request)
    {
        $request->validate([
            'mobile' => 'required|string|size:11',
            'code' => 'required|integer|digits:4|digits:6'
        ]);

        $result = FaraPayamak::sendOtp(
            $request->mobile,          // شماره گیرنده
            '',                        // شماره فرستنده (اختیاری)
            (int)$request->code        // کد عددی 4 یا 6 رقمی
        );

        if ($result['success']) {
            return response()->json([
                'success' => true,
                'message' => $result['message']
            ]);
        }

        return response()->json([
            'success' => false,
            'error' => $result['message']
        ], 500);
    }
}

3. دریافت اعتبار

$result = FaraPayamak::getCredit();

if ($result['success']) {
    echo $result['message'];  // "اعتبار شما 10,270 ریال است"
    echo "مبلغ: " . $result['data'];  // 10270.95
}

4. دریافت وضعیت تحویل پیامک

$result = FaraPayamak::getDeliveryStatus($recId);

if ($result['success']) {
    echo "وضعیت: " . $result['message'];  // "رسیده به گوشی"
    echo "کد: " . $result['data'];  // 1
}

5. دریافت پیامک‌های رسیده

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamakReceive;

// دریافت 50 پیامک آخر
$result = FaraPayamakReceive::getInboxMessages(1, 50);

if ($result['success']) {
    $messages = $result['data'];
    foreach ($messages as $message) {
        echo $message['text'];
    }
}

6. مدیریت دفترچه تلفن

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamakContacts;

// دریافت لیست گروه‌ها
$result = FaraPayamakContacts::getGroups();

if ($result['success']) {
    $groups = $result['data'];
}

// اضافه کردن گروه جدید
$result = FaraPayamakContacts::addGroup('مشتریان ویژه', 'گروه تست');

7. ارسال زماندار

use Amirrajabzadeh\FarapayamakLaravel\Facades\FaraPayamakSchedule;

$result = FaraPayamakSchedule::addSchedule(
    '09130908908',                    // شماره گیرنده
    '5000xxxx',                       // شماره فرستنده
    'پیامک زماندار',                   // متن
    false,                            // فلش
    '2024-12-25 14:30:00',           // تاریخ و زمان ارسال
    0                                 // دوره تکرار (0=بدون تکرار)
);

if ($result['success']) {
    echo "زمانبندی با موفقیت انجام شد. شناسه: " . $result['data'];
}

🔧 تزریق مستقیم (بدون Facade)

<?php

namespace App\Http\Controllers;

use Amirrajabzadeh\FarapayamakLaravel\Services\SendService;

class SmsController extends Controller
{
    protected $sendService;

    public function __construct(SendService $sendService)
    {
        $this->sendService = $sendService;
    }

    public function send()
    {
        $result = $this->sendService->sendSimpleSms(
            '09130908908',
            '5000xxxx',
            'متن پیامک'
        );
        
        return $result;
    }
}

📚 سایر سرویس‌ها

پکیج شامل 8 سرویس مجزا است:

⚠️ کدهای خطا

🔧 عیب‌یابی

خطا: Class 'SoapClient' not found

راه حل: افزونه SOAP را در PHP فعال کنید:

; در فایل php.ini
extension=soap

خطا: شماره فرستنده معتبر نیست (کد 5)

راه حل: شماره فرستنده باید یکی از شماره‌های ثبت شده در پنل فراپیامک باشد.

خطا: متن حاوی کلمات فیلتر شده (کد 7)

راه حل: متن پیامک خود را بررسی کنید. همچنین به صورت خودکار "لغو11" به انتهای پیام اضافه می‌شود.

📞 پشتیبانی

• ایمیل: amir.irdev@gmail.com
• وبسایت: https://amirrajabzadeh.ir
• گیت‌هاب: https://github.com/amirrajabzadeh/farapayamak-laravel
• گزارش باگ: Issues

📄 لایسنس

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

ساخته شده با ❤️ توسط امیر رجب زاده