README

A Laravel package for sending SMS using the Fast2sms API with a fluent, expressive interface.
Supports Quick SMS, DLT templates, OTP, queueing, scheduling, and balance checks.

Requirements
Features
Quick Start Guide
Installation
Configuration
Basic Usage
API Methods
Error Handling
Advanced Features
Documentation
Contributing
License

Requirements

PHP 8.3 or higher
Laravel 12 or higher (the package relies on illuminate/support v12+)

✨ Features

Fluent Interface: Chainable API for building and sending SMS.
Multiple Routes: Supports Quick SMS, DLT SMS, and OTP SMS.
Queue Support: Built-in job queueing for asynchronous processing.
Easy Configuration: Simple config file and environment variable setup.
DLT Compliant: Send DLT messages with templates and variables.
Service & Facade: Use the Fast2sms service directly or via facade.
API Helpers: Check wallet balance and DLT details.
Artisan Commands: Publish configuration and monitor balance.

🚀 Quick Start Guide

Install via Composer:

composer require itxshakil/laravel-fast2sms

Publish Configuration:
```
php artisan vendor:publish --tag=fast2sms-config
```
This creates fast2sms.php in your config directory.

Update Environment Variables: Add to your .env:

FAST2SMS_API_KEY="YOUR_API_KEY"
FAST2SMS_DEFAULT_SENDER_ID="FSTSMS"
FAST2SMS_DEFAULT_ROUTE="dlt"

Send Your First DLT SMS:

use Shakil\Fast2sms\Facades\Fast2sms;

Fast2sms::dlt(
    numbers: '9999999999',
    templateId: 'YOUR_TEMPLATE_ID',
    variablesValues: ['John Doe'],
    senderId: 'YOUR_SENDER_ID'
);

⚙️ Installation

Install the package via Composer:

composer require itxshakil/laravel-fast2sms

Supports Laravel auto-discovery. No manual provider registration required.

🛠️ Configuration

Publish the configuration file:

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

Creates fast2sms.php in your config directory.

Environment Variables: Update your .env file:

FAST2SMS_API_KEY="YOUR_API_KEY"
FAST2SMS_DEFAULT_SENDER_ID="FSTSMS"
FAST2SMS_DEFAULT_ROUTE="dlt"

📝 Basic Usage

Use the Fast2sms facade for convenience. Three primary sending methods, each with a dedicated helper.

Quick SMS

use Shakil\Fast2sms\Facades\Fast2sms;
use Shakil\Fast2sms\Enums\SmsLanguage;

Fast2sms::quick('9999999999', 'Hello, this is a Quick SMS!');
Fast2sms::quick('9999999999', 'नमस्ते! यह एक क्विक एसएमएस है।', SmsLanguage::UNICODE);

DLT SMS

use Shakil\Fast2sms\Facades\Fast2sms;

Fast2sms::dlt(
    numbers: '9999999999',
    templateId: 'YOUR_TEMPLATE_ID',
    variablesValues: ['John Doe'],
    senderId: 'YOUR_SENDER_ID'
);

OTP SMS

use Shakil\Fast2sms\Facades\Fast2sms;

Fast2sms::otp('9999999999', '123456');

Fluent Interface

use Shakil\Fast2sms\Facades\Fast2sms;
use Shakil\Fast2sms\Enums\SmsRoute;

Fast2sms::to('9999999999')
    ->route(SmsRoute::DLT)
    ->senderId('YOUR_SENDER_ID')
    ->templateId('YOUR_TEMPLATE_ID')
    ->variables(['John Doe'])
    ->send();

Check Wallet Balance

use Shakil\Fast2sms\Facades\Fast2sms;

$response = Fast2sms::checkBalance();

if ($response->success()) {
    echo "Wallet Balance: {$response->balance}\n";
    echo "SMS Count: {$response->smsCount}\n";
}

Check DLT Manager Details

use Shakil\Fast2sms\Facades\Fast2sms;
use Shakil\Fast2sms\Enums\DltManagerType;
use Shakil\Fast2sms\Responses\DltManagerResponse;

// Get DLT sender IDs
/** @var DltManagerResponse $sendersResponse */
$sendersResponse = Fast2sms::dltManager(DltManagerType::SENDER);

foreach ($sendersResponse->getSenders() as $sender) {
    echo "Sender ID: {$sender['sender_id']} | Entity ID: {$sender['entity_id']}\n";
}

📚 API Methods

Method	Description
`->to(string	array $numbers)`
`->message(string $message)`	Sets message content (DLT: template ID).
`->senderId(string $senderId)`	Sets DLT-approved sender ID.
`->route(SmsRoute $route)`	Sets SMS route (`DLT`, `QUICK`, `OTP`, etc.).
`->entityId(string $entityId)`	Sets DLT Principal Entity ID.
`->templateId(string $templateId)`	Sets DLT Content Template ID.
`->variables(array	string $values)`
`->flash(bool $flash)`	Toggles flash message.
`->language(SmsLanguage $language)`	Sets message language (`ENGLISH`, `UNICODE`).
`->schedule(string	DateTimeInterface $time)`
`->send()`	Sends SMS with configured parameters.
`->quick(...)`	Quick helper to send simple SMS.
`->dlt(...)`	Helper for DLT messages.
`->otp(...)`	Helper for OTP messages.
`->checkBalance()`	Retrieves wallet balance.
`->dltManager(string $type)`	Retrieves DLT manager details for `sender` or `template`.

