BotDetect CAPTCHA PHP Code Examples

The BotDetect PHP Captcha package includes a number of code examples which can help you get started with integrating BotDetect in your PHP websites and configuring various Captcha options.

First Time Here?

Check the BotDetect Developer Crash Course for key integration steps.

Table of Contents

BotDetect PHP CAPTCHA Code Examples Location

After unpacking the BotDetect Captcha library, you can find the PHP Captcha code examples in the examples/simple-api folder. If you copy the contents of this this folder to a path accessible by your Http server software configured to run PHP (the htdocs folder in Apache installations, Inetpub on IIS, etc.), the index.html will guide you to individual examples.

BotDetect CAPTCHA PHP Integration Code Examples

Integration code examples show how to integrate BotDetect in your PHP websites.


PHP Basic Captcha Code Example

This code example shows the most basic source code required to protect a PHP form with BotDetect Captcha and validate the user input.

It can be used as a starting point when you are getting started with BotDetect.

Default Source Code Folder Online Source
examples/simple-api/simple-api-php-basic-captcha-example

PHP Form Captcha Code Example

This code example shows how to add BotDetect Captcha protection to a typical PHP form.

Captcha validation is integrated with other form fields validation, and only submissions that meet all validation criteria are accepted.

This kind of validation could be used on various types of public forms which accept messages, and are at risk of unwanted automated submissions.

For example, it could be used to ensure bots can't submit anything to a contact form, add guestbook entries, blog post comments or anonymous message board / forum replies.

Default Source Code Folder Online Source
examples/simple-api/simple-api-php-form-captcha-example

PHP Login Form Captcha Code Example

This code example shows how to add BotDetect Captcha validation to simple PHP login forms.

To prevent bots from trying to guess the login info by brute force submission of a large number of common values, the visitor first has to prove they are human (by solving the Captcha), and only then is their username and password submission checked against the authentication data store.

Also, if they enter an invalid username + password combination three times, they have to solve the Captcha again. This prevents attempts in which the attacker would first solve the Captcha themselves, and then let a bot brute-force the authentication info.

Default Source Code Folder Online Source
examples/simple-api/simple-api-php-login-form-captcha-example

PHP jQuery Validation Captcha Code Example

This code example shows how to integrate BotDetect PHP Captcha validation with jQuery Validation client-side form validation.

Client-side validation is not secure by itself (it can be bypassed trivially by bots that don't execute JavaScript at all), so the example shows how the protected form action must always be secured by server-side Captcha validation first, and uses client-side validation only to improve the user experience.

Default Source Code Folder Online Source
examples/simple-api/simple-api-php-jquery-validation-captcha-example

BotDetect PHP CAPTCHA Configuration Code Examples

Captcha options code examples show how to use particular BotDetect Captcha options in your PHP websites.

PHP Captcha Options: Application Config Settings Code Example

This code example shows how to configure Captcha challenges by overriding Captcha library defaults in application configuration files.

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.

Default Source Code Folder Online Source
examples/simple-api/simple-api-captcha-application-config-settings-example

PHP Captcha Options: Client-Side Workflow Settings Code Example

This code example shows how to use custom BotDetect client-side events to execute user-defined JavaScript code at various stages of the Captcha challenge workflow.

Client-side Captcha object initialization, Captcha image reloading, Captcha sound playback, built-in Captcha Ajax validation, and Captcha help link clicks all have a number of related client-side "events" and hooks where user-defined client-side callbacks can be injected.

User code can be associated with Captcha workflow events using the BotDetect.RegisterCustomHandler() function, as shown in the example JavaScript code.

Loading the form will initialize the client-side Captcha object (created by the BotDetect.Init() JavaScript call included in Captcha markup), and result in the PostInit event.

Clicking the Captcha sound icon will result in the PrePlaySound event before the audio elements are added to the page DOM. There is no PostPlaySound event since not all browsers allow user callbacks when browser sound playing finishes.

Clicking the Captcha reload icon will result in PreReloadImage and PostReloadImage events, executed before and after the Http request loading the new Captcha image from the server.

Clicking the Captcha image (i.e. the included Captcha help link) will result in the OnHelpLinkClick event.

Typing in a Captcha code and clicking the Validate button will first result in the PreAjaxValidate event, and later in either AjaxValidationFailed or AjaxValidationPassed depending on whether the server responds that the typed-in Captcha code was correct or not. In case of Ajax asynchronous request errors, AjaxValidationError will be called.

Default Source Code Folder Online Source
examples/simple-api/simple-api-captcha-clientside-workflow-settings-example

PHP Captcha Options: Form Object Settings Code Example

This code example shows how to configure Captcha challenges by setting Captcha object properties in PHP form source.

Multiple PHP forms within the same PHP website can be protected by BotDetect Captcha challenges: e.g. you could include botdetect.php in both your Contact form and Registration form source.

To function properly, separate Captcha challenges placed on each form should have different names (CaptchaId values sent to the Captcha object constructor, "Captcha1" and "Captcha2" in this example), and can use completely different Captcha settings.

Even multiple Captcha instances placed on the same form won't interfere with each other's validation and functionality. And if a user opens the same page in multiple browser tabs, each tab will independently validate the shown Captcha code.

Shared Captcha settings should always be placed in the CaptchaConfig.php application configuration file, and only diverging settings set through Captcha object instance properties in form code, to avoid code duplication.

Settings that affect only Captcha container markup generation take effect immediately (changing $Captcha->Html output), but settings that affect Captcha challenge (image or sound) generation in separate Http requests need to be saved in PHP Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to defaults when the PHP Session expires.

Please note that if configured values are dynamic (e.g. CaptchaRandomization helper or other function calls in form code), they will be re-calculated only when the form is reloaded (form code is executed). For example, Captcha ImageStyle randomized in PHP form source will not change on each Captcha Reload button click, but only on each form load.

Default Source Code Folder Online Source
examples/simple-api/simple-api-captcha-form-object-settings-example