How To Include the BotDetect PHP CAPTCHA Library From a Shared Location (BotDetect v3.0; deprecated)

The default and simplest method of including the BotDetect Captcha library is to copy the botdetect.php file and the whole botdetect folder to the root of your PHP website, as explained in the How To Add BotDetect CAPTCHA Protection to PHP Forms integration guide.

However, if you have multiple PHP websites and applications on the same server, it is also possible to keep the BotDetect Captcha library at a single location and include it from there in all PHP websites that need it. Keeping multiple local copies can waste disk space (considering that BotDetect uses megabytes of font files), and complicates upgrading the Captcha library to newer versions.

In other cases, it might be necessary to separate the (private) BotDetect source code files and resources from the (public) resources such as icons, client-side scripts and style sheets it uses. For example, it would make sense to only put these public resources in a virtual folder accessible by anonymous Http requests, while keeping BotDetect .php source files, fonts and sound files in a secured location that the web server process can access but doesn't make available to visitors.

Since many override central settings as needed, by using a local configuration file.

This how to guide will explain the details of these advanced deployment options.

Including the BotDetect PHP CAPTCHA Library Source From a Shared Location

Instead of copying the botdetect.php file and the whole botdetect folder to the root of your PHP website, start by copying just the botdetect.php file to each individual website.

Then, open the local copy of the botdetect.php file in a text editor. The default declarations we're interested in look like this:

<?php // include BotDetect PHP CAPTCHA Library


// 1. define BotDetect paths

// physical path to Captcha library files (the BotDetect folder)
$LBD_Include_Path = __DIR__ . '/botdetect/';

// BotDetect Url prefix (base Url of the BotDetect public resources)
$LBD_Url_Root = 'botdetect/public/';

// physical path to the folder with the (optional!) config override file
$LBD_Config_Override_Path = __DIR__;

As you can see, BotDetect defaults to keeping the botdetect folder contents just below the botdetect.php file.

To include Captcha library files from a folder other than the current one, change the $LBD_Include_Path value to point to the central location of the botdetect folder.

Since we need the physical location of the BotDetect source files, both relative and absolute file system paths are allowed.

Relative File System Path to CAPTCHA Library Source

// physical path to Captcha library files (the BotDetect folder)
$LBD_Include_Path = __DIR__ . '../../botdetect/';

Absolute File System Path to CAPTCHA Library Source

// physical path to Captcha library files (the BotDetect folder)
$LBD_Include_Path = . 'c:/xampp/htdocs/botdetect/lib/botdetect/';

[back to the top of the page]

Referencing BotDetect Public Resources From the CAPTCHA Library

Since the public BotDetect resources (icons, client-side scripts, style sheets) are located in the botdetect/public folder of the Captcha library by default, when we change the path from which we include the Captcha library, we also must adjust the base Url of these Captcha resources.

If the central copy of the Captcha library is located in a virtual folder (accessible to anonymous Http requests), the public resource Url base can point to that location. On the other hand, if the Captcha library is kept in a folder which is not served by the web server software, you can copy the contents of the botdetect/public folder to a virtual directory separate from the library and reference them from there.

Relative URL Path to CAPTCHA Public Resources

// BotDetect Url prefix (base Url of the BotDetect public resources)
$LBD_Url_Root = '../../botdetect/public/';

Absolute URL Path to CAPTCHA Public Resources

// BotDetect Url prefix (base Url of the BotDetect public resources)
$LBD_Url_Root = 'http://hostname/subfolder/botdetect_public/';

[back to the top of the page]

Overriding CAPTCHA Library Settings in Local Configuration Files

Settings defined in the botdetect/CaptchaConfig.php file of the central Captcha library will apply to all PHP websites including BotDetect from that central copy.

When you want to selectively override certain Captcha settings in individual websites only, you can create a local file called CaptchaConfig.php (in the same folder where the local botdetect.php file is located).

You don't have to specify all Captcha settings in this local file, but only those values that differ from the baseline settings:

<?php

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

$LBD_CaptchaConfig->CodeLength = 4;

?>

You should always call CaptchaConfiguration::GetSettings(); to get existing Captcha settings first.

The local configuration file must be called CaptchaConfig.php, and it should be located in the same folder as the botdetect.php file referencing it.

It's also possible to specify the location of the configuration override in the local botdetect.php file (for more advanced cases, such as having two versions of the local configuration file, applying to two groups of multiple websites each etc.):

// physical path to the folder with the (optional!) config override file
$LBD_Config_Override_Path = 'config/override/folder/';

[back to the top of the page]