Build Ussd (Unstructured Supplementary Service Data) applications with laravel without breaking a sweat.
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
We provide a ussd artisan command which allows you to quickly create new states.
php artisan ussd:state Welcome
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
{
//
}
}
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;
}
}
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
{
//
}
}
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);
}
}
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());
}
}
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!!!
You'll find the documentation on https://sparors.github.io/ussd-docs.
$ vendor\bin\phpunit
Please see the changelog for more information on what has changed recently.
Please see contributing.md for details and a todolist.
If you discover any security related issues, please email isaacsai030@gmail.com instead of using the issue tracker.
MIT. Please see the license file for more information.