PHP Library for reCAPTCHA

The reCAPTCHA PHP Library provides a simple way to place a CAPTCHA on your PHP website, helping you stop bots from abusing your website. The library wraps the reCAPTCHA API.

The library also includes an API for Mailhide, a way to wrap email addresses in a reCAPTCHA, hiding them from spammers.

reCAPTCHA Quickstart

These instructions should get you started quickly.

Download the reCAPTCHA Library, extract recaptchalib.php in the directory where you your forms live.
If you haven't done so, sign up for an API key.

Now we're ready to start modifying your code. First, we'll add code to display the CAPTCHA:

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

In the code that processes the form submission, you need to add code to validate the CAPTCHA. Otherwise, the CAPTCHA will appear, but the answers won't be checked. The validation code looks like:

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

if (!$resp->is_valid) {
  die ("The reCAPTCHA wasn't entered correctly. Go back and try it again." .
       "(reCAPTCHA said: " . $resp->error . ")");
}

The recaptcha_get_html function

The recaptcha_get_html function displays that HTML that presents reCAPTCHA to the user.

recaptcha_get_html
Parameter
$pubkey -- string. required.	Your reCAPTCHA public key, from the API Signup Page
$error -- string. optional (null is the default)	If this string is set, the reCAPTCHA area will display the error code given. This error code comes from ReCaptchaResponse->$error
$use_ssl -- boolean. optional (false is default)	Should the SSL-based API be used? If you are displaying a page to the user over SSL, be sure to set this to true so an error dialog doesn't come up in the user's browser.
Return value	A string containing HTML to put on the web page.

Customizing client side behavior

There are many options available to customize the look and feel of the client side code. You can even create your own theme. Look at our client API guide for more information on this topic.

The recaptcha_check_answer function

After the user has filled out the HTML form, including their answer for the CAPTCHA, we want to check their answer when they submit the form using the recaptcha_check_answer function. The user's answer will be in two form fields, recaptcha_challenge_field and recaptcha_response_field. The reCAPTCHA library will make an HTTP request to the reCAPTCHA server and verify the user's answer.

recaptcha_check_answer

Parameter

$privkey -- string. required. Your reCAPTCHA private key, from the API Signup Page.

$remoteip -- string. required. The user's IP address, in the format 192.168.0.1

$challenge -- string. required.
The value of the form field recaptcha_challenge_field

$response -- string. required The value of the form field recaptcha_response_field

Return value An instance of the ReCaptchaResponse class

ReCaptchaResponse

Field

$is_valid -- boolean Did reCAPTCHA believe the answer was valid?

$error -- string If the answer was invalid what was the problem? This error code can be used in recaptcha_get_html

Return value The HTML or raw url to decode the email address, depending on which you function you called.

Mailhide

The reCAPTCHA PHP Library includes bindings for the Mailhide API. This API allows you to wrap an email in a reCAPTCHA to prevent spammers from seeing it: exam...@example.com.

The Mailhide portion of the PHP Library requires the PHP mcrypt module.

The Mailhide API consists of two functions recaptcha_mailhide_html and recaptcha_mailhide_url. The functions have the same parameters. the _html version returns HTML that can be directly put on your web page. The username portion of the email that is passed in is truncated and replaced with a link that calls Mailhide. The _url version gives you the url to decode the email and leaves it up to you to place the email in HTML.

recaptcha_mailhide_url / recaptcha_mailhide_html

Parameter

$pubkey -- string The Mailhide public key from the signup page

$privkey -- string The Mailhide private key from the signup page

$email -- string The email address you want to hide.

Examples

The following is a "Hello World" with reCAPTCHA:

<html>
  <body>
    <form action="" method="post">
<?php

require_once('recaptchalib.php');
$publickey = "...";
$privatekey = "...";

# the response from reCAPTCHA
$resp = null;
# the error code from reCAPTCHA, if any
$error = null;

# are we submitting the page?
if ($_POST["submit"]) {
  $resp = recaptcha_check_answer ($privatekey,
                                  $_SERVER["REMOTE_ADDR"],
                                  $_POST["recaptcha_challenge_field"],
                                  $_POST["recaptcha_response_field"]);

  if ($resp->is_valid) {
    echo "You got it!";
    # in a real application, you should send an email, create an account, etc
  } else {
    # set the error code so that we can display it. You could also use
    # die ("reCAPTCHA failed"), but using the error message is
    # more user friendly
    $error = $resp->error;
  }
}
echo recaptcha_get_html($publickey, $error);
?>
    <br/>
    <input type="submit" name="submit" value="submit" />
    </form>
  </body>
</html>

The following example shows how to use Mailhide:

<html><body>
<?
require_once ("recaptchalib.php");
// get a key at http://mailhide.recaptcha.net/apikey
$mailhide_pubkey = '';
$mailhide_privkey = '';
?>
The Mailhide version 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>

If you're looking for some more examples, take a look at the WordPress and MediaWiki plugins, which use this library.

Guidelines for CAPTCHA Integration:

Make the experience for the user as smooth as possible if they don't pass the CAPTCHA. Make use of the error parameter to display an error message. Be sure to preserve the data that the user wrote. The quickstart guide uses the PHP "die" function to display an error. While this is simple for the programmer, it is not a good user experience.
If you are writing a plugin for an application with a management UI, provide a link to get a reCAPTCHA key with the recaptcha_get_signup_url function. This function has two optional parameters. First, you can pass a domain name to pre-fill the signup form. Second, you can pass an app name to let us track which plugins are popular.