bitarun/laravel-notification-service

Notification service for Laravel applications with support for Email and SMS, including queue support.

v1.0.4 2026-07-20 06:51 UTC

Requires

• php: ^8.1
• illuminate/support: ^11.0|^12.0|^13.0

MIT

• bitabadrkhani

• queue
• email
• sms
• notification
• laravel

Published on Packagist.org on 2026-07-20 06:52 UTC

README

یک پکیج ساده، تمیز و انعطاف‌پذیر برای ارسال نوتیفیکیشن (ایمیل و پیامک) در پروژه‌های Laravel

✨ ویژگی‌ها

• 📧 ارسال ایمیل با استفاده از سیستم Mailable خود لاراول
• 📱 ارسال پیامک از طریق وب‌سرویس SMS
• 🚀 پشتیبانی کامل از صف (Queue) — به‌صورت اختیاری و قابل تنظیم
• 🎯 پشتیبانی از ورودی ساده (رشته) یا DTO کامل برای گیرنده
• 🛡️ مدیریت خطای یکپارچه با Exception اختصاصی
• ⚡ رابط کاربری ساده از طریق Facade

📥 نصب

از طریق Composer نصب کنید:

composer require bitarun/laravel-notification-service

پکیج به‌صورت خودکار (Auto-Discovery) توسط لاراول شناسایی می‌شود و نیازی به ثبت دستی Service Provider نیست.

انتشار فایل تنظیمات

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

این دستور فایل config/notification.php را در پروژهٔ شما ایجاد می‌کند.

⚙️ تنظیمات

پس از انتشار فایل کانفیگ، مقادیر زیر را در فایل .env پروژه‌تان تنظیم کنید:

# صف
NOTIFICATION_QUEUE_ENABLED=false
NOTIFICATION_QUEUE_CONNECTION=database
NOTIFICATION_QUEUE_NAME=default

# پیامک
SMS_API_KEY=your-api-key
SMS_URL=https://api.sms.ir/v1/send/verify
SMS_TEMPLATE_ID=your-template-id

کلید	توضیح	پیش‌فرض
NOTIFICATION_QUEUE_ENABLED	آیا نوتیفیکیشن‌ها به‌صورت پیش‌فرض وارد صف شوند؟	false
NOTIFICATION_QUEUE_CONNECTION	کانکشن صف مورد استفاده	کانکشن پیش‌فرض لاراول
NOTIFICATION_QUEUE_NAME	نام صف مورد استفاده	default
SMS_API_KEY	کلید API سرویس پیامکی	—
SMS_URL	آدرس endpoint سرویس پیامکی	https://api.sms.ir/v1/send/verify
SMS_TEMPLATE_ID	شناسهٔ قالب پیامک	—

🚀 شروع سریع

📧 ارسال ایمیل

use Bitarun\LaravelNotificationService\Facades\Notification;

Notification::sendEmail($user->email, new \App\Mail\WelcomeMail);

📱 ارسال پیامک

use Bitarun\LaravelNotificationService\Facades\Notification;

Notification::sendSms($user->phone_number, 'کد تایید شما: ۱۲۳۴۵');

همین! به همین سادگی 🎉

🎯 استفاده از DTO گیرنده (اختیاری)

اگر نیاز به اطلاعات بیشتری از گیرنده دارید (مثلاً نام، برای استفاده در قالب ایمیل)، می‌توانید از NotificationRecipient استفاده کنید:

use Bitarun\LaravelNotificationService\DTOs\NotificationRecipient;
use Bitarun\LaravelNotificationService\Facades\Notification;

$recipient = new NotificationRecipient(
    email: $user->email,
    name: $user->name
);

Notification::sendEmail($recipient, new \App\Mail\WelcomeMail);

💡 هر دو روش (رشتهٔ ساده یا DTO کامل) به‌طور یکسان پشتیبانی می‌شوند و می‌توانید بر اساس نیاز خود انتخاب کنید.

🚦 مدیریت صف (Queue)

به‌صورت پیش‌فرض، رفتار صف بر اساس مقدار NOTIFICATION_QUEUE_ENABLED در فایل .env تعیین می‌شود. اما می‌توانید این رفتار را به‌صورت مستقیم و per-call نیز override کنید:

اجبار به ارسال از طریق صف

Notification::queue()->sendEmail($user->email, new \App\Mail\WelcomeMail);

اجبار به ارسال فوری (بدون صف)

Notification::now()->sendSms($user->phone_number, 'این پیام فوری ارسال می‌شود');

رفتار پیش‌فرض (طبق تنظیمات .env)

Notification::sendEmail($user->email, new \App\Mail\WelcomeMail);

🛡️ مدیریت خطا

در صورت بروز خطا در ارسال (مثلاً fail شدن درخواست به سرویس پیامکی)، یک Exception اختصاصی پرتاب می‌شود که می‌توانید آن را مدیریت کنید:

use Bitarun\LaravelNotificationService\Exceptions\SmsSendingFailedException;

try {
    Notification::sendSms($user->phone_number, 'کد تایید: ۱۲۳۴۵');
} catch (SmsSendingFailedException $e) {
    logger()->error('ارسال پیامک ناموفق بود: ' . $e->getMessage());
}

⚙️ در صورت استفاده از صف، این خطاها به‌صورت خودکار توسط مکانیزم failed_jobs لاراول مدیریت می‌شوند.

📋 پیش‌نیازها

نیازمندی	نسخه
PHP	8.1 یا بالاتر
Laravel	11.x, 12.x یا بالاتر

🤝 مشارکت

پیشنهادات، گزارش باگ و Pull Request‌ها با آغوش باز پذیرفته می‌شوند! لطفاً پیش از ارسال تغییرات بزرگ، یک Issue باز کنید تا در موردش گفتگو کنیم.

📄 لایسنس

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

ساخته‌شده با ❤️ توسط Bitarun