How To Include the BotDetect PHP CAPTCHA Library From a Shared Location
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 Captcha library options can be changed using the
botdetect/CaptchaConfig.php file, sharing a single copy of the Captcha library between multiple PHP websites also shares those settings from the central configuration file. However, BotDetect also allows individual applications to 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
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
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/';
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/';
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/';
BotDetect 3.0 PHP Captcha Library Beta1 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.
BotDetect PHP Captcha v3.0.Beta1 now supports localized Captcha generation, using various Unicode character sets and downloadable multi-language captcha pronunciations.