Download the PHP package bitarun/laravel-notification-service without Composer

📦 Laravel Notification Service

🇮🇷 فارسی • 🇬🇧 English

فارسی

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

✨ ویژگی‌ها

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

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

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

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

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

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

📥 نصب

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

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

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

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

⚙️ تنظیمات

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

🚀 شروع سریع

📧 ارسال ایمیل

📱 ارسال پیامک

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

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

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

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

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

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

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

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

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

🛡️ مدیریت خطا

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

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

📋 پیش‌نیازها

🤝 مشارکت

پیشنهادات، گزارش باگ و 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:

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

📥 Installation

Install via Composer:

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

Publish the config file

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:

🚀 Quick Start

📧 Sending an Email

📱 Sending an SMS

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:

💡 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

Force immediate sending (no queue)

Default behavior (per .env settings)

🛡️ 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:

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

📋 Requirements

🤝 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.

🇬🇧 English

Made with ❤️ by Bitarun