How To add BotDetect CAPTCHA protection to PHP forms

Start by downloading the Sample BotDetect CAPTCHA PHP project.

• LanapBotDetectHandler.php
• Rendering a CAPTCHA image
• Using an audio CAPTCHA
• Reloading the CAPTCHA image
• Validating user input

LanapBotDetectHandler.php

The sample PHP project includes LanapBotDetectHandler.php, an PHP file that you can use as a helper in your PHP applications.

This file uses the BotDetect CAPTCHA COM control to create a random CAPTCHA image, which is then rendered in the calling PHP page. You can use it "as is" and you don't need to modify it – just copy it to the same folder where your form's PHP source is located.

Always use the POST method!

The PHP code that calls the LanapBotDetectHandler.php module has to be inside a <form> tag that uses the POST method.

[back to top]

Rendering a CAPTCHA image

The easiest way to render a CAPTCHA image is to put an <img> tag like this one in the HTML code of your PHP page:

<img src="LanapBotDetectHandler.php?Command=CreateImage" 
  alt="CAPTCHA image" id="CaptchaImage" />

If you have BotDetect installed and you copied the LanapBotDetectHandler.php module to the same folder as your form, this will result in a picture similar to this being rendered:

Setting additional CAPTCHA image properties

If you want to set additional properties (like choosing the image size, type etc...) just specify them as querystring parameters. For example:

<img src="LanapBotDetectHandler.php?Command=CreateImage&
  TextStyle=28&ImageWidth=300&imageHeight=40&CodeLength=7&
  CodeType=1&Format=PNG" alt="CAPTCHA image" id="CaptchaImage" />

The resulting picture would look like this:

All other parameters (besides ?Command=CreateImage) are optional, and if a parameter is not specified, the default value is used.

For example, the TextStyle parameter specifies the CAPTCHA image drawing algorithm used (out of 50 BotDetect CAPTCHA algorithms). You can find the list of all valid values, examples of use and screenshots for this parameter at the TextStyle reference page.

You can find detailed information about all available CAPTCHA parameters in the BotDetect Component Interface reference documentation.

[back to top]

Using an audio CAPTCHA

If you want to also use a sound CAPTCHA to improve the accessibility of your page, the simplest way to access it is as follows:

<a href="LanapBotDetectHandler.php?Command=CreateSound">
  <img src="speaker.gif" alt="Play Sound" style="border:0;" />
</a>

A speaker icon is used as a link which invokes the sound CAPTCHA playback. You could also use a text link (e.g. "Play Sound") or a different picture if that's more suitable for your application.

Using JavaScript to play the sound CAPTCHA

The previous example is simple, but not very polished - it opens the sound CAPTCHA directly, which will prompt the user to download it.

It would be more user-friendly to play the audio CAPTCHA automatically (in the background of the current page), if the user's browser supports it. This can be achieved with the following code:

<a href="LanapBotDetectHandler.php?Command=CreateSound" 
  onclick="LBD_LoadSound('soundPlaceholder', 
    'LanapBotDetectHandler.php?Command=CreateSound'); 
    return false;">
  <img src="speaker.gif" alt="Play sound" style="border:0;" />
</a>
<div id="soundPlaceholder" style="visibility:hidden; border:0; 
  width:0; height:0;"></div>

This code uses the BotDetectScript.js helper script to dynamically add the CAPTCHA sound object to the page, and start it's playback in the default media player plug-in configured in the user's browser (.wav files are usually handled by Windows Media Player for IE users, and QuickTime for Firefox, Opera and Safari users).

Note that this code will revert to the behavior of the first script for clients without JavaScript support, providing a form of graceful degradation for such users and ensuring the audio CAPTCHA is accessible by the widest possible audience.

[back to top]

Reloading the CAPTCHA image

If you want to add a Reload button allowing the user to change the CAPTCHA image, the JavaScript code is also included in the BotDetectScript.js file. The LBD_ReloadImage function takes the client ID of the CAPTCHA <img> element:

<a href="#" onclick='LBD_ReloadImage("CaptchaImage"); return false;' 
  title="Change the code">
    <img src="reload.gif" alt="Change the code" />
</a>

[back to top]

Validating user input

In a typical CAPTCHA usage scenario, you will have a text box on the page to receive the user's input, and compare it's submitted value to the code rendered in the CAPTCHA image. The Validate method of the BotDetect CAPTCHA component compares the hashed values of the CAPTCHA code and the passed parameter value.

<?php
session_start();
  
$result = false;
$codeKey = "LanapBotDetectCode";
// TODO: read the input from the submitted text box value
$inputCode = $_REQUEST["CaptchaCode"];

if (isset($_SESSION[$codeKey])) {
  $code = $_SESSION[$codeKey];
  $result = (0 == strcasecmp($inputCode, $code));
  // each Captcha code can only be validated once
  unset($_SESSION[$codeKey]);
}

if(!$result) {
  // TODO: the user entered an invalid value
  $redirect_url = "INCORRECT_INPUT_PAGE.PHP";
  header("Location: $redirect_url");
}
?>

[back to top]