README

reCAPTCHA 是一项免费 CAPTCHA 服务，可保护网站免受垃圾邮件和滥用。这是一个 PHP 库，用于封装从 reCAPTCHA 服务处理响应所需的服务器端验证步骤。此客户端支持 v2 和 v3。

• reCAPTCHA: https://www.google.com/recaptcha
• 此存储库: https://github.com/google/recaptcha
• 托管演示: https://recaptcha-demo.appspot.com/
• 版本: 1.3.0
• 许可协议: BSD，见 LICENSE

安装

Composer（推荐）

使用 Composer 从 Packagist 安装此库：google/recaptcha

从您的项目目录运行以下命令以添加依赖项

composer require google/recaptcha "^1.3"

或者，直接将依赖项添加到您的 composer.json 文件中

"require": {
    "google/recaptcha": "^1.3"
}

对早期版本 PHP 的支持

1.3 版本迁移到 PHP 8 及以上。对于早期版本，您需要继续使用 1.2 版本。

直接下载

下载 ZIP 文件 并将其提取到您的项目中。在 src/autoload.php 中提供了一个自动加载脚本，您可以在您的脚本中包含它。例如

require_once '/path/to/recaptcha/src/autoload.php';
$recaptcha = new \ReCaptcha\ReCaptcha($secret);

项目中的类按照 PSR-4 标准 structured，因此您也可以使用您自己的自动加载器或直接在您的代码中包含所需的文件。

用法

首先在 https://www.google.com/recaptcha/admin 获取您要集成的 reCAPTCHA 类型的适当密钥，对于 v2 在 https://g.co/recaptcha/v3 或 v3。

然后按照开发者网站上的 集成指南 将 reCAPTCHA 功能添加到您的前端。

当您需要验证用户的响应时，此库会发挥作用。在 PHP 端，您需要 reCAPTCHA 服务的响应和您的凭据中的密钥。使用您的密钥实例化 ReCaptcha 类，指定任何其他验证规则，然后使用 reCAPTCHA 响应（通常在 $_POST['g-recaptcha-response'] 或 JS 中的 grecaptcha.execute() 的响应，在示例中为 $gRecaptchaResponse）和用户的 IP 地址调用 verify()。例如

<?php
$recaptcha = new \ReCaptcha\ReCaptcha($secret);
$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
                  ->verify($gRecaptchaResponse, $remoteIp);
if ($resp->isSuccess()) {
    // Verified!
} else {
    $errors = $resp->getErrorCodes();
}

以下方法可用

• setExpectedHostname($hostname)：确保主机名匹配。如果您已禁用凭据中的“域名/包名验证”，则必须这样做。
• setExpectedApkPackageName($apkPackageName)：如果您正在验证 Android 应用的响应。同样，如果您已禁用凭据中的“域名/包名验证”，则必须这样做。
• setExpectedAction($action)：确保操作与 v3 API 匹配。
• setScoreThreshold($threshold)：为 v3 API 的响应设置分数阈值
• setChallengeTimeout($timeoutSeconds)：设置用户通过reCAPTCHA与您的服务器处理之间的超时。

每个set*()方法都返回ReCaptcha实例，因此您可以链式调用它们。例如

<?php
$recaptcha = new \ReCaptcha\ReCaptcha($secret);
$resp = $recaptcha->setExpectedHostname('recaptcha-demo.appspot.com')
                  ->setExpectedAction('homepage')
                  ->setScoreThreshold(0.5)
                  ->verify($gRecaptchaResponse, $remoteIp);

if ($resp->isSuccess()) {
    // Verified!
} else {
    $errors = $resp->getErrorCodes();
}

您可以在ReCaptcha类的常量中找到库错误代码的常量，例如ReCaptcha::E_HOSTNAME_MISMATCH

有关用法和结构的更多详细信息，请参阅ARCHITECTURE。

示例

您可以在examples/中找到每种reCAPTCHA类型的示例。您可以通过使用Composer脚本来本地运行示例

composer run-script serve-examples

这使用了内置的PHP开发服务器，在http://localhost:8080/托管示例

这些示例还托管在Google AppEngine Flexible环境中，网址为https://recaptcha-demo.appspot.com/。这是通过app.yaml配置的，您也可以将其用于将部署到自己的AppEngine项目。

贡献

没有人有足够的工程师，所以我们非常欢迎通过拉取请求来接受贡献。有关详细信息，请参阅CONTRIBUTING