This documentation is for developers that want to implement their own captcha
challenge and integrate it with the base captcha module

Example implementations:
  text_captcha.module
  image_captcha.module




=== Required: hook_captcha($op, $captcha_type='') ===

The hook_captcha() hook is the only required function if you want to integrate
with the captcha module.
Functionality depends on the first argument $op:
  * 'list': you should return an array of possible captcha type names that your
    module implements.
  * 'generate': generate a captcha challenge.
    You should return an array that offers form elements and the solution
    of your captcha challenge, defined by the second argument $captcha_type.
    The returned array $result should have the following items:
    $result['value']: this is the solution of your captcha challenge
    $result['form']: an array of the form elements you want to add to the form.
      There should be a key 'captcha_answer' in this array, which points to
      the form element where the user enters his answer.

To make this more clear: a simple example. The captcha challenge is called
'Foo captcha' and the challenge is that the user should enter "foo" in a
textfield.

"""
/**
 * Implementation of hook_captcha().
 */
function foo_captcha_captcha($op, $captcha_type='') {
  switch($op) {
    case 'list':
      return array("Foo captcha");
    case 'generate':
      if ($captcha_type == "Foo captcha") {
        $result = array();
        $result['solution'] = 'foo';
        $result['form']['captcha_answer'] = array (
          '#type' => 'textfield',
          '#title' => t('Enter "foo"'),
          '#required' => TRUE,
        );
        return $result;
      }
  }
}
"""

Validation of the answer against the solution and other stuff is done by the
base captcha module.




=== Required: the .info file ===

You should specify that your module depends on the base captcha module.
Optionally you could put your module in the "Spam control" package.

For our simple foo captcha module this would mean the following lines in the
file foo_captcha.info:

"""
name = "Foo captcha"
description = "Captcha module that implements the foo captcha."
package = "Spam control"
dependencies = captcha
"""




=== Recommended: hook_menu($may_cache) ===

More advanced captcha modules probably want some configuration page. To integrate
nicely with the captcha module you should offer your configuration page as a
MENU_LOCAL_TASK menu entry under 'admin/user/captcha/'.

For our simple foo captcha module this would mean:

"""
/**
 * Implementation of hook_menu().
 */
function foo_captcha_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items[] = array(
      'path' => 'admin/user/captcha/foo_captcha',
      'title' => t('Foo captcha'),
      'callback' => 'drupal_get_form',
      'callback arguments' => array('foo_captcha_settings_form'),
      'type' => MENU_LOCAL_TASK,
    );
  }
  return $items;
}
"""

You should of course implement a function foo_captcha_settings_form() which
returns the form of you configuration page.




=== Optional: hook_help($section) ===
To offer a description/explanation of your captcha challenge, you can use the
normal hook_help() system.

For our simple foo captcha module this would mean:

"""
/**
 * Implementation of hook_help().
 */
function text_captcha_help($section) {
  switch ($section) {
    case 'admin/user/captcha/foo_captcha':
      return '<p>' . t('This is a very simple captcha, which requires users to enter "foo" in a textfield.') . '</p>';
  }
  return $output;
}
"""