README

USSD Monkey

USSD Monkey 包旨在帮助开发者通过在 JSON 文件中定义菜单流程来快速构建 USSD 应用程序。此 README.md 文件提供了如何有效使用此包的文档。此包使用 Redis 临时存储会话信息。

安装

要安装 USSD Monkey 包，您可以使用 Composer

composer require gantry-motion/ussd-monkey

使用方法

安装包后，您需要通过提供 USSD 菜单 JSON 文件的路径并根据需要指定自定义类命名空间来配置它。以下是一个示例配置

$config = [
    'environment' => 'development',
    'ussd_menu_file' => ROOTPATH . 'ussdMenu.json',
    'custom_class_namespace' => 'App\Controllers\USSD'
];

然后，实例化 USSD Monkey 类并调用 push 方法来渲染应用程序菜单的内容

$ussd = new USSDMonkey($config);
$ussd->push($params, $menu);

push 方法接受两个参数：由您的 USSD 网关发送的参数（例如会话 ID、服务代码、电话号码和请求字符串）以及要显示的默认菜单。

配置

该包包含默认配置设置，但您可以根据需要覆盖它们。以下是一些关键配置选项

• environment：设置环境为“生产”或“开发”。
• input_format：定义输入格式。接受的值：“chained”。
• output_format：确定输出格式。接受的值：“conend”或“json”。
• enable_chained_input：启用或禁用链式输入（如果 USSD 网关提供商支持）。接受的值：“true”或“false”。
• enable_back_and_forth_menu_nav：启用或禁用前后菜单导航。接受的值：“true”或“false”。
• chars_per_line：指定每行的字符数。
• menu_items_separator：定义菜单项的分隔符（| 或 ，）。
• nav_next：定义移动到下一个菜单的导航字符串。
• nav_prev：定义移动到上一个菜单的导航字符串。
• sanitizePhoneNumber：启用或禁用电话号码清理。接受的值：“true”或“false”。
• error_title：设置错误消息的标题。
• error_message：设置默认错误消息。
• disabled_func：列出您项目中要标记为在 USSD 使用期间暂停的任何禁用功能。
• request_variables：将请求变量映射到 USSD 网关提供商发送的相应名称（会话 ID、服务代码、电话号码、请求字符串）。
• redis：Redis 的配置设置。

您可以通过在实例化 USSD Monkey 类时提供自定义配置数组来覆盖这些设置。

要查看 USSD Monkey 将使用的配置，您可以利用包提供的 configInfo() 函数。以下是您如何使用它

$ussd = new USSDMonkey($config);
$current_config = $ussd->configInfo();
echo json_encode($current_config);

此代码将输出 USSD Monkey 将为您的 USSD 应用程序使用的当前配置设置的 JSON 表示形式。然后，您可以检查这些设置以确保它们符合您的要求。

示例

以下是您可能使用自定义配置实例化 USSD Monkey 类的示例

use GantryMotion\USSDMonkey\USSDMonkey;

$config = [
    'ussd_menu_file' => 'path/to/ussdMenu.json',
    'custom_class_namespace' => 'App\Controllers\USSD',
    // Override other configuration options as needed
];

$params = $_POST;
$ussd = new USSDMonkey($config);
$ussd->push($params, 'default_menu');

以下是 ussdMenu.json 文件结构的示例

{
    "default_menu": {
        "menu_title": "USSD Monkey",
        "display": "1. Say Hello |2. Say Goodbye |3. Say Good Night",
        "options": {
            "1": {
                "display": "Enter a name",
                "options": {
                    "display": "_EXECUTE_",
                    "execute_func": "say_hello"
                }
            },
            "2": {
                "display": "Enter a name",
                "options": {
                    "display": "_EXECUTE_",
                    "execute_func": "get_people_titles",
                    "options": {
                        "display": "_EXECUTE_",
                        "execute_func": "say_goodbye"
                    }
                }
            },
            "3": {
                "display": "Enter a name",
                "options": {
                    "display": "1. Wish sweet dream |2. Let bedbugs not bite",
                    "options": {
                        "1": {
                            "display": "_EXECUTE_",
                            "execute_func": "say_goodnight_sweet_dreams"
                        },
                        "2": {
                            "display": "_EXECUTE_",
                            "execute_func": "say_goodnight_bedbugs_dont_bite"
                        }
                    }
                }
            }
        }
    }
}

此 JSON 结构定义了 USSD 应用程序的菜单选项。每个菜单项都有一个显示标签和可选的关联操作（_EXECUTE_）。该结构支持嵌套选项以创建多级菜单。请确保您的 ussdMenu.json 文件符合此格式才能与 USSD Monkey 正确工作。

以下是包含您 USSD 应用程序的定制方法的 USSD PHP 类的示例

namespace App\Controllers;

class USSD
{
    public function say_hello($data)
    {
        $name = $data[1];
        $display = "Hello " . $name;
        return $display;
    }

    public function get_people_titles($data)
    {
        $titles = ["1" => "Mr", "2" => "Mrs", "3" => "Ms", "4" => "Dr"];

        $title_list = [];
        foreach ($titles as $key => $value) {
            $title_list[] = $key . ' ' . $value;
        }
        $display = "Select Title" . PHP_EOL;
        $display .= implode('|', $title_list);
        return $display;
    }

    public function say_goodbye($data)
    {
        $name = $data[1];
        $index = $data[2];

        $titles = ["1" => "Mr", "2" => "Mrs", "3" => "Ms", "4" => "Dr"];

        $display = "Goodbye " . $titles[$index] . " " . $name;
        return $display;
    }

    public function say_goodnight_sweet_dreams($data)
    {
        $name = $data[1];
        $display = "Good night " . $name . ", and sweet dreams";
        return $display;
    }

    public function say_goodnight_bedbugs_dont_bite($data)
    {
        $name = $data[1];
        $display = "Good night " . $name . ", and don't let the bedbugs bite";
        return $display;
    }
}

这个 USSD 类包含与您 ussdMenu.json 文件中定义的操作相对应的方法。这些方法处理从 USSD 菜单接收到的数据，并返回适当的响应。请确保命名空间和类名与您的配置中指定的相匹配。

就是这样！您现在可以使用 USSD Monkey 包来构建您的 USSD 应用程序了。