PHP Server SDK

SDK sisi server PHP resmi — diterbitkan sebagai captchala/captchala-php di Packagist.

Tiga tugas yang ditangani SDK ini untuk Anda:

1. Validate — memverifikasi pass token pt_ dari browser SDK.
2. Issue — mencetak server token sct_ sekali pakai untuk mengikat tantangan berikutnya ke aksi / IP / UID tertentu.
3. Moderate — moderasi konten multi-modal (teks + gambar) terhadap pipeline yang kompatibel dengan OpenAI, sama seperti yang dipakai dashboard.

Pasang

composer require captchala/captchala-php

Membutuhkan PHP ≥ 8.0 dengan ext-json. Memakai cURL bila tersedia, jatuh kembali ke file_get_contents.

Validate (token pt_)

Kirim IP pengguna akhir sebagai argumen ketiga (dari CF-Connecting-IP / X-Forwarded-For, jatuh kembali ke REMOTE_ADDR). Opsional, tetapi disarankan — dipakai 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 '';
}

Tidak ada IP di tangan? Gunakan $client->validate($_POST['captcha_token']) — tetap melakukan verifikasi, hanya tanpa sinyal risiko tambahan berbasis IP.

Jika server_token awal diterbitkan dengan bind_uid, bandingkan uid yang dikembalikan dengan pengguna yang sebenarnya Anda harapkan:

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

Menerbitkan server token

Untuk alur bernilai tinggi (login, registrasi, pembayaran) pola yang disarankan adalah: backend mencetak token sct_ sekali pakai, mengirimkannya ke peramban, peramban meneruskannya sebagai prop serverToken. Setiap token sekali pakai, terikat aksi, dan opsional terikat IP / UID saat diterbitkan.

$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // detik; default 300
    maxUses:   5,           // anggaran retry SDK
    bindUid:   $user->id,   // dipasangkan dengan ValidateResult::getUid() saat verifikasi
);

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

return ['server_token' => $issue->getToken()];  // kirim ke peramban

Moderasi konten

Multi-modal — menerima campuran URL teks dan gambar dalam format kompatibel OpenAI:

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

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

if ($result->isFlagged()) {
    // model di hulu menandai; periksa kategori untuk alasannya
    if ($result->hasCategory('violence', 'csam')) {
        // blokir keras
    }
}

Pintasan teks polos:

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

Kategori ditentukan oleh model (mis. violence, hate, sexual, self-harm); iterasikan getCategories() secara defensif daripada meng-hardcode himpunan tetap.

Kelas hasil

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

Tautan

• Packagist · GitHub
• Ikhtisar Web SDK · Referensi API