It's better when it's simple

User Tools

Site Tools



Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Use an image verification (CAPTCHA) to defeat spambots

Last updated on
Helper, Action

Example CAPTCHA with image and Audio This plugin implements a Completely Automated Public Turing test to tell Computers and Humans Apart also known as CAPTCHA.


Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.



  • Needs the gd image library, on Ubuntu for php 5 use sudo apt-get install php5-gd, for php 7 use sudo apt-get install php7.0-gd.


The plugin provides different methods of CAPTCHAs selectable in the config manager.

The js method displays 5 random characters which need to be copied into an input box. This task is done through JavaScript automatically, then the whole CAPTCHA test is hidden from the user. Usual Spambots won't execute JavaScript or search the page for the characters, so this test should be quite effective without requiring any manual interaction from most users. The test is perfectly accessible for disabled users or users without JavaScript.

The text method works just like the JavaScript method but without the automatic JavaScript. This will defeat SpamBots with enabled JavaScript but requires more interaction from users. It's still pretty simple to defeat by analyzing the page source. Accessibility is as good as with the first method.

The math method is similar to the text mode but displays a simple mathematical problem in the form of an addition or subtraction. The user has to solve the problem and enter the result. This takes a bit more brain work from users. It's still relatively easy to defeat by a customized bot.

The question method allows to specify a single, static question to which a single static answer has to be provided by the user. The accessibility is the same as for the text method but it is very easy to defeat with a custom spam bot. However since the question can be customized (by changing the question and answer config options) this can be used to require domain specific knowledge from your users.

The image method finally does display the random chars as an automatically generated image. This test can not be defeated without using costly OCR techniques. Unfortunately this method effectively locks out blind users or users with textbrowsers. This feature needs the libGD PHP extension.

The audio method improves the accessibility of the image CAPTCHA by adding a .wav download. The .wav file plays the letters of the CAPTCHA read in the NATO phonetic alphabet. Please note, that because of the way how the wave file is generated it might be easier to automatically decode than the image.

The svg method works similar to the image method, but creates an inline SVG of the random letters. It should be much easier to read for humans. Until spammers catch up OCR'ing embedded SVG it should be relatively safe against automated solving. It has the same accessibility problems as the image method.

The svgaudio method combines the svg method with the audio method, providing an alternative audio version next to the SVG image.

The figlet method creates an ASCII art rendering of the text. It has very bad accessibility and is relatively easy to defeat by a script, but is funny to look at ;-)

You can specify the number of characters to use for all CAPTCHAs (except math and question mode of course) in the config.

If you select the image type you may specify the size of the generated image. Larger images take more screen space and might be easier to recognize with OCR. On the other hand larger images are better to read for humans, too. Make sure your image is wide enough to display the configured number of characters.

By default the CAPTCHA method is only applied for anonymous users. You may enable it for logged in users as well through the forusers option.

The CAPTCHA by default protects the following actions:

  • page editing
  • user registration
  • password resets

You can optionally require a CAPTCHA for logins by enabling the loginprotect config option.

Helper Methods

The plugin provides a helper plugin which let's you add CAPTCHA checks to your own plugins. The helper provides three methods:


Returns true when the CAPTCHA should be used - it checks the forusers config option for you. Always check this method before using the other methods.


Returns the HTML for the CAPTCHA. It takes care of all other CAPTCHA options.


Use this function to check if the CAPTCHA was filled correctly. It returns false if the CAPTCHA was not filled correctly and by default also prints a message about it. If you don't want this message, pass false as first parameter.


//add captcha if available
/** @var helper_plugin_captcha $captcha */
$captcha = $this->loadHelper('captcha', false);
if ($captcha && $captcha->isEnabled()) {
/** @var helper_plugin_captcha $captcha */
$captcha = $this->loadHelper('captcha', false);
if ($captcha && $captcha->isEnabled()) {
    $captchaok = $captcha->check();


It's installed but I see no CAPTCHA?

Read the documentation again. The default settings js method uses a hidden CAPTCHA. There's nothing to see.

plugin/captcha.txt · Last modified: 2023-12-06 23:50 by andi

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki