andriichuk / laravel-bsg-sms-channel

v0.1.0 2026-09-26 14:21 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.9||^8.2
• illuminate/contracts: ^11.0||^12.0||^13.5
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.9
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Serhii Andriichuk

• sms
• notifications
• laravel
• bsg
• laravel-bsg-sms-channel

Published on Packagist.org on 2026-09-26 14:21 UTC

README

Send SMS notifications through the BSG World REST API using Laravel's notification system.

$user->notify(new Invitation());

Installation

Requirements: PHP 8.3+ and Laravel 11.x, 12.x, or 13.5+.

composer require andriichuk/laravel-bsg-sms-channel

The service provider is auto-discovered by Laravel.

Configuration

Add your BSG API key and registered sender name to config/services.php:

return [
    // ...

    'bsg' => [
        'api_key' => env('BSG_SMS_API_KEY'),
        'from' => env('BSG_SMS_FROM'),
        'log_response' => env('BSG_SMS_LOG_RESPONSE', false),
    ],
];

Then add the corresponding environment variables:

BSG_SMS_API_KEY="live_your_api_key"
BSG_SMS_FROM="YourSender"
BSG_SMS_LOG_RESPONSE=false

BSG sends the API key in the X-API-KEY request header. The sender name must be registered in your BSG account and may contain up to 14 characters.

Usage

Notifiable model

Add routeNotificationForBsg to the notifiable model and return the recipient's full international phone number:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForBsg(): string
    {
        return $this->phone; // e.g. [phone]
    }
}

Notification class

Add BsgChannel to via() and return an Sms instance from toBsg():

use Andriichuk\BsgSmsChannel\BsgChannel;
use Andriichuk\BsgSmsChannel\Sms;
use Illuminate\Notifications\Notification;

class Invitation extends Notification
{
    public function via(object $notifiable): array
    {
        return [BsgChannel::class];
    }

    public function toBsg(object $notifiable): Sms
    {
        return new Sms(
            text: 'You have been invited!',
            reference: 'invite-'.$notifiable->getKey(),
        );
    }
}

Send the notification as usual:

$user->notify(new Invitation());

Anonymous notifications

use Andriichuk\BsgSmsChannel\BsgChannel;
use Illuminate\Support\Facades\Notification;

Notification::route(BsgChannel::class, '[phone]')
    ->notify(new Invitation());

Message options

Sms supports the following named arguments:

• text — message body (required).
• phone — recipient number; when omitted, the channel resolves it from the notifiable.
• from — per-message sender override; defaults to services.bsg.from.
• reference — external message ID of up to 32 alphanumeric characters.
• validity — validity period from 1 to 72 hours.
• tariff — tariff number from 0 to 9.
• twoWay — marks the message as a 2-way SMS.

return new Sms(
    text: 'Your verification code is 123456',
    validity: 1,
    tariff: 0,
    twoWay: false,
);

Phone numbers are normalized to digits before being sent. Optional arguments are omitted from the API request when they are null, so BSG's defaults remain in effect.

Testing

composer test

Static analysis and code style checks are also available:

composer analyse
composer format

Changelog

See CHANGELOG for release notes.

Security

Please use the repository's security policy to report vulnerabilities privately.

Credits

• Serhii Andriichuk

License

The MIT License. See LICENSE for details.