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:^2.0Laravel 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-configWe provide a ussd artisan command which allows you to quickly create new states.
php artisan ussd:state WelcomeLinux/Unix
php artisan ussd:state Airtime/WelcomeWindows
php artisan ussd:state Airtime\WelcomeWelcome 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 MakePaymentMakePayment 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());
}
}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());
}
}
?>You can use the development server the ships with Laravel by running, from the project root:
php artisan serveYou 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/phpunitPlease 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 [email protected] instead of using the issue tracker.
MIT. Please see the license file for more information.