Capturing Incoming Data

InstantUssd is using an event-driven architecture. Whenever a USSD request is received, InstantUssd triggers a UssdEvent containing details about the the last served menu_id. This event is then processed by a listener of the same name as the last served menu_id.

Terminology

• A Listener is any PHP callback that reacts to a UssdEvent.
• An EventManager aggregates listeners for the UssdEvent.

UssdEventManager

UssdEventManager class aggregates all UssdEvent listeners.

namespace InstantUssd;

use InstantUssd\Listeners;
use Bitmarshals\InstantUssd\UssdEventManager as InstantUssdEventManager;
use Bitmarshals\InstantUssd\Listeners\UssdEventListener;

/**
 * Description of UssdEventManager
 * 
 * Aggregates USSD event listeners for the different USSD screens 
 *
 * @author David Bwire
 */
class UssdEventManager extends InstantUssdEventManager {

    public function __construct(array $ussdMenusConfig) {
        parent::__construct($ussdMenusConfig);

        // HOME PAGE example
        // example - attaching an event
        $this->attach('Bitmarshals\InstantUssd', 'home_instant_ussd', function($e) use ($ussdMenusConfig) {
            // instantiate your CUSTOM listener class
            $listener             = new Listeners\HomeInstantUssd($e, $ussdMenusConfig);
            $continueUssdHops     = true;
            $appendNavigationText = true;
            // TRIGGER IT
            return call_user_func([$listener, "onTrigger"], $continueUssdHops, $appendNavigationText);
        });

        // DEFAULT LISTENER - Helps with quick setup
        $defaultListener = function($e) use ($ussdMenusConfig) {
            $continueUssdHops     = true;
            $appendNavigationText = true;
            $listener             = new UssdEventListener($e, $ussdMenusConfig);
            return call_user_func([$listener, "onTrigger"], $continueUssdHops, $appendNavigationText);
        };
        // REGISTER - SELF
        $this->attach("Bitmarshals\InstantUssd", 'your_menu_id', $defaultListener);
    }

}

UssdEventListener

This is where processing of incoming data happens.

You'll extend Bitmarshals\InstantUssd\Listeners\UssdEventListener class to build custom UssdEventListeners. You'll have to override Bitmarshals\InstantUssd\Listeners\UssdEventListener::captureIncomingData in order to process incoming data.

namespace InstantUssd\Listeners;

use Bitmarshals\InstantUssd\Listeners\UssdEventListener;

/**
 * Description of HomeInstantUssd
 *
 * @author David Bwire
 */
class HomeInstantUssd extends UssdEventListener {

    public function captureIncomingData() {

        $ussdEvent = $this->ussdEvent;

        // client's phone number
        $phoneNumber     = $ussdEvent->getParam('phone_number');
        // session_id
        $sessionId       = $ussdEvent->getParam('session_id');
        // service code
        $serviceCode     = $ussdEvent->getParam('service_code');
        // incoming response
        $latestResponse  = $this->latestResponse;
        // menu sending in data
        $lastServedMenu  = $this->lastServedMenu;
        // configuration of menu sending in data
        $menuConfig      = $this->menuConfig;
        // entire ussd_menus config
        $ussdMenusConfig = $this->ussdMenusConfig;
        // all responses sent in this session
        $allResponses    = $ussdEvent->getNonExtraneousValues();
        // very first response
        $firstResponse   = $ussdEvent->getFirstResponse();
        // your controller instance
        $yourController  = $ussdEvent->getInitializer();
        // service locator
        $serviceLocator  = $ussdEvent->getServiceLocator();
        // InstantUssd instance
        $instantUssd     = $ussdEvent->getInstantUssd();
        // save to db; etc
        return;
    }

}

⇐ Looping Menus | Sample Application ⇒