Download the PHP package misaf/laravel-sms-gateway without Composer

Laravel SMS Gateway

A driver-based SMS gateway manager for Laravel, with one installable package per provider. Payloads pass through untouched, so every provider's own API fields stay available, and every send attempt, success and failure dispatches an event.

Requires PHP 8.4+ and Laravel 13.

Installation

The core ships only the null driver, which sends nothing and returns a fake successful response — fine for local and testing, but it delivers no messages. For that, install one or more driver packages:

All service providers auto-register, and each driver registers itself on the core manager. See each driver's README for its credentials and options.

Usage

Drivers can coexist, and the payload goes straight to the provider, so use the fields its API expects. The facade is the entry point: the container binds only SmsGatewayManager and its sms-gateway alias — the SmsGateway contract is deliberately not bound, so type-hinting it for injection will not resolve.

Events

Every HTTP driver dispatches four events from Misaf\LaravelSmsGateway\Events, each carrying the driver name:

• SmsSending — before the request leaves, with the payload
• SmsSent — after a successful (2xx) response, with the Request and Response
• SmsSendFailed — after a failed (non-2xx) response, with the Request and Response
• SmsSendUnreachable — when the gateway was never reached (connection error or timeout), with the exception; there is no request or response to report

The retry policy uses throw: false, so a rejected send does not raise — SmsSendFailed is how you observe it. A connection error or timeout still raises after the retries are spent, with SmsSendUnreachable dispatched just before it surfaces.

Configuration

config/sms-gateway.php:

The client timeout sits one second above the connection timeout so a slow gateway loses the race. Only connection failures and gateway 5xx responses are retried; a rejected credential or a malformed payload fails on the first attempt.

That is the whole core configuration. The defaults.* values are the fallback for custom drivers only — each first-party driver owns its own timeout.* and retry.* keys with driver-specific environment variables (e.g. SMS_GATEWAY_TWILIO_SERVER_TIMEOUT), so one gateway can be tuned without touching the others. Endpoints and credentials belong to the driver packages, where every credential key and every base_url is required and may not be empty: a missing or empty value fails when the driver is resolved, rather than sending an unauthenticated request or one to a relative URL.

Registering a custom driver

Extend Misaf\LaravelSmsGateway\Drivers\SmsGatewayDriver. The base class owns the timeouts, the retry policy and the events; the driver supplies its name, its authentication, and the call it makes. Constructor values take no defaults — config is the only place a value is written down — and every one the driver cannot work without is guarded with self::requireConfigured(), since a config key that is present but empty passes Config::string().

A driver that needs neither the shared retry policy nor the events may implement Misaf\LaravelSmsGateway\Contracts\SmsGateway directly instead.

Register it from a service provider:

From a package service provider, defer the registration so provider discovery order cannot matter:

The registration key is the name used by SmsGateway::driver('custom'); the driver reads its own configuration and reports its own driverName() on the events, so nothing is inferred from that key.

Contributing

This repository is a monorepo: the core package lives at the root, and every driver lives in Drivers/laravel-sms-gateway-<driver> and is split out to its own read-only repository on release. Open issues and pull requests here.

Changelog

See CHANGELOG for what has changed recently.

License

MIT. See LICENSE.