BotDetect PHP CAPTCHA Web API Reference

To make Captcha integration into PHP websites easy, the BotDetect PHP Captcha library exposes a public API focused on ease of use from PHP forms.

Captcha class

The Captcha file includes the Captcha PHP class declaration, which is the main public interface of the BotDetect PHP Captcha Library.

Instances of the Captcha type can be created on your PHP forms and will take care of Captcha display and validation.

Captcha Class Reference
BotDetect PHP Captcha Library Reference: Captcha Class public function function __construct()
  • $p_CaptchaId
The Captcha object constructor takes the Captcha identifier (a string) as parameter, and automatically initializes the instance identifier.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get CaptchaId Unique identifier of the Captcha object within the application (for example, if you placed one Captcha object on the Registration page and another on the Contact Us page, they would have distinct CaptchaId values).
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get InstanceId Globally unique identifier of the current Captcha object instance, used to ensure each page load keeps separate Captcha codes, for example when opening the same form in multiple browser tabs.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set CodeLength Length (number of characters) of the Captcha code rendered; the default value is 5.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set CodeStyle

Numeric representation of the Captcha CodeStyle, i.e. the algorithm used to generate Captcha codes from default pre-defined locale character sets; the default value is 0.

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ImageStyle

Numeric representation of the Captcha ImageStyle, i.e. the algorithm used to render Captcha codes in images; the default image style is 0.

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ImageWidth Width of the generate Captcha image, in pixels; the default Captcha image width is 250 px.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ImageHeight Height of the generate Captcha image, in pixels; the default Captcha image height is 50 px.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ImageFormat

Numeric representation of the ImageFormat in which the Captcha image will be generated; the default format is 0.

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set CustomDarkColor Optional custom dark color point; modifies the color palette used for Captcha image drawing. Should be a Html color, i.e. specified either by name ("Red") or hex value ("#f00" or "#ff0000")
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set CustomLightColor Optional custom light color point; modifies the color palette used for Captcha image drawing. Should be a Html color, i.e. specified either by name ("Red") or hex value ("#f00" or "#ff0000")
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ImageTooltip Tooltip (alt text) used in the Captcha image markup
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ReloadEnabled Controls whether Captcha reloading is enabled (is the reload icon and related code added to Captcha markup)
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ReloadTooltip Tooltip (alt text) used in the reload icon markup
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set ReloadIconUrl The Url of the Reload icon used in Captcha markup
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set SoundEnabled Controls whether Captcha sound is enabled (is the sound icon and related code added to Captcha markup)
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set SoundStyle

Captcha sound style - can be a fixed or a randomized value selected from the 10 BotDetect sound generation algorithms.

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set SoundFormat

Captcha sound output format (WavPcm16bit8KhzMono or WavPcm8bit8KhzMono).

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set SoundRegenerationMode

BotDetect audio Captcha sound regeneration mode determining how will multiple consecutive requests for audio Captcha with the same Captcha code be handled by BotDetect; the default mode is Limited.

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set UseHorizontalIcons By default, tells is the selected Captcha image height so low (<40 px) that we should switch to horizontal icon rendering (sound icon shown to the right of the reload icon, instead of below it); can be user-specified to always (or never) switch to the horizontal icon layout
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set UseSmallIcons By default, tells is the selected Captcha image height so low (<50 px) that we should switch to smaller icons (17 px vs. default 22 px); can be user-specified to always (or never) use small icons
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set UserInputID User input textbox client-side identifier, used for Captcha validation and all client-side user input processing, e.g. automatic user input lowercasing and focusing.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get/__set TabIndex

Starting tabindex for the Captcha control Html output.

The keyboard-selectable Captcha markup elements are: the Captcha reload icon, the Captcha sound icon, and (only in the Free version of BotDetect) the BotDetect website link.

