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.
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.
- Installation
- Usage
- Creating USSD Screens
- The
Request
object - Request Payload
- Setting request payload
- Retrieving request payload
- Using Arrays in Payload
- The Mandatory Methods
- Optional Methods
- Exception Handling
- Input Data Validation
- Extending for Multiple Implementations
- Example Request Implementation
- Required methods
- Example Response Implementation
- Routing
- Sample Request Factory
- Sample Response Factory
- Localization
- Audit
- Session Data CleanUp
- Example Screen Implementation
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.
message()
must return a string message that will be displayed on the screen.options()
must return an array of options which will be exposed to the user. Return an empty array for screens that require no options.execute()
this should be used to implement whatever the app should do with request data. The request data is returned bygetRequestValue()
within the screen object. You may use that to access the request data. If you want to redirect the user to another screen, return therender()
method of the target screen:return (new Register($this->request))->render()
. The Screen initialization takes one argument, therequest
object.previous()
this should return an object of theScreen
class. It tells the session where to navigate to when the user chooses the back option.Optional Methods
You can extend the following methods to change some properties of the screen.
type()
should return an integer delegated to constantsRELEASE
andRESPONSE
of theTNM\USSD\Response
class. It defaults toRESPONSE
if not overridden.RESPONSE
renders a screen with an input field, whileRELEASE
renders a screen without an input field, used to instruct the USSD Gateway to close the USSD session.acceptsResponse()
, instead of the complexity oftype()
method, you can callacceptsResponse()
. It should return a boolean which instructs the screen whether to render an input field or to send a screen that marks the end of the USSD session.goesBack()
return a boolean value defining if the screen should have aback
navigation option. You can leave it alone unless you are defining the landing screen.
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:
getSession()
should return the sessionid
assigned by the USSD gatewaygetMsisdn()
should return the msisdn making a ussd requestgetMessage()
should return the message sent with the requestgetType()
should return the type of request.
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.
- A note on audit: An audit trail will not be available for the data that has been cleaned up.
Example Screen Implementation
All versions of ussd with dependencies
ext-json Version *
ext-simplexml Version *
tnmdev/ussd-simulator Version dev-master
tnmdev/msisdn-helpers Version dev-main