BotDetect CAPTCHA Options: Application Config Settings Code Example

The PHP Captcha options: Application config settings code example shows how to configure Captcha challenges by overriding Captcha library defaults in application configuration files.

First Time Here?

Check the BotDetect Developer Crash Course for key integration steps.

BotDetect allows user-defined customization of many Captcha options through a special CaptchaConfig.php file, which should be placed in the same folder as the botdetect.php include used by your PHP forms.

Captcha settings from this configuration file will apply to all Captcha challenges shown on forms including that particular copy of botdetect.php, and will act as defaults with which all Captcha objects will be created. This makes configuration file settings the simplest and most convenient way of Captcha customization for most use cases.

The CaptchaConfig.php file used in this code example contains detailed descriptions and explanations of the many customizable Captcha options exposed by the BotDetect PHP Captcha configuration API.

Example Location

The PHP Captcha options: Application config settings code example is included in the examples/simple-api-captcha-application-config-settings-example folder of the download package.

Download the BotDetect PHP CAPTCHA Library and run this example

index.php

<?php session_start(); ?>
<?php require("custom-captcha-request-handler.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 Options: Application Config Settings Code Example</title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <link type="text/css" rel="Stylesheet" href="stylesheet.css" />
  <script type="text/javascript" src="custom-captcha-request-handler.php?get=script-include"></script>
</head>
<body>
  <form method="post" action="" class="column" id="form1">

    <h1>BotDetect PHP CAPTCHA Options: <br /> Application Config Settings Code Example</h1>

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

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

      <div class="validationDiv">
        <input name="CaptchaCode" type="text" id="CaptchaCode" />
        <input type="submit" name="ValidateCaptchaButton" id="ValidateCaptchaButton" value="Validate" />
        <?php // when the form is submitted
          if ($_POST) {
            // validate the Captcha to check we're not dealing with a bot
            $isHuman = $AppConfigCustomizedCaptcha->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>
  </form>
</body>
</html>

In the form source, we don't follow the non-standard procedure for adding Captcha protection to a PHP form, i.e we're using the custom-captcha-request-handler.php file instead of simple-botdetect.php in default to process Captcha challenge Http requests.

lib/config/botdetect.xml

<?xml version="1.0" encoding="UTF-8"?>
<botdetect xmlns="https://captcha.com/schema/php"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://captcha.com/schema/php
           https://captcha.com/schema/php/botdetect-4.2.3.xsd">

    <captchaStyles>
        <captchaStyle>
            <name>AppConfigCustomizedCaptcha</name>
            <userInputID>CaptchaCode</userInputID>
            <!--Captcha codes-->

            <!--Number of characters in randomly generated Captcha codes (answers to Captcha
            challenges).
            The default value is random (4-6 characters).
            Valid user Captcha code length setting values are integers larger than 0 and
            smaller than 16.
            It is recommended to always randomize Captcha code length since it
            significantly increases Captcha security vs. automated analysis.-->
            <codeLength>3-5</codeLength>


            <!--Character types used to generate random Captcha codes.-->
            <!--The default value is Alphanumeric.-->
            <!--Valid user Captcha code style setting values are members of the BotDetect-->
            <!--CodeStyle enumeration (Alpha, Numeric, or Alphanumeric).-->
            <!--Since entropy of the Captcha challenge depends on character set size to-->
            <!--the power of Captcha code length, alpha codes should be slightly longer-->
            <!--than alphanumeric ones (while numeric Captcha codes should be significantly-->
            <!--longer) to achieve an appropriate level of Captcha security.-->
            <codeStyle>Alpha</codeStyle>


            <!--Strings that should never occur in randomly generated Captcha codes. Can be
            both single characters (allows Captcha character set customization) and
            sequences of two or more characters (useful for swear words filtering, avoiding
            particular hard-to-read sequences etc.).
            The default value is empty (Captcha code filtering is optional).
            Valid user disallowed Captcha code substring setting values are lists of
            arbitrary strings, in CSV format. Whitespace is ignored, and disallowed
            substrings are not case-sensitive (because Captcha codes are case-insensitive
            as well).
            The character set used for Captcha code generation is automatically chosen
            based on Captcha locale. Since each character needs to have its pronunciation
            recorded and available to BotDetect code, expanding that default character set
            to include new characters is not supported (it would break Captcha sound
            functionality). However, if a particular character is found hard to read,
            it can easily be excluded from randomly generated Captcha codes. Furthermore,
            offensive or otherwise undesirable words and character sequences can be banned.
            Since Captcha codes are generally short, it doesn't make sense to use an
            actual dictionary of words, but simple short sequences that cover multiple
            disallowed values. E.g. to prevent the random generator from using both 'man',
            'manners' and 'mannequin' in Captcha codes, it's enough to ban the 'man'
            sequence.-->
            <disallowedCodeSubstrings>d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z,aa,bb,cc,abc,bca,cab
            </disallowedCodeSubstrings>


            <!--Captcha images-->

            <!--The BotDetect drawing algorithm used to render Captcha codes in image Captcha
            challenges.
            The default value is random (an image style is chosen from all available
            values for each Captcha image generated).
            Valid user Captcha image style setting values are members of the BotDetect
            ImageStyle enumeration. Please note that some image styles are restricted to
            licensed versions of BotDetect, and will be ignored in free version
            implementations.
            It's best to randomize the Captcha image style, since randomly choosing a
            style for each Captcha image generated provides the highest level of Captcha
            security against automated OCR analysis.-->
            <imageStyle>Chipped,Fingerprints,Graffiti,Bullets</imageStyle>


            <!--Size of Captcha image challenges generated.
            The default value is 250 x 50 pixels.
            Valid user Captcha image size setting values are integers: widths can be
            between 20 and 500 pixels and heights between 20 and 200 pixels.
            To keep Captcha images reasonably readable, their width:height ratio
            should be approximately the same as the average Captcha code length.ls-->
            <imageWidth>200</imageWidth>
            <imageHeight>50</imageHeight>


            <!--Image format in which Captcha images will be generated and sent to the client.
            The default value is Jpeg.
            Valid user Captcha image format setting values are members of the BotDetect
            ImageFormat enumeration (Jpeg, Png, Gif).
            Please note that some Captcha image styles will result in low-quality
            (pixelated) images when the image format is set to Gif, due to randomized
            color schemes and use of color gradients. When switching image formats,
            please take care to check the impact on Captcha image readability.-->
            <imageFormat>Png</imageFormat>


            <!--BotDetect allows Captcha image color scheme customization though two color
            points: a custom dark color and a custom light color.
            The default values are empty (Captcha color customization is optional).
            Valid user Captcha custom dark / light color setting values are Html colors,
            so you can use both predefined color names and custom color hex values.
            Since many Captcha drawing styles randomize the actual color used, the
            user-defined values are used as randomization starting points instead of
            absolute values. Furthermore, since some drawing styles use light text on
            a dark background, while other draw dark text on a light background, text
            and background colors are not set directly, but are referred to as simply
            the "dark" and the "light" color. This allows you to randomize the image
            drawing style, for example, and still keep a consistent color scheme
            adjusted to your website design.-->
            <customDarkColor>#483d8b</customDarkColor>
            <customLightColor>#87cefa</customLightColor>


            <!--Captcha sounds-->

            <!--Is Captcha sound enabled.
            The default value is true.
            Valid user Captcha sound enabled setting values are booleans.
            Captcha sound can be disabled entirely (for example if you are using the
            free version of BotDetect, which only supports demo sound that is not
            actually accessible to human visitors) by setting this property to false.-->
            <soundEnabled>true</soundEnabled>


            <!--The BotDetect audio generation algorithm used to pronounce Captcha codes in
            sound Captcha challenges.
            The default value is random (a sound style is chosen from all available
            values for each Captcha sound generated).
            Valid user Captcha sound style setting values are members of the BotDetect
            SoundStyle enumeration. Please note that some sound styles are restricted
            to licensed versions of BotDetect, and will be ignored in free version
            implementations.
            It's best to randomize the Captcha sound style, since randomly choosing a
            style for each Captcha sound generated provides the highest level of Captcha
            security against automated audio analysis and voice recognition.-->
            <soundStyle>Dispatch,RedAlert,Synth</soundStyle>


            <!--Audio format in which Captcha sounds will be generated and sent to the client.
            The default value is WavPcm16bit8kHzMono.
            Valid user Captcha sound format setting values are members of the BotDetect
            SoundFormat enumeration (WavPcm16bit8kHzMono, WavPcm8bit8kHzMono).
            Using 8 bit sound instead of default 16 bits per example lowers the WAV file
            download size, but reduces sound quality.-->
            <soundFormat>WavPcm16bit8kHzMono</soundFormat>


            <!--How will multiple consecutive requests for audio Captcha with the same
            Captcha code ("sound regeneration") be handled by BotDetect - a tradeoff
            of security, usability, and storage requirements.
            The default value is Limited.
            Valid user Captcha sound regeneration mode setting values are members of the
            BotDetect SoundRegenerationMode enumeration (None, Limited, Unlimited).
            BotDetect defaults to limited sound regeneration as the most reasonable
            overall trade-off. At user discretion, higher security and usability can be
            achieved by disabling sound regeneration at the cost of significant amounts
            of server-side storage space. Unlimited sound regeneration is not recommended
            due to low security, but is left as an option for backwards-compatibility.-->
            <soundRegenerationMode>None</soundRegenerationMode>


            <!--Captcha localization & locale-dependent strings-->

            <!--Captcha locale string, determining the exact character set used for random
            Captcha code generation and the pronunciation language used for sound
            Captcha generation.
            The default value is en-US.
            Valid user Captcha locale setting values are composed of ISO language codes
            (for example en, ru, cmn, ...), charset codes (for example ja-Hira uses
            Japanese Hiragana characters, while ja-Kana uses Japanese Katakana characters)
            and country codes (for example en-US and en-GB differ in the pronunciation
            used).
            Check the BotDetect localization page to find the list of currently supported
            locales, and download the pronunciation resources required for Captcha sounds.
            If you use a right-to-left locale setting like Arabic or Hebrew, you should
            also set the appropriate text direction on the textbox element used for
            Captcha code retyping (dir="rtl").-->
            <locale>en-US</locale>


            <!--The alternative text of the Captcha image Html element.
            The default value is Retype the CAPTCHA code from the image.
            Valid user Captcha image tooltip setting values are arbitrary strings.-->
            <imageTooltip>Custom Captcha image tooltip</imageTooltip>


            <!--Tooltip of the Captcha sound icon.
            The default value is "Speak the CAPTCHA code".
            Valid user Captcha sound tooltip setting values are arbitrary strings.-->
            <soundTooltip>Custom Captcha sound icon tooltip</soundTooltip>


            <!--Tooltip of the Captcha reload icon.
            The default value is "Change the CAPTCHA code".
            Valid user Captcha reload tooltip setting values are arbitrary strings.-->
            <reloadTooltip>Custom Captcha reload icon tooltip</reloadTooltip>


            <!--Text or tooltip of the Captcha help link, depending on help link mode.
            The default value depends on the width of the Captcha image.
            Valid user Captcha help link setting values are strings at least 4 characters
            long.-->
            <helpLinkText>Custom Captcha help link text</helpLinkText>


            <!--Url of the localized Captcha help page the help link points to.
            The default value depends on Captcha locale.
            Valid user Captcha help link url setting values are absolute or relative Urls.
            This setting is only supported in licensed versions of BotDetect.-->
            <helpLinkUrl>custom-captcha-help-page.html</helpLinkUrl>


            <!--Captcha controls & appearance-->

            <!--Is Captcha reloading (changing the Captcha code because the current one is
            too hard to read) enabled.
            The default value is true.
            Valid user Captcha reload enabled setting values are booleans.
            Requesting a new Captcha challenge on the current form requires client-side
            scripting, so the reload icon is only shown in browsers that have JavaScript
            enabled. When JavaScript is disabled or unsupported, the visitor can still
            get a different Captcha challenge by reloading the form.-->
            <reloadEnabled>false</reloadEnabled>


            <!--Default BotDetect Captcha icons are 22x22 pixels large, but there is also a
            smaller set of 17x17 px icons used when the default ones are too large.
            This settings allows you to control which icon set will be used.
            The default value is true when the Captcha image height is < 50px, and false
            otherwise.
            Valid user use small Captcha icons setting values are booleans: setting this
            value to true will force BotDetect to use small built-in icons, while false
            will disable automatic switching to small icons depending on image height.
            This setting only applies to default BotDetect icons, and should not be used
            in combination with user-defined icons.-->


            <useSmallIcons>false</useSmallIcons>
            <!--BotDetect displays the Captcha sound and reload icon one below the other by
            default, and switches to displaying them one beside the other when Captcha
            images are small enough. This setting allows you to control which BotDetect
            icon layout will be used.
            The default value is true when the Captcha image height is <40px, and false
            otherwise.
            Valid user use horizontal Captcha icons setting values are booleans: setting
            this value to true will force BotDetect to use a horizontal icon layout,
            while false will disable automatic switching to horizontal icons depending
            on image height.
            This setting only applies to default BotDetect icons, and should not be used
            in combination with user-defined icons.-->
            <useHorizontalIcons>false</useHorizontalIcons>


            <!--Url of the optional custom Captcha sound icon that will be used instead of
            the default one.
            The default value is 'botdetect/public/bdc-sound-icon.gif'.
            Valid user Captcha sound icon setting values are absolute or relative Urls.
            When specifying a custom Captcha sound icon, you should make sure its
            filename includes "icon", and also provide a disabled variation of the icon
            that will be shown during sound playback (to prevent the user from clicking
            the icon multiple times). The disabled sound icon variant should be the same
            size and have a filename based on the active one ("icon" replaced with
            "disabled-icon").-->
            <soundIconUrl>custom-sound-icon.gif</soundIconUrl>


            <!--Url of the optional custom Captcha reload icon that will be used instead of
            the default one.
            The default value is 'botdetect/public/bdc-reload-icon.gif'.
            Valid user Captcha reload icon setting values are absolute or relative Urls.
            When specifying a custom Captcha reload icon, you should make sure its
            filename includes "icon", and also provide a disabled variation of the icon
            that will be shown while the browser is waiting to fetch a new Captcha
            challenge from the server (to prevent the user from clicking the icon
            multiple times). The disabled reload icon variant should be the same size
            and have a filename based on the active one ("icon" replaced with
            "disabled-icon").-->
            <reloadIconUrl>bdc-reload-icon.gif</reloadIconUrl>


            <!--Custom width of the Captcha icons div element.
            The default value depends on Captcha image height, since BotDetect will
            automatically determine default icon size and position to match it.
            Valid user Captcha icons div width setting values are positive integers.
            If your custom Captcha icons are not of the same size as the default
            BotDetect ones (22x22 px), the UseHorizontalIcons setting won't be able to
            control the icon layout correctly. You can control whether your custom icons
            will be displayed one beneath the other or one beside the other by setting
            an appropriate icons div width: setting it to at least twice the icon width
            + 8px of padding will result in horizontal icon layout, while smaller values
            will result in vertical icon layout.-->
            <iconsDivWidth>25</iconsDivWidth>


            <!--Will Captcha markup include a link to a Captcha help page providing Captcha
            instructions and explanations for form users.
            The default value is true.
            Valid user help link enabled setting values are booleans.
            This setting is only supported in licensed version of BotDetect.-->
            <helpLinkEnabled>true</helpLinkEnabled>


            <!--How will the Captcha help link be displayed.
            The default value is Text.
            Valid user Captcha help link mode setting values are members of the
            BotDetect HelpLinkMode enumeration ("Image" or "Text").
            When using the Image help link mode, Captcha image is wrapped in a link, and
            clicking it opens the help page in a new browser tab. This mode takes less
            space, but can lead to accidental clicks (particularly by mobile visitors).
            When using the Text help link mode, Captcha image height is automatically
            reduced by 10 px and a text link to the Captcha help page is inserted below
            it. If this makes the Captcha images less readable, you can compensate by
            increasing the Captcha image height.-->
            <helpLinkMode>text</helpLinkMode>


            <!--User-defined CSS classes that will be added to the BotDetect CAPTCHA
            container <div>.
            The default value is empty.
            Valid user additional Css classes setting values are strings containing
            desired class names in standard space-delimited CSS class format.
            CSS style declarations for these custom classes must be defined in a user
            stylesheet added to the page.-->
            <additionalCssClasses>class1 class2 class3</additionalCssClasses>


            <!--User-defined CSS style declarations that will be added as inline style
            of the BotDetect CAPTCHA container <div>.
            The default value is empty.
            Valid user additional Css style setting values are strings containing
            desired CSS style declarations in standard semicolon-delimited CSS style format.-->
            <additionalInlineCss>border: 4px solid #fff; background-color: #f8f8f8;</additionalInlineCss>


            <!--Captcha client-side-->

            <!--Should the BotDetect JavaScript client-side script code be included by the
            generated Captcha container markup.
            The default value is true.
            Valid user add script include setting values are booleans.
            This setting will usually only be set to false if you have multiple Captcha
            instances on the same form and only want the first one's markup to include
            the required BotDetect client-side code. Another possible use is when you
            manually add the necessary <script> include to page <head>, possibly combined
            with other JavaScript code and minified to reduce the number of Http requests
            made by the page.-->
            <addScriptInclude>false</addScriptInclude>


            <!--Should the JavaScript code for BotDetect client-side object creation be
            included in the generated Captcha container markup.
            The default value is true.
            Valid user add init script setting values are booleans.
            Adding the initialization script fragment should be turned off only if you
            will manually add the necessary <script> code to form <head> for example.-->
            <addInitScriptInclude>true</addInitScriptInclude>


            <!--Should user Captcha code input be automatically uppercased on the fly.
            The default value is true.
            Valid user auto uppercase input setting values are booleans.
            Since Captcha validation is not and should not be case-sensitive (it would
            hinder human visitors more than bots, and how would case differences be
            communicated through audio Captcha in all supported pronunciation languages?),
            automatically uppercasing user input is a small usability improvement that
            helps communicate the case-insensitivity of the Captcha challenge to users.-->
            <autoUppercaseInput>true</autoUppercaseInput>


            <!--Should the Captcha code input textbox automatically 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.
            The default value is true.
            Valid user Captcha auto focus input setting values are booleans.
            Automatic input element focusing is not triggered by auto-reloading of
            expired Captcha challenges, since the user might be filling out another
            field on the form when the auto-reload starts and shouldn't be distracted.-->
            <autoFocusInput>true</autoFocusInput>


            <!--Should the Captcha user input textbox automatically be cleared on all
            reload icon clicks and auto-reloads of expired Captcha codes.
            The default value is true.
            Valid user auto clear input setting values are booleans.
            Automatic input clearing is a small usability improvement: since any
            previous user input will be invalidated by Captcha reloading, it helps so
            users don't have to delete the previous input themselves.-->
            <autoClearInput>true</autoClearInput>


            <!--Should Captcha challenges automatically be reloaded when the Captcha code
            expires (controlled by the CodeTimeout property).
            The default value is true.
            Valid user auto reload expired Captchas setting values are booleans.
            Automatic reloading of expired Captcha codes 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 reloaded automatically when it is no longer
            valid).-->
            <autoReloadExpiredCaptchas>true</autoReloadExpiredCaptchas>


            <!--Time period in seconds after which automatic reloading of expired Captcha
            challenges will cease.
            The default value is 7200 seconds (2 hours).
            Valid user auto reload timeout setting values are positive integers.
            This timeout prevents indefinite extension of the visitor Session, when the
            user leaves the form open in a background browser tab over the weekend for
            example.-->
            <autoReloadTimeout>3600</autoReloadTimeout>


            <!--Starting delay (in miliseconds) of Captcha audio JavaScript playback.
            The default value is 0 (no delay).
            Valid user Captcha sound start delay setting values are positive integers.
            An initial delay before browser sound playback can be useful for improving
            usability of the Captcha audio for blind people using JAWS or similar screen
            readers. Such assistive technology will read the label associated with the
            Captcha code textbox and start sound playback simultaneously when the sound
            icon is activated (since Captcha sound playing automatically focuses the
            Captcha code textbox by default). 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.-->
            <soundStartDelay>1000</soundStartDelay>


            <!--Should BotDetect also add a remote JavaScript include
            (remote.captcha.com/include.js) loaded from the captcha.com server (which is
            currently used only for stats, but is planned to develop into additional
            Captcha functionality).
            The default value is true.
            Valid user remote script enabled setting values are booleans.
            This setting is only supported in licensed version of BotDetct.-->
            <remoteScriptEnabled>true</remoteScriptEnabled>


            <!--Captcha-related PHP application settings-->

            <!--The Url of the PHP script processing Captcha challenge Http requests.
            The default value is "simple-botdetect.php".
            Valid user Captcha handler Url setting values are strings containing Url
            paths.
            If you need to implement a custom handler for Captcha requests (for example,
            to conform to conventions of a MVC framework), you can change the base Url
            of Captcha image/sound/validation requests through the HandlerUrl
            configuration property. You will of course also have to implement the
            BotDetect Captcha library initialization (usually performed by simple-botdetect.php)
            in your custom handler .php source.-->
            <handlerUrl>custom-captcha-request-handler.php</handlerUrl>
        </captchaStyle>
    </captchaStyles>

</botdetect>

Since the code example 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 which are described at the Captcha configuration options page .

The example botdetect.xml file shows and explains most Captcha configuration settings available.