PHPackages                             yasser-elgammal/lara-sms - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. yasser-elgammal/lara-sms

ActiveLibrary[Mail & Notifications](/categories/mail)

yasser-elgammal/lara-sms
========================

A package to sending SMS for laravel projects.

1.0.0(6mo ago)1617MITPHP

Since Oct 23Pushed 6mo agoCompare

[ Source](https://github.com/YasserElgammal/lara-sms)[ Packagist](https://packagist.org/packages/yasser-elgammal/lara-sms)[ RSS](/packages/yasser-elgammal-lara-sms/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (2)Versions (3)Used By (0)

Lara SMS Gateway Package
========================

[](#lara-sms-gateway-package)

A powerful and flexible Laravel SMS gateway package with support for multiple providers
(**MobilySms**, **Msegat**, **Dreams**, **Taqnyat**, **Jawaly**, **Infobip**, **Twilio**, **Vonage**, **Unifonic**, **SMS Misr**) intelligent fallback mechanisms, and a fluent builder pattern for clean message construction.

---

Features
--------

[](#features)

- ✅ **Multiple Gateway Support** - Twilio, Vonage, SMS Misr, Jawaly (easily add more)
- ✅ **Strategy Pattern** - Pluggable gateway architecture
- ✅ **Fluent Builder Pattern** - Clean, intuitive message construction
- ✅ **Fallback Strategies** - Try All, Fail Fast, custom ordering
- ✅ **Intelligent Retries** - Automatic retries for transient failures
- ✅ **Error Differentiation** - Retryable vs Non-retryable errors
- ✅ **Clean DTOs** - Structured message and result objects
- ✅ **Configuration Driven** - All settings in config files
- ✅ **Laravel Facade** - Easy access from anywhere
- ✅ **Comprehensive Logging** - Full audit trail of all attempts
- ✅ **Metadata Support** - Attach custom data to messages

---

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require yasser-elgammal/lara-sms
```

### Step 2: Publish Configuration

[](#step-2-publish-configuration)

```
php artisan vendor:publish --tag=sms-config
```

### Step 3: Add Environment Variables

[](#step-3-add-environment-variables)

Add needed sms gateways to your `.env` file:

```
# --------------------------------------------------------------------------
# SMS Default Gateway
# --------------------------------------------------------------------------
#
# You can set the default SMS gateway in your .env file using:
#
#   SMS_DEFAULT_GATEWAY=mobilysms
#
# Supported gateway names:
#   - infobip
#   - vonage
#   - jawaly
#   - smsmisr
#   - msegat
#   - mobilysms
#   - dreams
#   - taqnyat
#   - twilio
#
# Example:
#   SMS_DEFAULT_GATEWAY=msegat
#

# ===============================
# 🌐 GENERAL SMS SETTINGS
# ===============================
SMS_DEFAULT_GATEWAY=jawaly
SMS_FALLBACK_STRATEGY=fail_fast
SMS_TIMEOUT=30
SMS_RETRY_ATTEMPTS=3
SMS_RETRY_DELAY=1000

# ===============================
# 🇸🇦 SAUDI GATEWAYS
# ===============================

# 🇸🇦 MobilySms GATEWAY
MOBILY_USERNAME=your_username
MOBILY_PASSWORD=your_password
MOBILY_SENDER=YourApp
MOBILY_BASE_URL=https://www.mobilysms.net

# 🇸🇦 MSEGAT GATEWAY
MSEGAT_USERNAME=your_msegat_username
MSEGAT_API_KEY=your_msegat_api_key
MSEGAT_USER_SENDER=auth-mseg
MSEGAT_MSG_ENCODING=UTF8

# 🇸🇦 DREAMS GATEWAY
DREAMS_USERNAME=your_dreams_username
DREAMS_SECRET_KEY=your_dreams_secret_key
DREAMS_SENDER=YourApp

# 🇸🇦 TAQNYAT GATEWAY
TAQNYAT_TOKEN=your_taqnyat_token
TAQNYAT_SENDER_ID=YourApp

# 🇸🇦 JAWALY GATEWAY
JAWALY_API_KEY=your_jawaly_api_key
JAWALY_API_SECRET=your_jawaly_api_secret
JAWALY_SENDER=YourApp

# ===============================
# 🌍 INTERNATIONAL GATEWAYS
# ===============================

# 🌍 INFOBIP
INFOBIP_API_KEY=
INFOBIP_SENDER=
INFOBIP_BASE_URL=

# 🇺🇸 TWILIO GATEWAY
TWILIO_SID=your_twilio_sid
TWILIO_TOKEN=your_twilio_token
TWILIO_FROM=+1234567890

# 🌍 VONAGE GATEWAY
VONAGE_API_KEY=your_vonage_api_key
VONAGE_API_SECRET=your_vonage_api_secret
VONAGE_SENDER=YourApp

# 🌍 UNIFONIC
UNIFONIC_APP_SID=
UNIFONIC_TOKEN=
UNIFONIC_SENDER=
UNIFONIC_BASE_URL=

# ===============================
# 🇪🇬 EGYPT GATEWAYS
# ===============================

# 🇪🇬 SMS MISR GATEWAY
SMSMISR_USERNAME=your_smsmisr_username
SMSMISR_PASSWORD=your_smsmisr_password
SMSMISR_SENDER=YourApp
```

### Step 4: Clear Cache

[](#step-4-clear-cache)

```
php artisan config:cache
```

---

Quick Start
-----------

[](#quick-start)

### Simplest Usage - Quick Send

[](#simplest-usage---quick-send)

```
use YasserElgammal\LaraSms\Facades\LaraSms;
use Illuminate\Support\Facades\Log;

// Send a quick SMS
$result = LaraSms::quickSend('201234567890', 'Hello World!');

if ($result->success) {
    Log::debug("SMS sent! Message ID: {$result->messageId}");
} else {
    Log::debug("Failed: {$result->error}");
}
```

Usage Guide
-----------

[](#usage-guide)

### Basic Usage

[](#basic-usage)

#### 1. Quick Send (One-liner)

[](#1-quick-send-one-liner)

```
use YasserElgammal\LaraSms\Facades\LaraSms;

LaraSms::quickSend('201234567890', 'Your OTP is 123456');
```

#### 2. Builder with Basic Fields

[](#2-builder-with-basic-fields)

```
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello World!')
    ->send();
```

#### 3. Builder with All Fields

[](#3-builder-with-all-fields)

```
LaraSms::builder()
    ->to('201234567890')
    ->from('MyApp')
    ->text('Your verification code is: 123456')
    ->send();
```

---

### Builder Pattern - Complete Reference

[](#builder-pattern---complete-reference)

The builder provides a fluent interface for constructing SMS messages with full control over sending options.

#### Setting Recipients and Messages

[](#setting-recipients-and-messages)

```
LaraSms::builder()
    ->to('201234567890')           // Set recipient (required)
    ->from('MyApp')                 // Set sender (optional)
    ->text('Hello!')                // Set message text (required)
    ->send();
```

#### Adding Metadata

[](#adding-metadata)

Attach custom data to your SMS:

```
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello World !')
    ->metadata([
        'language' => '2', // 1=Eng, 2=Arabic, 3=Unicode
        'environment' => '1', //1=Live, 2=Test
        'delay_until' => '2025-12-31 23:59:00' // example if message scheduling
    ])->gateway('smsmisr')->send();
```

#### Controlling Fallback Strategies

[](#controlling-fallback-strategies)

```
// Strategy 1: Try All Gateways
// Attempts all gateways until one succeeds
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->useFallback(FallbackStrategy::TRY_ALL)
    ->send();

// Or use helper
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->tryAll()
    ->send();
```

```
// Strategy 2: Fail Fast (Default)
// Stops on first non-retryable error
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->useFallback(FallbackStrategy::FAIL_FAST)
    ->send();

// Or use helper
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->failFast()
    ->send();
```

#### Gateway Selection and Ordering

[](#gateway-selection-and-ordering)

```
// Use specific gateway order
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->gateways(['jawaly', 'twilio', 'vonage'])  // Custom order
    ->send();

// Use only one gateway (no fallback)
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->gateway('jawaly')  // Only Jawaly, fail if it fails
    ->send();

// Restrict to specific gateways
LaraSms::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->gateways(['jawaly', 'twilio'])  // Skip others
    ->send();
```

**Behavior:**

- Stops immediately on non-retryable error (auth, invalid phone, etc.)
- Continues on retryable errors (timeout, server 5xx)
- More cost-effective
- Faster failure response

#### Custom Gateway Order

[](#custom-gateway-order)

```
// Prefer cheaper gateway (local) first
SMS::builder()
    ->to('201234567890')
    ->text('Marketing message')
    ->gateways(['smsmisr'])  // Local only
    ->send();

// Regional preference
SMS::builder()
    ->to('201234567890')
    ->text('Important message')
    ->gateways(['jawaly', 'smsmisr', 'twilio'])  // Local first, then international
    ->send();

// Quality vs Cost trade-off
SMS::builder()
    ->to('201234567890')
    ->text('Verification code')
    ->gateways(['twilio', 'vonage', 'jawaly'])  // Premium first, fallback to budget
    ->send();
```

---

### Error Handling

[](#error-handling)

#### Understanding SmsResult

[](#understanding-smsresult)

```
$result = SMS::builder()
    ->to('201234567890')
    ->text('Hello!')
    ->send();

// Result properties:
$result->success;      // bool - Did it succeed?
$result->messageId;    // ?string - ID from gateway
$result->gateway;      // ?string - Which gateway succeeded
$result->error;        // ?string - Error message if failed
$result->attempts;     // array - All attempts made

// Example usage
use Illuminate\Support\Facades\Log;

if ($result->success) {
    Log::debug("✅ Message sent via {$result->gateway}");
    Log::debug("📧 Message ID: {$result->messageId}");
} else {
    Log::debug("❌ All gateways failed");
    Log::debug("📋 Error: {$result->error}");

    // Check attempts
    foreach ($result->attempts as $attempt) {
        Log::debug(
            $attempt['gateway'] . ': ' .
            ($attempt['success'] ? '✓' : '✗ ' . $attempt['error'])
        );
    }
}
```

---

🤝 Contributing
--------------

[](#-contributing)

Pull requests are welcome! For major changes, please open an issue first to discuss what you’d like to modify.

---

⚖️ License
----------

[](#️-license)

MIT © 2025 **Yasser Elgammal**

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance66

Regular maintenance activity

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

201d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/fd677b48e144f6f9b0c90bb236b60e721212c3d74a4e2226fb93c4cac7475260?d=identicon)[YasserElgammal](/maintainers/YasserElgammal)

---

Top Contributors

[![YasserElgammal](https://avatars.githubusercontent.com/u/35766609?v=4)](https://github.com/YasserElgammal "YasserElgammal (3 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/yasser-elgammal-lara-sms/health.svg)

```
[![Health](https://phpackages.com/badges/yasser-elgammal-lara-sms/health.svg)](https://phpackages.com/packages/yasser-elgammal-lara-sms)
```

###  Alternatives

[tijsverkoyen/css-to-inline-styles

CssToInlineStyles is a class that enables you to convert HTML-pages/files into HTML-pages/files with inline styles. This is very useful when you're sending emails.

5.8k505.3M227](/packages/tijsverkoyen-css-to-inline-styles)[minishlink/web-push

Web Push library for PHP

1.9k12.0M53](/packages/minishlink-web-push)[laravel-notification-channels/twilio

Provides Twilio notification channel for Laravel

2587.7M12](/packages/laravel-notification-channels-twilio)[spatie/url-signer

Generate a url with an expiration date and signature to prevent unauthorized access

4422.3M16](/packages/spatie-url-signer)[mattketmo/email-checker

Throwaway email detection library

2742.0M5](/packages/mattketmo-email-checker)[laravel-notification-channels/discord

Laravel notification driver for Discord.

2371.3M11](/packages/laravel-notification-channels-discord)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)