modules/captcha/captcha_api.txt

// $Id: captcha_api.txt,v 1.11 2009/08/18 23:39:41 soxofaan Exp $

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


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

The hook_captcha() hook is the only required function if you want to integrate
with the base CAPTCHA module.
Functionality depends on the first argument $op:
  * 'list': you should return an array of possible challenge types
    that your module implements.
  * 'generate': generate a challenge.
    You should return an array that offers form elements and the solution
    of your challenge, defined by the second argument $captcha_type.
    The returned array $captcha should have the following items:
    $captcha['solution']: this is the solution of your challenge
    $captcha['form']: an array of the form elements you want to add to the form.
      There should be a key 'captcha_response' in this array, which points to
      the form element where the user enters his answer.
    An optional additional argument $captcha_sid with the captcha session ID is
    available for more advanced challenges (e.g. the image CAPTCHA uses this
    argument, see image_captcha_captcha()).

Let's give a simple example to make this more clear.
We create the challenge 'Foo CAPTCHA', which requires the user to
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') {
        $captcha = array();
        $captcha['solution'] = 'foo';
        $captcha['form']['captcha_response'] = array(
          '#type' => 'textfield',
          '#title' => t('Enter "foo"'),
          '#required' => TRUE,
        );
        return $captcha;
      }
      break;
  }
}
"""

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 = "The foo CAPTCHA requires the user to enter the word 'foo'."
package = "Spam control"
dependencies[] = captcha
core = 6.x
"""


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

