README

A small, framework-agnostic PHP library for sending SMS through pluggable providers. No framework, no hard HTTP dependency — providers talk to any PSR-18 HTTP client, so it drops into Laravel, Symfony, or plain PHP alike.

Requirements

PHP 8.1+
A PSR-18 HTTP client and PSR-17 factories (e.g. guzzlehttp/guzzle + nyholm/psr7, or symfony/http-client) — only for HTTP-based providers.

Installation

composer require pralhadstha/sms-gateways

For an HTTP provider you also need a client and factories, for example:

composer require nyholm/psr7 guzzlehttp/guzzle

Usage

Every provider implements Pralhadstha\Sms\SmsGateway:

use Pralhadstha\Sms\SmsGateway;
use Pralhadstha\Sms\SmsMessage;

function notify(SmsGateway $sms): void
{
    $result = $sms->send(new SmsMessage(
        to: '+9779800000000',
        text: 'Your account has been activated.',
    ));

    if ($result->failed()) {
        // inspect $result->error and $result->raw
    }
}

Sparrow SMS (Nepal)

use GuzzleHttp\Client;
use Nyholm\Psr7\Factory\Psr17Factory;
use Pralhadstha\Sms\Gateway\SparrowGateway;

$factory = new Psr17Factory();

$sms = new SparrowGateway(
    client: new Client(),
    requestFactory: $factory,
    streamFactory: $factory,
    token: getenv('SPARROW_TOKEN'),
    from: 'YourIdentity',
);

Disabling / testing

Pralhadstha\Sms\Gateway\NullGateway — accepts every message and reports success without sending. Use it when no credentials are configured.
Pralhadstha\Sms\Gateway\ArrayGateway — records messages in memory so your application's tests can assert on what would have been sent:

$sms = new ArrayGateway();
$sms->send(new SmsMessage('123', 'hi'));

assert($sms->count() === 1);
assert($sms->lastMessage()->text === 'hi');

Error handling

send() returns an SmsResult:

Provider rejection (non-2xx, error in body) → SmsResult::failed() is true; read ->error and ->raw.
Transport failure (DNS, timeout, connection) → throws Pralhadstha\Sms\Exception\SmsException.

Adding a provider

Implement SmsGateway and return an SmsResult. HTTP providers should accept PSR-18/PSR-17 abstractions in the constructor — see SparrowGateway as the reference.

final class MyProviderGateway implements SmsGateway
{
    public function send(SmsMessage $message): SmsResult
    {
        // ... call the provider, map the response ...
        return SmsResult::success();
    }
}

Development

composer install
composer test     # PHPUnit
composer stan     # PHPStan (level 8)
composer cs       # PHP-CS-Fixer (dry run); composer cs-fix to apply

License

MIT — see LICENSE.

pralhadstha / sms-gateways

Maintainers

Package info

Statistics

Security