Download the PHP package ijeyg/larapayamak without Composer

Larapayamak

Unified Laravel SMS package for Iranian providers with clean multi-gateway switching.

A lightweight and practical SMS abstraction for Laravel projects that need to switch providers without rewriting business logic.

✨ Key Highlights

• Multi-gateway architecture for Iranian SMS providers
• Runtime gateway switching via gateway($name)
• Facade + Dependency Injection support
• Simple SMS and pattern/template SMS APIs
• Laravel package auto-discovery
• Contract-based provider abstraction
• CI-tested quality pipeline (Pest, PHPStan, Pint)

Why Larapayamak? 🚀

If your application depends on SMS delivery (OTP, notifications, order updates), provider lock-in is risky. Larapayamak gives you one consistent API while keeping provider selection flexible.

Features

• ✅ Unified API through Ijeyg\Larapayamak\Services\SmsService
• ✅ Facade API through Ijeyg\Larapayamak\Facades\Larapayamak
• ✅ Multi-gateway runtime selection via gateway('provider')
• ✅ Default gateway from config/env (SMS_GATEWAY)
• ✅ Pattern/template messaging support where provider supports it
• ✅ Package auto-discovery (service provider + facade alias)
• ✅ Clean separation using provider contract (SmsProviderInterface)
• ✅ Test suite with Pest + architecture checks

Supported SMS Gateways

Installation

Laravel auto-discovers:

• Ijeyg\Larapayamak\LarapayamakServiceProvider
• Facade alias: Larapayamak

Configuration

Publish config:

Config file path:

Environment Variables

Set the default gateway:

Full example for all gateways:

Architecture

Core classes

• Ijeyg\Larapayamak\Services\SmsService
• Ijeyg\Larapayamak\Services\GatewayManager
• Ijeyg\Larapayamak\Contracts\SmsProviderInterface
• Ijeyg\Larapayamak\Facades\Larapayamak

Message flow

1. App code calls Larapayamak facade or injected SmsService
2. SmsService delegates to selected provider
3. Provider sends request through internal HTTP client
4. Package returns Illuminate\Http\JsonResponse

Basic Usage

1) Facade usage

2) Dependency Injection usage

3) Controller example

4) Service class example

Multi-Gateway Usage (Main Feature) 🔁

Runtime switching without changing your domain logic:

Per-gateway examples

Error Handling

• Gateway send methods return JsonResponse with success state.
• On provider/network exceptions, gateway methods return HTTP 500 JSON responses.
• Invalid gateway names throw InvalidArgumentException.

Example:

Real-World Use Cases

• OTP / verification codes
• E-commerce order status updates
• Transaction notifications
• Marketing campaigns with provider fallback strategy

OTP Example

E-commerce Example

Multi-Provider Strategy

Use one default provider for normal traffic and switch per action/tenant when needed:

• Default from SMS_GATEWAY
• Override at runtime with gateway('...')
• Keep your business logic provider-agnostic

Testing & Quality

This package uses:

• Pest for tests
• PHPStan for static analysis
• Laravel Pint for code style
• GitHub Actions matrix CI for Laravel/PHP combinations

Useful commands:

Supported Versions

• PHP: ^8.2
• Laravel: 10.x and 11.x
• Laravel 12: experimental/non-official (not claimed as stable support)

Contributing

PRs and issues are welcome.

Recommended local workflow:

License

MIT. See LICENSE.md.

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

معرفی پکیج

Larapayamak یک پکیج لاراول برای ارسال پیامک از چند سرویس‌دهنده ایرانی با یک API یکپارچه است.
فلسفه پکیج ساده است: کد کسب‌وکار شما نباید با عوض شدن Provider تغییر کند.

چرا Larapayamak؟ 🌟

• یک API ثابت برای چند سرویس‌دهنده
• سوییچ سریع درگاه در زمان اجرا با gateway(...)
• مناسب OTP، فروشگاه اینترنتی و پیامک‌های تراکنشی
• استفاده راحت با Facade یا Dependency Injection
• ساختار تمیز بر پایه Contract

ویژگی‌ها

• پشتیبانی از چند درگاه پیامکی ایرانی
• ارسال پیامک ساده و پترن (در درگاه‌های پشتیبانی‌شده)
• انتخاب درگاه پیش‌فرض با .env
• تغییر درگاه به‌صورت پویا داخل کد
• Auto-discovery در لاراول
• پوشش تست و CI

درگاه‌های پشتیبانی‌شده

نصب و راه‌اندازی

پکیج به‌صورت خودکار Service Provider و Facade را رجیستر می‌کند.

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

مسیر فایل:

متغیرهای محیطی

درگاه پیش‌فرض:

نمونه کامل برای همه درگاه‌ها:

معماری پکیج

ایده اصلی

• SmsService نقطه ورود اصلی برای ارسال پیامک است.
• GatewayManager Provider مناسب را انتخاب می‌کند.
• همه Providerها قرارداد SmsProviderInterface را پیاده‌سازی می‌کنند.

روند اجرا

1. فراخوانی از Facade یا سرویس تزریق‌شده
2. انتخاب درگاه پیش‌فرض یا درگاه مشخص‌شده با gateway()
3. ارسال درخواست به سرویس‌دهنده
4. دریافت خروجی به‌صورت JsonResponse

استفاده پایه

استفاده با Facade

استفاده با Dependency Injection

استفاده از چند Gateway (ویژگی کلیدی) 🔁

نمونه برای هر درگاه

مدیریت خطا

• در خطاهای شبکه یا خطاهای سرویس‌دهنده، خروجی JsonResponse با success=false برمی‌گردد.
• اگر نام درگاه نامعتبر باشد، InvalidArgumentException دریافت می‌کنید.
• بهتر است همیشه مقدار success را چک کنید.

مثال‌های واقعی

OTP

فروشگاه اینترنتی

استراتژی چند‌سرویس‌دهنده

اگر پایداری ارسال برای شما مهم است:

• یک درگاه پیش‌فرض در .env داشته باشید.
• برای سناریوهای خاص (مثل OTP یا پیامک تبلیغاتی)، درگاه را با gateway(...) تغییر دهید.
• منطق دامنه را مستقل از Provider نگه دارید.

تست‌ها و کیفیت کد

ابزارهای کنترل کیفیت:

• Pest
• PHPStan
• Laravel Pint
• GitHub Actions (Matrix CI)

نسخه‌های پشتیبانی‌شده

• PHP: ^8.2
• Laravel: 10 و 11
• Laravel 12: فعلاً رسمی نیست و در حد بررسی/تست است

تغییرات

برای مشاهده تغییرات هر نسخه، فایل CHANGELOG.md را بررسی کنید.

مشارکت‌کنندگان

برای مشارکت در توسعه، لطفاً راهنمای مشارکت را بررسی کنید و Pull Request بفرستید.
لیست مشارکت‌کنندگان پروژه در GitHub قابل مشاهده است.

امنیت

اگر مشکل امنیتی پیدا کردید، لطفاً آن را عمومی منتشر نکنید و از طریق ایمیل زیر اطلاع دهید:
[email protected]

لایسنس

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