Skip to content

Commit

Permalink
Initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
Azanda committed May 21, 2020
1 parent 98e1aa7 commit 2e6910b
Show file tree
Hide file tree
Showing 3 changed files with 288 additions and 0 deletions.
139 changes: 139 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# MenuPlus

[Ussd](https://en.wikipedia.org/wiki/Unstructured_Supplementary_Service_Data) is an amazing technology for anyone looking to create apps which can reach a large volume of people. Ussd is an ancient technology yet it still serves a purpose in our day and age. This PHP library simplies the process behind creating said apps with the [AAT Mobile Ussd API](https://www.aat.co.za/always-active-mobile/ussd/)

Read more about MenuPlus:

- [Requirements](#requirements)
- [Installation](#installation)
- [Ussd Menus](#ussd-menus)
- [Getting Started](#getting-started)
- [Author](#author)
- [License](#license)


## Requirements

In order for you to use MenuPlus you need to set up an account with [AAT Mobile](https://www.aat.co.za/always-active-mobile/ussd/) for ussd, after which you can require this library and code away 👨🏽‍💻

## Installation

MenuPlus is installed via [Composer](https://getcomposer.org/).

```bash
composer require azandazama/menuplus
```

You can of course also manually edit your composer.json file

```bash
{
"require": {
"azandazama/menuplus": "^1.0"
}
}
```

## Ussd Menus

*MenuPlus* offers different types of ussd menus which serve different purposes. Code and screenshots will be shown below.

### Standard Menu
This menu has all the bells and whistles offering you with unlimited options and option urls. [screenshot](https://ztdev.co.za)


```php
$ussd->title = 'Welcome to the Example Ussd Platform!';
$ussd->options = ['Option 1', 'Option 2', 'Option 3'];
$ussd->option_url = ['index.php?page=1', 'index.php?page=2', 'index.php?page=3'];
echo $ussd->addMenu($url);
```

Options have URLs( `$ussd->option_url` ) and you can consider Options( `$ussd->options` ) as links and menus as pages. Options and Option URLs are parallel arrays and each option corrisponds to each option URL


### Free Text Menu
This menu has no options and the title is therefore considered as the option. [screenshot](https://ztdev.co.za)

```php
$ussd->title = 'Please provide first and last name';
$ussd->option_url = 'index.php?file=4';
echo $ussd->addMenu($url);
```

### Paginated Menu
This menu offers all the bells and whistles and also allows you to order your menu with pagination

```php
$ussd->title = 'Select an option';
$ussd->options = ['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5', 'Option 6', 'Option 7'];
// Menu options can all share the same url
$ussd->option_url = 'index.php?page=5';
// [3] is the amount of options that will be shown in this menu
return $ussd->paginateMenu($url, 3);
```


## Getting Started

The following is a basic usage example of the MenuPlus library.

```php
<?php
require_once './vendor/autoload.php';

$ussd = new \MenuPlus\Ussd;
// ensure your url ends with a backslash
$url = 'http://localhost:7000/';

function initMenu($ussd, $url)
{
switch(@$_GET['page'])
{
case '':
// This is the first menu the application will serve
$ussd->title = 'Welcome to the Example Ussd Platform!';
$ussd->options = ['Questionnaire', 'Register', 'Shows available', 'Exit'];
$ussd->option_url = ['index.php?page=1', 'index.php?page=2', 'index.php?page=3', 'index.php?page=4', 'index.php?page=exit'];
return $ussd->addMenu($url);
break;
case 1:
$ussd->title = 'What year was Nelson Mandela born';
$ussd->options = ['1900', '1918', 'Back'];
$ussd->option_url = ['index.php?page=answer&ans=wrong', 'index.php?page=answer&ans=correct', 'index.php'];
return $ussd->addMenu($url);
break;
case 2:
// FreeText Menu's have no options just one title and url
$ussd->title = 'Please provide first and last name';
$ussd->option_url = 'index.php?file=names';
return $ussd->addMenu($url);
break;
case 3:
$ussd->title = 'Select your favourite TV show';
$ussd->options = ['The Simpsons', 'Star Wars', 'Peanuts', 'South Park',
'Courage the Cowardly Dog', 'Avatar: The Last Airbender',
'Dexters Laboratory', 'Futurama', 'The Jetsons', 'Phineas and Ferb',
'Kim Possible', 'Samurai Jack', 'Dora the Explorer'];
// Menu options can all share the same url
$ussd->option_url = 'index.php?page=shows';
// [5] is the amount of options that will be shown per menu
return $ussd->paginateMenu($url, 5);
break;
case 'exit':
$ussd->title = "Thank you!\nUssd Platform";
return $ussd->addMenu($url);
break;
}
}

echo initMenu($ussd, $url);
```

## Author

* Azanda Zama (Email: judah.zama@gmail.com, IG: [@azanda.zama](https://instagram.com/azanda.zama), Twitter: [@azanda_zama](https://twitter.com/azanda_zama), Linkedin: [Azanda Zama](https://za.linkedin.com/in/azanda-zama-a176b2167))

## License

[MIT](https://choosealicense.com/licenses/mit/)
18 changes: 18 additions & 0 deletions composer.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"name": "azandazama/menuplus",
"description": "MenuPlus: A PHP library that simplifies the process of creating ussd applications",
"type": "library",
"license": "MIT",
"authors": [
{
"name": "Azanda Zama",
"email": "judah.zama@gmail.com"
}
],
"autoload": {
"psr-4": {
"MenuPlus\\": "src/"
}
},
"require": {}
}
131 changes: 131 additions & 0 deletions src/ussd.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
<?php
namespace MenuPlus;

class Ussd
{
# global vars
public $title = '';
public $options = [];
public $option_url = [];

function addMenu($url)
{
$response = '<?xml version="1.0" encoding="utf-8"?>';
$response .= '<request><headertext>'.$this->title.'</headertext>';
$response .= '<options>';
if(!empty($this->options))
{
for($i = 0;$i < count($this->options);$i++)
{
if(is_array($this->option_url))
{
$response .= '<option command="'.($i+1).'" order="'.($i+1).'" callback="'.$url.''.$this->option_url[$i].'" display="true">'.$this->options[$i].'</option>';
}
else
{
$response .= '<option command="'.($i+1).'" order="'.($i+1).'" callback="'.$url.''.$this->option_url.'" display="true">'.$this->options[$i].'</option>';
}
}
}
else if(empty($this->options) && !empty($this->option_url))
{
$response .= '<option command="1" order="1" callback="'.$url.''.$this->option_url.'" display="false">';
}
$response .= '</options></request>';
return $response;
}

function paginateMenu($url, $limit)
{
if(count($this->options) > $limit)
{
$pageCount = ceil(count($this->options)/$limit);

if(!isset($_GET['file']) || $_GET['request'] == '*')
{
$page = 1;
$response = '<?xml version="1.0" encoding="utf-8"?>';
$response .= '<request><headertext>'.$this->title.' (1/'.$pageCount.')'."\n\n".'Press # to scroll down'."\n".'</headertext>';
$response .= '<options>';
$i = 1;
$start = ($page-1) * $limit;
$arrayData = array_splice($this->options, $start, $limit);
$count = 1;
for($i = 0;$i < count($arrayData); $i++)
{
$response .= '<option command="'.$count.'" order="'.$count.'" callback="'.$url.''.$this->option_url.'" display="true">'.$arrayData[$i].'</option>';
$count++;
}
$response .= '<option command="'.$count.'" order="'.$count.'" callback="'.$url.'index.php?page='.$_GET['page'].'&file=2" display="false"></option>';
$response .= '</options></request>';
return $response;
}
else if($_GET['file'] >= 1)
{
# get current page count
$count = $_GET['file'];
if($count == $pageCount)
{
# no scroll down opt
$response = '<?xml version="1.0" encoding="utf-8"?>';
$response .= '<request><headertext>'.$this->title.' ('.$count.'/'.$pageCount.')'."\n\n".'Press * to scroll up'."\n".'</headertext>';
$response .= '<options>';
# get numbering for options
$pg_cnt = $limit * $count;
$i = $pg_cnt - $limit + 1;
# get point where records will continue
$start = ($count-1) * $limit;
$arrayData = array_splice($this->options, $start, $limit);
$c = 1;
for($i = 0;$i < count($arrayData); $i++)
{
$response .= '<option command="'.$c.'" order="'.$c.'" callback="'.$url.''.$this->option_url.'" display="true">'.$arrayData[$i].'</option>';
$c++;
}
$response .= '<option command="'.($c+1).'" order="'.($c+1).'" callback="'.$url.'index.php?file='.$_GET['page'].'" display="false"></option>';
$response .= '</options></request>';
return $response;
}
else
{
# add scroll down opt
$response = '<?xml version="1.0" encoding="utf-8"?>';
$response .= '<request><headertext>'.$this->title.' ('.$count.'/'.$pageCount.')'."\n\n".'Press # to scroll down'."\n".'</headertext>';
$response .= '<options>';
# get numbering for options
$pg_cnt = $limit * $count;
$i = $pg_cnt - $limit + 1;
# get point where records will continue
$start = ($count-1) * $limit;
$arrayData = array_splice($this->options, $start, $limit);
$c = 1;
for($i = 0;$i < count($arrayData); $i++)
{
$response .= '<option command="'.$c.'" order="'.$c.'" callback="'.$url.''.$this->option_url.'" display="true">'.$arrayData[$i].'</option>';
$c++;
}
$response .= '<option command="'.($c+1).'" order="'.($c+1).'" callback="'.$url.'index.php?page='.$_GET['page'].'&file='.($count+1).'" display="false"></option>';
$response .= '</options></request>';
return $response;
}
}

}
else
{
$response = '<?xml version="1.0" encoding="utf-8"?>';
$response .= "<request><headertext>".$this->title."\n</headertext>";
$response .= '<options>';
$count = 1;
for($i = 0;$i < count($this->options); $i++)
{
$response .= '<option command="'.$count.'" order="'.$count.'" callback="'.$url.''.$this->option_url.'" display="true">'.$this->options[$i].'</option>';
$count++;
}
$response .= '</options>';
$response .= '</request>';
return $response;
}
}

}

0 comments on commit 2e6910b

Please sign in to comment.