How to integrate reCAPTCHA

From Unofficial reCAPTCHA Wiki

To add reCAPTCHA protection to a form you must

display the reCAPTCHA control when you display the form to the user
ask the reCAPTCHA verification server to check the user's response when you validate the user's input

See I can't work out where to add reCAPTCHA if you're having difficulty working out where the reCAPTCHA calls must be added to your code.

Before you can do either of these things you must

download and install the reCAPTCHA library for the language you are using and
obtain a pair of cryptographic keys for your site

1 Displaying the reCAPTCHA control
2 Checking user input
- 2.1 Success?
3 A practical example
4 Further Reading

[edit] Displaying the reCAPTCHA control

We'll assume you're using the PHP reCAPTCHA library. For other languages the detail will differ but the logic is the same.

First include recaptchalib.php:

 require_once('recaptchalib.php');

define your public and private keys:

 # These are /not/ real keys - you must replace them with your *own* keys
 define('PUBLIC_KEY',  '6LcTCgAAAAAAgOdATOWSL66jRLL6ioPibkgMp');
 define('PRIVATE_KEY', '6LtYPgAAAAAAbodQWSLAP66jR997ioPibkgMp');

then somewhere inside the <form> .. </form> tags include the reCAPTCHA control

 echo recaptcha_get_html( PUBLIC_KEY );

Now test your form. You should see the reCAPTCHA control.

[edit] Checking user input

When the user submits the form you must ask the verification server to check their response to the reCAPTCHA challenge.

The information reCAPTCHA needs to check the response will be in two form fields: recaptcha_challenge_field and recaptcha_response_field. To find out whether the reCAPTCHA challenge was completed successfully you must pass your private key, the IP address of the user's computer and the contents of these two fields to recaptcha_check_answer like this:

 # Ask reCAPTCHA to check the user's response
 $response = recaptcha_check_answer( 
   PRIVATE_KEY, $_SERVER['REMOTE_ADDR'], 
   $_POST['recaptcha_challenge_field'], 
   $_POST['recaptcha_response_field'] );

[edit] Success?

recaptcha_check_answer returns an object that represents whether the user successfully completed the challenge.

If $response->is_valid is true then the captcha challenge was correctly completed and you should continue with form processing.

If $response->is_valid is false then the user failed to provide the correct captcha text and you should redisplay the form to allow them another attempt. In this case $response->error will be an error code that should be provided to recaptcha_get_html. Passing the error code makes the reCAPTCHA control display a message explaining that the user entered the text incorrectly and should try again.

[edit] A practical example

   
    <html>
        <body>
            <form action="" method="post">
                <?php
                    # Get the reCAPTCHA library
                    require_once('recaptchalib.php');

                    # These are /not/ real keys - you must replace them with your *own* keys
                    # obtained from http://recaptcha.net/api/getkey
                    define('PUBLIC_KEY',  '6LcTCgAAAAAAgOdATOWSL66jRLL6ioPibkgMp');
                    define('PRIVATE_KEY', '6LtYPgAAAAAAbodQWSLAP66jR997ioPibkgMp');

                    # Did the user fail the captcha test?
                    $error = null;

                    # This is where we process the user's response. We don't
                    # do this when the form is initially displayed - only
                    # when the user submits it.
                    if ($_POST["recaptcha_response_field"]) {
                        $response = recaptcha_check_answer( 
                            PRIVATE_KEY, $_SERVER['REMOTE_ADDR'],
                            $_POST['recaptcha_challenge_field'],
                            $_POST['recaptcha_response_field']
                        );

                        if ( $response->is_valid ) {
                            # The user passed the reCAPTCHA test: form submission should continue
                            # Your other form validation logic should go here.
                        
                            # For example
                            # ... validate user input ...
                            # ... store form data in a database ...
                            # ... redirect to 'thank you' page
                        
                        }
                        else {
                            # The user failed the reCAPTCHA test so we need
                            # to fill in the error message and re-try the
                            # form submission
                            $error = $response->error;
                        }
                    }
                
                    # Display the reCAPTCHA challenge. The first time
                    # through $error will be null. 

                    echo recaptcha_get_html( PUBLIC_KEY, $error );
                ?>
                <br />
                <!-- example form fields - your own fields go here -->
                Username: <input type="text" name="username" value="" /><br />
                Email address: <input type="text" name="email"    value="" /><br />
                <input type="submit" value="submit" />
            </form>
        </body>
    </html>