Upgrading from v1.x to v2.0

This guide provides a detailed walkthrough for migrating from Laravel Fast2SMS v1.x to v2.0. For a quick summary, see UPGRADING.md.

Breaking Changes Summary

Step-by-Step Migration

Step 1 — Update the Package

composer require itxshakil/laravel-fast2sms:^2.0

Step 2 — Update Exception Catches

v2.0 introduces a typed exception hierarchy. Update your catch blocks to use specific exception types:

Before (v1.x):

use Shakil\Fast2sms\Exceptions\Fast2smsException;

try {
    Fast2sms::quick(...);
} catch (Fast2smsException $e) {
    // handle all errors
}

After (v2.0):

use Shakil\Fast2sms\Exceptions\AuthenticationException;
use Shakil\Fast2sms\Exceptions\Fast2smsException;
use Shakil\Fast2sms\Exceptions\RateLimitException;

try {
    Fast2sms::quick(...);
} catch (AuthenticationException $e) {
    // 401 — bad API key
} catch (RateLimitException $e) {
    // 429 — slow down
} catch (Fast2smsException $e) {
    // everything else
}

Catching Fast2smsException still works as a catch-all — no change required if you prefer broad handling.

Step 3 — Update DTO Usage

DTOs are now readonly class. You can no longer mutate properties after construction:

Before (v1.x):

$params = new SmsParameters(...);
$params->message = 'Updated message'; // worked in v1

After (v2.0):

// Create a new instance instead
$params = new SmsParameters(message: 'Updated message', ...);

Step 4 — Update Fake Assertions

The fake API has been completely rewritten with typed, descriptive assertion methods:

Before (v1.x):

Fast2sms::assertSent();    // only generic method available
Fast2sms::assertNotSent(); // generic — no typed channel variants

After (v2.0):

// SMS-specific (new in v2)
Fast2sms::assertSmsSent();
Fast2sms::assertSmsNotSent();
Fast2sms::assertSmsSentTo('9876543210');
Fast2sms::assertSmsSentWithMessage('OTP');
Fast2sms::assertSmsSentCount(1);

// Combined
Fast2sms::assertNothingSent();
Fast2sms::assertSentCount(2);

// Low-level generic (still available in v2) — closure receives raw array payload
Fast2sms::assertSent(fn (array $message) => $message['numbers'] === ['9876543210']);

assertSent() survived into v2 as a low-level escape hatch that accepts a closure for custom assertions across both SMS and WhatsApp sends. assertNotSent() also survived into v2 as a generic counterpart — use assertSmsNotSent() or assertWhatsAppNotSent() for typed, channel-specific assertions.

Step 5 — Update SmsMessage Methods

The old fluent methods are deprecated and will be removed in v3.0.0:

Before (v1.x):

SmsMessage::create('Hello')
    ->content('Hello')
    ->route(SmsRoute::QUICK)
    ->to('9876543210');

After (v2.0):

SmsMessage::create('Hello')
    ->withRoute(SmsRoute::QUICK)
    ->withNumbers('9876543210');

What Stays the Same

• The Fast2sms facade and core method signatures (quick(), otp(), dlt(), whatsapp(), etc.)
• Config file structure and all environment variable names
• SmsChannel notification channel
• Fast2smsPhone validation rule
• All Artisan commands
• Queue job behaviour

New in v2.0 — Cost-Saving Features

v2.0 ships six opt-in features to reduce unnecessary API calls and protect your SMS budget. They are all disabled by default and require no changes to existing code.

New exception classes to catch (all extend Fast2smsException):

• Shakil\Fast2sms\Exceptions\DuplicateSendException
• Shakil\Fast2sms\Exceptions\InsufficientBalanceException
• Shakil\Fast2sms\Exceptions\ThrottleExceededException

See Cost-Saving Features for full documentation, config keys, env variables, and usage examples.

See Also

• UPGRADING.md — quick reference
• CHANGELOG.md — full change log
• Cost-Saving Features
• API Reference
• Error Handling
• Testing