simicolonsy / mtn-otp

dev-main 2026-09-21 17:04 UTC

Requires

• php: ^8.2
• ext-curl: *
• ext-iconv: *

Requires (Dev)

• illuminate/cache: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• phpunit/phpunit: ^11.0

MIT

• simicolon

• php
• sms
• laravel
• otp
• verification
• mtn
• syria

Published on Packagist.org on 2026-09-21 17:07 UTC

README

Send OTP via MTN Syria SMS gateway. Works with Laravel or plain PHP.

Requirements

• PHP 8.2+
• ext-curl
• ext-iconv

Installation

composer require simicolonsy/mtn-otp

Configuration

Laravel

Publish the config file:

php artisan vendor:publish --tag=mtn-otp-config

Add to your .env:

MTN_OTP_USERNAME=your_username
MTN_OTP_PASSWORD=your_password
MTN_OTP_SENDER=YourSenderName

Plain PHP

use simicolon\MtnOtp\MtnOtpConfig;

$config = MtnOtpConfig::fromArray([
    'username' => 'your_username',
    'password' => 'your_password',
    'sender'   => 'YourSenderName',
]);

Usage

Full OTP Flow (Generate + Send + Verify)

Laravel

use simicolon\MtnOtp\MtnOtpManager;

// In your controller
public function sendOtp(Request $request, MtnOtpManager $otp)
{
    $result = $otp->generateAndSend($request->phone);

    // ['status' => 'sent', 'message' => 'OTP sent successfully']
    // ['status' => 'failed', 'message' => '...']

    return response()->json($result);
}

public function verifyOtp(Request $request, MtnOtpManager $otp)
{
    $result = $otp->verify($request->phone, $request->code);

    // ['status' => 'verified', 'message' => 'OTP verified successfully']
    // ['status' => 'invalid', 'message' => 'Invalid OTP code']
    // ['status' => 'expired', 'message' => 'OTP expired or not found']

    return response()->json($result);
}

Plain PHP

use simicolon\MtnOtp\MtnOtpConfig;
use simicolon\MtnOtp\MtnOtpClient;
use simicolon\MtnOtp\MtnOtpManager;
use simicolon\MtnOtp\Store\ArrayStore;

$config = MtnOtpConfig::fromArray([
    'username' => 'your_username',
    'password' => 'your_password',
    'sender'   => 'YourSenderName',
]);

$manager = new MtnOtpManager(
    new MtnOtpClient($config),
    new ArrayStore(),   // or implement OtpStoreInterface
    $config,
);

// Send OTP
$result = $manager->generateAndSend('0944123456');

// Verify OTP
$result = $manager->verify('0944123456', '12345');

Send Custom SMS (Without OTP Manager)

use simicolon\MtnOtp\MtnOtpClient;
use simicolon\MtnOtp\MtnOtpConfig;

$config = MtnOtpConfig::fromArray([...]);
$client = new MtnOtpClient($config);

// Send any message
$client->send('0944123456', 'Your order #1234 has been confirmed');

Config Options

Option	Default	Description
base_url	https://services.mtnsyr.com:7443/...	MTN gateway URL
username	—	Gateway username
password	—	Gateway password
sender	—	Sender name
lang	2	1 = English, 2 = Arabic
encoding	ucs2-hex	ucs2-hex, windows-1256, utf-8
otp_template	رمز التحقق الخاص بك هو: {code}	OTP message template
timeout	10	HTTP timeout in seconds
code_length	5	OTP code length (4-10)
expiry_minutes	45	How long the code is valid

Custom Store

Implement OtpStoreInterface to use your own storage (Redis, Database, etc.):

use simicolon\MtnOtp\OtpStoreInterface;

class MyDatabaseStore implements OtpStoreInterface
{
    public function store(string $phone, string $code, int $expiryMinutes): void
    {
        // Save to database with expiry
    }

    public function get(string $phone): ?string
    {
        // Retrieve from database (return null if expired)
    }

    public function forget(string $phone): void
    {
        // Delete from database
    }
}

Custom HTTP Client

Implement HttpClientInterface to replace the default cURL client:

use simicolon\MtnOtp\HttpClientInterface;

class GuzzleClient implements HttpClientInterface
{
    public function get(string $url, int $timeout): string
    {
        // Use Guzzle or any HTTP client
    }
}

$client = new MtnOtpClient($config, new GuzzleClient());

Phone Number Format

All phone numbers are automatically normalized to 963XXXXXXXXX format:

• 0944123456 → 963944123456
• 963944123456 → 963944123456
• [phone] → 963944123456

Testing

composer install
composer test

License

MIT