Download the PHP package itxshakil/laravel-fast2sms without Composer

Laravel Fast2SMS is a first-class Laravel package for sending SMS and WhatsApp messages via the Fast2SMS API. It provides a fluent, type-safe API, Laravel Notifications support, queue integration, a powerful fake for testing, and a rich exception hierarchy — so you can build reliable messaging features with confidence.

The most complete Fast2SMS integration for Laravel:

• SMS + OTP + DLT + WhatsApp
• Queue + Notifications
• Prevents wasting SMS money in production

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Cost-Saving Features
• Sending SMS
• Sending WhatsApp Messages
• Laravel Notifications
• Queuing
• Events & Listeners
• Testing
• Artisan Commands
• Phone Validation
• Error Handling
• Upgrade Guide
• Contributing
• License

Features

• 📱 SMS — Quick, OTP, and DLT routes with flash and bulk support
• 💬 WhatsApp — Text, image, document, location, and interactive messages
• 🔔 Laravel Notifications — SmsChannel and WhatsAppChannel out of the box
• ⚡ Queue support — Dispatch sends as background jobs with per-send overrides
• 🧪 Fake & assert — Fast2sms::fake() with 16 rich assertion helpers
• 🚨 Typed exceptions — AuthenticationException, RateLimitException, ApiException, and more
• 💰 Cost-saving features — Recipient deduplication (on by default), dedup guard, throttle, balance gate, batch splitting, invalid-recipient stripping
• 🔍 PHPStan level 6 — Fully typed, zero suppressions
• 🛠 Artisan commands — Balance monitor, WABA details, event discovery, IDE helper
• 🇮🇳 Indian phone validation — Fast2smsPhone rule class

Requirements

Installation

Install via Composer:

The package auto-discovers its service provider. Publish the config file:

Add your API key to .env:

Full installation guide: docs/installation.md

Quick Start

Configuration

After publishing, edit config/fast2sms.php. All keys can be set via environment variables:

Use FAST2SMS_DRIVER=log in local/testing environments to log messages instead of making real API calls.

Full configuration reference: docs/configuration.md

Cost-Saving Features

Most cost-saving features are opt-in and disabled by default — enable only what you need. Recipient deduplication is the exception: it is enabled by default.

Recipient Deduplication

Automatically removes duplicate numbers from the recipient list before every send. This is enabled by default — set to false to disable:

Invalid Recipient Stripping

Validates each number against the Fast2smsPhone rule, logs a warning for each removed number, and throws ValidationException if all numbers are invalid:

Idempotency / Dedup Guard

Prevents the same message being sent twice within a configurable window (applies to both SMS and WhatsApp):

Throws DuplicateSendException on a repeated identical call within the TTL.

Send-Rate Throttle

Limits the number of sends per minute using a sliding-window cache counter (applies to both SMS and WhatsApp):

Throws ThrottleExceededException when the limit is reached.

Balance Gate

Checks your wallet balance before every send and fires LowBalanceDetected. When abort is true, throws InsufficientBalanceException to prevent the API call (applies to both SMS and WhatsApp):

Batch Splitting

Splits large recipient lists into chunks and issues one API call per chunk:

SMS Credit Estimation

Use SmsMessage helpers to estimate cost before sending:

Full cost-saving features guide: docs/cost-saving-features.md

Full upgrade guide: UPGRADING.md

Sending SMS

Quick SMS

OTP SMS

DLT SMS

Flash SMS

Multiple Recipients

Full SMS guide: docs/sms-guide.md

Sending WhatsApp Messages

Phone number format for WhatsApp: Always include the country code prefix (e.g. 919876543210 for India — 91 + 10-digit number). This differs from SMS, which accepts 10-digit numbers directly.

Text

Image

Document

Location

Interactive

Convenience alias: Fast2sms::viaWhatsApp($to) is shorthand for Fast2sms::whatsapp()->to($to). Both are public API; whatsapp()->to(...) is the canonical form.

Full WhatsApp guide: docs/whatsapp.md

Laravel Notifications

SMS Notification

Add routeNotificationForFast2sms() to your notifiable model (e.g. User) to tell the channel which number to use:

WhatsApp Notification

Add routeNotificationForWhatsapp() to your notifiable model (e.g. User) to tell the channel which number to use:

Full notifications guide: docs/notifications.md

Queuing

Enable queuing in .env:

Then send as usual — the package dispatches a background job automatically:

Override queue settings per-send:

Full queuing guide: docs/queuing.md

Events & Listeners

The package dispatches the following events:

Listening to Events

Discover All Events

Full events guide: docs/events.md

Testing

Use Fast2sms::fake() to prevent real HTTP calls in tests:

WhatsApp Assertions

Combined Assertions

Stopping the Fake

Fast2sms::fake() stores the fake in a static property. Call Fast2sms::stopFaking() in tearDown to restore real HTTP behaviour when managing the fake lifecycle manually in plain PHPUnit tests:

Note: When using Orchestra Testbench or Laravel's full boot cycle the container is re-booted between tests, so stopFaking() is usually not required.

Full testing guide: docs/testing.md

Artisan Commands

Phone Validation

Use the Fast2smsPhone rule to validate Indian mobile numbers:

The rule validates 10-digit Indian mobile numbers starting with 6–9.

Error Handling

All exceptions extend Fast2smsException, so you can catch broadly or specifically:

Exception Reference

Full error handling guide: docs/error-handling.md

Full API reference: docs/api-reference.md

Upgrade Guide

Upgrading from v1.x? See UPGRADING.md for the full migration guide, including:

• New exception types to catch
• Readonly DTO changes
• Fake assertion API changes
• Deprecated method renames (content() → withContent(), to() → withNumbers())
• Response type-hint updates

Also available as an extended guide: docs/upgrade-v1-to-v2.md

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

The MIT License (MIT). Please see LICENSE.md for more information.

Made with ❤️ for the Laravel community · Shakil Alam