README

A robust, extensible, driver-based SMS package for Laravel. Send SMS via multiple providers (Twilio, Vonage, etc.) with built-in failover support, queuing, and easy testing.

Features

• Multi-Driver Support: Easily switch between providers (Twilio, Vonage, Log, etc.).
• Failover Logic: Automatically try fallback providers if the primary one fails.
• Queue Support: Seamless integration with Laravel Queues for background sending.
• Event-Driven: Dispatches events for sending, sent, and failed messages.
• Testing Fakes: Simple assertions for unit testing your SMS logic.
• Extensible: Add custom drivers with ease.

Installation

You can install the package via composer:

composer require bankola/laravel-multi-sms

Configuration

Publish the configuration file:

php artisan vendor:publish --tag="sms-config"

This will create a config/sms.php file. You should configure your drivers and credentials in your .env file:

SMS_DRIVER=failover

TWILIO_SID=your_sid
TWILIO_TOKEN=your_token
TWILIO_FROM=your_phone_number

VONAGE_KEY=your_key
VONAGE_SECRET=your_secret
VONAGE_FROM=your_brand_name

SMS_LOG_CHANNEL=stack

Usage

Sending an SMS

use Bankola\MultiSms\Facades\Sms;
use Bankola\MultiSms\DTO\SmsMessage;

Sms::send(new SmsMessage(
    to: '+1234567890',
    body: 'Your OTP is 1234'
));

Using a Specific Driver

Sms::driver('twilio')->send($message);

Queuing an SMS

Sms::queue($message);

// Or specifying a driver for the queue
Sms::queue($message, 'vonage');

Drivers

Log Driver

The log driver is perfect for local development. It writes the contents of the SMS to your Laravel logs.

Twilio Driver

Requires twilio/sdk. Configure TWILIO_SID, TWILIO_TOKEN, and TWILIO_FROM in your .env.

Vonage Driver

Requires vonage/client. Configure VONAGE_KEY, VONAGE_SECRET, and VONAGE_FROM in your .env.

Failover Driver

The failover driver iterates through a list of drivers until one successfully sends the message.

'failover' => [
    'driver' => 'failover',
    'drivers' => ['twilio', 'vonage', 'log'],
],

Events

The package dispatches the following events:

• Bankola\MultiSms\Events\SmsSending: Before a message is sent.
• Bankola\MultiSms\Events\SmsSent: After a message is successfully sent.
• Bankola\MultiSms\Events\SmsFailed: When a message fails to send.

Testing

Use the fake() method to mock SMS sending in your tests:

use Bankola\MultiSms\Facades\Sms;

public function test_it_sends_an_sms()
{
    Sms::fake();

    // ... run your code ...

    Sms::assertSent(function ($message) {
        return $message->to === '+1234567890' && str_contains($message->body, 'OTP');
    });
}

Extending

You can register custom drivers using the extend method in your AppServiceProvider:

use Bankola\MultiSms\Facades\Sms;

Sms::extend('custom_provider', function ($app, $config) {
    return new CustomSmsDriver($config);
});

The custom driver must implement Bankola\MultiSms\Contracts\SmsDriverInterface.

License

The MIT License (MIT). Please see License File for more information.