Depending on your settings (is Captcha reloading enabled, are Captcha sounds enabled) and the version of BotDetect you are using (free or paid), the next available tabindex on the page can be from 0 to 3 greater than this value.
BotDetect PHP Captcha Library Reference: Captcha Class public function bool Validate
  • $p_UserInput = null
  • $p_InstanceId = null
Validate the Captcha from a regular server-side call (resulting from a full form submission); both parameters are optional.
  • If $p_UserInput (the user input of the Captcha code) is specified, the passed value is used for validation; if it's left null, the code will try to automatically find and read the POST parameter named as specified in the UserInputId field.
  • If $p_InstanceId (the InstanceId of the Captcha code that is being validated) is specified, the passed value is used for validation; if it's left null, the code will try to automatically read it from the hidden field included in Captcha markup.

In most cases, you will call this function without any parameters ($Captcha->Validate()). The optional parameters can be used for Captcha integration in advanced scenarios where the default functionality won't be enough

BotDetect PHP Captcha Library Reference: Captcha Class public function bool AjaxValidate
  • $p_UserInput
  • $p_InstanceId
Validate the Captcha from a server-side call resulting from a partial (Ajax) Captcha validation request; both parameters are mandatory.

The separation of Ajax validation from regular Captcha validation is necessary because there is a fundamental difference in their behavior.

Captcha validation always deletes the stored Captcha code on validation (allowing only one Captcha validation attempt of each Captcha code for security purposes, regardless if validation succeeds or fails).

Since successful Ajax Captcha validation will often be succeeded by repeated full submission validation of the same Captcha code, the AjaxValidate call doesn't delete successfully validated Captcha codes (but does delete codes the validation of which failed).

This function is available to make it easier to integrate BotDetect Captcha validation with all manners of custom Ajax validation approaches and frameworks. You don't need to call it when using regular Captcha validation or the built-in BotDetect Ajax Captcha validation functionality.

BotDetect PHP Captcha Library Reference: Captcha Class public property property __get IsSolved

Has the current Captcha instance been successfully validated already.

BotDetect\CaptchaClass.asp Captcha Class public function function Reset Resets the IsSolved status of the current Captcha object instance.
BotDetect\CaptchaClass.asp Captcha Class public function function Html Generates the Html markup needed to add the current Captcha object instance to a PHP form.
BotDetect PHP Captcha Library Reference: Captcha Class public property property __get CaptchaBase Underlying CaptchaBase object, which the web-focused Captcha class delegates most core Captcha functionality to.

CaptchaUrls class

The CaptchaUrls helper class contains static functions which return various Captcha Urls, based on the current library configuration.

Captcha Class Reference
BotDetect PHP Captcha Library Reference: CaptchaUrls Class static function static function CaptchaImageUrl
  • $p_CaptchaId
  • $p_InstanceId
Returns the Captcha image Url based on the given Captcha object instance
BotDetect PHP Captcha Library Reference: CaptchaUrls Class static function static function CaptchaSoundUrl
  • $p_CaptchaId
  • $p_InstanceId
Returns the Captcha sound Url based on the given Captcha object instance
BotDetect PHP Captcha Library Reference: CaptchaUrls Class static function static function LayoutStylesheetUrl Returns the Captcha layout stylesheet Url
BotDetect PHP Captcha Library Reference: CaptchaUrls Class static function static function ScriptIncludeUrl Returns the Captcha client-script library include Url

botdetect/CaptchaConfigDefaults.php file

The botdetect/CaptchaConfigDefaults.php file contains the application default values used by the PHP Captcha library. You can modify various Captcha parameters simply by editing the values from this file in your PHP websites. Greyed-out items haven't been implemented yet in the Alpha release.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value CodeLength = CaptchaRandomization:: GetRandomCodeLength(4, 6)

Captcha code length, in characters.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value CodeStyle = CodeStyle::Alphanumeric

Captcha code style (alphanumeric, alpha, or numeric).

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value CodeTimeout = 1200

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.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value DisallowedCodeSubstrings = ''

