BotDetect CAPTCHA PHP FAQ

This page will contain answers to frequently asked questions about BotDetect PHP Captcha deployment and integration.

CAPTCHA PHP Integration & Deployment

Which versions of PHP BotDetect PHP Captcha library supports?

At the moment, the BotDetect PHP Captcha library is tested with PHP 7.0.x, PHP 5.6.x, PHP 5.5.x, 5.4.x, and PHP 5.3.x (with 5.3.2 being the oldest compatible release we are aware of).

I'm trying to use BotDetect in my PHP website but Captcha images are broken / don't display at all.

To check which error causes the issue, right-click on the broken Captcha image and copy its Url (or use View Source and copy the image Url from there). Then open a new browser tab and paste the Captcha image Url to access it directly.

The most common error is

PHP Fatal error: Call to undefined function imagecreatetruecolor()

which is caused by trying to use BotDetect in PHP installations without the GD library. Since BotDetect requires the GD library to generate Captcha images, you can resolve this error by installing it.

I'm trying to use BotDetect in my PHP website but Captcha images are broken / don't display at all. When I open the image Url in a new browser tab, I get 404 Not Found or 403 Forbidden errors.

BotDetect uses botdetect.php paths to both include the Captcha library and serve Captcha images and sounds. For BotDetect to work properly, you must ensure that botdetect.php requests are not included in Url rewriting or routing of any kind (for example: .htaccess redirects, Url rewriting or routing by your CMS or blog engine). If you need to change the path used by BotDetect, you must also modify the BotDetect HandelrUrl configuration property.

My website uses Global content delivery network (CDN). Is there anything I should take care of in order to assure that BotDetect works?

BotDetect will not work if BotDetect markup is added to webform on a server side, and then forms with Captcha are delivered through CDN.

Basically, the issue is that BotDetect markup that is added into your webform markup contains some parameters that are unique for each rendered Captcha.

Delivery through CDN freeze this parameters to values that are stored in CDN, and therefore Captcha fails to display, validate (or both depending of your implementation).

There are 2 ways to resolve this issue:

  • To exclude webform containing BotDetect markup from being served through CDN:

    All of other content referenced (styles, images, scripts, etc...) in your web page source, can still be served through CDN so there will be no larger performance penalty.

    OR:

  • To add BotDetect markup to your webform with JavaScript.

Please note:

Whatever approach you decide to go with, you still MUST exclude /botdetect.php OR /simple-botdetect.php urls from being served through CDN.

Does BotDetect PHP Captcha library require PHP Session state?

At the moment, BotDetect Captcha validation has only been tested to work correctly when using PHP Sessions.

However, if you take a look at the botdetect/CaptchaConfigDefaults.php file included in the Captcha library, you can see there are three persistence-related functions defined outside the core library source: BDC_Persistence_Save(), BDC_Persistence_Load(), and BDC_Persistence_Clear().

BotDetect doesn't use PHP sessions directly, but always calls these functions when dealing with persistence - so if you want to customize the storage medium (to, for example, save data to a MySQL database), you can modify these functions to implement alternative data access.

