ghasedak/laravel-notification

Ghasedak SMS Notifications Channel for Laravel

1.0.0 2020-10-13 13:09 UTC

Requires

• ghasedak/laravel: ~1.0.0

MIT

• Elham Salimi
• Ghasedak Team

README

Ghasedak Laravel Notification

Easy-to-use SDK for implementing Ghasedak SMS Notification in your Laravel projects.
Explore the docs »

Web Service Documents · REST API . Report Bug · Request Feature

Table of Contents

• Install
  • Setting up Ghasedak service
  • Add environmental variables to .env file
• Usage
  • Parameters of GhasedakSimpleSms() method
  • Sending Notifications
  • Example
• One-Time Passwords (OTP)
  • Parameters
  • Example
• Licence

Install

The easiest way to install is by using Composer:

composer require ghasedak/laravel-notification

Composer is a dependency manager for PHP which allows you to declare the libraries your project depends on, and it will manage (install/update) them for you. If you are not familiar with Composer, you can read its documentations and download it via getcomposer.org.

Setting up Ghasedak service

To setup Ghasedak service properly you need an API key. To get that you should have a Ghasedak account. Register and get your API key.
Then you need to set simple configuration by adding following code to your services.php file.

// config/services.php

'ghasedak' => [
    'api_key' => env("GHASEDAK_API_KEY"),
    'linenumber' => env('LINE_NUMBER', null),
]

Add environmental variables to .env file

As final step of installing the package, you must add previousley defined variables to .env file.

GHASEDAK_API_KEY=your_api_key
LINE_NUMBER=your_line_number

Don't forget to replace your_api_key and your_line_number with actual information.

Usage

To use notifications in Laravel you should first create one with simple Artisan command:

php artisan make:notification SendSimpleNotification

Then you can use the channel in your via() method inside the notification you just created:

namespace App\Http\Notifications;

use Ghasedak\LaravelNotification\GhasedakChannel;
use Ghasedak\LaravelNotification\GhasedakSimpleSms;
use Illuminate\Notifications\Notification;


class SendSms extends Notification
{
    public function via($notifiable)
    {
        return [GhasedakChannel::class];
    }

    public function toSms($notifiable)
    {
        // send simple message
        return (new GhasedakSimpleSms)->message('Hello, World!')->linenumber('300xxxxx');
    }
}

As default phone field is set for receptor, but you can add routeNotificationForSms method to your Notifiable model to customize phone number:

public function routeNotificationForSms()
{
    return $this->phone;
}

Parameters of GhasedakSimpleSms() method

Parameter	Required	Description	Type	Example
message	Yes	Text to be sent	string	Hello, World!
receptor	Yes	The number of the recipient(s) of the message (seperated by comma ,).	string	09111111111
linenumber	No	The number of the sender of the message, which, if not specified, will be selected from your dedicated lines with a higher priority.(If you do not have a dedicated line, you must specify the linenumber)	string	5000222
senddate	No	The exact date and time of sending the message based on Unix time, if not specified, the message will be sent instantly.	string	1508144471

Sending Notifications

Notifications may be sent using the notify method of the Notifiable trait:

use Ghasedak\LaravelNotification\GhasedakSimpleSms;

$user->notify(new GhasedakSimpleSms());

Example

Here is a sample code for SendSimple Notification with support for custom parameters instead of using a fixed template:

// App\Http\Notifications\SendSimpleNotification.php

namespace App\Http\Notifications;

use Ghasedak\LaravelNotification\GhasedakChannel;
use Ghasedak\LaravelNotification\GhasedakSimpleSms;
use Illuminate\Notifications\Notification;

class SendSimpleNotification extends Notification
{
    public function __construct($params)
    {
        $this->params = $params;
    }

    public function via($notifiable)
    {
        return [GhasedakChannel::class];
    }

    public function toSms($notifiable)
    {
        return (new GhasedakSimpleSms)
            ->message($this->params['message'])
            ->linenumber($this->params['linenumber'])
            ->senddate($this->params['senddate'] ?? null)
            ->checkid($this->params['checkid'] ?? null);
    }
}

Send notification using notify method:

$arr = array(
            'message' => 'Hello, World!', // message 
            'linenumber' => '3000xxxxx', // choose a line number from your account
        );
$user->notify(new GhasedakSimpleSms($arr));

One-Time Passwords (OTP)

The One-Time-Password (OTP) Interface is used to perform a mobile authentication or to implement Two-Factor-Authentication (2FA).

$params = ['1', '2'];
$arr = array(
    'type' => 1,
    'template' => 'template',
    'params' => $params
);
$user->notify(new SendOTPNotification($arr));

Parameters

Parameter	Required	Description	Type	Example
receptor	Yes	The number of the recipient of the message.	string	09111111111
type	Yes	Set 1 to send text message and 2 to send voice message.	int	Hello, World!
template	Yes	The title of the template you created in your panel.	string	my-template
checkid	No	It is used to set a unique number for each SMS, and after sending the SMS, all the information of the sent message can be received with the status method.	string	2071
params	Yes	Array of parameters (You must enter at least one parameter).	array of strings	abcdef

Example

The following is a sample code for SendOTP Notification with support for custom parameters instead of using a fixed template:

// App\Http\Notifications\SendOTPNotification.php

namespace App\Http\Notifications;

use Ghasedak\LaravelNotification\GhasedakChannel;
use Ghasedak\LaravelNotification\GhasedakOTPSms;
use Illuminate\Notifications\Notification;

class SendOTPNotification extends Notification
{
    public function __construct($params)
    {
        $this->params = $params;
    }

    public function via($notifiable)
    {
        return [GhasedakChannel::class];
    }

    public function toSms($notifiable)
    {
        return (new GhasedakOTPSms)
            ->type($this->params['type'])
            ->template($this->params['template'])
            ->params($this->params['params']);
    }

}

Send notification using notify method:

$params = ['param1', 'param2', 'param3'];   
$arr = array(
    'type' => 1,      // 1 for text message and 2 for voice message
    'template' => 'my-template', // name of the template which you've created in you account
    'params' => $params, // parameters (supporting up to 10 parameters) 
);
$user->notify(new SendSimpleNotification($arr));

:)

License

Freely distributable under the terms of the MIT license.