PHP Server SDK

Официальный серверный SDK на PHP — опубликован как captchala/captchala-php на Packagist.

Три задачи, которые SDK берёт на себя:

1. Validate — проверка pt_ pass Token из браузерного SDK.
2. Issue — выпуск одноразового sct_ server Token для привязки предстоящего запроса к конкретному action / IP / UID.
3. Moderate — мультимодальная (текст + изображение) модерация контента через тот же OpenAI-совместимый pipeline, что использует панель управления.

Установка

composer require captchala/captchala-php

Требуется PHP ≥ 8.0 с ext-json. Использует cURL при наличии, иначе откатывается на file_get_contents.

Validate (pt_ Token)

Передавайте IP конечного пользователя третьим аргументом (из CF-Connecting-IP / X-Forwarded-For, с откатом на REMOTE_ADDR). Необязательно, но рекомендуется — используется для дополнительных проверок риска.

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

Нет IP под рукой? Используйте $client->validate($_POST['captcha_token']) — он всё равно выполнит проверку, просто без дополнительного сигнала риска на основе IP.

Если вы выпустили исходный server_token с bind_uid, сравните возвращённый uid с пользователем, которого ожидаете:

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

Выпуск server Token

Для ответственных потоков (вход, регистрация, оплата) рекомендуемая схема: backend выпускает одноразовый sct_ Token, передаёт его в браузер, браузер передаёт его как prop serverToken. Каждый Token одноразовый, привязан к action и опционально к IP / UID на момент выпуска.

$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

Модерация контента

Мультимодальная — принимает смесь текста и URL изображений в формате, совместимом с OpenAI:

$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
    }
}

Сокращённый вариант для plain-text:

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

Категории определяются моделью (например violence, hate, sexual, self-harm); итерируйте getCategories() защитно, а не зашивайте фиксированный набор.

Классы результатов

Класс	Методы
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()

Ссылки

• Packagist · GitHub
• Обзор Web SDK · Справочник API