wasiliana/laravel-sdk

This package is built to make it easier to interact with Wasiliana Api for Laravel developers.


Keywords
laravel, LaravelSdk
License
MIT

Documentation

Wasiliana Laravel Sdk

Latest Version on Packagist Total Downloads Build Status StyleCI

Introduction

This package is built for Laravel developers to easen interaction with Wasiliana Rest Api.

😃 Installation

composer require wasiliana/laravel-sdk

This command will install the latest version of the package.

⚙️ Configuration

You can use php artisan wasiliana:install to copy the distribution configuration file to your app's config directory:

php artisan wasiliana:install

This will copy wasiliana.php settings file in your config directory.

Settings available in config file published.

return [
    'sms' => [
        'service_1' => [
            'name' => 'test',
            'from' => env('SMS_SERVICE_1_SENDER_ID', 'WASILIANA'),
            'key' => env('SMS_SERVICE_1_API_KEY', null)
        ],
    ],
    'airtime' => [
        'service_1' => [
            'name' => 'testAirtime',
            'key' => env('AIRTIME_SERVICE_1_API_KEY', null)
        ],
    ]
];

In a scenario where you have more than one service; the structure will appear as below.

return [
    'sms' => [
        'service_1' => [
            'name' => 'testSms',
            'from' => env('SERVICE_1_SENDER_ID', 'WASILIANA'),
            'key' => env('SERVICE_1_API_KEY', null)
        ],
        'service_2' => [
            'name' => 'testSms2',
            'from' => env('SERVICE_2_SENDER_ID', 'WASILIANA'),
            'key' => env('SERVICE_2_API_KEY', null)
        ]
    ],
    'airtime' => [
        'service_1' => [
            'name' => 'testAirtime',
            'key' => env('AIRTIME_SERVICE_1_API_KEY', null)
        ]
    ]
];

🔥 Usage

1. Sms

Import the Sms Facade at the top;

use Wasiliana\LaravelSdk\Facades\Sms;

Example 1: request

Using default service configured in wasiliana config file

$response = Sms::to(['2547XXXXXYYY', '2547XXXXXZZZ']) //use an array for multiple recipients
    ->message('This cold...Mayoooo!!!') // your message
    ->send(); // fire request

// OR

$response = Sms::send('2547XXXXXYYY', 'This cold...Mayoooo!!!'); //compose message, add recipients and send

Example 2: request

Using a different service configured in wasiliana config file

$response = Sms::to('2547XXXXXYYY')
    ->message('This a test dispatch.')
    ->service('service_2')
    ->send();

// OR

$response = Sms::service('service_2')->send(['2547XXXXXYYY', '2547XXXXXZZZ'], 'This a send test using a different service.'); // for multiple recipients use an array

Example 3: Request

Defing a custom message_uid prefix

$response = Sms::to(['2547XXXXXYYY', '2547XXXXXZZZ'])
    ->message('This cold...Mayoooo!!!')
    ->prefix('notification') // custom message_uid prefix 
    ->send();

// OR

$response = Sms::send('2547XXXXXYYY', 'This cold...Mayoooo!!!', 'notification');

Example 4: Response

After every request a response in array format is returned

// success response
// a confirmation from Wasiliana that the request has been received.
Array
(
    [status] => success
    [data] => Successfully Dispatched the sms to process
    [message_uid] => conversation_id_20220831154811
)

// error response
Array
(
    [status] => error
    [message] => Error in the data provided
    [data] => Array
        (
            [0] => The message field is required.
        )

)

The confirmation of whether the message was delivered successfully, to a number, or not is delivered to the callback configured in your account.

2. Airtime

Import the Sms Facade at the top;

use Wasiliana\LaravelSdk\Facades\Airtime;

Example 1: Request

Using default service configured in wasiliana config file

$response = Airtime::amount(10)->phone('0720XXXYYY')->send();

Example 2: Request

Send same amount of airtime to multiple numbers at once

$response = Airtime::amount(10)->->phone(['0723XXXYYY', '0711YYYXXX'])->send();

Example 3: Request

Using a different service configured in wasiliana config file

$response = Airtime::amount(10)->phone('0720XXXYYY')->service('service_2')->send();

Example 4: Response

Success and error responses retirned

// success response
Array
(
    [status] => success
    [message] => Ksh. 10 has been toped up sucessfuly
)

// error response
Array
(
    [status] => error
    [message] => Error in the data provided
    [data] => Array
        (
            [0] => The phone field is required.
        )

)

Array
(
    [status] => error
    [message] => You do not have sufficient airtime
    [data] => 
)

Environment variables

You can update your .env to have the SENDER_ID and API_KEY values instead of having them in the config file;

SMS_SERVICE_1_SENDER_ID=<Sender_Id>
SMS_SERVICE_1_API_KEY=<Api_Key>

AIRTIME_SERVICE_1_API_KEY=<Api_Key>

NOTE: You don't have to define a SENDER_ID in the .env when you are using the shared WASILIANA SENDER_ID

License

MIT. Please see the license file for more information.