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)

Son kullanıcının IP'sini üçüncü argüman olarak geçirin (CF-Connecting-IP / X-Forwarded-For'dan, REMOTE_ADDR'a düşerek). İsteğe bağlı ancak önerilir — ek risk kontrolleri için kullanılır.

use Captchala\Client;

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

if (!$result->isValid()) {
    http_response_code(400);
    exit($result->getError());   // e.g. "token_expired"
}
// Verification passed; proceed with the request.
// $result->getCaptchaArgs() has platform / user_ip / referer / pkg / solved_at / risk_score

// Real end-user IP behind a CDN / proxy
function captchala_client_ip(): string {
    foreach (['HTTP_CF_CONNECTING_IP', 'HTTP_X_FORWARDED_FOR', 'HTTP_X_REAL_IP', 'REMOTE_ADDR'] as $h) {
        if (!empty($_SERVER[$h])) {
            $ip = trim(explode(',', $_SERVER[$h])[0]);
            if (filter_var($ip, FILTER_VALIDATE_IP)) return $ip;
        }
    }
    return '';
}

Elinizde IP yok mu? $client->validate($_POST['captcha_token']) kullanın — yine de doğrulama yapar, sadece ek IP tabanlı risk sinyali olmadan.

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');
}

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ı