README

Framework-agnostic SMS gateway with multi-provider fallback support for PHP 8.3+.

Features

• Multi-driver support — register multiple SMS providers and switch between them
• Automatic fallback — if one provider fails, the next one in the chain is used
• Laravel integration — service provider with auto-discovery, notification channel, and publishable config
• Extensible — implement SmsDriverInterface to add your own providers

Supported Providers

Installation

composer require mkakpabla/sms-gateway

Laravel

The service provider is auto-discovered. Publish the configuration file:

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

Add your credentials to .env:

SMS_DRIVER=faster-message

# FasterMessage
FASTER_MESSAGE_FROM=MyApp
FASTER_MESSAGE_API_URL=https://api.fastermessage.com
FASTER_MESSAGE_USERNAME=your-username
FASTER_MESSAGE_PASSWORD=your-password

# AfrikSMS
AFRIKSMS_CLIENT_ID=your-client-id
AFRIKSMS_API_KEY=your-api-key
AFRIKSMS_SENDER_ID=AFRIKSMS

# NATYABIP
NATYABIP_USERNAME=your-username
NATYABIP_PASSWORD=your-password
NATYABIP_FROM=EASYSERVICE
NATYABIP_API_URL=https://api.natyabip.com/smsapiprod_web/FR/api.awp

Usage

Standalone

use SmsGateway\SmsGateway;
use SmsGateway\SmsMessage;
use SmsGateway\Drivers\FasterMessageDriver;

$gateway = new SmsGateway();

$gateway->registerDriver('faster-message', new FasterMessageDriver(
    from: 'MyApp',
    apiUrl: 'https://api.fastermessage.com',
    username: 'your-username',
    password: 'your-password',
));

$gateway->setDefaultDriver('faster-message');

$gateway->send('+22890001234', SmsMessage::create('Hello!'));

AfrikSMS

use SmsGateway\SmsGateway;
use SmsGateway\SmsMessage;
use SmsGateway\Drivers\AfrikSmsDriver;

$gateway = new SmsGateway();

$gateway->registerDriver('afriksms', new AfrikSmsDriver(
    clientId: 'your-client-id',
    apiKey: 'your-api-key',
    senderId: 'AFRIKSMS',
));

$gateway->setDefaultDriver('afriksms');

$gateway->send('22890001234', SmsMessage::create('Hello!'));

NATYABIP

use SmsGateway\SmsGateway;
use SmsGateway\SmsMessage;
use SmsGateway\Drivers\NatyabipDriver;

$gateway = new SmsGateway();

$gateway->registerDriver('natyabip', new NatyabipDriver(
    apiUrl: 'https://your-natyabip-api-url',
    username: 'your-username',
    password: 'your-password',
    from: 'EASYSERVICE',
));

$gateway->setDefaultDriver('natyabip');

$gateway->send('22890001234', SmsMessage::create('Hello!'));

With fallback

$gateway->registerDriver('driver-a', $driverA);
$gateway->registerDriver('driver-b', $driverB);

$gateway->setFallbackOrder(['driver-a', 'driver-b']);

// Tries driver-a first, falls back to driver-b on failure
$gateway->sendWithFallback('+22890001234', SmsMessage::create('Hello!'));

Laravel Notification

Implement the HasSmsNotification contract on your notification:

use Illuminate\Notifications\Notification;
use SmsGateway\Contracts\HasSmsNotification;
use SmsGateway\SmsMessage;

class OrderShipped extends Notification implements HasSmsNotification
{
    public function via($notifiable): array
    {
        return ['sms-gateway'];
    }

    public function toSms(object $notifiable): SmsMessage
    {
        return SmsMessage::create('Your order has been shipped!');
    }
}

Make sure your notifiable model provides a phone number:

public function routeNotificationForSms(): string
{
    return $this->phone;
}

Creating a Custom Driver

Implement SmsDriverInterface:

use SmsGateway\Contracts\SmsDriverInterface;
use SmsGateway\SmsMessage;

class MyCustomDriver implements SmsDriverInterface
{
    public function send(string $to, SmsMessage $message): void
    {
        // Your implementation here
    }
}

Then register it:

$gateway->registerDriver('my-driver', new MyCustomDriver());

Configuration

The config file (config/sms-gateway.php) supports the following options:

Testing

composer test

Quality tools

composer phpstan   # Static analysis
composer phpmd     # Mess detector
composer phpcs     # Code style
composer quality   # Run all checks

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

MIT