README

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=ussd-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\States;

use Sparors\Ussd\State;

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

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

Creating Actions

Available from v2.0.0

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

php artisan ussd:action MakePayment

MakePayment action class generated

<?php

namespace App\Http\Ussd\Actions;

use Sparors\Ussd\Action;

class MakePayment extends Action
{
    public function run(): string
    {
        return ''; // The state after this
    }
}

Run your logic and return the next state's fully qualified class name

<?php

namespace App\Http\Ussd\Actions;

use Sparors\Ussd\Action;
use App\Http\Ussd\States\PaymentSuccess;
use App\Http\Ussd\States\PaymentError;

class MakePayment extends Action
{
    public function run(): string
    {
        $response = Http::post('/payment', [
            'phone_number' => $this->record->phoneNumber
        ]);

        if ($response->ok()) {
            return PaymentSuccess::class;
        }

        return PaymentError::class;
    }
}

Creating Menus

Add your menu to the beforeRendering method

<?php

namespace App\Http\Ussd\States;

use Sparors\Ussd\State;

class Welcome extends State
{
    protected function beforeRendering(): void
    {
        $name = $this->record->name;

        $this->menu->text('Welcome To Laravel USSD')
            ->lineBreak(2)
            ->line('Select an option')
            ->listing([
                'Airtime Topup',
                'Data Bundle',
                'TV Subscription',
                'ECG/GWCL',
                'Talk To Us'
            ])
            ->lineBreak(2)
            ->text('Powered by Sparors');
    }

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

Linking States with Decisions

Add your decision to the afterRendering method and link them with states

<?php

namespace App\Http\Ussd\States;

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

class Welcome extends State
{
    protected function beforeRendering(): void
    {
       $this->menu->text('Welcome To Laravel Ussd')
            ->lineBreak(2)
            ->line('Select an option')
            ->listing([
                'Airtime Topup',
                'Data Bundle',
                'TV Subscription',
                'ECG/GWCL',
                'Talk To Us'
            ])
            ->lineBreak(2)
            ->text('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)
                       ->between(2, 5, MaintenanceMode::class)
                       ->any(Error::class);
    }
}

Setting Initial State

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\States\Welcome;

class UssdController extends Controller
{
	public function index()
	{
	      $ussd = Ussd::machine()
	      ->setFromRequest([
		  'network',
		  'phone_number' => 'msisdn',
		  'sessionId' => 'UserSessionID',
		  'input' => 'msg'
	      ])
	      ->setInitialState(Welcome::class)
	      ->setResponse(function (string $message, string $action) {
		  return [
		      'USSDResp' => [
			  'action' => $action,
			  'menus' => '',
			  'title' => $message
		      ]
		  ];
	      });

	    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://localhost:8000 to see the application in action.

Enjoy!!!

Documentation

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

Testing

$ vendor\bin\phpunit

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

License

MIT. Please see the license file for more information.

sparors / laravel-ussd

Maintainers

Details