Defines rules about character sequences you want to avoid using in randomly generated CAPTCHA codes. Must be a CSV string.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value TestModeEnabled = false

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ImageStyle = CaptchaRandomization:: GetRandomImageStyle()

Captcha image style - can be a fixed or a randomized value selected from the 60 BotDetect image drawing algorithms.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ImageWidth = 250

Captcha image width, in pixels.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ImageHeight = 50

Captcha image height, in pixels.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ImageFormat = ImageFormat::Jpeg

Captcha image output format (Jpeg, Gif or Png).

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value CustomDarkColor = ''

Used to override the default Captcha image color scheme. Html named or hex color value of the dark color used in Captcha images.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value CustomLightColor = ''

Used to override the default Captcha image color scheme. Html named or hex color value of the light color used in Captcha images.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value DisabledImageStyles = ''

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundEnabled = true

Is Captcha sound enabled.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundStyle = SoundStyle::Dispatch;

Captcha sound style - can be a fixed or a randomized value selected from the 10 BotDetect sound generation algorithms.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundFormat = SoundFormat:: WavPcm16bit8kHzMono;

Captcha sound output format (WavPcm16bit8KhzMono or WavPcm8bit8KhzMono).

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundRegenerationMode = SoundRegenerationMode::Limited

BotDetect audio Captcha sound regeneration mode determining how will multiple consecutive requests for audio Captcha with the same Captcha code be handled by BotDetect.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value WarnAboutMissingSoundPackages = true

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.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value DisabledSoundStyles = ''

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value Locale = 'en-US'

Captcha locale string, affecting the charset used for Captcha code generation, and the pronunciation language used for sound Captchas.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ImageTooltip = ''

Custom Captcha image alt text / title.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundTooltip = ''

Custom sound Captcha icon alt text / title.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ReloadTooltip = ''

Custom reload Captcha icon alt text / title.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value HelpLinkUrl = ''

Url to which the Captcha help link points to.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value HelpLinkText = ''

Text used in the Captcha help link; leave empty for default image width-dependent text.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ReloadEnabled = true

Is Captcha reloading enabled.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value UseSmallIcons = null

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value UseHorizontalIcons = null

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value ReloadIconUrl = null

Url of the Captcha reload icon; can be a relative or an absolute Url pointing to the icon of your choice

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundIconUrl = null

Url of the Captcha sound icon; can be a relative or an absolute Url pointing to the icon of your choice

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value IconsDivWidth = null

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value HelpLinkEnabled = true

Is the Captcha help link enabled or not.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value HelpLinkMode = HelpLinkMode::Text

Controls how the Captcha help link is displayed; supported modes are HelpLinkMode::Image and HelpLinkMode::Text.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AdditionalCssClasses = ''

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AdditionalInlineCss = ''

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AddScriptInclude = true

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AddInitScript = true

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AutoUppercaseInput = true

Anything the users type in the input textbox will be uppercased 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.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AutoFocusInput = true

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.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AutoClearInput = 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.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AutoReloadExpiredCaptchas = true

Captcha images are automatically reloaded when the Captcha code expires (as set in the CodeTimeout element, or the ASP Session timeout), 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 reloaded automatically when it is no longer valid).

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value AutoReloadTimeout = 7200

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).

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value SoundStartDelay = 0

Captcha sound JavaScript playback starting delay, in milliseconds.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value RemoteScriptEnabled = true

By default, BotDetect also adds a remote JavaScript include loaded from the captcha.com server, which is currently used only for stats, but is planned to develop into additional Captcha functionality. This include can be disabled using this configuration property.

botdetect/CaptchaConfigDefaults.php PHP Captcha Library configuration value HandlerUrl = 'botdetect.php'

For custom integrations into 3rd party frameworks, it might be necessary to modify the base Url of Captcha image and sound requests, which can be achieved using this configuration setting