README

InstantUssd 是一个 USSD 开发库，旨在为你提供一套工具，以便轻松快速地构建自己的 USSD 应用程序。

目标

加速 USSD 开发
简化 USSD 代码的维护

特性

最小化编码（以配置形式提供 USSD 菜单）
自动屏幕到屏幕导航
自动验证用户输入
提供复杂 USSD 流程的现成解决方案，涉及来回导航、可选屏幕、循环屏幕集、从屏幕跳转到屏幕以及恢复超时 USSD 会话

安装

您需要 PHP 5.6+ 来安装此软件包。

然后您必须修改您的 composer.json 文件并运行 composer update 以将软件包的最新版本包含到您的项目中。

"require": {
    "bitmarshals/instant-ussd": "0.1.*"
}

或者您可以从终端运行 composer require 命令。

composer require bitmarshals/instant-ussd

安装软件包后，下一步取决于您使用的框架。

用法

初始化

实例化 Bitmarshals\InstantUssd\InstantUssd，传入 instant_ussd 配置和您的控制器实例。

// Within your Controller
use Bitmarshals\InstantUssd\InstantUssd;
use Bitmarshals\InstantUssd\Response;
use InstantUssd\UssdValidator;

$instantUssdConfig = $config['instant_ussd'];
$instantUssd       = new InstantUssd($instantUssdConfig, $this);

从 InstantUssd 中检索 Bitmarshals\InstantUssd\UssdService 实例。此服务提供了解析、打包和处理传入 USSD 数据的实用工具。

$ussdParams  = $_POST;
$ussdText    = $ussdParams['text'];

// package incoming data in a format instant-ussd understands
$ussdService = $instantUssd->getUssdService($ussdText);
$ussdData    = $ussdService->packageUssdData($ussdParams);

导航检查

在进一步操作之前，我们需要运行一些测试来检查是否应该提前退出、显示主页（USSD 流程中的第一个屏幕）或导航到上一个屏幕。

退出检查

// Should we EXIT early?
$isExitRequest = $ussdService->isExitRequest();
if ($isExitRequest === true) {
    return $instantUssd->exitUssd([])
                    ->send();
}

主页检查

// Should we SHOW HOME Page?
$isFirstRequest       = $ussdService->isFirstRequest();
$userRequestsHomePage = $ussdService->isExplicitHomepageRequest();
if ($isFirstRequest || $userRequestsHomePage) {
    // set your home page
    $yourHomePage = "home_instant_ussd";
    return $instantUssd->showHomePage($ussdData, $yourHomePage)
                    ->send();
}

后退检查

// Should we GO BACK?
$isGoBackRequest = $ussdService->isGoBackRequest();
if ($isGoBackRequest === true) {
    $resultGoBak = $instantUssd->goBack($ussdData);
    if ($resultGoBak instanceof Response) {
        return $resultGoBak->send();
    }
    // fallback to home page if previous menu missing
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}

处理最新用户响应

导航检查完成后，我们现在应该处理最新的用户响应。

检索最后服务的菜单及其配置

InstantUssd 保存了当前会话中我们访问过的屏幕的历史记录。让我们检索我们发送给用户的菜单及其配置设置。

// get last served menu_id from database
$lastServedMenuId = $instantUssd->retrieveLastServedMenuId($ussdData);
// check we got last_served_menu
if (empty($lastServedMenuId)) {
    // fallback to home page
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}
// Get $lastServedMenuConfig. The config will used in validation trigger below
// Set $ussdData['menu_id'] to know the specific config to retreive
$ussdData['menu_id']  = $lastServedMenuId;
$lastServedMenuConfig = $instantUssd->retrieveMenuConfig($ussdData);
// check we have $lastServedMenuConfig
if (empty($lastServedMenuConfig)) {
    // fallback to home page
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}

验证最新响应

// VALIDATE incoming data
$validator = new UssdValidator($lastServedMenuId, $lastServedMenuConfig);
$isValid   = $validator->isValidResponse($ussdData);
if (!$isValid) {
    // handle invalid data
    $nextScreenId = $lastServedMenuId;
    // essentially we're re-rendering the menu with error message
    return $instantUssd->showNextScreen($ussdData, $nextScreenId)
                    ->send();
}

捕获验证数据

// send valid data FOR PROCESSING. Save to db, etc
// this step should give us a pointer to the next screen
$nextScreenId = $instantUssd->processIncomingData(
        $lastServedMenuId, $ussdData);
if (empty($nextScreenId)) {
    // we couldn't find the next screen
    return $instantUssd->showError($ussdData, "Error. "
                            . "Next screen could not be found.")
                    ->send();
}

显示下一个屏幕

// we have the next screen; SHOW NEXT SCREEN
return $instantUssd->showNextScreen($ussdData, $nextScreenId)
                ->send();

示例应用程序

查看 InstantUssd App。

许可证

BSD 3-Clause 许可证

文档

请参阅我们的详细 Wiki 文档以获取更多信息。

bitmarshals / instant-ussd

维护者

详细信息