PHP SDK

clearance-rest/sdk, Numbers, Emails ve Captchas API’lerini tek bir istemci ve üç servisle sarar. Her çağrı API anahtarınızı gönderir, sert bir deadline koyar ve hataları tipli exception’lara çevirir.

Kurulum

composer require clearance-rest/sdk

Yapılandırma

use ClearanceRest\Client;

$client = new Client(apiKey: 'cr_live_...');

// Ya da argümansız, ortamdan okuyarak:
$client = new Client();

Argümansız kullanıldığında istemci, Node.js SDK’sının kullandığı adlarla şu ortam değişkenlerini okur:

Değişken	Amaç
CLEARANCE_REST_API_KEY	Projenizin API anahtarı.
CLEARANCE_REST_URL	API base URL’ini ezer.
CLEARANCE_REST_NUMBERS_URL	Numbers base URL’ini ezer. Varsayılan https://api.clearance.rest/numbers.
CLEARANCE_REST_EMAILS_URL	Emails base URL’ini ezer. Varsayılan https://api.clearance.rest/emails.
CLEARANCE_REST_CAPTCHAS_URL	Captchas base URL’ini ezer. Varsayılan https://api.clearance.rest/captchas.

Anahtar yoksa hiçbiri gönderilmez ve API 401 döndürür.

Deadline

Herhangi bir çağrıya timeout (milisaniye) verin. SDK bunu X-Service-Timeout olarak gönderir ve HTTP istemcisinin kendi timeout’unu da onun biraz üstüne ayarlar; böylece ölü bir ağ bir çağrıyı sonsuza kadar asılı bırakamaz. SDK yeniden denemez.

Metotlar named argument alır, bu yüzden bunları camelCase yazın.

Captchas

use ClearanceRest\Services\Captchas;

$solution = $client->captchas->resolve(
    task: ['type' => 'ImageToTextTask', 'body' => '<base64 image>'],
    provider: 'capsolver',
    timeout: 30_000,
);

echo Captchas::solutionValue($solution); // hangi çözücü yanıtladıysa token ya da metin

Rehber: Captcha çözme.

Emails

$email = $client->emails->wait(
    emailAccount: 'user@domain.com',
    matchRegex: 'Verification',
    codeRegex: '\d{6}',
    timeout: 45_000,
);
echo $email['code'];

Bir Gmail ya da Outlook posta kutusu bağlama:

$authorizeUrl = $client->emails->oauthStart('gmail', 'https://app.example.com/settings/mailboxes', 'user-42')['authorize_url'];
$result   = $client->emails->oauthResult('gmail', $token);
$accounts = $client->emails->accounts('gmail')['accounts'];

try {
    $client->emails->disconnect('gmail', 'a@b.com');
} catch (\ClearanceRest\Exceptions\ChallengeRequestException $e) {
    if ($e->getStatus() !== 404) throw $e; // 404: zaten bağlı değildi
}

Rehberler: E-posta bekleme ve Posta kutusu bağlama.

Numbers

$number = $client->numbers->rent(service: 'tg', country: 6)['number'];

$sms = $client->numbers->wait(number: $number['phoneNumber'], codeRegex: '\d{4,6}', timeout: 120_000);

$client->numbers->release(sid: $number['sid']);

$numbers = $client->numbers->list(sync: true)['numbers'];

rent varsayılan olarak Hero SMS kullanır. Twilio:

$client->numbers->availables(country: 'US', sms: true);
$client->numbers->rent(provider: 'twilio', phoneNumbers: ['+14155550100']);

Hero SMS referans verisi ve tek çağrıda “fiyata bak, sonra kirala”:

$countries = $client->numbers->countries()['countries'];
$services  = $client->numbers->services(country: 6)['services'];
$prices    = $client->numbers->prices(country: 6, service: 'tg')['prices'];
$operators = $client->numbers->operators(country: 6)['operators'];

$cheapest = $client->numbers->rentCheapest(service: 'tg', country: 6);

$client->numbers->resend(sid: $number['sid']); // Hero SMS'ten SMS'i tekrar iste

Mobil numaralar:

$claim = $client->numbers->claimToken(label: 'agency-1'); // token, expires_at, qr_payload

// Tek kullanımlık bir bilet almak için HTTP çağrısı yapar ve tarayıcıya vermek güvenli bir
// ws URL'i döndürür: API anahtarınızı değil, bileti taşır.
$socketUrl = $client->numbers->claimSocketUrl(label: 'agency-1');

$apkUrl = $client->numbers->downloadApkUrl(); // istek yok, anahtar yok

Rehberler: Hero SMS numaraları, Twilio numaraları ve Mobil numaralar.

Kodunuzu test etme

SDK kullanan bir uygulamanın testleri gerçek API’yi çağırmamalıdır. İstemci herhangi bir Guzzle ClientInterface kabul eder; ona bir MockHandler’lı istemci verin:

use ClearanceRest\Client;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

$mock = new MockHandler([
    new Response(200, [], json_encode(['success' => true, 'number' => ['sid' => 'x', 'phoneNumber' => '+6281234567890']])),
]);

$client = new Client(
    apiKey: 'test-key',
    httpClient: new GuzzleClient(['handler' => HandlerStack::create($mock)]),
);

Laravel’in Http::fake()’i bu istemciyi yakalamaz; çünkü yalnızca Http::get() ve benzerleriyle yapılan istekleri görür. MockHandler yanıtlarını sıraya koyduğunuz sırayla döndürür ve URL eşleştirmez; bu yüzden onları testinizin çağrıları yapacağı sırayla ekleyin.

Yalnızca Node’a özgü özellikler

AbortSignal ile iptal Node.js SDK’sına özgüdür; PHP’de karşılığı yoktur.