PHPackages bitmarshals/instant-ussd - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. bitmarshals/instant-ussd ActiveLibrary[Utility & Helpers](/categories/utility) bitmarshals/instant-ussd ======================== Library to help you rapidly develop and easily maintain your USSD applications. 0.5.2(7y ago)826171BSD-3-ClausePHPPHP >=5.6.0 Since Aug 21Pushed 7y ago1 watchersCompare [ Source](https://github.com/davidbwire/instant-ussd)[ Packagist](https://packagist.org/packages/bitmarshals/instant-ussd)[ Docs](https://github.com/bitmarshals/instant-ussd)[ RSS](/packages/bitmarshals-instant-ussd/feed)WikiDiscussions master Synced 2w ago READMEChangelog (2)Dependencies (6)Versions (31)Used By (1) InstantUssd =========== [](#instantussd) [![](https://avatars1.githubusercontent.com/u/30041331?v=4&s=80)](https://avatars1.githubusercontent.com/u/30041331?v=4&s=80) InstantUssd is a USSD development library meant to provide you with a set of tools to easily and quickly build your own USSD applications. Goals ----- [](#goals) - Speed up USSD development - Ease maintenance of USSD code Features -------- [](#features) - Minimal coding (Provide USSD menus as config) - Automatic screen to screen navigation - Out of the box validation of user inputs - Ready solutions for complex USSD flows involving going back and forth, optional screens, looping set of screens, jumping from screen to screen and resuming timed-out USSD sessions Installation ------------ [](#installation) You will need PHP 5.6+ to install this package. You must then modify your `composer.json` file and run `composer update` to include the latest version of the package in your project. ``` "require": { "bitmarshals/instant-ussd": "0.1.*" } ``` Or you can run the `composer require` command from your terminal. ``` composer require bitmarshals/instant-ussd ``` Once the package is installed the next step is dependant on which framework you're using. Usage ----- [](#usage) ### Initialization [](#initialization) Instantiate `Bitmarshals\InstantUssd\InstantUssd` passing in `instant_ussd` config and your controller instance. ``` // Within your Controller use Bitmarshals\InstantUssd\InstantUssd; use Bitmarshals\InstantUssd\Response; use InstantUssd\UssdValidator; $instantUssdConfig = $config['instant_ussd']; $instantUssd = new InstantUssd($instantUssdConfig, $this); ``` Retrieve an instance of `Bitmarshals\InstantUssd\UssdService` from `InstantUssd`. This service provides utilities for parsing, packaging and handling incoming USSD data. ``` $ussdParams = $_POST; $ussdText = $ussdParams['text']; // package incoming data in a format instant-ussd understands $ussdService = $instantUssd->getUssdService($ussdText); $ussdData = $ussdService->packageUssdData($ussdParams); ``` ### Navigation Checks [](#navigation-checks) Before proceeding further we need to run a few test to check if we should exit early, show home page (very first screen in a USSD flow) or navigate to the previous screen. #### Exit Check [](#exit-check) ``` // Should we EXIT early? $isExitRequest = $ussdService->isExitRequest(); if ($isExitRequest === true) { return $instantUssd->exitUssd([]) ->send(); } ``` #### Home Page Check [](#home-page-check) ``` // 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(); } ``` #### Go Back Check [](#go-back-check) ``` // 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(); } ``` ### Process Latest User Response [](#process-latest-user-response) With the navigation checks complete, we should now handle the most recent user response. #### Retrieve Last Served Menu and Its Config [](#retrieve-last-served-menu-and-its-config) `InstantUssd` keeps a history of the screens we've visited during the current session. Let's retrieve the menu we sent to our user and its config settings. ``` // 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 Latest Response [](#validate-latest-response) ``` // 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(); } ``` #### Capture Validated Data [](#capture-validated-data) ``` // 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(); } ``` #### Show Next Screen [](#show-next-screen) ``` // we have the next screen; SHOW NEXT SCREEN return $instantUssd->showNextScreen($ussdData, $nextScreenId) ->send(); ``` ### Sample Application [](#sample-application) Check out [InstantUssd App](https://github.com/davidbwire/instant-ussd-app). License ------- [](#license) BSD 3-Clause License Documentation ------------- [](#documentation) Please refer to our extensive [Wiki documentation](https://github.com/bitmarshals/instant-ussd/wiki) for more information. ### Health Score 31 — LowBetter than 66% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity20 Limited adoption so far Community13 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~19 days Total 29 Last Release 2703d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2409778?v=4)[David Bwire](/maintainers/davidbwire)[@davidbwire](https://github.com/davidbwire) --- Top Contributors [![davidbwire](https://avatars.githubusercontent.com/u/2409778?v=4)](https://github.com/davidbwire "davidbwire (166 commits)") --- Tags ussdinstant ussdussd frameworkussd librarybitmarshalsDavid Bwire ### Embed Badge ![Health badge](/badges/bitmarshals-instant-ussd/health.svg) ``` [![Health](https://phpackages.com/badges/bitmarshals-instant-ussd/health.svg)](https://phpackages.com/packages/bitmarshals-instant-ussd) ``` ### Alternatives [neuron-core/neuron-ai The PHP Agentic Framework. 2.0k496.1k33](/packages/neuron-core-neuron-ai)[roundcube/roundcubemail The Roundcube Webmail suite 7.0k1.4k3](/packages/roundcube-roundcubemail)[spatie/laravel-export Create a static site bundle from a Laravel app 672139.5k6](/packages/spatie-laravel-export)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 252.5k](/packages/eslazarev-wildberries-sdk)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)