⚠️ Exceptions

All errors throw Fast2smsException.
Catch them when handling SMS sending:

use Shakil\Fast2sms\Exceptions\Fast2smsException;

try {
    Fast2sms::quick('9999999999', 'Hello World');
} catch (Fast2smsException $e) {
    logger()->error("SMS failed: " . $e->getMessage());
}

🧩 Advanced Features

🚀 Queue Integration

Supports Laravel's queue system for asynchronous SMS sending.

Queue Configuration:

// config/queue.php 
'connections' => [ 
    'redis' => [ 
        'driver' => 'redis', 
        // ... other redis configuration 
    ], 
],

Queueing SMS Messages:

use Shakil\Fast2sms\Facades\Fast2sms;

// Queue a Quick SMS
Fast2sms::quickQueue('9999999999', 'Hello from queue!');

// Queue a DLT SMS
Fast2sms::dltQueue(
    numbers: '9999999999',
    templateId: 'YOUR_TEMPLATE_ID',
    variablesValues: ['John Doe'],
    senderId: 'YOUR_SENDER_ID'
);

// Queue an OTP SMS
Fast2sms::otpQueue('9999999999', '123456');

Advanced Queue Options:

use Shakil\Fast2sms\Facades\Fast2sms;
use Shakil\Fast2sms\Enums\SmsRoute;

Fast2sms::to('9999999999')
    ->message('Test message')
    ->route(SmsRoute::QUICK)
    ->onConnection('redis')   // Specify queue connection
    ->onQueue('sms')          // Specify queue name
    ->delay(now()->addMinutes(10)) // Add delay
    ->queue();                // Queue the SMS

Queue Methods:

Method	Description
`->queue()`	Queue SMS using default settings
`->onConnection(string $name)`	Set queue connection
`->onQueue(string $queue)`	Set queue name
`->delay($delay)`	Set delay before processing
`->quickQueue()`	Queue Quick SMS
`->dltQueue()`	Queue DLT SMS
`->otpQueue()`	Queue OTP SMS

📱 Notifications Channel

Use Fast2sms as a notification channel in your Laravel applications:

Create a Notification:

use Illuminate\Notifications\Notification;
use Shakil\Fast2sms\Facades\Fast2sms;
use Shakil\Fast2sms\Enums\SmsRoute;
class LowSmsBalanceNotification extends Notification
{
    public function __construct(
        protected float $balance,
        protected float $threshold
    ) {}

    public function via($notifiable)
    {
        return ['fast2sms'];
    }

    public function toFast2sms($notifiable)
    {
        return Fast2sms::to($notifiable->phone)
            ->message("Low SMS balance: {$this->balance}. Threshold: {$this->threshold}.")
            ->route(SmsRoute::QUICK)
            ->send();
    }
}

Use route in SMS Notification:

use Illuminate\Notifications\RoutesNotifications;
use Illuminate\Notifications\Notifiable;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
    use Notifiable, RoutesNotifications;

    protected $fillable = ['name', 'email', 'phone'];

    public function routeNotificationForFast2sms()
    {
        return $this->phone; // Return the phone number for Fast2sms
    }
}

Send the notification:

use App\Notifications\LowSmsBalanceNotification;
use Illuminate\Support\Facades\Notification;
Notification::route('fast2sms', '9999999999')
    ->notify(new LowSmsBalanceNotification(500, 1000));

Model Setup: Ensure your model has a phone attribute:

use Illuminate\Database\Eloquent\Model;
class User extends Model
{
    protected $fillable = ['name', 'email', 'phone'];
}

Schedule the command:

php artisan sms:monitor --threshold=500

If no threshold is specified, the value from your configuration file will be used:

// config/fast2sms.php
'balance_threshold' => 1000,

Listen for the event in AppServiceProvider:

use App\Notifications\LowSmsBalanceNotification;
use Illuminate\Support\Facades/Event;
use Illuminate\Support\Facades\Notification;
use Shakil\Fast2sms\Events\LowBalanceDetected;

public function boot(): void
{
    Event::listen(function (LowBalanceDetected $event) {
        Notification::route('mail', 'dev@example.com')
            ->notify(new LowSmsBalanceNotification(
                $event->balance,
                $event->threshold
            ));
    });
}

Example schedule in App\Console\Kernel:

protected function schedule(Schedule $schedule)
{
    $schedule->command('sms:monitor')->hourly();
}

📚 Documentation

Learn how to use Laravel Fast2sms effectively:

Getting Started

Features

🤝 Contributing

Contributions are always welcome!
Open an issue or submit a pull request for bugs or suggestions.

📄 License

This package is open-source software licensed under the MIT license.

itxshakil / laravel-fast2sms

Maintainers

Details