More advanced CAPTCHA modules probably want some configuration page.
To integrate nicely with the base 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['admin/user/captcha/foo_captcha'] = array(
      'title' => t('Foo CAPTCHA'),
      'page callback' => 'drupal_get_form',
      'page 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 your configuration page.


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

For our simple foo CAPTCHA module this would mean:

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


=== Optional: custom response validation ===
The CAPTCHA module provides an option for case sensitive and case insensitve
validation of the responses. If this is not sufficient, you can provide
your own validation function with the 'captcha_validate' field, illustrated
by the following example:

"""
/**
 * Implementation of hook_captcha().
 */
function foo_captcha_captcha($op, $captcha_type='') {
  switch ($op) {
    ...
    case 'generate':
      if ($captcha_type == 'Foo CAPTCHA') {
        $captcha = array();
        $captcha['solution'] = ...
        $captcha['form'] = ...
        $captcha['captcha_validate'] = 'foo_captcha_custom_validation';
        return $captcha;
      }
      break;
  }
}

/**
 * Custom CAPTCHA validation function.
 *
 * @param solution the solution for the challenge as reported by hook_captcha('generate', ...).
 * @param response the answer given by the user.
 * @return TRUE on succes and FALSE on failure.
 */
function foo_captcha_custom_validation($solution, $response) {
  return $response == "foo" || $response == "bar";
}
"""

Previous example shows the basic usage for custom validation with only a $solution
and $response argument, which should be sufficient for most CAPTCHA modules.
More advanced CAPTCHA modules can also use extra provided arguments $element
and $form_state:
"""
function foo_captcha_custom_validation($solution, $response, $element, $form_state) {
  return $form_state['foo']['#bar'] = 'baz';
}
"""
These extra arguments are the $element and $form_state arguments of the validation function
of the #captcha element. See captcha_validate() in captcha.module for more info about this.

1	// $Id: captcha_api.txt,v 1.11 2009/08/18 23:39:41 soxofaan Exp $
2
3	This documentation is for developers that want to implement their own
4	challenge type and integrate it with the base CAPTCHA module.
5
6
7	=== Required: hook_captcha($op, $captcha_type='') ===
8
9	The hook_captcha() hook is the only required function if you want to integrate
10	with the base CAPTCHA module.
11	Functionality depends on the first argument $op:
12	* 'list': you should return an array of possible challenge types
13	that your module implements.
14	* 'generate': generate a challenge.
15	You should return an array that offers form elements and the solution
16	of your challenge, defined by the second argument $captcha_type.
17	The returned array $captcha should have the following items:
18	$captcha['solution']: this is the solution of your challenge
19	$captcha['form']: an array of the form elements you want to add to the form.
20	There should be a key 'captcha_response' in this array, which points to
21	the form element where the user enters his answer.
22	An optional additional argument $captcha_sid with the captcha session ID is
23	available for more advanced challenges (e.g. the image CAPTCHA uses this
24	argument, see image_captcha_captcha()).
25
26	Let's give a simple example to make this more clear.
27	We create the challenge 'Foo CAPTCHA', which requires the user to
28	enter "foo" in a textfield.
29
30	"""
31	/**
32	* Implementation of hook_captcha().
33	*/
34	function foo_captcha_captcha($op, $captcha_type='') {
35	switch ($op) {
36	case 'list':
37	return array('Foo CAPTCHA');
38	case 'generate':
39	if ($captcha_type == 'Foo CAPTCHA') {
40	$captcha = array();
41	$captcha['solution'] = 'foo';
42	$captcha['form']['captcha_response'] = array(
43	'#type' => 'textfield',
44	'#title' => t('Enter "foo"'),
45	'#required' => TRUE,
46	);
47	return $captcha;
48	}
49	break;
50	}
51	}
52	"""
53
54	Validation of the answer against the solution and other stuff is done by the
55	base CAPTCHA module.
56
57
58
59
60	=== Required: the .info file ===
61
62	You should specify that your module depends on the base CAPTCHA module.
63	Optionally you could put your module in the "Spam control" package.
64
65	For our simple foo CAPTCHA module this would mean the following lines in the
66	file foo_captcha.info:
67
68	"""
69	name = "Foo CAPTCHA"
70	description = "The foo CAPTCHA requires the user to enter the word 'foo'."
71	package = "Spam control"
72	dependencies[] = captcha
73	core = 6.x
74	"""
75
76
77
78
79	=== Recommended: hook_menu($may_cache) ===
80
81	More advanced CAPTCHA modules probably want some configuration page.
82	To integrate nicely with the base CAPTCHA module you should offer your
83	configuration page as a MENU_LOCAL_TASK menu entry under 'admin/user/captcha/'.
84
85	For our simple foo CAPTCHA module this would mean:
86
87	"""
88	/**
89	* Implementation of hook_menu().
90	*/
91	function foo_captcha_menu($may_cache) {
92	$items = array();
93	if ($may_cache) {
94	$items['admin/user/captcha/foo_captcha'] = array(
95	'title' => t('Foo CAPTCHA'),
96	'page callback' => 'drupal_get_form',
97	'page arguments' => array('foo_captcha_settings_form'),
98	'type' => MENU_LOCAL_TASK,
99	);
100	}
101	return $items;
102	}
103	"""
104
105	You should of course implement a function foo_captcha_settings_form() which
106	returns the form of your configuration page.
107
108
109
110
111	=== Optional: hook_help($section) ===
112	To offer a description/explanation of your challenge, you can use the
113	normal hook_help() system.
114
115	For our simple foo CAPTCHA module this would mean:
116
117	"""
118	/**
119	* Implementation of hook_help().
120	*/
121	function foo_captcha_help($path, $arg) {
122	switch ($path) {
123	case 'admin/user/captcha/foo_captcha':
124	return '<p>'. t('This is a very simple challenge, which requires users to enter "foo" in a textfield.') .'</p>';
125	}
126	}
127	"""
128
129
130
131	=== Optional: custom response validation ===
132	The CAPTCHA module provides an option for case sensitive and case insensitve
133	validation of the responses. If this is not sufficient, you can provide
134	your own validation function with the 'captcha_validate' field, illustrated
135	by the following example:
136
137	"""
138	/**
139	* Implementation of hook_captcha().
140	*/
141	function foo_captcha_captcha($op, $captcha_type='') {
142	switch ($op) {
143	...
144	case 'generate':
145	if ($captcha_type == 'Foo CAPTCHA') {
146	$captcha = array();
147	$captcha['solution'] = ...
148	$captcha['form'] = ...
149	$captcha['captcha_validate'] = 'foo_captcha_custom_validation';
150	return $captcha;
151	}
152	break;
153	}
154	}
155
156	/**
157	* Custom CAPTCHA validation function.
158	*
159	* @param solution the solution for the challenge as reported by hook_captcha('generate', ...).
160	* @param response the answer given by the user.
161	* @return TRUE on succes and FALSE on failure.
162	*/
163	function foo_captcha_custom_validation($solution, $response) {
164	return $response == "foo" \|\| $response == "bar";
165	}
166	"""
167
168	Previous example shows the basic usage for custom validation with only a $solution
169	and $response argument, which should be sufficient for most CAPTCHA modules.
170	More advanced CAPTCHA modules can also use extra provided arguments $element
171	and $form_state:
172	"""
173	function foo_captcha_custom_validation($solution, $response, $element, $form_state) {
174	return $form_state['foo']['#bar'] = 'baz';
175	}
176	"""
177	These extra arguments are the $element and $form_state arguments of the validation function
178	of the #captcha element. See captcha_validate() in captcha.module for more info about this.
179