プロバイダー

Cloudflare Turnstile (`turnstile`)

ウィジェットのオプション: action、cData、theme (auto、light、dark)、size (normal、 flexible、compact)、language、appearance (always、execute、interaction-only)、 execution (render、execute)、tabindex、retry、retryInterval、refreshExpired、 refreshTimeout、feedbackEnabled と、コールバック callback、errorCallback、 expiredCallback、timeoutCallback、beforeInteractiveCallback、afterInteractiveCallback、 unsupportedCallback (グローバル関数の名前)。これらは data-* 属性として出力されます。

action は最大 32 文字、cData は最大 255 文字です (英数字、_ と -)。 action を設定した場合、検証レスポンスのアクションがそれと一致する必要があります。
トークンは最大 2048 文字で、300 秒間有効で、一度だけ検証できます。それより長いトークンは、リクエストを送信せずに拒否されます。
すべての検証リクエストには idempotency_key (UUID) が付くので、retry で同じリクエストを安全に再送できます。

Google reCAPTCHA v2 (`recaptcha_v2`)

「私はロボットではありません」チェックボックスを表示します。ウィジェットのオプション: theme (light、dark)、size (normal、compact)、tabindex、callback、expiredCallback、 errorCallback。language はスクリプトの hl パラメータとして送信されます。レスポンスにはアクションが含まれないので、action はチェックされません。invisible reCAPTCHA (size が invisible) では、grecaptcha.execute() を呼び出す JavaScript を自分で書く必要があります。

www.google.com にアクセスできない環境では、scriptUrl を https://www.recaptcha.net/recaptcha/api.js に、verifyUrl を https://www.recaptcha.net/recaptcha/api/siteverify に設定してください。

Google reCAPTCHA v3 (`recaptcha_v3`)

reCAPTCHA v3 にはウィジェットがありません。widget() は hidden の g-recaptcha-response input と小さなスクリプトを出力します。フォームが送信されると、スクリプトはアクションを指定して grecaptcha.execute() を呼び出し、トークンを input に格納して、フォームを再度送信します (クリックされた送信ボタンは維持されます)。トークンは 2 分で期限切れになるので、送信時に取得します。

php

echo $this->Captcha->widget(['action' => 'contact']);

php

public $components = ['Captcha.Captcha' => ['actions' => ['add'], 'action' => 'contact', 'scoreThreshold' => 0.7]];

action のデフォルトは submit です。英数字、/ と _ を使えます。検証レスポンスのアクションは設定したアクションと一致する必要があるので、コンポーネントにもウィジェットと同じアクションを設定してください。
scoreThreshold のデフォルトは 0.5 です。スコアのないレスポンスや、スコアがそれより低いレスポンスは score-too-low で失敗します。スコアは $this->Captcha->getResult()->getScore() で読み取れます。たとえば、リクエストを拒否する代わりに追加の確認を求める場合に使います。自分で判定する場合は、scoreThreshold を false に設定してください。

hCaptcha (`hcaptcha`)

ウィジェットのオプション: theme (light、dark)、size (normal、compact)、tabindex、callback、 expiredCallback、chalexpiredCallback、openCallback、closeCallback、errorCallback。 language はスクリプトの hl パラメータとして送信されます。

hCaptcha の推奨に従って、サイトキーが検証エンドポイントに送信される (sitekey) ので、別のサイトキーで発行されたトークンは拒否されます。
hCaptcha のスクリプトは、recaptchacompat=off を付けて読み込まない限り、 g-recaptcha-response も追加します。recaptchacompat=off を付けて読み込むには、 $this->Captcha->widget(['script' => ['query' => ['recaptchacompat' => 'off']]]) とします。
hCaptcha Enterprise の score はチェックされません (hCaptcha のスコアは、高いほどボットの可能性が高いことを意味します)。getResult()->getScore() で読み取ってください。

カスタムプロバイダー

provider に CaptchaProviderInterface を実装したクラスを設定します。BaseCaptchaProvider を継承すると、共通の動作を利用できます。

php

// src/Lib/MyCaptchaProvider.php (legacy layout: app/Lib/MyCaptchaProvider.php)
App::uses('BaseCaptchaProvider', 'Captcha.Lib/Provider');

class MyCaptchaProvider extends BaseCaptchaProvider
{
    protected string $defaultScriptUrl = 'https://captcha.example.com/api.js';
    protected string $defaultVerifyUrl = 'https://captcha.example.com/siteverify';
    protected string $widgetClass = 'my-captcha';
    protected string $field = 'my-captcha-response';
    protected array $widgetOptions = ['theme' => 'data-theme'];

    public function name(): string
    {
        return 'my_captcha';
    }
}

php

Configure::write('Captcha.provider', 'MyCaptchaProvider'); // or 'MyPlugin.MyCaptchaProvider'

クラスがまだ読み込まれていなければ、Lib (またはプラグインの Lib) から App::uses() で読み込まれます。クラスは、マージされた設定の配列を引数に生成されます。

リファレンス

Cloudflare Turnstile: クライアントサイドでの表示、ウィジェットの設定、サーバーサイドでの検証、テスト、 Content Security Policy
Google reCAPTCHA: v2 チェックボックス、 v3、ユーザーのレスポンスの検証、 FAQ (テスト用のキー、CSP)
hCaptcha: 開発者ガイド、設定

プロバイダー ​

Cloudflare Turnstile (turnstile) ​

Google reCAPTCHA v2 (recaptcha_v2) ​

Google reCAPTCHA v3 (recaptcha_v3) ​

hCaptcha (hcaptcha) ​

カスタムプロバイダー ​

リファレンス ​