Download the PHP package rayzenai/laravel-sms without Composer

Laravel SMS

A comprehensive Laravel package for sending SMS messages through various providers with Filament admin panel integration.

Features

• 📱 Send single and bulk SMS messages
• 🔄 Multiple SMS provider support (HTTP, Twilio, SwiftSMS, etc.)
• 📊 Filament admin panel integration for SMS management
• 👥 User selection for bulk SMS - send to existing users in your database
• 🔍 Automatic duplicate phone number detection and handling
• 📝 SMS logs and tracking
• ⚡ Rate limiting and retry mechanisms
• 🛡️ Built-in error handling and logging
• 🇳🇵 Nepali phone number validation
• 📦 Bulk SMS optimization with provider-specific batch sending
• ✨ Modern UI with improved toggles and form layout

Requirements

• PHP 8.2 or higher
• Laravel 11, 12, or 13
• Filament 5.0 (for admin panel features)

Installation

You can install the package via composer:

Configuration

Step 1: Publish Configuration

Publish the configuration file:

This will publish a laravel-sms.php configuration file to your config directory.

Step 2: Run Migrations

Run the migrations to create the necessary database tables:

Step 3: Configure Environment Variables

Add the following variables to your .env file:

Selecting a provider is just SMS_PROVIDER=<name>. The name maps to an entry in the providers array of config/laravel-sms.php. You can also switch per message at runtime with Sms::provider('aakash')->send(...).

Step 4: Configure User Model Integration (Optional)

If you want to enable sending SMS to users from your database, update the config file:

Usage

Phone Number Validation

The package now supports validation for Nepali phone numbers:

• Numbers must start with +977
• Must have 10 digits after the country code (e.g., +977 9801002468)

Example Validation Rule:

Basic Usage

Sending a Single SMS

Sending Bulk SMS

Sending to a User (or any Model)

Implement the HasSmsNumber contract and add the Smsable trait. The model decides how its number is derived — a column, an accessor, concatenating a country code, or returning null when the record can't be reached. No config, no assumptions about your schema.

Then send with the model itself:

• smsPhoneNumber() returning null means "unreachable": $user->sendSMS() is a safe no-op (returns null), and bulk sends skip that recipient automatically.
• A single Sms::to($user)->send() throws if the user resolves to no number; bulk filters them out.

Choosing a Provider at Runtime

The active provider comes from SMS_PROVIDER, but you can override it per message without touching config:

Checking Provider Balance / Credit

Providers that support it (e.g. AakashSMS) implement ReportsBalance. Ask the active provider — or a specific one — for its remaining credit:

Calling balance() on a provider that doesn't support it throws an UnsupportedFeatureException.

Using in Controllers

API Endpoints

The package provides the following API endpoints. They spend real SMS credits, so they require authentication. Both are registered behind config('laravel-sms.routes.middleware'), which defaults to:

Publish the config to swap the guard for whichever one your application uses — but keep an auth guard and a rate limiter in the list. If your application only ever sends through the Sms facade, drop the endpoints entirely:

Requests that fail are logged via report(); the response body carries only a generic message, so provider errors are not exposed to the caller.

Send Single SMS

Endpoint: POST /api/sms/send

Request Body:

Response:

Send Bulk SMS

Endpoint: POST /api/sms/send-bulk

Request Body:

Response:

Filament Integration

Step-by-Step Filament Setup

1. Install Filament (if not already installed)

2. Register the SMS Plugin

In Filament v5, you'll need to register the LaravelSmsPlugin in your Panel service provider:

3. Access the SMS Management

Once you have registered the plugin (or the SentMessageResource directly), you will see SMS Management → Sent Messages in the admin panel navigation.

1. Navigate to your Filament admin panel (typically /admin)
2. Open Sent Messages under SMS Management to browse/filter the log.
3. Click Send SMS (the resource's create button) to compose and send.

Sending lives on the resource's create screen — creating a "sent message" is sending one. There is no separate page to register. With Filament Shield, access is gated by the resource's Create permission (composing/sending) and ViewAny/View (reading the log) — no bespoke page permission needed.

Filament Features:

Send SMS (the "create" screen):

• Single SMS sending with phone number validation
• Bulk SMS sending to multiple recipients
• User selection mode for bulk SMS
  • Select users from your database
  • Automatic duplicate phone number detection
  • Shows which users share the same phone number
  • "Select All" option for all unique phone numbers
  • Displays count of unique numbers vs total users
• Real-time character count for messages (160 character limit)
• Toggle between single and bulk SMS modes
• Toggle between manual entry and user selection (for bulk mode)
• Nepali phone number validation (+977 format)
• Success/error notifications

Sent Messages list/view:

• View all sent SMS messages in a table
• Filter by status (pending, sent, failed, delivered)
• Filter by date range
• Search by recipient or message content
• View detailed SMS information
• Bulk delete functionality
• Export SMS logs

Customizing Filament Resources

If you need to customize the Filament resources, you can publish them:

Then modify the published resources in app/Filament/Resources/SentMessageResource.php.

Advanced Configuration

Providers Registry

Every provider is registered by name in config/laravel-sms.php. Each entry names the class and carries that provider's own credentials. SMS_PROVIDER selects which one is active by default.

The manager instantiates the active provider and injects its config array (plus the shared timeout and default_sender). Adding a provider is just a class plus an entry here — see Creating Custom SMS Providers.

Rate Limiting

Rate limiting is enabled by default. Configure it in your .env:

Logging

All SMS activities are logged when enabled:

You can create a custom log channel in config/logging.php:

Creating Custom SMS Providers

Adding a provider takes two steps: write a class and register it. That's the whole extension surface.

1. Write the provider

Extend AbstractSmsProvider and implement send(). You get the shared $config, $timeout, and $sender, plus a default sendBulk() that loops send() — so a simple provider only implements one method.

• Native bulk? Override sendBulk() and return ['status' => ..., 'batch_id' => ..., 'recipients_count' => ..., 'response' => ...].
• Report credit/balance? Also implements ReportsBalance and add a balance() method returning ['credit' => ..., 'response' => ...] — then Sms::balance() works for your provider.

2. Register it

Then set SMS_PROVIDER=custom (or use Sms::provider('custom') per message).

Testing

Credits

• Rayzen AI

License

The MIT License (MIT). Please see License File for more information.