Download the PHP package moffhub/sms-handler without Composer

SMS Handler

A simple, unified SMS integration library for Laravel. Send SMS messages through multiple providers with a consistent API, automatic fallback, rate limiting, templating, cost estimation, and analytics.

Features

• [x] Send SMS, Bulk SMS, and Scheduled SMS
• [x] Multiple provider support (Advanta, Africa's Talking, Twilio, Nexmo, Onfon Media)
• [x] Custom provider extensibility
• [x] Automatic fallback provider chain
• [x] Per-provider rate limiting
• [x] SMS templating with variable interpolation
• [x] Cost estimation and segment counting
• [x] Analytics and success rate tracking
• [x] Webhook delivery report handling with signature validation
• [x] Events (SmsSent, SmsFailed, DeliveryReportReceived)
• [x] Structured logging with credential scrubbing
• [x] Laravel Notification channel support
• [x] Phone number and message validation
• [x] Database or file logging

Supported Providers

• Advanta - Kenya SMS gateway
• Africa's Talking - Pan-African SMS gateway
• Twilio - Global SMS provider
• Nexmo/Vonage - Global SMS provider
• Onfon Media - Kenya SMS gateway
• Custom - Build your own provider

Installation

Configuration

Publish the config and migrations:

Environment Variables

Add the following to your .env file based on your provider:

Usage

Using the Facade

Using Dependency Injection

Switching Providers at Runtime

Fallback Provider Chain

Configure a fallback provider that is used automatically when the primary provider fails with a ProviderException. Fallback is limited to one level (no chaining beyond the fallback).

Or in config/sms.php:

When the primary provider fails, the package will:

1. Log the failure
2. Automatically retry with the fallback provider
3. Log the fallback activation
4. Return the fallback result (or null if the fallback also fails)

Non-ProviderException errors (e.g., validation errors) are not retried and are rethrown.

Rate Limiting

Configure per-provider rate limits (messages per minute). When the limit is exceeded, messages are automatically queued for later delivery instead of being rejected.

Or in config/sms.php:

Programmatic access:

Rate Limiting Recommendations

• Set rate limits based on your provider's API quotas to avoid being blocked.
• Start with conservative limits and increase as needed.
• Monitor your queue to ensure rate-limited messages are being delivered.
• Use null (unlimited) only for providers with no known API rate limits.

SMS Templating

Define reusable SMS templates with {{ variable }} interpolation:

Send a templated SMS:

Message length is validated after interpolation. If the rendered message exceeds the configured max_message_length, an InvalidMessageException is thrown.

Cost Estimation

Estimate the cost of sending an SMS before dispatching. The estimator calculates SMS segment count based on message encoding (GSM-7 vs UCS-2) and multiplies by the configured per-segment cost.

Segment Counting Rules

Unicode characters (emoji, CJK, Arabic, etc.) force UCS-2 encoding, which reduces the per-segment capacity.

Configure per-segment cost in your provider config:

When logging to the database (SMS_LOG_CHANNEL=model), the estimated_cost and segment_count columns are automatically populated on each SmsLog record.

Analytics & Success Rate Tracking

Query SMS analytics aggregated from the sms_logs table:

CLI Stats Command

View SMS statistics from the command line:

Error Handling

Exception Types

The package defines a hierarchy of exceptions:

Handling Exceptions

Events

Listen for SMS lifecycle events:

Webhook Setup

Enable webhooks to receive delivery reports from providers:

This registers POST routes for each provider:

Webhook Signature Validation

Set webhook secrets to validate incoming requests:

If a secret is configured, the package validates the signature header on incoming webhook requests. Invalid signatures receive a 403 response.

Provider Webhook Setup

Twilio:

1. Go to your Twilio Console > Phone Numbers > Active Numbers
2. Click your number and set the "A MESSAGE COMES IN" webhook URL to your endpoint
3. Set the Status Callback URL to https://yourdomain.com/sms/webhooks/twilio

Africa's Talking:

1. Go to your AT Dashboard > SMS > SMS Callback URLs
2. Set the Delivery Reports URL to https://yourdomain.com/sms/webhooks/africastalking

Advanta:

1. Configure the callback URL in your Advanta dashboard or pass it in the API request
2. Set it to https://yourdomain.com/sms/webhooks/advanta

Nexmo/Vonage:

1. Go to Vonage Dashboard > Settings
2. Set the SMS Delivery Receipt URL to https://yourdomain.com/sms/webhooks/nexmo

Onfon:

1. Contact Onfon support to configure your callback URL
2. Set it to https://yourdomain.com/sms/webhooks/onfon

Delivery Report Payload Examples

Twilio:

Africa's Talking:

Advanta:

Nexmo/Vonage:

Onfon:

Africa's Talking Integration

The library fully supports the Africa's Talking Bulk SMS API:

Sandbox Testing

Production

Features

• Automatic sandbox/production URL detection
• Phone number formatting (supports 0712..., 254712..., +254712...)
• Bulk SMS with enqueue support
• Sender ID/Short code support
• Detailed response handling with message IDs and costs

Custom Providers

Create your own provider by extending CustomProvider:

Register your provider:

Add config:

Update .env:

Laravel Notifications

Use SMS in Laravel notifications:

Ensure your notifiable model has a routeNotificationForSms method:

Logging

SMS messages can be logged to file or database:

When using database logging, each SmsLog record includes:

• provider - The provider class used
• to - Recipient phone number
• message - Message content
• success - Boolean success status
• message_id - Provider message ID
• delivery_status - Updated via webhooks
• estimated_cost - Calculated cost based on segments and provider rate
• segment_count - Number of SMS segments
• scheduled_at - For scheduled messages
• response - Raw provider response

Structured Logging

The package logs structured events to a configurable log channel:

Log events include:

• sms.sent - Successful send with provider, recipient, message_id
• sms.failed - Failed send with provider, recipient, error details
• sms.bulk_failed - Bulk send failure
• sms.delivery_report - Incoming delivery report

All log entries are scrubbed of sensitive data (API keys, tokens, secrets).

Testing & Mocking

Faking HTTP Requests

Use Laravel's HTTP faking to test SMS sending without making real API calls:

Faking Events

Test that events are dispatched correctly:

Testing Templates

Testing Cost Estimation

Troubleshooting

Common Issues

SMS not sending:

1. Check your provider credentials in .env
2. Verify SMS_PROVIDER is set to a valid provider name
3. Check SMS_LOG_CHANNEL=log and review Laravel logs for errors
4. Ensure your queue worker is running if using queued sending

Validation errors:

• Phone numbers must have at least 9 digits and no more than 15 (E.164)
• Messages cannot be empty or exceed SMS_MAX_MESSAGE_LENGTH (default: 918 characters)
• Phone numbers are auto-formatted; supported formats: 0712345678, 254712345678, +254712345678

Rate limiting:

• If messages are being queued unexpectedly, check rate_limit config per provider
• Use Sms::rateLimiter()->remainingAttempts('provider') to check remaining quota
• Clear the limiter with Sms::rateLimiter()->clear('provider')

Webhooks not receiving reports:

• Ensure SMS_WEBHOOKS_ENABLED=true
• Verify your webhook URL is publicly accessible (use ngrok for local dev)
• Check webhook secrets match what the provider expects
• Review logs for 403 responses (signature validation failures)

Fallback not activating:

• Fallback only triggers on ProviderException, not on validation errors
• Verify the fallback provider name matches a configured driver
• Fallback is limited to 1 level -- the fallback provider's own fallback is not used
• Check logs for "SMS fallback activated" messages

Cost estimation showing 0:

• Ensure per_segment_cost is configured for the provider in config/sms.php
• Cost is 0.0 by default if not configured

Debug Logging

Enable debug-level structured logging:

Testing

License

MIT License. See LICENSE for details.