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:

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'));
    }
}

Register it from a service provider:

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