^Status|stub|
^Todo|Write me|

====== 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 =====

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 [[http://docs.kohanaphp.com/general/filesystem#cascading|cascading filesystem]]):

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

__Note__: all groups inherit and overwrite the default group.

=== Styles ===

''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)

=== Picture height and width ===

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

=== Complexity ====

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 ====

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

=== Fonts ====

''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 ====

''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.

===== Methods =====

==== valid() ====
''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() ====
''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() ====
''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() ====
''reset_count()'' resets the Captcha response counters and removes the count sessions.


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

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

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

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

===== Usage example =====

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

<code php>
// 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();
</code>