PHP Sunucu SDK

Resmi PHP sunucu tarafı SDK'sı — Packagist üzerinde captchala/captchala-php olarak yayınlanmıştır.

SDK'nın sizin için üstlendiği üç iş:

1. Validate — tarayıcı SDK'sından gelen bir pt_ pass token'ını doğrulayın.
2. Issue — gelecek challenge'ı belirli bir action / IP / UID'ye bağlamak için tek seferlik bir sct_ server token'ı basın.
3. Moderate — panelin kullandığı OpenAI uyumlu pipeline ile çok modlu (metin + görüntü) içerik moderasyonu.

Kurulum

composer require captchala/captchala-php

PHP ≥ 8.0 ve ext-json gerektirir. cURL mevcutsa onu kullanır, aksi halde file_get_contents'a düşer.

Doğrulama (pt_ token)

use Captchala\Client;

$client = new Client('your_app_key', 'your_app_secret');
$result = $client->validate($_POST['captcha_token']);

if (!$result->isValid()) {
    http_response_code(400);
    exit($result->getError());   // e.g. "token_expired", "client_ip_mismatch"
}
// Verification passed; proceed with the request.

Orijinal server_token'ı bind_uid ile düzenlediyseniz, döndürülen uid değerini gerçekten beklediğiniz kullanıcıyla karşılaştırın:

if ($result->getUid() !== $expectedUserId) {
    http_response_code(400);
    exit('user mismatch');
}

Token'ı bir IP'ye bağladıysanız, doğrulama tarafında da kullanıcı IP'sini geçirin:

$client->validate($token, false, $request->ip());

Sunucu token'ı düzenleme

Yüksek değerli akışlar (giriş, kayıt, ödeme) için önerilen desen şudur: backend tek seferlik bir sct_ token basar, tarayıcıya iletir, tarayıcı bunu serverToken prop'u olarak geçirir. Her token tek kullanımlık, action kapsamlı ve isteğe bağlı olarak düzenleme anında IP / UID'ye bağlıdır.

$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // seconds; default 300
    maxUses:   5,           // SDK retry budget
    bindUid:   $user->id,   // pair with ValidateResult::getUid() on verify
);

if (!$issue->isOk()) {
    return ['error' => $issue->getError()];   // rate_limit_exceeded, invalid_action, ...
}

return ['server_token' => $issue->getToken()];  // hand to browser

İçerik moderasyonu

Çok modlu — OpenAI uyumlu formatta metin ve görüntü URL'lerinin karışımını kabul eder:

$result = $client->moderationCheck([
    ['type' => 'text', 'text' => $userComment],
    ['type' => 'image_url', 'image_url' => ['url' => $uploadedImageUrl]],
], userId: $user->id);

if (!$result->isOk()) {
    // request error: invalid_credentials, no_content, transport failure, ...
    return ['error' => $result->getError()];
}

if ($result->isFlagged()) {
    // upstream model flagged; inspect categories for the why
    if ($result->hasCategory('violence', 'csam')) {
        // hard block
    }
}

Düz metin kısayolu:

$result = $client->moderationText('user comment here', userId: $user->id);

Kategoriler model tanımlıdır (örn. violence, hate, sexual, self-harm); sabit bir küme kodlamak yerine getCategories() üzerinde defansif olarak iterasyon yapın.

Result sınıfları

Sınıf	Yöntemler
ValidateResult	isValid(), getError(), getUid(), getChallengeId(), getAction(), isOffline(), isClientOnly(), getWarning(), toArray()
IssueResult	isOk(), getToken(), getExpiresIn(), getIssuedAt(), getError(), getMessage(), toArray()
ModerationResult	isOk(), isFlagged(), hasCategory(...$names), getCategories(), getContentType(), getRaw(), getError(), getMessage(), toArray()

Bağlantılar

• Packagist · GitHub
• Web SDK genel bakışı · API Referansı