README

فارسی

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

✨ ویژگی‌ها

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

📱 پیش‌نیاز سرویس پیامک (SMS)

این پکیج برای ارسال پیامک به‌صورت اختصاصی بر اساس ساختار API سرویس sms.ir (به‌طور دقیق‌تر، متد ارسال پیامک تایید بر پایه‌ی قالب/Template) پیاده‌سازی شده است.

⚠️ توجه: این بخش از پکیج با سایر سرویس‌های پیامکی (مثل کاوه‌نگار، ملی‌پیامک و...) تست یا سازگار نشده و به‌احتمال زیاد به‌دلیل تفاوت در ساختار درخواست/پاسخ API، بدون تغییر در کد کار نخواهد کرد. برای استفاده از این قابلیت باید حتماً از سرویس sms.ir استفاده کنید.

برای استفاده از قابلیت ارسال پیامک، پیش از هر چیز باید:

در سایت sms.ir ثبت‌نام کنید.
یک API Key از پنل کاربری خود دریافت کنید.
یک قالب (Template) برای ارسال پیامک تایید بسازید و شناسهٔ قالب (Template ID) آن را یادداشت کنید.
مقادیر دریافتی را در فایل .env پروژه‌تان قرار دهید (به بخش تنظیمات مراجعه کنید).

📥 نصب

از طریق 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.ir)
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.ir دریافت می‌کنید	—
`SMS_URL`	آدرس endpoint سرویس پیامکی sms.ir (نیازی به تغییر ندارد)	`https://api.sms.ir/v1/send/verify`
`SMS_TEMPLATE_ID`	شناسهٔ قالبی که در پنل sms.ir برای ارسال پیامک تایید ساخته‌اید	—

🚀 شروع سریع

📧 ارسال ایمیل

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 یا بالاتر
حساب کاربری در sms.ir	برای استفاده از قابلیت ارسال پیامک

🤝 مشارکت

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

📄 لایسنس

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

🇮🇷 فارسی • 🇬🇧 English

English

A simple, clean, and flexible notification package (Email & SMS) for Laravel projects

✨ Features

📧 Send emails using Laravel's native Mailable system
📱 Send SMS via the sms.ir web service
🚀 Full Queue support — optional and configurable
🎯 Supports simple input (string) or a full recipient DTO
🛡️ Unified error handling with a dedicated exception
⚡ Simple interface via a Facade

📱 SMS Service Prerequisite

This package's SMS sending feature is implemented specifically against the API structure of sms.ir (more precisely, its template-based verification SMS method).

⚠️ Note: This part of the package has not been tested or made compatible with other SMS providers (e.g. Kavenegar, Melipayamak, etc.), and due to differences in request/response structure it will most likely not work with them without code changes. You must use sms.ir to use this feature.

Before using the SMS feature, you need to:

Sign up at sms.ir.
Get an API Key from your user panel.
Create a Template for sending verification SMS and note its Template ID.
Put these values in your project's .env file (see the Configuration section).

📥 Installation

Install via Composer:

composer require bitarun/laravel-notification-service

The package is automatically discovered by Laravel, so there's no need to register the Service Provider manually.

Publish the config file

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

This command creates the config/notification.php file in your project.

⚙️ Configuration

After publishing the config file, set the following values in your project's .env file:

# Queue
NOTIFICATION_QUEUE_ENABLED=false
NOTIFICATION_QUEUE_CONNECTION=database
NOTIFICATION_QUEUE_NAME=default

# SMS (sms.ir)
SMS_API_KEY=your-api-key
SMS_URL=https://api.sms.ir/v1/send/verify
SMS_TEMPLATE_ID=your-template-id

Key	Description	Default
`NOTIFICATION_QUEUE_ENABLED`	Whether notifications are queued by default	`false`
`NOTIFICATION_QUEUE_CONNECTION`	The queue connection to use	Laravel's default connection
`NOTIFICATION_QUEUE_NAME`	The queue name to use	`default`
`SMS_API_KEY`	API key obtained from your sms.ir user panel	—
`SMS_URL`	The sms.ir SMS service endpoint (no need to change)	`https://api.sms.ir/v1/send/verify`
`SMS_TEMPLATE_ID`	The template ID created in your sms.ir panel for sending verification SMS	—

🚀 Quick Start

📧 Sending an Email

use Bitarun\LaravelNotificationService\Facades\Notification;

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

📱 Sending an SMS

use Bitarun\LaravelNotificationService\Facades\Notification;

Notification::sendSms($user->phone_number, 'Your verification code: 12345');

That's it! 🎉

🎯 Using a Recipient DTO (Optional)

If you need more recipient information (e.g. a name, for use in an email template), you can use 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);

💡 Both approaches (a simple string or a full DTO) are equally supported, and you can pick whichever fits your needs.

🚦 Queue Management

By default, queue behavior is determined by the NOTIFICATION_QUEUE_ENABLED value in your .env file. However, you can also override this behavior directly on a per-call basis:

Force sending via the queue

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

Force immediate sending (no queue)

Notification::now()->sendSms($user->phone_number, 'This message is sent immediately');

Default behavior (per .env settings)

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

🛡️ Error Handling

If a sending error occurs (e.g. a failed request to the SMS service), a dedicated exception is thrown that you can handle:

use Bitarun\LaravelNotificationService\Exceptions\SmsSendingFailedException;

try {
    Notification::sendSms($user->phone_number, 'Verification code: 12345');
} catch (SmsSendingFailedException $e) {
    logger()->error('SMS sending failed: ' . $e->getMessage());
}

⚙️ When using the queue, these errors are automatically handled by Laravel's failed_jobs mechanism.

📋 Requirements

Requirement	Version
PHP	8.1 or higher
Laravel	11.x, 12.x or higher
An sms.ir account	Required for the SMS feature

🤝 Contributing

Suggestions, bug reports, and pull requests are welcome! Please open an issue before submitting major changes so we can discuss it first.

📄 License

This package is released under the MIT License.