此页面由 Cloud Translation API 翻译。

将 reCAPTCHA 与 PHP 搭配使用

重要提示：reCAPTCHA API 1.0 版已不再受支持，请升级到 2.0 版。了解详情

reCAPTCHA PHP 库提供了一种在 PHP 网站上添加人机识别系统的简单方法，可帮助您阻止漫游器滥用该功能。该库封装了 reCAPTCHA API。

如需将 reCAPTCHA 与 PHP 搭配使用，您可以下载 reCAPTCHA PHP 库。在该页面中，您只需要一个文件 (recaptchalib.php)。其他文件是示例、自述文件以及法律文件，不会影响功能。

快速入门

客户端（如何显示人机识别系统图片）

如果您想要使用 PHP 库显示 reCAPTCHA widget，则需要在将放置 reCAPTCHA widget 的 <form> 元素中插入以下代码段：

  require_once('recaptchalib.php');
  $publickey = "your_public_key"; // you got this from the signup page
  echo recaptcha_get_html($publickey);

使用以上代码，您的表单可能如下所示：

  <html>
    <body> <!-- the body tag is required or the CAPTCHA may not show on some browsers -->
      <!-- your HTML content -->

      <form method="post" action="verify.php">
        <?php
          require_once('recaptchalib.php');
          $publickey = "your_public_key"; // you got this from the signup page
          echo recaptcha_get_html($publickey);
        ?>
        <input type="submit" />
      </form>

      <!-- more of your HTML content -->
    </body>
  </html>

不要忘记通过将 your_public_key 替换为您的 API 公钥来设置 $publickey。

请注意，“action”属性的值为“verify.php”。现在，verify.php 是提交此表单值的目标文件。因此，您需要一个与客户端 HTML 位于同一位置的文件 verify.php。

上例中的 require_once 函数要求 recaptchalib.php 与表单文件位于同一目录中。如果该文件位于其他目录中，您必须相应地关联它。例如，如果您的 recaptchalib.php 位于名为“captcha”的目录中，该目录与您的表单文件位于同一级别，则函数将如下所示：require_once('captcha/recaptchalib.php')。

服务器端（如何测试用户是否输入了正确答案）

以下代码应放置在 verify.php 文件的顶部：

  <?php
  require_once('recaptchalib.php');
  $privatekey = "your_private_key";
  $resp = recaptcha_check_answer ($privatekey,
                                $_SERVER["REMOTE_ADDR"],
                                $_POST["recaptcha_challenge_field"],
                                $_POST["recaptcha_response_field"]);

  if (!$resp->is_valid) {
    // What happens when the CAPTCHA was entered incorrectly
    die ("The reCAPTCHA wasn't entered correctly. Go back and try it again." .
         "(reCAPTCHA said: " . $resp->error . ")");
  } else {
    // Your code here to handle a successful verification
  }
  ?>

在上面的代码中：

recaptcha_check_answer 会返回一个对象，表示用户是否成功完成了挑战。

如果 $resp->is_valid 为 true，则表示已正确完成人机识别系统验证，您应继续处理表单。

如果 $resp->is_valid 为 false，则表示用户未能提供正确的人机识别系统文本，您应该重新显示该表单，允许用户再次尝试。在这种情况下，$resp->error 将是可以向 recaptcha_get_html 提供的错误代码。传递错误代码会使 reCAPTCHA 控件显示一条消息，说明用户输入的文本不正确，应重试。

请注意，此代码请求获取私钥，请勿将其与公钥混淆。您可以从公钥所在的页面获取该 ID。

此外，请确保将表单设置为使用 $_POST（而不是 $_REQUEST）获取表单变量，并且表单本身使用的是 POST 方法。

大功告成！现在，reCAPTCHA 应该可以在您的网站上运行。

延伸阅读

自定义外观和风格

提示和指南

问题排查

PHP 插件参考指南

下面完整列出了 reCAPTCHA PHP 插件的所有方法。

recaptcha_get_html 函数

recaptcha_get_html 函数会显示向用户显示 reCAPTCHA 的 HTML。

recaptcha_get_html
参数
$pubkey - 字符串。必填。	您的 reCAPTCHA 公钥（在 API 注册页面上提供）
$error -- 字符串。可选（默认值为 null）	如果设置了此字符串，reCAPTCHA 区域将显示给定错误代码。此错误代码来自 ReCaptchaResponse->$error
$use_ssl -- 布尔值。可选（默认值为 false）	是否应使用基于 SSL 的 API？如果您要通过 SSL 向用户显示网页，请务必将此字段设为 true，这样用户的浏览器中就不会显示错误对话框。
返回值	包含要放在网页上的 HTML 的字符串。

recaptcha_check_answer 函数

用户填写完 HTML 表单（包括提供人机识别系统回答）后，我们希望在用户使用 recaptcha_check_answer 函数提交表单时检查他们的回答。用户的回答会显示在两个表单字段 recaptcha_challenge_field 和 recaptcha_response_field 中。reCAPTCHA 库会向 reCAPTCHA 服务器发出 HTTP 请求，并验证用户的答案。

recaptcha_check_answer
参数
$privkey -- 字符串。必需。	您的 reCAPTCHA 私钥（在 API 注册页面上提供）。
$remoteip - 字符串。必需。	用户的 IP 地址，格式为 192.168.0.1
$challenge - 字符串。必填。	表单字段 recaptcha_challenge_field 的值
$response -- 字符串。必填	表单字段 recaptcha_response_field 的值
返回值	ReCaptchaResponse 类的实例

ReCaptchaResponse
字段
$is_valid -- 布尔值	reCAPTCHA 是否认为答案有效？
$error -- 字符串	如果答案无效，问题是什么？此错误代码可用于 recaptcha_get_html
返回值	用于对电子邮件地址进行解码的 HTML 或原始网址，具体取决于您调用的函数。

Mailhide

reCAPTCHA PHP 库包含 Mailhide API 绑定。此 API 允许您将电子邮件封装到 reCAPTCHA 中，以防止垃圾邮件发送者看到：exam...@example.com。

PHP 库的 Mailhide 部分需要 PHP mcrypt 模块。

Mailhide API 由 recaptcha_mailhide_html 和 recaptcha_mailhide_url 两个函数组成。这些函数具有相同的参数。_html 版本会返回可直接放置在您网页上的 HTML。传入的电子邮件的用户名部分会被截断并替换为调用 Mailhide 的链接。_url 版本会为您提供用于解码电子邮件的网址，由您自行决定是否将电子邮件放入 HTML 中。

recaptcha_mailhide_url / recaptcha_mailhide_html
参数
$pubkey -- 字符串	注册页面上的 Mailhide 公钥
$privkey -- 字符串	注册页面中的 Mailhide 私钥
$email -- 字符串	您要隐藏的电子邮件地址。

以下示例展示了如何使用 Mailhide：

<html><body>
<?
require_once ("recaptchalib.php");
// get a key at http://www.google.com/recaptcha/mailhide/apikey
$mailhide_pubkey = '';
$mailhide_privkey = '';
?>
The Mailhide encoding of example@example.com is
<?
echo recaptcha_mailhide_html ($mailhide_pubkey,
                              $mailhide_privkey,
                              "example@example.com");
?>.
<br>
The url for the email is:
<?
echo recaptcha_mailhide_url ($mailhide_pubkey,
                             $mailhide_privkey,
                             "example@example.com");
?>
<br>
</body></html>