Download the PHP package tnmdev/ussd without Composer

On this page you can find all versions of the php package tnmdev/ussd. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package ussd

TNM USSD Adapter

This package creates an adapter, boilerplate code and functionality that lets you interact with USSDC and offer USSD channel to your API. The interface is open and documentated for implementation with various USSD interfaces.

Table of contents generated with markdown-toc

Installation

Then publish the package's migrations and config files.

Then install the ussd scaffold. This will also run migrations to create session tracking tables

Once you install the package, the USSD app will be accessible on /api/ussd endpoint. A landing screen will be created for you at App\Screens\Welcome.php.

Usage

Creating USSD Screens

This will create a boilerplate USSD screen object for you. You can go ahead and edit the contents of message, options and execute methods. The screen extends TNM\USSD\Screen class which gives you means of accessing the request details, and encoding USSD response.

The Request object

Screen has $request as a public property. This is an object of TNM\USSD\Http\Request class.

The request class exposes four properties from the xml request passed on by USSDC.

Property Description
message The message passed from USSD
type Integer value representing the type of request
session USSD session ID
msisdn The number making the USSD request

The USSD screen that is sent to the user is represented by Screens which extend the TNM\USSD\Screen class.

Request Payload

You can move payload from between screens using request payload. Any piece of data added to a request payload can be accessed by other request within the session.

Setting request payload

Request payload can be added by calling addPayload method on request's trail object. It takes a key-value pair of parameters.

Retrieving request payload

Using Arrays in Payload

There are times where you have associative arrays for options. For example, you can have a list of products, with id, price, name and humanized. Where name is what the product is referred to as in your system, and humanized is how you want it to appear on the screen.

An array of such items can be pushed to payload with a third boolean parameter. This tells the trail object to serialize the input before storing it.

Manipulating array payloads is made possible by HasBundledOptions trait of TNM\USSD\Traits namespace. So to use arrays in your payload, you need to use HasBundledOptions trait in your Screen.

Here are some of the uses of the bundled options trait: to list/map an associative array as USSD options, you can map to the array key of your choice using the map method.

The map method takes two arguments. First is the array key you want to map with, and the second is the payload key you want to list from.

When the user makes an option on the USSD screen, you can map back to any key of the associative array option made by calling the find method.

The implementation in the snippet above, will assign the ID of the chosen product to a payload key chosenProduct. The trait looks for the user's option passed as the second argument. You can specify the field to look in by passing a third argument, which defaults to humanized. So the assumption is that your options associative array will have a field for displaying the content. You can rename it to anything that suits you. Just make sure you pass a third argument to tell the method where to look.

In other cases you may just want to fetch the whole array on a particular payload key. The method is the same as a normal payload, again with a second boolean argument.

The Mandatory Methods

The Screen class will require you to implement the following methods.

Exception Handling

The USSD adapter has a self-rendering exception handler. To use it, throw new UssdException of the TNM\USSD\Exceptions namespace. It takes two params: the request object and the message you want to pass to the user. The exception handler renders a USSD screen with the error message and terminates the session.

Input Data Validation

You can set rules to validate the user input by using Validates trait of the TNM\USSD\Http namespace. The trail will require you to implement rules() method, which should return a string of validation rules.

To validate input, call $this->validate($this->request, $label) in execute() method of your Screen class.

If the input has a validation error, ValidationException of the TNM\USSD\Exceptions namespace will be thrown and an error screen will be rendered for you automatically.

Extending for Multiple Implementations

This adapter was designed with extendability in mind. Right now it supports TruRoute and Flares USSD interfaces used by TNM and Airtel Malawi respectively. However, with the pluggable interface, it can be extended to support any mobile network operator.

To extend, create a request and response class. These classes must implement the TNM\USSD\Http\UssdRequestInterface and TNM\USSD\Http\UssdResponseInterface respectively. The response class has been simplified further that you only need to extend the XMLResponse class.

Implementation details of the request class may vary. However, we strongly recommend having a constructor that decodes the USSD request from the mobile operator into an array that should be assigned to $request private property and have the interface methods return their values based on the private property.

Example Request Implementation

Required methods

The request interface requires you to implement the following methods:

Example Response Implementation

The following is an example response class implementation. You will need to add a sample response XML file in your response directory. This sample file will be provided to you by the MNO. For TNM and Airtel Malawi, we have you covered.

TNM Response XML template
TNM Response Class

Routing

You can distinguish requests from different mobile operators using a route parameter adapter.

All requests from a network that uses Flares adapter should be routed to api/ussd/flares. So when you create your own extension, the route for the operator should be api/ussd/{adapter}.

This is not resolved magically. You are required to define the implementation in TNM\USSD\Factories\RequestFactory and TNM\USSD\Factories\ResponseFactory

Sample Request Factory
Sample Response Factory

Localization

You can set the session language in any screen of the application. The following screen will come in the newly selected language.

This feature implements the Laravel's localization with language files. Refer to the Laravel docs for more detail. So your implementation can be like the following:

Sample Localization Implementation

Audit

You can track user sessions, system messages and user responses with a CLI tool.

This command gives you a list of all the transactions that were done by a number. The list contains session ID and timestamp.

This command gives you all the details of the transaction from the beginning of a session to the end. The trail includes system messages, user responses to each message and their timestamps in a chronological order.

When a user response was an option, it reports a string value that is represented by the number that was selected, saving you from having to lookup which option was on number 1, 2 or etc.

Session Data CleanUp

The package keeps track of sessions using a database table. This database table may need to clean-up after some time. To clean up run the following command in the application directory.

It takes the option of number of days' data to preserve. If no option is passed, it deletes everything older than 60 days.

Example Screen Implementation


All versions of ussd with dependencies

PHP Build Version
Package Version
Requires php Version ^8.0
ext-json Version *
ext-simplexml Version *
tnmdev/ussd-simulator Version dev-master
tnmdev/msisdn-helpers Version dev-main
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package tnmdev/ussd contains the following files

Loading the files please wait ....