tafeni / php-ussd-framework

This is a port of https://github.com/hubtel/ussd-framework

USSD Framework in PHP []

This is a simple Framework for building Ussd applications in PHP against the Hubtel USSD API.

This project is a ported from the original C# version

Purpose

There are many ways to integrate with the Hubtel USSD API across the many programming languages.

This project seeks to create a light weight 1 Mb framework that will make it easy for any one to bootstrap a ussd application in minutes.

Discliamer: this is not a Hubtel sponsered project. It is a hubby project to fill in the gap.

Take your time to understand how Hubtel USSD API works. https://developers.hubtel.com/documentations/ussd

Main specs

• Designed with PHP's object oriented architecture
• Simple application configuration settings
• Session storage flexibility i.e. either Redis store or any RDMS
• Simple standards for development
• Use of HTTPFul for making API request
• Simple custom logging engine

Install

To explain better.

1 Clone/Download this project

Clone the repository unto your machine/server, then navigate into the project.

2 Create Database with Table named 'UssdSessions' First , we create the table UssdSessions where all session requests and responses are registered

CREATE TABLE ussd_sessions (
  ussd_session_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
  session_id VARCHAR(36) NOT NULL,
  sequence INT NOT NULL,
  client_state TEXT NOT NULL,
  date_created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Then we define the applications settings, in /Config/settings.php

// ussd application settings
return [
    // USSD Settings
    'appilcationPath' => '\UssdApp', # the folder that contains all your ussd applications logic
    'initiationController' => 'Main', # the main controller/class of your ussd logic
    'initiationAction' => 'start', # the main action/function/method of your ussd logic 
    'storageType' => 'database', # uncomment if you are using database to log your sessions
    #'storageType' => 'redis', # uncomment if you are using redis to log your sessions
    'redis' => [
        'dev' => [
            'redis' => '',
            'config' => ''
        ],
        'prod' => [
            'redis' => '',
            'config' => ''
        ]
    ],
    'database' => [
        // dev database settings
        'dev' => [
            'dsn' => "mysql:host=127.0.0.1;dbname=local_db;charset=utf8",# change only the dbname to your actual dbname
            'username' => 'username',
            'password' => '******',
        ],

        // prod database settings
        'prod' => [
            'dsn' => 'mysql:host=www.example.com;dbname=production_db;charset=utf8',
            'username' => 'username',
            'password' => 'password',
        ]
    ],
    'accessControlAllowOrigin' => [
        'path' => "https://example.com/ussd"
    ],        
    
    // logging settings
    'logger' => [
        'name' => 'ussd-framework-logger', # your logger's identifier
        'path' => __DIR__ . '/../Logs/general.log', # path to your logger file
    ]
];

3 Run the application

You need composer install on your machine to be able to run this project. Find out how to setup here https://getcomposer.org/doc/00-intro.md.

Execute either of the following commands

composer start

or

composer.phar start

4 Finish

If you did all things well you should have your demo application running ;)

Demo

The demo application can be found in the /UssdApp/ folder.

...
    
    # Main startup method/action for the USSD initiates the USSD session
    public function start()
    {
        $menu = new \UssdFramework\UssdMenu();
        $menu->header($this->_header)
                ->createAndAddItem('Form Inputs', 'form_input')
                ->createAndAddItem('Redirect', 'same_class_redirect')
                ->createAndAddItem('Another Class', 'start', 'Second')
                ->createAndAddItem('Render', 'render_message')
                ->createAndAddItem('List Items', 'list_items')
                ->createAndAddItem('Api Calls', 'api_call')
                ->createAndAddItem('Exit', 'close', 'Main');
        return $this->renderMenu($menu);
    }
...
   

You can run or edit it there. Good luck

PS: Looking forward to your feed back, suggestions for improvement, pull requests and critics.

Credits

I will like to credit Aaron Baffour-Awuah for starting this project.