PHP Server SDK

SDK sisi pelayan PHP rasmi — diterbitkan sebagai captchala/captchala-php di Packagist.

Tiga tugas yang dikendalikan SDK untuk anda:

1. Sahkan — sahkan token pass pt_ daripada SDK pelayar.
2. Keluarkan — cetak token pelayan sct_ sekali guna untuk mengikat cabaran yang akan datang kepada tindakan / IP / UID tertentu.
3. Kawal selia — pengawasan kandungan pelbagai mod (teks + imej) terhadap saluran serasi-OpenAI yang sama digunakan oleh papan pemuka.

Pemasangan

composer require captchala/captchala-php

Memerlukan PHP ≥ 8.0 dengan ext-json. Menggunakan cURL apabila tersedia, jatuh balik kepada file_get_contents.

Sahkan (token pt_)

Hantar IP pengguna akhir sebagai argumen ketiga (daripada CF-Connecting-IP / X-Forwarded-For, jatuh balik kepada REMOTE_ADDR). Pilihan, tetapi disyorkan — ia digunakan untuk pemeriksaan risiko tambahan.

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

Tiada IP di tangan? Gunakan $client->validate($_POST['captcha_token']) — ia masih mengesahkan, cuma tanpa isyarat risiko tambahan berasaskan IP.

Jika anda mengeluarkan server_token asal dengan bind_uid, bandingkan uid yang dikembalikan dengan pengguna yang anda jangkakan:

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

Keluarkan token pelayan

Untuk aliran bernilai tinggi (log masuk, pendaftaran, pembayaran), pola yang disyorkan ialah: backend mencetak token sct_ sekali guna, menyerahkannya kepada pelayar, dan pelayar menghantarnya sebagai prop serverToken. Setiap token adalah sekali guna, terhad kepada tindakan, dan secara pilihan diikat kepada IP / UID pada masa pengeluaran.

$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // saat; lalai 300
    maxUses:   5,           // bajet cuba semula SDK
    bindUid:   $user->id,   // pasangkan dengan ValidateResult::getUid() semasa pengesahan
);

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

return ['server_token' => $issue->getToken()];  // serahkan kepada pelayar

Kawal selia kandungan

Pelbagai mod — menerima campuran teks dan URL imej dalam format serasi-OpenAI:

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

if (!$result->isOk()) {
    // ralat permintaan: invalid_credentials, no_content, kegagalan pengangkutan, ...
    return ['error' => $result->getError()];
}

if ($result->isFlagged()) {
    // model huluan telah menanda; periksa kategori untuk sebabnya
    if ($result->hasCategory('violence', 'csam')) {
        // sekatan keras
    }
}

Pintasan teks biasa:

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

Kategori ditakrifkan oleh model (cth. violence, hate, sexual, self-harm); lelarkan getCategories() secara defensif dan bukannya mengekod set tetap.

Kelas hasil

Kelas	Kaedah
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()

Pautan

• Packagist · GitHub
• Gambaran Web SDK · Rujukan API