CAPTCHA Customization PHP Code Sample

The PHP Captcha customization code sample shows how to customize BotDetect CAPTCHA behavior and appearance.

First Time Here?

Check the BotDetect Developer Crash Course for key integration steps.

BotDetect 3.0 allows user-defined customization of many Captcha options through a special botdetect/CaptchaConfig.php configuration file; some customizations also require page source changes.

Shown customizations include: CAPTCHA image color scheme, sound & reload icons and their tooltips, custom client-side handlers for BotDetect actions such as sound playing and Captcha reloading (resulting in simple message boxes on icon clicks in this sample), ...

The CaptchaConfig.php file used in this code sample contains detailed descriptions and explanations of the many customizable options.

You can then use chosen customization options to configure BotDetect to precisely match your application requirements.

Download the BotDetect PHP CAPTCHA Library and run this sample

Downloaded Location

The PHP Captcha customization code sample is included in the samples/captcha_customization_sample folder of the download package.

index.php

<?php session_start(); ?>
<?php require("botdetect.php"); ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.
  org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
  <title>BotDetect PHP CAPTCHA Customization Sample</title>
  <link type="text/css" rel="Stylesheet" href="StyleSheet.css" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <link type="text/css" rel="Stylesheet" href="<?php echo CaptchaUrls::
    LayoutStylesheetUrl() ?>" />
</head>
<body>
  <form method="post" action="" id="form1">

    <h1>BotDetect PHP CAPTCHA Customization Sample</h1>

    <fieldset>
      <legend>PHP CAPTCHA validation</legend>
      <label for="CaptchaCode">Retype the characters from the picture:</label>

      <?php // Adding BotDetect Captcha to the page
        $CustomizedCaptcha = new Captcha("CustomizedCaptcha");
        $CustomizedCaptcha->UserInputID = "CaptchaCode";
        echo $CustomizedCaptcha->Html();
      ?>

      <div class="validationDiv">
        <input name="CaptchaCode" type="text" id="CaptchaCode" />
        <input type="submit" name="ValidateCaptchaButton" value="Validate" 
          id="ValidateCaptchaButton" />

        <?php // when the form is submitted
          if ($_POST) {
            // validate the Captcha to check we're not dealing with a bot
            $isHuman = $CustomizedCaptcha->Validate();

            if (!$isHuman) {
              // Captcha validation failed, show error message
              echo "<span class=\"incorrect\">Incorrect code</span>";
            } else {
              // Captcha validation passed, perform protected action
              echo "<span class=\"correct\">Correct code</span>";
            }
          }
        ?>
      </div>

    </fieldset>

    <script type="text/javascript">
      // custom javascript handler executed before Captcha sounds are played
      BotDetect.RegisterCustomHandler('PrePlaySound', 
        function() { 
          alert('PrePlaySound: ' + this.Id); 
        }
      );
      
      // custom javascript handler executed before Captcha images are reloaded
      BotDetect.RegisterCustomHandler('PreReloadImage', 
        function() { 
          alert('PreReloadImage: ' + this.Image.src + ' AutoReload: ' + this.
            AutoReloading); 
        }
      );
      
      // custom javascript handler executed after Captcha images are reloaded
      BotDetect.RegisterCustomHandler('PostReloadImage', 
        function() { 
          alert('PostReloadImage: ' + this.Image.src); 
        }
      );
    </script>

  </form>
</body>
</html>

In the form source, we follow the standard procedure for adding Captcha protection to a PHP form.

The script fragment below the form shows a very simple example of using the BotDetect client-side API to customize Captcha behavior.

[back to top]

botdetect/CaptchaConfig.php

<?php

// override lib settings
$LBD_CaptchaConfig = CaptchaConfiguration::GetSettings();


// Captcha code configuration
// ---------------------------------------------------------------------------

// Captcha code length, in characters
$LBD_CaptchaConfig->CodeLength = 4;

// Captcha code style (alphanumeric, alpha, or numeric)
$LBD_CaptchaConfig->CodeStyle = CodeStyle::Alpha;

// Captcha code timeout in seconds - the Captcha can only be successfully
// solved within the specified time after generation. This is an optional
// security improvement that narrows the window of opportunity for attacks
// based on re-using the Captcha image on another site controlled by the
// attacker, or similar human-solver-based attacks on Captcha-protected
// forms.
$LBD_CaptchaConfig->CodeTimeout = 600;

