norris1z/hubtel-ussd

An unofficial php library for processing Hubtel USSD requests

Hubtel USSD

Based on Hubtel's USSD API, _(*1)

About

This package helps you to build maintainable and scalable USSD applications by breaking down your "long switch" statement USSD application into modules, _(*2)

Getting Started

Check out this link to know how you can acquire a USSD code from Hubtel., _(*3)

Installing

Install the package from composer, _(*4)

composer require norris1z/hubtel-ussd

Usage

Setup a route to respond to all Hubtel's requests., _(*5)

Note that Hubtel sends no csrf tokens hence disable csrfprotection for that route., _(*6)

For Laravel, add the route to the except array in the VerifyCsrfToken middleware., _(*7)

Hubtel\USSD\Request::class is a class which represents the request from Hubtel. It has methods for all the parameters listed on Hubtel's Documentation Page., _(*8)

View Source Request.php, _(*9)

Hubtel\USSD\Response::class is a class which represents the response sent to Hubtel. It has methods for all the parameters listed on Hubtel's Documentation Page., _(*10)

View Source Response.php, _(*11)

RequestTypes::class has two properties, RESPONSE and RELEASE for indicating the type of response in a sequence., _(*12)

    $response = Response::createInstance('Hello Hubtel, i want a response',RequestTypes::RESPONSE);
    $response = Response::createInstance('Hello Hubtel, end the sequence',RequestTypes::RELEASE);

USSD::class is a class with one static method process which takes two parameters a Request (an instance of Hubtel\USSD\Reqeust) and an array of sequence (any class that implements the Hubtel\USSD\SequenceInterface);, _(*13)

     USSD::process(/** An instance of Hubtel\USSD\Request **/,[
        new Sequence1(),
        new Sequence2(),
        new Sequence3()
    ])->toArray();

All seqeunces must have implement the SequenceInterface and hence have a handle method and must return an instance of Hubtel\USSD\Response (Response). The USSD::process method automagically injects a Request parameter into the handle method of each sequence. This Request is an instace of Hubtel\USSD\Request which grants access to all properties and methods in the request., _(*14)

    //Sequence1.php
    use Hubtel\USSD\Request;
    use Hubtel\USSD\RequestTypes;
    use Hubtel\USSD\Response;
    use Hubtel\USSD\SequenceInterface;

    class Sequence1 implements SequenceInterface
    {

        public function handle(Request $request)
        {
            return Response::createInstance('Welcome to Freebie Service.\n1. Free Food\n2. Free Drink\n3. Free Airtime',RequestTypes::RESPONSE);
        }
    }

Visit Hubtel's USSD Api documentation page for the list of methods on the request and response classes, _(*15)

Examples

1. Laravel
2. Lumen

Feel free to submit pull-requests for examples with other frameworks :blush:, _(*16)

Running the tests

composer test, _(*17)

Authors

• Norris Oduro - Norris1z

License

This project is licensed under the MIT License, _(*18)