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 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|
|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).|
|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.|
|property __get/__set CodeLength||Length (number of characters) of the Captcha code rendered; the default value is 5.|
|property __get/__set CodeStyle||
Numeric representation of the Captcha
|property __get/__set ImageStyle||
Numeric representation of the Captcha
|property __get/__set ImageWidth||Width of the generate Captcha image, in pixels; the default Captcha image width is 250 px.|
|property __get/__set ImageHeight||Height of the generate Captcha image, in pixels; the default Captcha image height is 50 px.|
|property __get/__set ImageFormat||
Numeric representation of the
|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 (
|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 (
|property __get/__set ImageTooltip||Tooltip (alt text) used in the Captcha image markup|
|property __get/__set ReloadEnabled||Controls whether Captcha reloading is enabled (is the reload icon and related code added to Captcha markup)|
|property __get/__set ReloadTooltip||Tooltip (alt text) used in the reload icon markup|
|property __get/__set ReloadIconUrl||The Url of the Reload icon used in Captcha markup|
|property __get/__set SoundEnabled||Controls whether Captcha sound is enabled (is the sound icon and related code added to Captcha markup)|
|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|
|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|
|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.|
|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.
||Validate the Captcha from a regular server-side call (resulting from a full form submission); both parameters are optional.
In most cases, you will call this function without any parameters (
||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
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.
|property __get IsSolved||
Has the current
|function Reset||Resets the
|function Html||Generates the Html markup needed to add the current
|property __get CaptchaBase||Underlying
CaptchaUrls helper class contains static functions which return various Captcha Urls, based on the current library configuration.
|Captcha Class Reference|
|static function ImageUrl
||Returns the Captcha image Url based on the given
|static function SoundUrl
||Returns the Captcha sound Url based on the given
|static function LayoutStylesheetUrl||Returns the Captcha layout stylesheet Url|
|static function ScriptIncludeUrl||Returns the Captcha client-script library include Url|
BotDetect\CaptchaConfig.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.
|CodeLength = 5||
Captcha code length, in characters.
|CodeStyle = CodeStyle::Alphanumeric||
Captcha code style (alphanumeric, alpha, or numeric).
|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.
|Locale = 'en-US'||
Captcha locale string, affecting the charset used for Captcha code generation, and the pronunciation language used for sound Captchas.
|CustomCharset = ''||
Defines a custom character set for Captcha code generation, specifying the alphanumeric characters which will be used for all Captcha codes regardless of the code style value set.
|BannedSequences = ''||
Defines rules about character sequences you want to avoid using in randomly generated CAPTCHA codes. Must be a CSV string.
|ImageStyle = CaptchaRandomization:: GetRandomImageStyle()||
Captcha image style - can be a fixed or a randomized value selected from the 60 BotDetect image drawing algorithms.
|ImageWidth = 250||
Captcha image width, in pixels.
|ImageHeight = 50||
Captcha image height, in pixels.
|ImageFormat = ImageFormat::Jpeg||
Captcha image output format (Jpeg, Gif or Png).
|CustomDarkColor = ''||
Used to override the default Captcha image color scheme. Html named or hex color value of the dark color used in Captcha images.
|CustomLightColor = ''||
Used to override the default Captcha image color scheme. Html named or hex color value of the light color used in Captcha images.
|ImageTooltip = 'CAPTCHA'||
Custom Captcha image alt text / title.
|HelpLinkEnabled = true||
Is the Captcha help link enabled or not.
|HelpLinkMode = HelpLinkMode::Text||
Controls how the Captcha help link is displayed; supported modes are
|HelpLinkUrl = 'http://captcha.com/captcha.html'||
Url to which the Captcha help link points to.
|HelpLinkText = ''||
Text used in the Captcha help link; leave empty for default image width-dependent text.
|SoundEnabled = true||
Is Captcha sound enabled.
|SoundStyle = SoundStyle::Dispatch;||
Captcha sound style - can be a fixed or a randomized value selected from the 10 BotDetect sound generation algorithms.
|SoundFormat = SoundFormat:: WavPcm16bit8kHzMono;||
Captcha sound output format (WavPcm16bit8KhzMono or WavPcm8bit8KhzMono).
|SoundTooltip = 'Speak the CAPTCHA code'||
Custom sound Captcha icon alt text / title.
|WarnAboutMissing SoundPackages = 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
|SoundStartDelay = 0||
|ReloadEnabled = true||
Is Captcha reloading enabled.
|ReloadTooltip = 'Speak the CAPTCHA code'||
Custom reload Captcha icon alt text / title.
|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).
|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).
|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.
|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.
|AutoLowercaseInput = 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.
|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
|ReloadIconUrl = LBD_URL_ROOT . 'LBD_ReloadIcon.gif'||
Url of the Captcha reload icon; can be a relative or an absolute Url pointing to the icon of your choice
|SoundIconUrl = LBD_URL_ROOT . 'LBD_SoundIcon.gif'||
Url of the Captcha sound icon; can be a relative or an absolute Url pointing to the icon of your choice
|LayoutStylesheetUrl = LBD_URL_ROOT . 'LBD_Layout.css'||
Url of the Captcha layout stylesheet; can be a relative or an absolute Url pointing to the stylesheet location within your website
|ScriptIncludeUrl = LBD_URL_ROOT . 'LBD_Scripts.js'||
Url of the Captcha client-side library include; can be a relative or an absolute Url pointing to the script include location within your website
Saves the given value using the provided key; used for all BotDetect persistence access, allowing you to modify the persistence medium used by the Captcha library
Load persisted value for the given string key; used for all BotDetect persistence access, allowing you to modify the persistence medium used by the Captcha library
Clear persisted value for the given string key; used for all BotDetect persistence access, allowing you to modify the persistence medium used by the Captcha library
BotDetect 3.0 PHP Captcha Library Alpha4 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.
The PHP library does not yet support the full feature set of the other BotDetect 3.0 Captcha products (ASP.NET and ASP Classic). Most notably, Captcha localization is not implemented yet, but is coming soon.
BotDetect 3 PHP is already available for purchase at a 50% pre-sale price.