As this module invents hooks for other modules to implement, it should have an api.php file to document them.

#5 captcha-missing_api_.php_file_for_hook_documentation-1988950-5.patch5.32 KBnagwani
FAILED: [[SimpleTest]]: [MySQL] Invalid PHP syntax in sites/default/modules/captcha/captcha.api.php. View


elachlan’s picture

Could you please provide a link to documentation on how to implement this, or provide a patch?

joachim’s picture

Sure, here are some docs pages about this:


All core modules have a *.api.php file that you can use as a template.

You can also use Module Builder to generate the scaffold for the api.php file.

nagwani’s picture

4.6 KB
FAILED: [[SimpleTest]]: [MySQL] Invalid PHP syntax in sites/default/modules/captcha/captcha.api.php. View

Attaching .api.php. Created from api.txt file. Please review.

joachim’s picture

Status: Active » Needs work

Looks like a good start! Few things missing and need cleaning up:

  1. +++ b/captcha.api.php
    @@ -0,0 +1,133 @@
    + * The hook is the only required function if you want to integrate with the base CAPTCHA module
    + *
    + * Modules may make changes to the comment before it is saved to the database.
    + * 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()).
    + **/
    + * Implementation of hook_captcha().
    + */
    +function hook_captcha_captcha($op, $captcha_type='') {

    You should have only one docblock for each function. The 'Implementation...' one should be removed.

  2. +++ b/captcha.api.php
    @@ -0,0 +1,133 @@
    +function foo_captcha_captcha($op, $captcha_type='') {

    Parameters and return need to be documented.

nagwani’s picture

4.69 KB
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch interdiff_36.patch. Unable to apply patch. See the log in the details link for more information. View
5.32 KB
FAILED: [[SimpleTest]]: [MySQL] Invalid PHP syntax in sites/default/modules/captcha/captcha.api.php. View


nagwani’s picture

Issue summary: View changes
Status: Needs work » Needs review

The last submitted patch, 5: interdiff.patch, failed testing.

Status: Needs review » Needs work
mgbellaire’s picture

joachim, are you saying that the "Implementation..." blocks need to be removed and not replaced by anything else?

mgbellaire’s picture

Updating shown files...

joachim’s picture

From the docs:

The summary starts with an imperative verb that tells why a module would want to implement the hook. Example: "Respond to node deletion." Hook definitions are placed in a .api.php file, which is not directly loaded by Drupal. Each is a fake function whose name starts with "hook", and whose function body is a sample implementation. Parameters and return value that the implementer must use need to be documented.

So for example:

 * Declare system queues to be usable by human workers.
 * @return
 *  An array keyed by the queue name, where each item is an array of data about
 *  the queue containing the following properties:
 *  - 'queue': The queue name.
 *  - 'label': A human-readable label for the queue. This needn't include the
 *    word 'queue'; UI texts add this in their phrasing, as in 'The foo queue'.
 *  - 'lease time': The lease time to grant when claiming an item from the queue
 *    for human workers. This should be long enough for the user to read the
 *    form, go and make a cup of tea, and so on. Suggested time is 30 minutes.
 *  - 'entity type': The type of the entities being queued.
 *  - 'entity operations': An array of the names of operations to be made
 *    available in the queue item processing form. These should also be defined
 *    in hook_entity_operation_info(), where their handlers and other properties
 *    should be set.
 *  - 'view mode': (optional) The view mode in which to display the entity in
 *    the queue processing form. Defaults to 'full', the same as entity_view().
 *    Entities using this system may wish to provide a view mode for this which
 *    suppresses the output of the entity title as a link.
function hook_human_queue_worker_info() {
  $info = array(
    'my_queue' => array(
      'queue' => 'my_queue',
      'label' => t("Dummy"),
      'lease time' => 30 * 60,
      'entity type' => 'entity_operations_test',
      'entity operations' => array(
        // These should be operations defined on the entity.
      'view mode' => 'queue_process',

  return $info;
max-kuzomko’s picture

Assigned: Unassigned » max-kuzomko

Status: Needs work » Needs review

Status: Needs review » Needs work
max-kuzomko’s picture

Assigned: max-kuzomko » Unassigned