PHP-Server-SDK

Offizielles serverseitiges PHP-SDK — veröffentlicht als captchala/captchala-php auf Packagist.

Drei Aufgaben, die das SDK für Sie übernimmt:

1. Validate — verifiziert einen pt_-Pass-Token aus dem Browser-SDK.
2. Issue — stellt einen Einmal-sct_-Server-Token aus, um die anstehende Challenge an eine bestimmte action / IP / UID zu binden.
3. Moderate — multimodale (Text + Bild) Content-Moderation gegen dieselbe OpenAI-kompatible Pipeline, die auch das Dashboard verwendet.

Installation

composer require captchala/captchala-php

Erfordert PHP ≥ 8.0 mit ext-json. Nutzt cURL, falls verfügbar, und fällt auf file_get_contents zurück.

Validate (pt_-Token)

use Captchala\Client;

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

if (!$result->isValid()) {
    http_response_code(400);
    exit($result->getError());   // e.g. "token_expired", "client_ip_mismatch"
}
// Verification passed; proceed with the request.

Falls Sie den ursprünglichen server_token mit bind_uid ausgestellt haben, vergleichen Sie die zurückgegebene uid mit dem tatsächlich erwarteten Nutzer:

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

Wenn Sie den Token an eine IP gebunden haben, übergeben Sie die Nutzer-IP auch auf der Verifizierungsseite:

$client->validate($token, false, $request->ip());

Server-Token ausstellen

Für hochwertige Flows (Anmeldung, Registrierung, Bezahlung) ist das empfohlene Muster: Das Backend stellt einen Einmal-sct_-Token aus, übergibt ihn an den Browser, und der Browser reicht ihn als serverToken-Prop weiter. Jeder Token ist Einmal-, action-bezogen und optional zum Zeitpunkt der Ausstellung an IP / UID gebunden.

$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

Inhalte moderieren

Multimodal — akzeptiert eine Mischung aus Text- und Bild-URLs im OpenAI-kompatiblen Format:

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

Reine-Text-Abkürzung:

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

Kategorien werden vom Modell definiert (z. B. violence, hate, sexual, self-harm); iterieren Sie getCategories() defensiv, statt einen festen Satz hart zu kodieren.

Result-Klassen

Klasse	Methoden
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
• Web-SDK-Übersicht · API-Referenz