SDKs

PHP SDK

otp-ps/sdk: typed PHP 8.1+ client with safe retries, timeouts, sandbox constants and phone validation; works with or without Composer.

Status: ready, not yet published. otp-ps/sdk will be on Packagist once OTP.ps releases it. Until then, use the PHP example client or the Laravel example.

PHP 8.1+, with the curl and json extensions (both standard). No other dependencies.

composer require otp-ps/sdk

On hosting without Composer, upload the package folder and require 'otp-ps-sdk/autoload.php';.

<?php
require 'vendor/autoload.php';

$otp = new OtpPs\Client(); // reads OTP_PS_API_KEY (and OTP_PS_BASE_URL)

// 1. Send. Keep $v->id in the session, never in a hidden form field.
$v = $otp->send('0599123456', purpose: 'order', locale: 'ar');
$_SESSION['otp'] = ['id' => $v->id, 'phone' => OtpPs\Phone::normalize('0599123456')];

// 2. Check what the customer typed. Trust only ->valid.
$r = $otp->check($_SESSION['otp']['id'], $_POST['code']);
if ($r->valid) {
    // verified: save $_SESSION['otp']['phone'] on the order or user
} elseif ($r->status === 'pending') {
    echo "Wrong code, {$r->attemptsLeft} tries left";
} else {
    echo 'Please ask for a new code'; // expired, failed or replaced
}

What it handles for you

Typed answersSendResult (with testCode for test keys), CheckResult (valid, attemptsLeft), Verification, Balance, all with read-only properties.
ErrorsEvery failure is an OtpPs\OtpPsException with errorCode (an API error code, or network_error, timeout, server_error), status, retryAfter and isRetryable().
Timeoutstimeout, default 15 seconds per attempt.
Safe retriesSends always carry an Idempotency-Key (yours or a generated one), so after a network failure or server error the client retries them (maxRetries, default 2) without sending or charging twice. Checks are never retried.
Sandbox$otp->mode is 'test' with a test key; OtpPs\Sandbox::SUCCESS, SMS_FAILED, INSUFFICIENT_BALANCE, RATE_LIMITED, EXPIRED and Sandbox::CODE give the sandbox numbers.
NumbersOtpPs\Phone::normalize($raw) → +9705XXXXXXXX or null, the API's rules.

Account information

$usage = $otp->usage();   // today, this month, last 30 days (array)
$limits = $otp->limits(); // permissions, spending limits and what's used (array)

Options

$otp = new OtpPs\Client(
    apiKey: getenv('OTP_PS_API_KEY'),
    baseUrl: 'https://otp.ps',
    timeout: 15,
    maxRetries: 2,
);

Errors

try {
    $v = $otp->send($phone, purpose: 'order', idempotencyKey: "order-{$orderId}-otp-1");
} catch (OtpPs\OtpPsException $e) {
    match ($e->errorCode) {
        'invalid_phone', 'unsupported_network' => showError('رقم الجوال غير صحيح (جوال أو Ooredoo فقط).'),
        'rate_limited' => showCountdown($e->retryAfter ?? 30),
        default => alertTeamAndShowGenericError($e),
    };
}

View as Markdown