Laravel Ussd

Build Ussd (Unstructured Supplementary Service Data) applications with laravel without breaking a sweat.

Installation

You can install the package via composer:

$ composer require sparors/laravel-ussd

Laravel Ussd provides zero configuration out of the box. To publish the config, run the vendor publish command:

$ php artisan vendor:publish --provider="Sparors\Ussd\UssdServiceProvider" --tag=config

Usage

Creating States

We provide a ussd artisan command which allows you to quickly create new states.

php artisan ussd:state Welcome

Creating Nested States

Linux/Unix

php artisan ussd:state Airtime/Welcome

Windows

php artisan ussd:state Airtime\Welcome

Welcome state class generated

<?php

namespace App\Http\Ussd;

use Sparors\Ussd\State;

class Welcome extends State
{
    protected function beforeRendering(): void
    {
       //
    }

    protected function afterRendering(string $argument): void
    {
        //
    }
}

Creating Menus

Add your menu to the beforeRendering method

<?php

namespace App\Http\Ussd;

use Sparors\Ussd\State;

class Welcome extends State
{
    protected function beforeRendering(): void
    {
       $this->menu->text('Welcome To LaravelUSSD')
            ->lineBreak(1)
            ->line('Select an option')
            ->listing(['Airtime Topup', 'Data Bundle', 'TV Subscription', 'ECG/GWCL', 'Talk To Us'])
            ->lineBreak(2);
            ->line('Powered by Sparors')
    }

    protected function afterRendering(string $argument): void
    {
        //
    }
}

Creating Decisions

Add your decision to the afterRendering method

<?php

namespace App\Http\Ussd;

use App\Http\Ussd\GetRecipientNumber;
use App\Http\Ussd\MaintenanceMode;
use App\Http\Ussd\Error;
use Sparors\Ussd\State;

class Welcome extends State
{
    protected function beforeRendering(): void
    {
       $this->menu->text('Welcome To Laravel Ussd')
            ->lineBreak(1)
            ->line('Select an option')
            ->listing(['Airtime Topup', 'Data Bundle', 'TV Subscription', 'ECG/GWCL', 'Talk To Us'])
            ->lineBreak(2);
            ->line('Powered by Sparors')
    }

    protected function afterRendering(string $argument): void
    {
        // If input is equal to 1, 2, 3, 4 or 5, render the appropriate state
        $this->decision->equal('1', GetRecipientNumber::class)
                       ->equal('2', MaintenanceMode::class)
                       ->equal('3', MaintenanceMode::class)
                       ->equal('4', MaintenanceMode::class)
                       ->equal('5', MaintenanceMode::class)
                       ->any(Error::class);
    }
}

Using States

Import the welcome state class and pass it to the setInitialState method

<?php

namespace App\Http\Controllers;

use Sparors\Ussd\Facades\Ussd;
use App\Http\Ussd\Welcome;

class UssdController extends Controller
{
	public function index()
	{
	    $ussd = Ussd::machine()
	        ->setInput('1')
	        ->setNetwork('MTN')
	        ->setSessionId('12350')
	        ->setPhoneNumber('0545112466')
	        ->setInitialState(Welcome::class);

	    return response()->json($ussd->run());
	}
}

Running the application

You can use the development server the ships with Laravel by running, from the project root:

php artisan serve

You can visit http://localhot:8000 to see the application in action.

Enjoy!!!

Documentation

You'll find the documentation on https://sparors.github.io/ussd-docs.

Testing

$ composer test

Change log

Please see the changelog for more information on what has changed recently.

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, please email isaacsai030@gmail.com instead of using the issue tracker.

Credits

• Sparors Inc
• All Contributors

License

MIT. Please see the license file for more information.