BotDetect PHP CAPTCHA Migration Guide

documentation > php captcha > release notes

This page contains instructions for updating your BotDetect PHP Captcha copy to newer versions, starting with BotDetect 3 Alpha2.

Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha4 to v3.0.Beta1

To take advantage of the v3.0.Beta1 changes, you have to update all Captcha library files included in the BotDetect download package. Since the library folder names have been changed, you should first backup the Alpha CaptchaLibrary folder, then delete it from your website source and copy downloaded files from the Beta lib folder.

If your PHP forms are running on Linux or another case-sensitive file-system, you should replace all require("BotDetect.php") calls with require("botdetect.php"). And if you had custom include paths defined in the old BotDetect.php file, you should merge your changes from it into the updated botdetect.php file.

If you had custom Captcha settings in the default library configuration file (CaptchaLibrary/BotDetect/CaptchaConfig.php), you should merge them with the configuration file at the new location (lib/botdetect/CaptchaConfig.php).

If you were using BotDetect classes other than Captcha, CodeStyle, ImageStyle, SoundStyle, SoundFormat, ImageFormat, HelpLinkMode, CaptchaUrls, CaptchaConfiguration, and CaptchaRandomization, please note that they have renamed with the LBD_ prefix (e.g. CaptchaBase became LBD_CaptchaBase) to avoid name clashes with 3rd party and user code.

Due to these internal class name changes, clearing Session data generated by the Alpha version of BotDetect is also recommended before deploying the updated Captcha library. Due to changes in some persisted fields, loading Session data with old values could cause errors for visitors whose Sessions remain active during the upgrade.

[back to top]

Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha3 to v3.0.Alpha4

To take advantage of the v3.0.Alpha4 changes, you have to update all Captcha library files included in the BotDetect download package. Simply copy the contents of the updated CaptchaLibrary folder over the old one, and check that your pages using Captcha protection work properly.

If you were using the available Captcha persistence medium configuration options to keep Captcha data outside PHP Sessions, please note that the configuration API has changed to only receive peristence function names instead of having them defined in the base configuration file. Changing this should be straightforward, and will allow you to keep your custom persistence functions declared anywhere in your code.

[back to top]

Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha2 to v3.0.Alpha3

To take advantage of the v3.0.Alpha3 changes, you have to update all Captcha library files included in the BotDetect download package. Simply copy the contents of the updated CaptchaLibrary folder over the old one, and check that your pages using Captcha protection work properly.

When deploying the updated Captcha library, clearing Session data generated by the old version is also recommended. Due to changes in some persisted fields, loading Session data with old values could cause errors.

[back to top]

Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha1 to v3.0.Alpha2

To take advantage of the v3.0.Alpha2 changes, you have to update all Captcha library files included in the BotDetect download package.

Due to requirements of more advanced PHP Captcha integration scenarios (including the Captcha library in multiple websites, various PHP framework compatibility etc.), including the BotDetect.php file doesn't automatically add the Captcha layout stylesheet anymore. When upgrading your forms to use v3.0.Alpha2, please add the BotDetect stylesheet using the CaptchaUrls::LayoutStylesheetUrl() function call.

Please note that the BotDetect/CaptchaConfig.php file format has been changed, so any changes you made in the v3.0.Alpha1 Captcha configuration will not be automatically upgraded. However, the format changes are minor and replicating your old changes in the new format is completely straightforward.

When deploying the updated Captcha library, clearing Session data generated by the old version is also recommended. Due to changes in some persisted fields, loading Session data with old values could cause errors.

[back to top]

Please Note

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 3 PHP is already available for purchase at a 33% discounted pre-release price.