Download the PHP package bmatovu/laravel-ussd without Composer

Table of Contents

• Overview
• Getting started
• Usage
  • Example
  • Menu validation
  • Simulator
• Constructs
  • Variable
  • Question
  • Response
  • Options
  • If
  • Choose
  • Action
  • List
• Advanced
  • Exceptions
  • Retries
  • Comparisons
  • Localization
  • Cache
  • Parser
  • Simulation
  • JSON
• Testing
• Alternatives

Overview

Effortlessly construct intricate USSD menus with streamlined efficiency by replacing convoluted nests of PHP files with the simplicity of XML-based menu construction. This approach allows for seamless execution similar to standard PHP scripts, minimizing code complexity and enhancing readability.

Let's explore an example of a simple SACCO USSD application.

Getting started

Installation

Publishables

Usage

Example

menus/menu.xml

app/Http/Controller/UssdController.php

routes/api.php

See more examples in the demo repo

Menu validation

The Schema

You can publish the default schema with the following command:

To ensure your menu files conform to the schema, you can validate them with the following command:

VSCode integration

For real-time XSD validations and suggestions, you can use the RedHat XML extension in Visual Studio Code. This extension provides helpful features for working with XML schemas, including syntax highlighting and validation.

Simulator

The package includes a CLI USSD simulator that supports several popular aggregators.

To get started, publish the simulator configuration file and update it with your aggregator and USSD service endpoint.

Usage:

Aggregators

• Africastalking
• Comviva (Airtel & MTN)

If your aggregator is not listed, you can request its addition by contacting us or by submitting a pull request.

Constructs

Variable

Note: This tag has no output

Question

Response

Note: this tag throws a FlowBreakException to mark a break in the normal flow.

Options

Options are like named grouped if, else-if statements that allow a user to navigate to a predefined path.

Disable backward navigation

By default, a 0) Back option is added to the rendered options. To disable this behaviour, use the noback attribute.

Note: Top-level options should use the noback attribute as there’s no previous level to return to.

If

It can contain any other tags, including nested <if> tags.

Choose

This construct is intended to handle scenarios typically covered by if, else if, else, and switch statements.

Example #1

Example #2

Example #3

Action

Action tags enable you to execute more tailored operations.

Arguments

You can provide arguments for these actions either through attributes or by defining variables.

Getting user input

When the text attribute is included in an action tag, it prompts the user for input in the same way that a <question> tag would.

List

Lists are designed to show dynamic items.

To use this feature, your provider must supply a list where each item includes both an id (a unique identifier) and a label (the text displayed to the user).

Accessing the selected item on the list

Note: Similar to actions, you can pass arguments to lists via attributes or as variables.

Advanced

Exceptions

The <response> tag throws a FlowBreakException which MUST be handled in your controller to manage the flow of the USSD interaction.

Additionally, you can catch other exceptions and optionally translate them into user-friendly messages, as demonstrated below...

resources/lang/en.json

Note: To minimize logging, the FlowBreakException should not be reported by your application. Ref

Retries

You can also configure the number of retry attempts and specify a custom error message.

Question

Using regex patterns.

Options & Lists

Validation can also be performed based on the available options in the list.

Note: Using retries in <action> tags is not recommended because these tags do not have visibility into the context provided by preceding tags.

Comparisons

The <if> and <when> tags support various types of comparisons.

If a comparison condition (cond) is not specified or is unsupported, the default comparison is eq (equals)

Localization

Create translation files within your project and reference the keys in your menu files. Here’s an example:

menus/menu.xml

resources/lang/fr.json

USSD simulation

Note:

• use the set_locale action to change locale directly from the USSD menu, and
• use App::setLocale to change the locale from your controller

Cache

This package stores USSD session data in the cache. Each key is prefixed with the session_id and will automatically expire based on the configured ttl (time-to-live).

Accessing variables

Reusing existing variables

Parser

Save default variables

Here's an example of how to save a variable from an incoming USSD request:

Use custom menu entry point

By default, parsing begins at the first element in your menu file, which corresponds to /menu/*[1].

If you want to start parsing from a different point or use a custom menu structure, you can specify the entry point in your code:

See: xpath playground

Simulation

You can enhance the USSD simulator by adding your preferred aggregator.

To do this, register the aggregator in the simulator configuration file. Ensure that the provider class implements the Bmatovu\Ussd\Contracts\Aggregator interface.

simulator.json

JSON

XML is often preferred for constructing configurations that resemble programming logic due to its robust schema validation capabilities and its clear, hierarchical structure. XML’s format is particularly useful for complex configurations and data structures, as it maintains readability and provides straightforward validation against defined schemas.

Testing

To run the package's unit tests, run the following command:

Alternatives

• sparors/laravel-ussd offers a different approach to building USSD menus.