PHP Server SDK

公式の PHP サーバーサイド SDK。Packagist に captchala/captchala-php として公開されています。

SDK が引き受ける 3 つの役割:

1. Validate — ブラウザ SDK が返した pt_ pass トークンを検証します。
2. Issue — ワンタイムの sct_ server トークンを発行し、これから出す challenge を特定のアクション / IP / UID に紐付けます。
3. Moderate — テキストと画像を含むマルチモーダルのコンテンツモデレーション。ダッシュボードと同じ OpenAI 互換パイプラインを使用します。

インストール

composer require captchala/captchala-php

PHP ≥ 8.0 と ext-json が必要です。cURL が使える環境では cURL を使い、なければ file_get_contents にフォールバックします。

Validate（pt_ トークン）

エンドユーザーの IP を第 3 引数として渡してください（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 トークンの発行

ログイン・新規登録・決済などの重要フローでは、次のパターンを推奨します。バックエンドがワンタイムの sct_ トークンを発行し、ブラウザに渡し、ブラウザはそれを serverToken prop として渡します。各トークンは単回使用・アクションスコープで、発行時に IP / UID へバインドすることもできます。

$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // 秒。デフォルト 300
    maxUses:   5,           // SDK 側の再試行回数
    bindUid:   $user->id,   // 検証時に ValidateResult::getUid() と突き合わせる
);

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

return ['server_token' => $issue->getToken()];  // ブラウザに渡す

コンテンツモデレーション

マルチモーダル — テキストと画像 URL を OpenAI 互換のフォーマットで混在させて渡せます。

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

if (!$result->isOk()) {
    // リクエスト側のエラー: invalid_credentials、no_content、通信失敗など
    return ['error' => $result->getError()];
}

if ($result->isFlagged()) {
    // 上流モデルがフラグ。理由はカテゴリで確認する
    if ($result->hasCategory('violence', 'csam')) {
        // ハードブロック
    }
}

プレーンテキスト向けショートカット:

$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 リファレンス