sparors / laravel-ussd
Create ussd with ease
Installs: 14 763
Dependents: 0
Suggesters: 0
Security: 0
Stars: 42
Watchers: 9
Forks: 20
Open Issues: 0
Requires
- illuminate/support: ~5|~6|~7|~8|~9
Requires (Dev)
- mockery/mockery: ^1.1
- orchestra/testbench: ~3|~4|~5|~6|~7
- phpunit/phpunit: ^9.5
- sempro/phpunit-pretty-print: ^1.0
README
Build Ussd (Unstructured Supplementary Service Data) applications with laravel without breaking a sweat.
Installation
You can install the package via composer:
composer require sparors/laravel-ussd
Laravel Ussd provides zero configuration out of the box. To publish the config, run the vendor publish command:
php artisan vendor:publish --provider="Sparors\Ussd\UssdServiceProvider" --tag=ussd-config
Usage
Creating States
We provide a ussd artisan command which allows you to quickly create new states.
php artisan ussd:state Welcome
Creating Nested States
Linux/Unix
php artisan ussd:state Airtime/Welcome
Windows
php artisan ussd:state Airtime\Welcome
Welcome state class generated
<?php namespace App\Http\Ussd\States; use Sparors\Ussd\State; class Welcome extends State { protected function beforeRendering(): void { // } protected function afterRendering(string $argument): void { // } }
Creating Actions
Available from v2.0.0
We provide a ussd artisan command which allows you to quickly create new actions.
php artisan ussd:action MakePayment
MakePayment action class generated
<?php namespace App\Http\Ussd\Actions; use Sparors\Ussd\Action; class MakePayment extends Action { public function run(): string { return ''; // The state after this } }
Run your logic and return the next state's fully qualified class name
<?php namespace App\Http\Ussd\Actions; use Sparors\Ussd\Action; use App\Http\Ussd\States\PaymentSuccess; use App\Http\Ussd\States\PaymentError; class MakePayment extends Action { public function run(): string { $response = Http::post('/payment', [ 'phone_number' => $this->record->phoneNumber ]); if ($response->ok()) { return PaymentSuccess::class; } return PaymentError::class; } }
Creating Menus
Add your menu to the beforeRendering method
<?php namespace App\Http\Ussd\States; use Sparors\Ussd\State; class Welcome extends State { protected function beforeRendering(): void { $name = $this->record->name; $this->menu->text('Welcome To Laravel USSD') ->lineBreak(2) ->line('Select an option') ->listing([ 'Airtime Topup', 'Data Bundle', 'TV Subscription', 'ECG/GWCL', 'Talk To Us' ]) ->lineBreak(2) ->text('Powered by Sparors'); } protected function afterRendering(string $argument): void { // } }
Linking States with Decisions
Add your decision to the afterRendering method and link them with states
<?php namespace App\Http\Ussd\States; use App\Http\Ussd\States\GetRecipientNumber; use App\Http\Ussd\States\MaintenanceMode; use App\Http\Ussd\States\Error; use Sparors\Ussd\State; class Welcome extends State { protected function beforeRendering(): void { $this->menu->text('Welcome To Laravel Ussd') ->lineBreak(2) ->line('Select an option') ->listing([ 'Airtime Topup', 'Data Bundle', 'TV Subscription', 'ECG/GWCL', 'Talk To Us' ]) ->lineBreak(2) ->text('Powered by Sparors'); } protected function afterRendering(string $argument): void { // If input is equal to 1, 2, 3, 4 or 5, render the appropriate state $this->decision->equal('1', GetRecipientNumber::class) ->between(2, 5, MaintenanceMode::class) ->any(Error::class); } }
Setting Initial State
Import the welcome state class and pass it to the setInitialState method
<?php namespace App\Http\Controllers; use Sparors\Ussd\Facades\Ussd; use App\Http\Ussd\States\Welcome; class UssdController extends Controller { public function index() { $ussd = Ussd::machine() ->setFromRequest([ 'network', 'phone_number' => 'msisdn', 'sessionId' => 'UserSessionID', 'input' => 'msg' ]) ->setInitialState(Welcome::class) ->setResponse(function (string $message, string $action) { return [ 'USSDResp' => [ 'action' => $action, 'menus' => '', 'title' => $message ] ]; }); return response()->json($ussd->run()); } }
Simplifying machine with configurator
Available from v2.5.0
You can use configurator to simplify repetitive parts of your application so they can be shared easily. Just implement and Sparors\Ussd\Contracts\Configurator
interface and use it in your machine.
<?php use Sparors\Ussd\Contracts\Configurator; // Creating a configurator in eg. App\Http\Ussd\Configurators\Nsano.php class Nsano implements Configurator { public function configure(Machine $machine): void { $machine->setFromRequest([ 'network', 'phone_number' => 'msisdn', 'sessionId' => 'UserSessionID', 'input' => 'msg' ])->setResponse(function (string $message, string $action) { return [ 'USSDResp' => [ 'action' => $action, 'menus' => '', 'title' => $message ] ]; }); } } ?>
<?php namespace App\Http\Controllers; use Sparors\Ussd\Facades\Ussd; use App\Http\Ussd\States\Welcome; use App\Http\Ussd\Configurators\Nsano' // Using it in a controller class UssdController extends Controller { public function index() { $ussd = Ussd::machine() ->useConfigurator(Nsano::class) ->setInitialState(Welcome::class); return response()->json($ussd->run()); } } ?>
Running the application
You can use the development server the ships with Laravel by running, from the project root:
php artisan serve
You can visit http://localhost:8000 to see the application in action.
Enjoy!!!
Documentation
You'll find the documentation on https://sparors.github.io/ussd-docs.
Testing
$ vendor/bin/phpunit
Change log
Please see the changelog for more information on what has changed recently.
Contributing
Please see contributing.md for details and a todolist.
Security
If you discover any security related issues, please email isaacsai030@gmail.com instead of using the issue tracker.
Credits
License
MIT. Please see the license file for more information.