bitmarshals/instant-ussd

Library to help you rapidly develop and easily maintain your USSD applications.

Tuesday, July 24, 2018
by davidbwire
Repository
1 Watchers
2 Stars
45 Installations

PHP
1 Dependents
0 Suggesters
0 Forks
0 Open issues
24 Versions
73 % Grown

The README.md

InstantUssd

, _(*1)

InstantUssd is a USSD development library meant to provide you with a set of tools to easily and quickly build your own USSD applications., _(*2)

Goals

Speed up USSD development
Ease maintenance of USSD code

Features

Minimal coding (Provide USSD menus as config)
Automatic screen to screen navigation
Out of the box validation of user inputs
Ready solutions for complex USSD flows involving going back and forth, optional screens, looping set of screens, jumping from screen to screen and resuming timed-out USSD sessions

Installation

You will need PHP 5.6+ to install this package., _(*3)

You must then modify your composer.json file and run composer update to include the latest version of the package in your project., _(*4)

"require": {
    "bitmarshals/instant-ussd": "0.1.*"
}

Or you can run the composer require command from your terminal., _(*5)

composer require bitmarshals/instant-ussd

Once the package is installed the next step is dependant on which framework you're using., _(*6)

Usage

Initialization

Instantiate Bitmarshals\InstantUssd\InstantUssd passing in instant_ussd config and your controller instance., _(*7)

// Within your Controller
use Bitmarshals\InstantUssd\InstantUssd;
use Bitmarshals\InstantUssd\Response;
use InstantUssd\UssdValidator;

$instantUssdConfig = $config['instant_ussd'];
$instantUssd       = new InstantUssd($instantUssdConfig, $this);

Retrieve an instance of Bitmarshals\InstantUssd\UssdService from InstantUssd. This service provides utilities for parsing, packaging and handling incoming USSD data., _(*8)

$ussdParams  = $_POST;
$ussdText    = $ussdParams['text'];

// package incoming data in a format instant-ussd understands
$ussdService = $instantUssd->getUssdService($ussdText);
$ussdData    = $ussdService->packageUssdData($ussdParams);

Before proceeding further we need to run a few test to check if we should exit early, show home page (very first screen in a USSD flow) or navigate to the previous screen., _(*9)

Exit Check

// Should we EXIT early?
$isExitRequest = $ussdService->isExitRequest();
if ($isExitRequest === true) {
    return $instantUssd->exitUssd([])
                    ->send();
}

Home Page Check

// Should we SHOW HOME Page?
$isFirstRequest       = $ussdService->isFirstRequest();
$userRequestsHomePage = $ussdService->isExplicitHomepageRequest();
if ($isFirstRequest || $userRequestsHomePage) {
    // set your home page
    $yourHomePage = "home_instant_ussd";
    return $instantUssd->showHomePage($ussdData, $yourHomePage)
                    ->send();
}

Go Back Check

// Should we GO BACK?
$isGoBackRequest = $ussdService->isGoBackRequest();
if ($isGoBackRequest === true) {
    $resultGoBak = $instantUssd->goBack($ussdData);
    if ($resultGoBak instanceof Response) {
        return $resultGoBak->send();
    }
    // fallback to home page if previous menu missing
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}

Process Latest User Response

With the navigation checks complete, we should now handle the most recent user response., _(*10)

InstantUssd keeps a history of the screens we've visited during the current session. Let's retrieve the menu we sent to our user and its config settings., _(*11)

// get last served menu_id from database
$lastServedMenuId = $instantUssd->retrieveLastServedMenuId($ussdData);
// check we got last_served_menu
if (empty($lastServedMenuId)) {
    // fallback to home page
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}
// Get $lastServedMenuConfig. The config will used in validation trigger below
// Set $ussdData['menu_id'] to know the specific config to retreive
$ussdData['menu_id']  = $lastServedMenuId;
$lastServedMenuConfig = $instantUssd->retrieveMenuConfig($ussdData);
// check we have $lastServedMenuConfig
if (empty($lastServedMenuConfig)) {
    // fallback to home page
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}

Validate Latest Response

// VALIDATE incoming data
$validator = new UssdValidator($lastServedMenuId, $lastServedMenuConfig);
$isValid   = $validator->isValidResponse($ussdData);
if (!$isValid) {
    // handle invalid data
    $nextScreenId = $lastServedMenuId;
    // essentially we're re-rendering the menu with error message
    return $instantUssd->showNextScreen($ussdData, $nextScreenId)
                    ->send();
}

Capture Validated Data

// send valid data FOR PROCESSING. Save to db, etc
// this step should give us a pointer to the next screen
$nextScreenId = $instantUssd->processIncomingData(
        $lastServedMenuId, $ussdData);
if (empty($nextScreenId)) {
    // we couldn't find the next screen
    return $instantUssd->showError($ussdData, "Error. "
                            . "Next screen could not be found.")
                    ->send();
}

Show Next Screen

// we have the next screen; SHOW NEXT SCREEN
return $instantUssd->showNextScreen($ussdData, $nextScreenId)
                ->send();

Sample Application

Check out InstantUssd App., _(*12)

License

BSD 3-Clause License, _(*13)

Documentation

Please refer to our extensive Wiki documentation for more information., _(*14)

The Versions

24/07 2018

dev-master

9999999-dev https://github.com/bitmarshals/instant-ussd

Library to help you rapidly develop and easily maintain your USSD applications.

library instant-ussd

Library to help you rapidly develop and easily maintain your USSD applications.

bitmarshals/instant-ussd

The README.md

InstantUssd

Goals

Features

Installation

Usage

Initialization

Navigation Checks

Exit Check

Home Page Check

Go Back Check

Process Latest User Response

Retrieve Last Served Menu and Its Config

Validate Latest Response

Capture Validated Data

Show Next Screen

Sample Application

License

Documentation

The Versions

dev-master

The Requires

by David Bwire

0.3.8

The Requires

by David Bwire

0.3.7

The Requires

by David Bwire

0.3.6

The Requires

by David Bwire

0.3.5

The Requires

by David Bwire

0.3.4

The Requires

by David Bwire

0.3.3

The Requires

by David Bwire

0.3.2

The Requires

by David Bwire

0.3.1

The Requires

by David Bwire

0.3.0

The Requires

by David Bwire

0.2.6

The Requires

by David Bwire

0.2.5

The Requires

by David Bwire

0.2.4

The Requires

by David Bwire

0.2.3

The Requires

by David Bwire

0.2.0

The Requires

by David Bwire

0.1.7

The Requires

by David Bwire

dev-add-license-1

The Requires

by David Bwire

0.0.1

The Requires

by David Bwire

0.1.6

The Requires

by David Bwire