Captcha Library

Captchas are used to protect your site by showing something that a computer can't recognize but a human can. They are usually placed on your registration page but they can be placed anywhere you want to make reasonably sure you are dealing with a person and not a bot.

Kohana's Captcha library can currently generates basic, alpha, word, math, riddle captchas. Captcha configuration is defined in groups which allows you to easily switch between different Captcha settings for different forms on your website.

Configuration is done in the application/config/captcha.php file, if it's not there take the one from system/config and copy it to the application folder (see cascading filesystem):

$config['default'] = array
(
    'style'      => 'basic',
    'width'      => 150,
    'height'     => 50,
    'complexity' => 4,
    'background' => '',
    'fontpath'   => SYSPATH.'fonts/',
    'fonts'      => array('DejaVuSerif.ttf'),
    'promote'    => FALSE,
);

Note: all groups inherit and overwrite the default group.

style defines the captcha type, e.g. basic, alpha, word, math, riddle. There are 5 different drivers:

• basic - draws a picture with a random text (only distinct alpha numeric characters that can't be mistaken for others)
• alpha - draws a picture with a random text (only distinct alpha characters)
• word - ask for a random word loaded from the current language (i18n/xx_XX/captcha.php)
• math - generates a mathematic challenge such as 2 + 8 = ?
• riddle - asks for a riddle such as Fire is... (hot or cold) (loaded from i18n/xx_XX/captcha.php)

For basic and alpha styles drawing a picture, height and width define the size of the picture.

It defines the difficulty level of the generated captcha. Usage depends on chosen style:

• basic - [1:10] complexity setting is used as character count
• alpha - [1:10] complexity setting is used as character count
• word - [2:9] complexity setting is used as word length
• math - [0;4;8], higher the complexity is, harder is the challenge

background is the path to background image file used for basic and alpha Captcha

fontpath is the font file used for basic and alpha Captcha. fonts is an array of font files. Several fonts means that characters have randomized fonts choosen in the array.

promote is a valid response count threshold to promote user (FALSE to disable). This means , in a particular session, if user answers captcha correctly count times already, promote user to human, and don't annoy him any more.

valid($response) validates a Captcha response and updates response counter. It's a static method that can be used as a Validation rule also. It takes:

• [string] $response the captcha response

valid_count($new_count = NULL, $invalid = FALSE) gets or sets the number of valid Captcha responses for this session. It takes:

• [integer] $new_count new counter value (default NULL)
• [boolean] $invalid trigger invalid counter (for internal use only) (default FALSE)
• returns [integer] counter value

invalid_count($new_count = NULL) gets or sets the number of invalid Captcha responses for this session. It takes:

• [integer] $new_count new counter value (default NULL)

reset_count() resets the Captcha response counters and removes the count sessions.

promoted($threshold = NULL) resets the Captcha response counters and removes the count sessions. It takes:

• [integer] $threshold valid response count threshold (default NULL)

render($html = TRUE) returns or outputs the Captcha challenge.. It takes:

• [boolean] $html TRUE to output html, e.g. <img src=”#” /> (default TRUE)

The code below demonstrates how to use captcha on a form. In your controller:

// Load Captcha library, you can supply the name of the config group you would like to use.
$captcha = new Captcha;
 
// Ban bots (that accept session cookies) after 50 invalid responses.
// Be careful not to ban real people though! Set the threshold high enough.
if ($captcha->invalid_count() > 49)
	exit('Bye! Stupid bot.');
 
// Form submitted
if ($_POST)
{
	// Captcha::valid() is a static method that can be used as a Validation rule also.
	if (Captcha::valid($this->input->post('captcha_response')))
	{
		echo '<p style="color:green">Good answer!</p>';
	}
	else
	{
		echo '<p style="color:red">Wrong answer!</p>';
	}
 
	// Validate other fields here
}
 
// Show form
echo form::open();
echo '<p>Other form fields here...</p>';
 
// Don't show Captcha anymore after the user has given enough valid
// responses. The "enough" count is set in the captcha config.
if ( ! $captcha->promoted())
{
	echo '<p>';
	echo $captcha->render(); // Shows the Captcha challenge (image/riddle/etc)
	echo '</p>';
	echo form::input('captcha_response');
}
else
{
	echo '<p>You have been promoted to human.</p>';
}
 
// Close form
echo form::submit(array('value' => 'Check'));
echo form::close();