// Captcha locale string, affecting the charset used for Captcha code
// generation, and the pronunciation language used for sound Captchas
$LBD_CaptchaConfig->Locale = 'en-US';

// Defines a custom character set for Captcha code generation, specifying
// the alphanumeric characters which will be used for all Captcha codes
// regardless of the codeStyle value set
$LBD_CaptchaConfig->CustomCharset = 'A,B,C,D,E,1,2,3,4';

// Defines rules about character sequences you want to avoid using in
// randomly generated Captcha codes. Must be a CSV string. 
// NOTE: see Captcha Code Filtering Sample for an example.
$LBD_CaptchaConfig->BannedSequences = '';


// Captcha image configuration
// ---------------------------------------------------------------------------

// Captcha image style - can be a fixed or a randomized value selected from
// the 60 BotDetect image drawing algorithms
$LBD_CaptchaConfig->ImageStyle = CaptchaRandomization::GetRandomImageStyle();

// Captcha image width, in pixels
$LBD_CaptchaConfig->ImageWidth = 250;

// Captcha image height, in pixels
$LBD_CaptchaConfig->ImageHeight = 50;

// Captcha image output format (JPG, GIF, PNG or BMP)
$LBD_CaptchaConfig->ImageFormat = ImageFormat::Png;

// Used to override the default Captcha image color scheme.
// Html named or hex color value of the dark color used in Captcha images.
$LBD_CaptchaConfig->CustomDarkColor = '#483D8B';

// Used to override the default Captcha image color scheme.
// Html named or hex color value of the light color used in Captcha images
$LBD_CaptchaConfig->CustomLightColor = '#87CEFA';

// Custom Captcha image alt text
$LBD_CaptchaConfig->ImageTooltip = 'CAPTCHA Image Custom Tooltip';


// Captcha sound configuration
// ---------------------------------------------------------------------------

// Is Captcha sound enabled
$LBD_CaptchaConfig->SoundEnabled = true;

// Captcha sound style - can be a fixed or a randomized value selected from
// the 10 BotDetect sound generation algorithms
$LBD_CaptchaConfig->SoundStyle = CaptchaRandomization::GetRandomSoundStyle();

// Captcha sound output format (WavPcm16bit8KhzMono or WavPcm8bit8KhzMono)
$LBD_CaptchaConfig->SoundFormat = SoundFormat::WavPcm16bit8kHzMono;

// Custom sound Captcha icon alt text / title
$LBD_CaptchaConfig->SoundTooltip = 'Sound Icon Custom English Tooltip';

// If the required SoundPackage in not deployed, the sound icon is not
// clickable and displays a warning tooltip by default. If you want to disable
// this warning and simply not display the sound Captcha icon at all for
// locales whose pronunciations are not deployed with the application,
// set this property to "false".
$LBD_CaptchaConfig->WarnAboutMissingSoundPackages = true;

// Starting delay of sound JavaScript playback, in miliseconds.
// Useful for improving usability of the Captcha sound for blind people using
// JAWS or similar readers, which will read the Captcha sound icon label when 
// it's selected and start sound playback simultaneously.
// Setting this delay to e.g. 2000 (2 seconds) will give the user time to hear
// both the pronounced label and the Captcha sound clearly.
$LBD_CaptchaConfig->SoundStartDelay = 1000;


// Captcha reload configuration
// ---------------------------------------------------------------------------

// Is Captcha reloading enabled
$LBD_CaptchaConfig->ReloadEnabled = true;

// Custom reload Captcha icon alt text / title
$LBD_CaptchaConfig->ReloadTooltip = 'Reload Icon Custom Tooltip';

// Captcha images are automatically reloaded when the Captcha code expires
// (as set in the $LBD_CaptchaConfig->CodeTimeout element), but only within 
// a certain interval from their first generation. 
// This allows you to have a short Captcha code timeout (e.g. 2 minutes) 
// to narrow the window of opportunity for Captcha reusing on other sites 
// or human-solver-powered bots, and actual visitors can still fill out 
// your form at their own pace and without rushing (since the Captcha image 
// will be automatically reloaded when it is no longer valid).
$LBD_CaptchaConfig->AutoReloadExpiredCaptchas = true;

