README

A simple driver-based SMS gateway manager for Laravel.

Features

Separate packages for each provider.
Switch drivers per request.
Laravel HTTP client access.
SMS sent events with request and response data.
Custom driver registration.

Requirements

PHP 8.3+
Laravel 13+

Installation

Install the core package:

composer require misaf/laravel-sms-gateway

Install one or more driver packages:

composer require misaf/laravel-sms-gateway-ghasedak

Publish the config file:

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

Driver Packages

First-party driver packages:

Driver	Package
`ghasedak`	`misaf/laravel-sms-gateway-ghasedak`
`ippanel`	`misaf/laravel-sms-gateway-ippanel`
`kavenegar`	`misaf/laravel-sms-gateway-kavenegar`
`magfa`	`misaf/laravel-sms-gateway-magfa`
`melipayamak`	`misaf/laravel-sms-gateway-melipayamak`
`messagebird`	`misaf/laravel-sms-gateway-messagebird`
`plivo`	`misaf/laravel-sms-gateway-plivo`
`smsir`	`misaf/laravel-sms-gateway-smsir`
`sunway`	`misaf/laravel-sms-gateway-sunway`
`textlocal`	`misaf/laravel-sms-gateway-textlocal`
`twilio`	`misaf/laravel-sms-gateway-twilio`
`vonage`	`misaf/laravel-sms-gateway-vonage`

Quick Start

Install the Ghasedak driver package:

composer require misaf/laravel-sms-gateway-ghasedak

Set the default driver in .env:

SMS_GATEWAY_DRIVER=ghasedak # Default driver
SMS_GATEWAY_GHASEDAK_APIKEY=your-api-key # Ghasedak API key

Add the matching service credentials in config/services.php:

'ghasedak' => [
    'api_key' => env('SMS_GATEWAY_GHASEDAK_APIKEY'),
],

Send through the default driver:

use Misaf\LaravelSmsGateway\Facade\SmsGateway;

$response = SmsGateway::driver()->send([
    'message'  => 'Hello',
    'receptor' => '09123456789',
]);

See the original provider documentation for available fields.

Configuration

Set SMS_GATEWAY_DRIVER in your application's .env file to choose the default driver.

Provider environment keys are defined by each driver package — see that package's README (linked under Driver Packages) for its variables.

Switching Drivers

Use driver() to send through a specific driver without changing the default:

SmsGateway::driver('ghasedak')->send($data);

SmsGateway::driver('kavenegar')->send($data);

HTTP Client Access

Use request() to send directly through the configured Laravel HTTP client for a driver:

$response = SmsGateway::driver('ghasedak')
    ->request()
    ->post('sms/send/simple', $data);

Use either send() or request() — after calling request()->post(...), you do not need to call send().

Events

HTTP drivers dispatch Misaf\LaravelSmsGateway\Events\SmsSent.

use Misaf\LaravelSmsGateway\Events\SmsSent;

final class StoreSmsGatewayResult
{
    public function handle(SmsSent $event): void
    {
        $driver = $event->driverName;
        $url = $event->request->url();
        $status = $event->response->status();
        $body = $event->response->json();
    }
}

Event properties:

$driverName: the resolved SMS gateway driver name.
$request: the Illuminate\Http\Client\Request instance.
$response: the Illuminate\Http\Client\Response instance.

Custom Drivers

Custom drivers should extend SmsGatewayDriver, implement send(), and use configureRequest() for driver-specific HTTP client options.

The driver name is taken from the extend() registration key; it selects the services.{name} config section and labels SmsSent events. Override driverName() only when those should use a different name.

namespace App\SmsGateways;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\Response;
use Misaf\LaravelSmsGateway\SmsGatewayDriver;

final class CustomDriver extends SmsGatewayDriver
{
    /**
     * @param array<string, mixed> $data
     */
    public function send(array $data): Response
    {
        return $this->request()->post('messages', $data);
    }

    protected function defaultBaseUrl(): string
    {
        return 'https://api.example.com';
    }

    protected function configureRequest(PendingRequest $request): PendingRequest
    {
        return $request->withToken($this->driverConfig('token'));
    }
}

use App\SmsGateways\CustomDriver;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;
use Misaf\LaravelSmsGateway\Facade\SmsGateway;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        SmsGateway::extend('custom', function (Application $app): CustomDriver {
            return $app->make(CustomDriver::class);
        });
    }
}

Testing

composer test
composer analyse

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

MIT

misaf / laravel-sms-gateway

Maintainers

Package info

Statistics

Security