# 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](/docs/examples/php) or the [Laravel example](/docs/examples/laravel).

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

```bash
composer require otp-ps/sdk
```

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

```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 answers | `SendResult` (with `testCode` for test keys), `CheckResult` (`valid`, `attemptsLeft`), `Verification`, `Balance`, all with read-only properties. |
| Errors | Every failure is an `OtpPs\OtpPsException` with `errorCode` (an API error code, or `network_error`, `timeout`, `server_error`), `status`, `retryAfter` and `isRetryable()`. |
| Timeouts | `timeout`, default 15 seconds per attempt. |
| Safe retries | Sends 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](/docs/sandbox). |
| Numbers | `OtpPs\Phone::normalize($raw)` → `+9705XXXXXXXX` or `null`, the API's rules. |

## Account information

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

## Options

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

## Errors

```php
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),
    };
}
```