// Since we don't want infinite sessions when the user leaves the form open
// in a background browser tab over the weekend (for example), we set a
// reasonable upper limit on the auto-reload period (e.g. 2 hours = 7200
// seconds).
$LBD_CaptchaConfig->AutoReloadTimeout = 7200;


// Captcha help link configuration
// ---------------------------------------------------------------------------

// Is the Captcha help link enabled or not
$LBD_CaptchaConfig->HelpLinkEnabled = true;

// Controls how the Captcha help link is displayed; supported modes are 
// "Image" and "Text"
$LBD_CaptchaConfig->HelpLinkMode = HelpLinkMode::Text;

// Url (absolute or relative) to which the Captcha help link points to
$LBD_CaptchaConfig->HelpLinkUrl = 'captcha.html';

// Text used in the Captcha help link; leave empty for default image width-
// dependent text
$LBD_CaptchaConfig->HelpLinkText = '';


// Captcha user input configuration
// ---------------------------------------------------------------------------

// The input textbox will be assigned focus on all Captcha Sound and
// Captcha Reload icon clicks, allowing the users to more easily type
// in the code as they hear it or as the new image loads. This does not
// apply to auto-reloading of expired Captchas, since the user might
// be filling out another field on the form when the auto-reload
// starts and shouldn't be distracted.
$LBD_CaptchaConfig->AutoFocusInput = true;

// The input textbox will be cleared on all Reload icon clicks and auto-
// reloads, since any previous input in the textbox will be invalidated
// by Captcha reloading. This is a small usability improvement that
// helps users avoid having to delete the previous input themselves.
$LBD_CaptchaConfig->AutoClearInput = true;

// Anything the users type in the input textbox will be lowercased
// on the fly, since Captcha validation is not and should not be case-
// sensitive. This is a small usability improvement that helps
// communicate that fact to the users clearly.
$LBD_CaptchaConfig->AutoLowercaseInput = true;


// Captcha remote script configuration
// ---------------------------------------------------------------------------

// Should BotDetect also add the remote JavaScript include loaded from the 
// captcha.com server. Currently used only for stats, but planned to develop
// into additional Captcha functionality.
$LBD_CaptchaConfig->RemoteScriptEnabled = true;


// Captcha URL configuration
// ---------------------------------------------------------------------------

// Custom Captcha sound icon, relative or absolute Url
$LBD_CaptchaConfig->SoundIconUrl = 'custom_sound_icon.gif';

// Custom Captcha reload icon, relative or absolute Url
$LBD_CaptchaConfig->ReloadIconUrl = 'http://captcha.com/images/refresh.png';

// For custom integrations into 3rd party frameworks, it might be necessary to 
// modifythe base Url of Captcha image and sound requests, as well 
// as the fixed BotDetect resources (stylesheet and client-side include)
$LBD_CaptchaConfig->HandlerUrl = 'botdetect.php';
$LBD_CaptchaConfig->LayoutStylesheetUrl = LBD_URL_ROOT . 'lbd_layout.css';
$LBD_CaptchaConfig->ScriptIncludeUrl = LBD_URL_ROOT. 'lbd_scripts.js';

?>

Since the code sample includes the BotDetect Captcha library from a shared location, we use a local config file to override base Captcha settings. If you are just copying the whole Captcha library to the root folder of your website, you could make the same changes in the main botdetect/CaptchaConfig.php file.

The sample CaptchaConfig.php file shows and explains most Captcha configuration settings available.

[back to top]


Please Note

BotDetect 3.0 PHP Captcha Library Beta1 is an in-progress port of BotDetect 3.0 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.

BotDetect 3 PHP is already available for purchase at a 33% discounted pre-release price.

© Lanapsoft, Inc. 2004-2013. All rights reserved.

BotDetect, BotDetect CAPTCHA, Lanap, Lanap CAPTCHA, Lanap BotDetect, Lanap BotDetect CAPTCHA, Lanapsoft, Lanapsoft CAPTCHA, Lanapsoft BotDetect, Lanapsoft BotDetect CAPTCHA, and Lanap Software are trademarks of Lanapsoft, Inc. All other product, brand, and company names are mentioned for identification purposes only and are trademarks or registered trademarks of their respective owners.