PHPackages                             mastertek/iran-sms-laravel - 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. mastertek/iran-sms-laravel

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

mastertek/iran-sms-laravel
==========================

A simple and convenient way to send SMS through Iranian SMS providers

1.1.0(2w ago)03MITPHPPHP ^8.2

Since May 24Pushed 1w agoCompare

[ Source](https://github.com/Mr-robot-r/iran-sms-laravel)[ Packagist](https://packagist.org/packages/mastertek/iran-sms-laravel)[ Docs](https://github.com/Mr-robot-r/iran-sms-laravel)[ RSS](/packages/mastertek-iran-sms-laravel/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (7)Versions (2)Used By (0)

Iran SMS Laravel
================

[](#iran-sms-laravel)

[![](https://camo.githubusercontent.com/3f53b264e07cc536b60e8cf87200475c5b1890c3349254ddaecef1e7a57726b8/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4972616e253230534d532532304c61726176656c2e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d616d7961766172692532466972616e2d736d732d6c61726176656c267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d53656e642b534d532b7468726f7567682b4972616e69616e2b534d532b70726f7669646572732b776974682b65617365266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)](https://camo.githubusercontent.com/3f53b264e07cc536b60e8cf87200475c5b1890c3349254ddaecef1e7a57726b8/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4972616e253230534d532532304c61726176656c2e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d616d7961766172692532466972616e2d736d732d6c61726176656c267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d53656e642b534d532b7468726f7567682b4972616e69616e2b534d532b70726f7669646572732b776974682b65617365266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)

[![PHP Version](https://camo.githubusercontent.com/f6ff66d798900e93804039016f36f5c8930b05eb6bfed80efcf44cac1fb2d75c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616d7961766172692f6972616e2d736d732d6c61726176656c)](https://camo.githubusercontent.com/f6ff66d798900e93804039016f36f5c8930b05eb6bfed80efcf44cac1fb2d75c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616d7961766172692f6972616e2d736d732d6c61726176656c)[![Laravel Version](https://camo.githubusercontent.com/900d56192fa622b9d0cddeabb8bb9f4bde1e6fb9ddd8d5428e2e657d20879fc4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f616d7961766172692f6972616e2d736d732d6c61726176656c2f696c6c756d696e617465253246636f6e7472616374733f6c6162656c3d4c61726176656c)](https://camo.githubusercontent.com/900d56192fa622b9d0cddeabb8bb9f4bde1e6fb9ddd8d5428e2e657d20879fc4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f616d7961766172692f6972616e2d736d732d6c61726176656c2f696c6c756d696e617465253246636f6e7472616374733f6c6162656c3d4c61726176656c)[![Packagist Version](https://camo.githubusercontent.com/154b5346b2559b033d0c4eef6167b400a58a046a731b0fcfba163b799d250877/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d7961766172692f6972616e2d736d732d6c61726176656c3f6c6162656c3d76657273696f6e)](https://camo.githubusercontent.com/154b5346b2559b033d0c4eef6167b400a58a046a731b0fcfba163b799d250877/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d7961766172692f6972616e2d736d732d6c61726176656c3f6c6162656c3d76657273696f6e)[![Packagist Downloads](https://camo.githubusercontent.com/8ce946104b05f522b5db7443740c3127014b040e5fca54c3c9dcb5f02034217a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d7961766172692f6972616e2d736d732d6c61726176656c)](https://camo.githubusercontent.com/8ce946104b05f522b5db7443740c3127014b040e5fca54c3c9dcb5f02034217a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d7961766172692f6972616e2d736d732d6c61726176656c)[![Packagist License](https://camo.githubusercontent.com/2b1e86db60c6fadfdce3bda84f2da87410eb04062f15a998ed2481d8074ff5de/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d7961766172692f6972616e2d736d732d6c61726176656c)](https://camo.githubusercontent.com/2b1e86db60c6fadfdce3bda84f2da87410eb04062f15a998ed2481d8074ff5de/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d7961766172692f6972616e2d736d732d6c61726176656c)[![Tests](https://camo.githubusercontent.com/956b424a8b3745d8677432552c6a6f442eee0ca1f50306837fa96b5a9afbfb2d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616d7961766172692f6972616e2d736d732d6c61726176656c2f74657374732e796d6c3f6c6162656c3d7465737473)](https://camo.githubusercontent.com/956b424a8b3745d8677432552c6a6f442eee0ca1f50306837fa96b5a9afbfb2d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616d7961766172692f6972616e2d736d732d6c61726176656c2f74657374732e796d6c3f6c6162656c3d7465737473)

A simple and convenient way to send SMS through Iranian SMS providers.

To view the Persian documentation, please refer to [README\_FA.md](./docs/README_FA.md).

برای مشاهده راهنمای فارسی، لطفاً به فایل [README\_FA.md](./docs/README_FA.md) مراجعه کنید.

Requirements
------------

[](#requirements)

- PHP version `8.2` or higher
- Laravel `^11.44`, `^12.4`, or `^13.0`

List of Available SMS Providers
-------------------------------

[](#list-of-available-sms-providers)

Provider Name (EN)Provider Name (FA)Provider WebsiteProvider KeyVersionSMS.irاس ام اس دات آی آر[sms.ir](https://sms.ir/)`sms_ir`1.0.0Meli Payamakملی پیامک[melipayamak.com](https://www.melipayamak.com/)`meli_payamak`1.0.0Payam Resanپیام رسان[payam-resan.com](https://payam-resan.com/)`payam_resan`1.0.0Kavenegarکاوه نگار[kavenegar.com](https://kavenegar.com/)`kavenegar`1.0.0Faraz SMSفراز اس ام اس[farazsms.com](https://farazsms.com/)`faraz_sms`1.0.0Raygan SMSرایگان اس ام اس[raygansms.com](https://raygansms.com/)`raygan_sms`1.0.0Web One SMSوب وان[webone-sms.com](https://webone-sms.com/)`web_one`1.0.0Amoot SMSپیامک آموت[amootsms.com](https://www.amootsms.com/P)`amoot_sms`1.0.0Fara Payamakفراپیامک[farapayamak.ir](https://farapayamak.ir/)`fara_payamak`1.0.0Ghasedakقاصدک[ghasedak.me](https://ghasedak.me/)`ghasedak`1.0.0Asanakآسانک[asanak.com](https://asanak.com/)`asanak`1.0.0Medianaمدیانا[mediana.ir](https://mediana.ir/)`mediana`1.0.0ParsGreenپارس گرین\[\]`parsgreen`1.0.0Caution

Providers have different rules for sending SMS messages. Please check [providers\_note\_en.md](./docs/providers_note_en.md).

Table of Content
----------------

[](#table-of-content)

- [Installation](#installation)
- [Publish Vendor File](#publish-vendor-files)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Creating an SMS Instance](#creating-an-sms-instance)
    - [Changing the Sender Number at Runtime](#changing-the-sender-number-at-runtime)
    - [Automatic Logging](#automatic-logging)
    - [Sending SMS](#sending-sms)
    - [Checking Sending Status](#checking-sending-status)
    - [Get Credit](#get-credit)
- [Working with Queues and Notifications](#working-with-queues-and-notifications)
- [Testing](#testing)
- [Contributing](#contributing)

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

[](#installation)

To install the package via Composer, run:

```
composer require mastertek/iran-sms-laravel
```

Publish Vendor Files
--------------------

[](#publish-vendor-files)

### Publish All Files

[](#publish-all-files)

To publish all vendor files (config and migrations):

```
php artisan iran-sms:install
```

**Note:** To create tables from migrations:

```
php artisan migrate
```

### Publish Specific Files

[](#publish-specific-files)

To publish only the config file:

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

To publish only the migration file:

```
php artisan vendor:publish --tag=iran-sms-migrations
```

**Note:** To create tables from migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

### Single Provider Setup

[](#single-provider-setup)

To configure a single SMS provider, add the following to your `.env` file:

```
# Default provider
SMS_PROVIDER=

# If provider uses username and password
SMS_USERNAME=
SMS_PASSWORD=

# If provider uses an API token
SMS_TOKEN=

# Default sender number
SMS_FROM=
```

**Note:** For the `SMS_PROVIDER`, refer to the `Provider Key` column in the [List of Available SMS Providers](#list-of-available-sms-providers).

### Multiple Provider Setup

[](#multiple-provider-setup)

After publishing the config file (see [Publish Vendor Files](#publish-vendor-files)), you can customize the environment variable names for each provider you want to use. Then, define those variables in your `.env` file.

For example, to configure the `trez` provider:

```
'providers' => [

    'trez' => [
        'username' => env('SMS_TREZ_USERNAME', ''), // Previously: env('SMS_USERNAME', '')
        'password' => env('SMS_TREZ_PASSWORD', ''), // Previously: env('SMS_PASSWORD', '')
        'token'    => env('SMS_TREZ_TOKEN', ''),    // Previously: env('SMS_TOKEN', '')
        'from'     => env('SMS_TREZ_FROM', ''),     // Previously: env('SMS_FROM', '')
    ],

    // Repeat this structure for any other providers you want to configure
],
```

Define the corresponding variables in your `.env` file:

```
SMS_TREZ_USERNAME=
SMS_TREZ_PASSWORD=
SMS_TREZ_TOKEN=
SMS_TREZ_FROM=

# Repeat for other providers you defined
```

Usage
-----

[](#usage)

**Note:** This package supports fluent method chaining like `Sms::provider()->otp()->log()->send();`, but for simplicity, this manual demonstrates usage with separate instances.

### Creating an SMS Instance

[](#creating-an-sms-instance)

You can create an SMS instance using the facade provided by the package:

```
use Mastertek\IranSms\Facades\Sms;

// Using the default provider
$sms = Sms::otp(string $phone, string $message);
$sms = Sms::text(string|array $phones, string $message);
$sms = Sms::pattern(string|array $phones, string $patternCode, array $variables);

// Using a specific provider
$sms = Sms::provider(string $provider)->otp(...);
$sms = Sms::provider(string $provider)->text(...);
$sms = Sms::provider(string $provider)->pattern(...);
```

**Note:** For the `$provider` name, refer to the `Provider Key` column in the [List of Available SMS Providers](#list-of-available-sms-providers).

### Changing the Sender Number at Runtime

[](#changing-the-sender-number-at-runtime)

To send an SMS from a number other than the default `SMS_FROM`, use the `from()` method when building your message:

```
$sms->from(string $from);
```

### Automatic Logging

[](#automatic-logging)

You can chain log configurations on your SMS instance before sending.

To help keep your code clean and logging consistent, especially when managing SMS sending from a central location, this package provides convenient methods to configure logging behavior based on the SMS type and sending status.

**Note:** Before using any logging features, make sure to create the necessary tables. (See [Publish Vendor Files](#publish-vendor-files).)

#### Log Based on SMS Type

[](#log-based-on-sms-type)

```
$sms->log(bool $log = true);           // Log any type of SMS
$sms->logOtp(bool $log = true);        // Log only OTP messages
$sms->logText(bool $log = true);       // Log only text messages
$sms->logPattern(bool $log = true);    // Log only pattern messages
```

#### Log Based on Sending Status

[](#log-based-on-sending-status)

**Note:** These methods implicitly enable logging. If you use them without calling a `log*()` method first, `log(true)` will be applied automatically.

```
$sms->logSuccessful(); // Log only if the message was sent successfully
$sms->logFailed();     // Log only if the message failed to send
```

#### Make Your Log Behavior Fluent

[](#make-your-log-behavior-fluent)

You can chain the logging methods to define custom logic fluently:

```
// Example: Log all message types except OTPs, only if they are sent successfully
$sms->log()->logOtp(false)->logSuccessful();
```

#### Prune Old Logs

[](#prune-old-logs)

To help keep your log table clean, this package provides an Artisan command to prune old log records. You can schedule this command using [Laravel's task scheduler](https://laravel.com/docs/12.x/scheduling#scheduling-artisan-commands)

Example: Delete logs created before 30 days ago

```
use Illuminate\Support\Facades\Schedule;

Schedule::command('iran-sms:prune-logs --days=30')->daily();
```

### Sending SMS

[](#sending-sms)

To send the SMS:

```
$sms->send();
```

**Note:** This method throws an exception if a client or server error occurs. See the `throw` method in [HTTP Client](https://laravel.com/docs/12.x/http-client#throwing-exceptions).

### Checking Sending Status

[](#checking-sending-status)

To check the status after sending:

```
$sms->successful(); // bool
$sms->failed();     // bool

// Get the error message (returns null if successful)
$sms->error();      // string|null
```

### Get Credit

[](#get-credit)

To Retrieve your current credit balance (in Rials):

```
use Mastertek\IranSms\Facades\Sms;

// Default provider credit balance
$credit = Sms::credit();                                // int

// Specific provider credit balance
$credit = Sms::provider(string $provider)->credit();    // int
```

**Note:** For the `$provider` name, refer to the `Provider Key` column in the [List of Available SMS Providers](#list-of-available-sms-providers).

Working with Queues and Notifications
-------------------------------------

[](#working-with-queues-and-notifications)

### Queues

[](#queues)

To send an SMS instance using [queues](https://laravel.com/docs/12.x/queues), you can [create an SMS instance](#creating-an-sms-instance) and dispatch it to a job where you call the `send()` method. You can use the `Mastertek\IranSms\Contracts\Sms` interface as a constructor type-hint.

**Note:** It's recommended to configure log options here to keep your code clean and consistent.

Example:

```
namespace App\Jobs;

use Mastertek\IranSms\Contracts\Sms;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

final class SendSms implements ShouldQueue
{
    use Queueable;

    /**
     * Create a new job instance.
     */
    public function __construct(private Sms $sms) {}

    /**
     * Execute the job.
     */
    public function handle(): void
    {
        $this->sms->log(true)->send();
    }
}
```

### Notifications

[](#notifications)

To send SMS using [notifications](https://laravel.com/docs/12.x/notifications), define a `toSms` method in your notification class and return an SMS instance. Also, include `Mastertek\IranSms\Channels\SmsChannel` in the `via` method.

**Note:** The `toSms` method must return an SMS instance with your log setup (if desired). The channel will handle sending it.

Example:

```
namespace App\Notifications;

use Mastertek\IranSms\Channels\SmsChannel;
use Mastertek\IranSms\Facades\Sms;
use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;

final class MyNotification extends Notification
{
    use Queueable;

    /**
     * Get the notification channels.
     */
    public function via(object $notifiable): array
    {
        return [SmsChannel::class];
    }

    /**
     * Get the SMS representation of the notification.
     */
    public function toSms(object $notifiable)
    {
        return Sms::text($notifiable->phone, 'Hi')->logFailed();
    }
}
```

Testing
-------

[](#testing)

This package provides fluent methods to fake and test SMS sending:

```
use Mastertek\IranSms\Facades\Sms;

/**
 * Fake the default provider to return successful response
 */
Sms::fake();

/**
 * Fake specific providers to return successful responses
 *
 * Note: Use `default` as the provider key to target the default provider
 */
Sms::fake([/* provider keys */]);

/**
 * Equivalent to the above (explicit success definition)
 */
Sms::fake([...], Sms::successfulRequest());

/**
 * Fake providers to return failed responses
 *
 * Optional: custom error message and error code
 */
Sms::fake([...], Sms::failedRequest(string $errorMessage = 'Error Message', string|int $errorCode = 0));

/**
 * Fake providers to throw a ConnectionException
 */
Sms::fake([...], Sms::failedConnection());

/**
 * Define different behaviors per provider
 */
Sms::fake([
    'provider_one' => Sms::successfulRequest(),
    'provider_two' => Sms::failedRequest(),
    'provider_three' => Sms::failedConnection(),
]);
```

**Note:** Defining both *global behavior* and *per-provider behaviors* together is not allowed in a single call. Use one strategy per `fake()` call.

**Note:** If you define multiple behaviors for the same provider, the last one will override the previous definitions.

Contributing
------------

[](#contributing)

Thank you for considering contributing to the Iran SMS Laravel! The contribution guide can be found in the [CONTRIBUTING.md](CONTRIBUTING.md). This file provides a step-by-step guide to easily add a new driver (SMS provider) to the package.

License
-------

[](#license)

**Iran SMS Laravel** was created by **[Reza Vahidi](https://github.com/Mr-robot-r/)** under the **[MIT license](https://opensource.org/licenses/MIT)**.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance97

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91% 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

Unknown

Total

1

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0b6bfe7752b80d1d94c794567fbee39bc6e740dfc550f499f6c1a9424f8f4e53?d=identicon)[mrrobot\_r](/maintainers/mrrobot_r)

---

Top Contributors

[![amyavari](https://avatars.githubusercontent.com/u/56732838?v=4)](https://github.com/amyavari "amyavari (132 commits)")[![Mr-robot-r](https://avatars.githubusercontent.com/u/45331794?v=4)](https://github.com/Mr-robot-r "Mr-robot-r (13 commits)")

---

Tags

laravelsmsiraniran-sms-laravelmastertek

###  Code Quality

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/mastertek-iran-sms-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/mastertek-iran-sms-laravel/health.svg)](https://phpackages.com/packages/mastertek-iran-sms-laravel)
```

###  Alternatives

[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.3M41](/packages/spatie-laravel-pdf)[spatie/laravel-health

Monitor the health of a Laravel application

88011.3M149](/packages/spatie-laravel-health)[vormkracht10/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24655.3k](/packages/vormkracht10-laravel-mails)[xammie/mailbook

Laravel Mail Explorer

482519.8k1](/packages/xammie-mailbook)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3913.7k](/packages/rawilk-profile-filament-plugin)[backstage/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24675.5k8](/packages/backstage-laravel-mails)

PHPackages © 2026

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