README

Laravel Iran Sms

This is a Laravel Package for Sms Senders Integration. This package supports Laravel 8+, all tests passed for laravel 8, 9, 10, 11 and 12!

Benefits of this package:

• Multiple drivers
• Support create custom drivers
• Have Fake build in driver, it can send success or failure sms/voice call message. (Can use in development and testing modes)
• Store sms reports in database
• Have a tools in only development mode in http://localhost/sms/get-sms-list (Your frontend developer can use it for access latest sms send with fake driver for example needs to otp codes, when he/she is developing some parts like forgot password)

• English documents
• داکیومنت فارسی

List of contents

• Laravel Iran Sms
• List of contents
• List of available drivers
  • Install
  • .env file
  • How to use
    • Working with Facades
    • Working with Channels (use laravel notification classes)
    • Create custom drivers:
    • Events
  • Contributing
  • Credits
  • License

List of available drivers

• fake sms sender : (Both: Voice call/Sms)
• Avanak : (Voice call driver)
• Ghasedak : (Sms)
• Kavenegar : (Sms)
• Magfa : (Sms)
• Sms Online : (Sms)

Note: for using each of them check config file and use the needed env in your env file like username/password or api key depend on witch driver you use.

Note: to use magfa/sms online/avanak you should install php ext-soap.

Important: Some drivers require additional packages. Install the driver package you need:

# For Kavenegar driver
composer require kavenegar/laravel

.env file for each driver:

fake sms sender

// Use in your local .env file

SMS_DRIVER=fake

// It's optional if you want you can set a number

FAKE_SENDER_NUMBER=101010

Ghasedak

// Use in your production .env file if you want to use Ghasedak as default sms driver

SMS_DRIVER=ghasedak

// Your Ghasedak account api key

GHASEDAK_API_KEY=your_api_key

// Your Ghasedak sender number (line number)

GHASEDAK_SENDER_NUMBER=3000xxxxx

Kavenegar

// Use in your production .env file if you want to use Kavenegar as default sms driver

SMS_DRIVER=kavenegar

// Your kavenegar account api key

KAVENEGAR_API_KEY=fsdf452fd

Magfa

// Use in your production .env file if you want to use Magfa as default sms driver

SMS_DRIVER=magfa

SMS_MAGFA_USERNAME=your magfa user name

SMS_MAGFA_PASSWORD=your magfa password

SMS_MAGFA_DOMAIN=your magfa domain

SMS_MAGFA_SENDER_NUMBER=your number in magfa you want to send sms with it

Sms Online

// Use in your production .env file if you want to use Sms Online as default sms driver

SMS_DRIVER=smsonline

SMS_ONLINE_USERNAME=your smsonline user name

SMS_ONLINE_PASSWORD=your smsonline password

SMS_ONLINE_SENDER_NUMBER=your number in smsonline you want to send sms with it

Avanak (voice caller)

// Use in your production .env file if you want to use Sms Online as default sms driver

VOICE_CALL_DRIVER=avanak

VOICE_AVANAK_USERNAME=your avanak user name

VOICE_AVANAK_PASSWORD=your avanak password

you can create your own custom drivers if it does not exist in the list, read the Create custom drivers section.

Install

Via Composer

$ composer require hooman-mirghasemi/laravel-iran-sms

Publish Vendor Files

It is optional and only if you need you can publish vendor files by these commands:

• publish configuration files:

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

• publish views for customization:

php artisan vendor:publish --tag=iran-sms-views

• publish migration:

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

.env file

You can use SMS_DRIVER env for set default sms driver. (in local don't change it, by default it set fake driver)

And also can use VOICE_CALL_DRIVER env. it is like SMS_DRIVER, but for voice call.

How to use

There are two option of using this package:

1- use Facades

2- use Channels

Working with Facades

You can use Sms or VoiceCall facades in anywhere of your code like this:

// At the top of the file.
use HoomanMirghasemi\Sms\Facades\Sms;
...

Sms::to('+989121234567')->message('your sms text')->send();

//Also you can set driver in run time:
Sms::driver('magfa')->to('+989121234567')->message('your sms text')->send();

available methods:

• to: set the mobile number should get sms.
• message: the text message can be a simple string or object of a class implement HoomanMirghasemi\Sms\Contracts\Message interface
• send: send the message.

Working with Channels (use laravel notification classes)

Make a laravel notification class, set via SmsChannel like this code:

// At the top of the file.
use HoomanMirghasemi\Sms\Channels\SmsChannel;
use HoomanMirghasemi\Sms\Contracts\Message\Message;
...

public function __construct(public SomeModel $someModel)
{
    $this->via = SmsChannel::class;
}

public function toSms(User $notifiable)
{
    $smsMessage = 'make your sms text ';
    // only if using kavehnegar set the pattern name
    $pattern = 'kavenagarMyPatternName';

    $message = new Message($smsMessage);
    $message->useTemplateIfSupports(
        $pattern,
        [
            'token1' => 'test',
            'token10' => $notifiable->name,
            'token20' => $this->family
        ]   
    );

    return Sms::to($notifiable->mobile)
        ->message($message);
}

Change condition of showing sms list page

By default when your laravel application is in production mode this page will response 404. You can now control this via .env file:

# Set to true to hide the SMS list page (default: true in production)
DONT_SHOW_SMS_LIST_PAGE=true

Or if you want more control, publish the config file and customize the condition:

// default config is:
'dont_show_sms_list_page_condition' => env(
    'DONT_SHOW_SMS_LIST_PAGE',
    env('APP_ENV', 'production') == 'production'
),

// you can check any thing like domain:
'dont_show_sms_list_page_condition' => env('APP_ENV') == 'production' || config('app.url') == 'https://yourproductiondomain.com',

now if you forgot to set app.env to production or temporary change it, it will be safe and return 404.

Create custom drivers:

Option A:

We welcome your participation, Create your driver and send a pull request.

Option A: This package is using strategy design pattern and laravel Manager class. so you can easily make your driver like this:

<?php

namespace App;

use HoomanMirghasemi\Sms\Abstracts\Driver;

class MyCustomDriver extends Driver
{
    public static bool $successSend = true;

    public function __construct(protected array $settings)
    {
        $this->from = data_get($this->settings, 'from');
    }

    public function send(): bool
    {
        // write api of sending sms by your custom provider

        return parent::send();
    }
    
    public function getBalance(): string
    {
         // write api of getting account balance from your custom provider
         return $balance;
    }
}

And register it into manager class in any of your service providers class like this:

$smsManager = app('sms');

$smsManager->extend('myCustomDriver', function ($app) {
    $setting = ['from' => '22336'];
    return new MyCustomDriver($setting);
});


// or using laravel ioc

$this->app->bind(MyCustomDriver::class, function () {
    $setting = ['from' => '22336'];
    return new MyCustomDriver($config);
});

$smsManager->extend('myCustomDriver', function ($app) {
    return $this->container->make(MyCustomDriver::class);
});

// or you can publish config file and add setting of your driver into it. then:

$this->app->bind(MyCustomDriver::class, function () {
    $config = config('sms.drivers.mycustomdriver') ?? [];
    return new MyCustomDriver($config);
});

$smsManager->extend('myCustomDriver', function ($app) {
    return $this->container->make(MyCustomDriver::class);
});

Events

You can listen for this event

• SmsSentEvent: Occurs when sms send. (the package use it to collect report into db)

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Credits

• Hooman Mirghasemi
• All Contributors

License

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