SDK PHP Server

SDK oficial server-side em PHP — publicado como captchala/captchala-php no Packagist.

Três tarefas que o SDK executa para você:

1. Validar — verifica um pass token pt_ vindo do SDK do navegador.
2. Emitir — cunha um server token sct_ de uso único para vincular o próximo desafio a uma action / IP / UID específica.
3. Moderar — moderação de conteúdo multimodal (texto + imagem) contra o mesmo pipeline compatível com OpenAI usado pelo painel.

Instalação

composer require captchala/captchala-php

Requer PHP ≥ 8.0 com ext-json. Usa cURL quando disponível, com fallback para file_get_contents.

Validar (token pt_)

Passe o IP do usuário final como terceiro argumento (de CF-Connecting-IP / X-Forwarded-For, com fallback para REMOTE_ADDR). É opcional, mas recomendado — é usado para verificações de risco adicionais.

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

Não tem o IP à mão? Use $client->validate($_POST['captcha_token']) — ele ainda verifica, apenas sem o sinal de risco extra baseado no IP.

Se você emitiu o server_token original com bind_uid, compare o uid retornado com o usuário que de fato espera:

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

Emitir um server token

Para fluxos de alto valor (login, cadastro, pagamento) o padrão recomendado é: o backend cunha um token sct_ de uso único, entrega ao navegador, o navegador o passa como a prop serverToken. Cada token é de uso único, com escopo de action e opcionalmente vinculado a IP / UID no momento da emissão.

$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

Moderar conteúdo

Multimodal — aceita uma mistura de texto e URLs de imagem em formato compatível com 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
    }
}

Atalho para texto puro:

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

As categorias são definidas pelo modelo (ex.: violence, hate, sexual, self-harm); itere getCategories() de forma defensiva em vez de fixar um conjunto rígido.

Classes de resultado

Classe	Métodos
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()

Links

• Packagist · GitHub
• Visão geral do SDK Web · Referência da API