(Please note, botdetect/CaptchaHandler.php does call session_start() in the first line, since it is meant to process direct requests and can't rely on your form code to do so. Depending on your changes, you might want to also comment-out this line and the corresponding session_write_close() calls.)

Why doesn't BotDetect offer a client-side persistence option? After all, other Captcha services don't store everything in the Session, but rather transfer an ID or a hashed token to the client.

That's exactly how BotDetect v1.0 used to work, and we abandoned that approach because it was a major security flaw.

Captchas with any kind of client-side persistence can be bypassed easily. For example, if a hashed token of the Captcha code is kept on the client, a simple replay attack can reuse a single correct Captcha code thousands of times. Implementation details vary, but all forms of client-side persistence can be tampered with and attacked by malicious clients.

BotDetect must use server side persistence by design - and we chose that approach because we believe it to be the right way to implement a secure Captcha.

Considering the nature of Captcha data that is persisted, the storage medium should be: per-visitor, server-side, automatically cleared - and Session state is the simplest option that fits those requirements.

If you're interested in changing the underlying persistence medium used by BotDetect, take a look at BotDetect persistence configuration options.

How can I find out which version of BotDetect PHP I currently use?.

Using the following method to get version of BotDetect PHP:

echo Captcha::LibInfo();

I purchased full version of BotDetect PHP library and want to switch my Laravel application (currently using free version) to use paid version. What I need to do?

You should replace the content of the following folder:

YOUR_LARAVEL_APP_ROOT\vendor\captcha-com\captcha\lib\botdetect\

which contains botdetect library with the following folder of zip with full version you downloaded:

botdetect-php-captcha-component.zip\BotDetect-PHP-CAPTCHA-Component-Enterprise-v4.x.y\botdetect-captcha-lib\botdetect\

I purchased full version of BotDetect PHP library and want to switch my CodeIgniter application (currently using free version) to use paid version. What I need to do?

You should replace the content of the following folder:

YOUR_CODEIGNITER_APP_ROOT\application\libraries\botdetect\lib\botdetect\

which contains botdetect library with the following folder of zip with full version you downloaded:

botdetect-php-captcha-component.zip\BotDetect-PHP-CAPTCHA-Component-Enterprise-v4.x.y\botdetect-captcha-lib\botdetect\

I purchased full version of BotDetect PHP library and want to switch my Symfony application (currently using free version) to use paid version. What I need to do?

You should replace the content of the following folder:

YOUR_SYMFONY_APP_ROOT\vendor\captcha-com\captcha\lib\botdetect\

which contains botdetect library with the following folder of zip with full version you downloaded:

botdetect-php-captcha-component.zip\BotDetect-PHP-CAPTCHA-Component-Enterprise-v4.x.y\botdetect-captcha-lib\botdetect\

I purchased full version of BotDetect PHP library and want to switch my CakePHP application (currently using free version) to use paid version. What I need to do?

You should replace the content of the following folder:

YOUR_CAKEPHP_APP_ROOT\vendor\captcha-com\captcha\lib\botdetect\

which contains botdetect library with the following folder of zip with full version you downloaded:

botdetect-php-captcha-component.zip\BotDetect-PHP-CAPTCHA-Component-Enterprise-v4.x.y\botdetect-captcha-lib\botdetect\

We noticed a strange behavior in Internet Explorer. Whenever we press the speak captcha button, it reloads the captcha first then plays the audio of the new captcha. This does not occur in Firefox or Chrome.

It is not a bug but expected and built in default behavior.

Once requested audio is cached on a client side (because of performance) for future replay. If caching fails in particular brand of browser (or due to custom configuration) then the brand new captcha (with a different code) is generated. That is exactly what happens in IE because audio cannot be cached on a client side with it.

You may ask yourself why different code but not the same? Because of security reasons -- we don't want to play different audio files for the same captcha code. Different audio versions of the same challenge would provide an attacker with an opportunity to try to guess the same char repeatedly until he can have a highly confident guess.

PHP CAPTCHA Validation & Security

The BotDetect Captcha image displays correctly on my page, but the PHP form is submitted regardless of the Captcha code entered.

You have most likely forgotten to include Captcha validation code in the PHP script that processes your form's submitted data. You can see an example code snippet for Captcha validation in the How To add BotDetect Captcha protection to PHP forms guide.

Also, you might want to take a look at the BotDetect PHP integration examples that come with BotDetect downloads, starting with the PHP basic Captcha integration code example.

Why can't users correct their Captcha code input when they get it wrong? If they make a mistake, it seems they have to type in a whole new code from a new image.

You are right, and this behavior of the Captcha component is by design. Only one validation attempt is allowed per Captcha code for security purposes.

If we allowed multiple retries on solving the same Captcha, it would significantly lower the Captcha security, since bots could just brute-force different code values until they eventually got it right. Also, it would be much easier to write a bot which used OCR techniques to bypass the Captcha: if, for example, it could recognize two out of the five digits in the image, it would just have to brute-force the remaining three.

So a failed validation attempt (whether on the client- or server-side) always invalidates the current Captcha code. Successful server-side validations also remove the code (so we prevent cases where somebody solves just one Captcha and then keeps reusing it for multiple submissions).

Successful client-side validations are the only ones that don't invalidate the current code, so you can also validate the same submitted values on the server-side once all form fields have been filled-out.

So basically, if the Captcha validation attempt wasn't successful, the Captcha image also needs to be reloaded and the previous user input cleared, since the old Captcha code has been invalidated.

I have a form protected with BotDetect Captcha that contains several other validated fields. When a user enters the correct Captcha code but server-side validation of another field fails, they are shown another Captcha image with a different code.

Is there a way to show them the same Captcha image and keep the entered code, so they don't have to solve more than one Captcha just because they entered an invalid value for another field?

Users definitely shouldn't have to solve another Captcha if they enter the correct Captcha code, but (for example) username validation fails. The purpose of Captcha is to ensure the user is human, and once they solve it this purpose is fulfilled.

If you have to return them to the form because another field value needs to be corrected, it's best not to show them the Captcha at all.

BotDetect remembers that the user has passed the Captcha test successfully in the IsSolved instance field, and you can only display and validate the Captcha if it hasn't already been solved. See the PHP Form Captcha code example for a demonstration of this feature.

For security reasons, it is not possible to get the same BotDetect Captcha image on two page loads, nor to use the same code for more than one Captcha image.