You are here

captcha.module in CAPTCHA 5.3

Same filename and directory in other branches
  1. 8 captcha.module
  2. 6.2 captcha.module
  3. 6 captcha.module
  4. 7 captcha.module

This module enables basic CAPTCHA functionality: administrators can add a CAPTCHA to desired forms that users without the 'skip CAPTCHA' permission (typically anonymous visitors) have to solve.

File

captcha.module
View source
<?php

/**
 * @file
 * This module enables basic CAPTCHA functionality:
 * administrators can add a CAPTCHA to desired forms that users without
 * the 'skip CAPTCHA' permission (typically anonymous visitors) have
 * to solve.
 *
 */
define('CAPTCHA_UNSOLVED_CHALLENGES_MAX', 20);
define('CAPTCHA_PERSISTENCE_SHOW_ALWAYS', 1);
define('CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM', 2);
define('CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL', 3);

/**
 * Implementation of hook_help().
 */
function captcha_help($section = 'admin/help#captcha') {
  switch ($section) {
    case 'admin/help#captcha':
      $output = '<p>' . t('"CAPTCHA" is an acronym for "Completely Automated Public Turing test to tell Computers and Humans Apart". It is typically a challenge-response test to determine whether the user is human. The CAPTCHA module is a tool to fight automated submission by malicious users (spamming) of for example comments forms, user registration forms, guestbook forms, etc. You can extend the desired forms with an additional challenge, which should be easy for a human to solve correctly, but hard enough to keep automated scripts and spam bots out.') . '</p>';
      $output .= '<p>' . t('Note that the CAPTCHA module interacts with page caching (see <a href="!performancesettings">performance settings</a>). Because the challenge should be unique for each generated form, the caching of the page it appears on is prevented. Make sure that these forms do not appear on too many pages or you will lose much caching efficiency. For example, if you put a CAPTCHA on the user login block, which typically appears on each page for anonymous visitors, caching will practically be disabled. The comment submission forms are another example. In this case you should set the "%commentlocation" to "%separatepage" in <a href="!commentsettings">the comment settings</a> for better caching efficiency.', array(
        '!performancesettings' => url('admin/settings/performance'),
        '%commentlocation' => t('Location of comment submission form'),
        '%separatepage' => t('Display on separate page'),
        '!commentsettings' => url('admin/content/comment/settings'),
      )) . '</p>';
      $output .= '<p>' . t('CAPTCHA is a trademark of Carnegie Mellon University.') . '</p>';
      return $output;
    case 'admin/user/captcha':
    case 'admin/user/captcha/captcha':
    case 'admin/user/captcha/captcha/settings':
      return t('<p>A CAPTCHA can be added to virtually each Drupal form. Some default forms are already provided in the form list, but arbitrary forms can be easily added and managed when the option "%adminlinks" is enabled.</p><p>Users with the "%skipcaptcha" <a href="@perm">permission</a> won\'t be offered a challenge. Be sure to grant this permission to the trusted users (e.g. site administrators). If you want to test a protected form, be sure to do it as a user without the "%skipcaptcha" permission (e.g. as anonymous user).</p>', array(
        '@perm' => url('admin/user/access'),
        '%adminlinks' => t('Add CAPTCHA administration links to forms'),
        '%skipcaptcha' => t('skip CAPTCHA'),
      ));
  }
}

/**
 * Implementation of hook_menu().
 */
function captcha_menu($may_cache) {
  $items = array();
  if ($may_cache) {

    // main configuration page of the basic CAPTCHA module
    $items[] = array(
      'path' => 'admin/user/captcha',
      'title' => t('CAPTCHA'),
      'description' => t('Administer how and where CAPTCHAs are used.'),
      'callback' => 'drupal_get_form',
      'callback arguments' => array(
        'captcha_admin_settings',
      ),
      'access' => user_access('administer CAPTCHA settings'),
      'type' => MENU_NORMAL_ITEM,
    );

    // the default local task (needed when other modules want to offer
    // alternative CAPTCHA types and their own configuration page as local task)
    $items[] = array(
      'path' => 'admin/user/captcha/captcha',
      'title' => t('CAPTCHA'),
      'type' => MENU_DEFAULT_LOCAL_TASK,
      'weight' => -20,
    );
    $items[] = array(
      'path' => 'admin/user/captcha/captcha/settings',
      'title' => t('General settings'),
      'type' => MENU_DEFAULT_LOCAL_TASK,
      'weight' => 0,
    );
    $items[] = array(
      'path' => 'admin/user/captcha/captcha/examples',
      'title' => t('Examples'),
      'description' => t('An overview of the available challenge types with examples.'),
      'callback' => 'captcha_examples',
      'type' => MENU_LOCAL_TASK,
      'weight' => 5,
    );

    // form for adding/editing CAPTCHA points
    $items[] = array(
      'path' => 'admin/user/captcha/captcha/captcha_point',
      'title' => t('Set CAPTCHA point'),
      'description' => t('Add or edit form_id\'s to protect with a CAPTCHA.'),
      'callback' => 'drupal_get_form',
      'callback arguments' => array(
        'captcha_point_admin_form',
      ),
      'type' => MENU_LOCAL_TASK,
      'weight' => 2,
    );
  }
  else {

    // Some non cachable menu items for disabling/deleting CAPTCHA points
    // start with arg(4) == 'captcha_point' for faster short circuit
    if (arg(4) == 'captcha_point' && arg(0) == 'admin' && arg(1) == 'user' && arg(2) == 'captcha' && arg(3) == 'captcha' && !is_null(arg(5))) {
      $items[] = array(
        'path' => 'admin/user/captcha/captcha/captcha_point/' . arg(5) . '/disable',
        'title' => t('Disable'),
        'callback' => 'drupal_get_form',
        'callback arguments' => array(
          'captcha_point_disable_confirm',
          arg(5),
          FALSE,
        ),
        'type' => MENU_CALLBACK,
      );
      $items[] = array(
        'path' => 'admin/user/captcha/captcha/captcha_point/' . arg(5) . '/delete',
        'title' => t('Delete'),
        'callback' => 'drupal_get_form',
        'callback arguments' => array(
          'captcha_point_disable_confirm',
          arg(5),
          TRUE,
        ),
        'type' => MENU_CALLBACK,
      );
    }
  }
  return $items;
}

/**
 * Implementation of hook_perm().
 */
function captcha_perm() {
  return array(
    'administer CAPTCHA settings',
    'skip CAPTCHA',
  );
}

/**
 * Implementation of hook_requirements().
 */
function captcha_requirements($phase) {
  $requirements = array();
  $t = get_t();
  if ($phase == 'runtime') {

    // show the wrong response counter in the status report
    $requirements['captcha_wrong_response_counter'] = array(
      'title' => $t('CAPTCHA'),
      'value' => $t('Already @counter blocked form submissions', array(
        '@counter' => variable_get('captcha_wrong_response_counter', 0),
      )),
      'severity' => REQUIREMENT_INFO,
    );

    // Check if there is an entry for uid=0 in the users table, this is required
    // to have working a $_SESSION variable for anonymous users.
    if (!db_result(db_query('SELECT COUNT(*) FROM {users} WHERE uid=%d', 0))) {
      $requirements['captcha_no_sessions_for_anonymous'] = array(
        'title' => $t('CAPTCHA'),
        'value' => $t('No sessions for anonymous users.'),
        'description' => $t('There is no entry for uid 0 in the %users table of the database. This disables persistent session data for anonymous users. Because the CAPTCHA module depends on this session data, CAPTCHAs will not work for anonymous users. Add a row for uid 0 to the %users table to resolve this.', array(
          '%users' => 'users',
        )),
        'severity' => REQUIREMENT_ERROR,
      );
    }
  }
  return $requirements;
}

/**
 * Return an array with the available CAPTCHA types, for use as options array
 * for a select form elements.
 * The array is an associative array mapping "$module/$type" to
 * "$type ($module)" with $module the module name implementing the CAPTCHA
 * and $type the name of the CAPTCHA type.
 * (It also includes a 'none' => '<none>' option)
 */
function _captcha_available_challenge_types() {
  $captcha_types['none'] = '<' . t('none') . '>';
  foreach (module_implements('captcha') as $module) {
    $result = call_user_func_array($module . '_captcha', array(
      'list',
    ));
    if (is_array($result)) {
      foreach ($result as $type) {
        $captcha_types["{$module}/{$type}"] = "{$type} ({$module})";
      }
    }
  }
  return $captcha_types;
}

/**
 * Get the description which appears above the CAPTCHA in forms.
 * If the locale module is enabled, an optional language code can be given
 */
function _captcha_get_description($lang_code = NULL) {
  $default = t('This question is for testing whether you are a human visitor and to prevent automated spam submissions.');
  if (module_exists('locale')) {
    if ($lang_code == NULL) {
      global $locale;
      $lang_code = $locale;
    }
    $description = variable_get("captcha_description_{$lang_code}", $default);
  }
  else {
    $description = variable_get('captcha_description', $default);
  }
  return filter_xss_admin($description);
}

/**
 * Form builder function for the general CAPTCHA configuration
 */
function captcha_admin_settings() {

  // field for the CAPTCHA administration mode
  $form['captcha_administration_mode'] = array(
    '#type' => 'checkbox',
    '#title' => t('Add CAPTCHA administration links to forms'),
    '#default_value' => variable_get('captcha_administration_mode', FALSE),
    '#description' => t('This option is very helpful to enable/disable challenges on forms. When enabled, users with the "%admincaptcha" permission will see CAPTCHA administration links on all forms (except on administrative pages, which shouldn\'t be accessible to untrusted users in the first place). These links make it possible to enable a challenge of the desired type or disable it.', array(
      '%admincaptcha' => t('administer CAPTCHA settings'),
    )),
  );

  // field set with form_id -> CAPTCHA type configuration
  $form['captcha_types'] = array(
    '#type' => 'fieldset',
    '#title' => t('Challenge type per form'),
    '#description' => t('Select the challenge type you want for each of the listed forms (identified by their so called <em>form_id</em>\'s). You can easily add arbitrary forms with the help of the \'%CAPTCHA_admin_links\' option or the <a href="!add_captcha_point">the CAPTCHA point form</a>.', array(
      '%CAPTCHA_admin_links' => t('Add CAPTCHA administration links to forms'),
      '!add_captcha_point' => url('admin/user/captcha/captcha/captcha_point'),
    )),
    '#tree' => TRUE,
    '#collapsible' => TRUE,
    '#collapsed' => FALSE,
    '#theme' => 'captcha_admin_settings_captcha_points',
  );

  // list all possible form_id's
  $captcha_types = _captcha_available_challenge_types();
  $result = db_query("SELECT * FROM {captcha_points} ORDER BY form_id");
  while ($captcha_point = db_fetch_object($result)) {
    $form['captcha_types'][$captcha_point->form_id]['form_id'] = array(
      '#value' => $captcha_point->form_id,
    );

    // select widget for CAPTCHA type
    $form['captcha_types'][$captcha_point->form_id]['captcha_type'] = array(
      '#type' => 'select',
      '#default_value' => "{$captcha_point->module}/{$captcha_point->type}",
      '#options' => $captcha_types,
    );

    // additional operations
    $form['captcha_types'][$captcha_point->form_id]['operations'] = array(
      '#value' => implode(", ", array(
        l(t('delete'), "admin/user/captcha/captcha/captcha_point/{$captcha_point->form_id}/delete"),
      )),
    );
  }

  // field(s) for setting the additional CAPTCHA description
  if (module_exists('locale')) {
    $langs = locale_supported_languages();
    $form['captcha_descriptions'] = array(
      '#type' => 'fieldset',
      '#title' => t('Challenge description'),
      '#description' => t('With this description you can explain the purpose of the challenge to the user.'),
    );
    foreach ($langs['name'] as $lang_code => $lang_name) {
      $form['captcha_descriptions']["captcha_description_{$lang_code}"] = array(
        '#type' => 'textfield',
        '#title' => t('For language %lang_name (code %lang_code)', array(
          '%lang_name' => $lang_name,
          '%lang_code' => $lang_code,
        )),
        '#default_value' => _captcha_get_description($lang_code),
        '#maxlength' => 256,
      );
    }
  }
  else {
    $form['captcha_description'] = array(
      '#type' => 'textfield',
      '#title' => t('Challenge description'),
      '#description' => t('With this description you can explain the purpose of the challenge to the user.'),
      '#default_value' => _captcha_get_description(),
      '#maxlength' => 256,
    );
  }

  // field for CAPTCHA persistence
  $form['captcha_persistence'] = array(
    '#type' => 'radios',
    '#title' => t('Persistence'),
    '#default_value' => variable_get('captcha_persistence', CAPTCHA_PERSISTENCE_SHOW_ALWAYS),
    '#options' => array(
      CAPTCHA_PERSISTENCE_SHOW_ALWAYS => t('Always add a challenge.'),
      CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM => t('Omit challenges for a form once the user has successfully responded to a challenge for that form.'),
      CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL => t('Omit challenges for all forms once the user has successfully responded to a challenge.'),
    ),
    '#description' => t('Define if challenges should be omitted during the rest of a session once the user successfully responses to a challenge.'),
  );

  // option for logging wrong responses
  $form['captcha_log_wrong_responses'] = array(
    '#type' => 'checkbox',
    '#title' => t('Log wrong responses'),
    '#description' => t('Report information about wrong responses to the !watchdoglog.', array(
      '!watchdoglog' => l(t('log'), 'admin/logs/watchdog'),
    )),
    '#default_value' => variable_get('captcha_log_wrong_responses', FALSE),
  );

  // submit button
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Submit'),
  );
  return $form;
}

/**
 * Custom theme function for a table of (form_id -> CAPTCHA type) settings
 */
function theme_captcha_admin_settings_captcha_points($form) {
  foreach (element_children($form) as $key) {
    $row = array();
    $row[] = drupal_render($form[$key]['form_id']);
    $row[] = drupal_render($form[$key]['captcha_type']);
    $row[] = drupal_render($form[$key]['operations']);
    $rows[] = $row;
  }
  $header = array(
    'form_id',
    t('Challenge type (module)'),
    t('Operations'),
  );
  $output = theme('table', $header, $rows);
  return $output;
}

/**
 * Submission function for captcha_admin_settings form
 */
function captcha_admin_settings_submit($form_id, $form_values) {
  if ($form_id == 'captcha_admin_settings') {
    variable_set('captcha_administration_mode', $form_values['captcha_administration_mode']);
    foreach ($form_values['captcha_types'] as $captcha_point_form_id => $data) {
      if ($data['captcha_type'] == 'none') {
        db_query("UPDATE {captcha_points} SET module = NULL, type = NULL WHERE form_id = '%s'", $captcha_point_form_id);
      }
      else {
        list($module, $type) = explode('/', $data['captcha_type']);
        db_query("UPDATE {captcha_points} SET module = '%s', type = '%s' WHERE form_id = '%s'", $module, $type, $captcha_point_form_id);
      }
    }

    // description stuff
    if (module_exists('locale')) {
      $langs = locale_supported_languages();
      foreach ($langs['name'] as $lang_code => $lang_name) {
        variable_set("captcha_description_{$lang_code}", $form_values["captcha_description_{$lang_code}"]);
      }
    }
    else {
      variable_set('captcha_description', $form_values['captcha_description']);
    }
    variable_set('captcha_persistence', $form_values['captcha_persistence']);
    variable_set('captcha_log_wrong_responses', $form_values['captcha_log_wrong_responses']);
    drupal_set_message(t('The CAPTCHA settings were saved.'), 'status');
  }
}
function captcha_point_admin_form($captcha_point_form_id = NULL) {
  $form = array();
  $default_captcha_type = 'none';
  if (isset($captcha_point_form_id)) {

    // use given CAPTCHA point form_id
    $form['captcha_point_form_id'] = array(
      '#type' => 'textfield',
      '#title' => t('Form ID'),
      '#description' => t('The Drupal form_id of the form to add the CAPTCHA to.'),
      '#value' => check_plain($captcha_point_form_id),
      '#disabled' => TRUE,
    );
    $result = db_query("SELECT * FROM {captcha_points} WHERE form_id = '%s'", $captcha_point_form_id);
    $captcha_point = db_fetch_object($result);
    if ($captcha_point) {
      $default_captcha_type = "{$captcha_point->module}/{$captcha_point->type}";
    }
  }
  else {

    // textfield for CAPTCHA point form_id
    $form['captcha_point_form_id'] = array(
      '#type' => 'textfield',
      '#title' => t('Form ID'),
      '#description' => t('The Drupal form_id of the form to add the CAPTCHA to.'),
    );
  }

  // select widget for CAPTCHA type
  $form['captcha_type'] = array(
    '#type' => 'select',
    '#title' => t('Challenge type'),
    '#description' => t('The CAPTCHA type to use for this form'),
    '#default_value' => $default_captcha_type,
    '#options' => _captcha_available_challenge_types(),
  );

  // redirect to general CAPTCHA settings page after submission
  $form['#redirect'] = 'admin/user/captcha';

  // submit button
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );
  return $form;
}

/**
 * validation function for captcha_point_admin_form
 */
function captcha_point_admin_form_validate($form, $form_values) {
  if (!preg_match('/^[a-z0-9_]+$/', $form_values['captcha_point_form_id'])) {
    form_set_error('captcha_point_form_id', t('Illegal form_id'));
  }
}

/**
 * submit function for captcha_point_admin_form
 */
function captcha_point_admin_form_submit($form, $form_values) {
  $captcha_point_form_id = $form_values['captcha_point_form_id'];
  $captcha_type = $form_values['captcha_type'];

  // remove old settings
  db_query("DELETE FROM {captcha_points} WHERE form_id = '%s'", $captcha_point_form_id);

  // save new settings
  if ($captcha_type == 'none') {
    db_query("INSERT INTO {captcha_points} (form_id, module, type) VALUES ('%s', NULL, NULL)", $captcha_point_form_id);
  }
  else {
    list($module, $type) = explode('/', $captcha_type);
    db_query("INSERT INTO {captcha_points} (form_id, module, type) VALUES ('%s', '%s', '%s')", $captcha_point_form_id, $module, $type);
  }
  drupal_set_message(t('Saved CAPTCHA point settings.'), 'status');
}

/**
 * Confirm dialog for disabling/deleting a CAPTCHA point
 *
 * @param $captcha_point_form_id the form_id of the form to disable the CAPTCHA
 *   from
 * @param $delete boolean for also deleting the CAPTCHA point
 */
function captcha_point_disable_confirm($captcha_point_form_id, $delete) {
  $form = array();
  $form['captcha_point_form_id'] = array(
    '#type' => 'value',
    '#value' => $captcha_point_form_id,
  );
  $form['captcha_point_delete'] = array(
    '#type' => 'value',
    '#value' => $delete,
  );
  if ($delete) {
    $message = t('Are you sure you want to delete the CAPTCHA for form_id %form_id?', array(
      '%form_id' => $captcha_point_form_id,
    ));
    $yes = t('Delete');
  }
  else {
    $message = t('Are you sure you want to disable the CAPTCHA for form_id %form_id?', array(
      '%form_id' => $captcha_point_form_id,
    ));
    $yes = t('Disable');
  }
  return confirm_form($form, $message, isset($_GET['destination']) ? $_GET['destination'] : 'admin/user/captcha/captcha', '', $yes);
}

/**
 * submission handler of CAPTCHA point disabling/deleting confirm_form
 */
function captcha_point_disable_confirm_submit($form, $form_values) {
  $captcha_point_form_id = $form_values['captcha_point_form_id'];
  $delete = $form_values['captcha_point_delete'];
  if ($delete) {
    db_query("DELETE FROM {captcha_points} WHERE form_id = '%s'", $captcha_point_form_id);
    drupal_set_message(t('Deleted CAPTCHA for form %form_id.', array(
      '%form_id' => $captcha_point_form_id,
    )));
  }
  else {
    db_query("UPDATE {captcha_points} SET module = NULL, type = NULL WHERE form_id = '%s'", $captcha_point_form_id);
    drupal_set_message(t('Disabled CAPTCHA for form %form_id.', array(
      '%form_id' => $captcha_point_form_id,
    )));
  }

  // redirect to CAPTCHA admin
  return 'admin/user/captcha';
}

/**
 * Helper function for checking if the CAPTCHA for the given form_id should
 * be skipped because of CAPTCHA persistence.
 */
function _captcha_persistence_skip($form_id) {
  $persistence = variable_get('captcha_persistence', CAPTCHA_PERSISTENCE_SHOW_ALWAYS);
  return $persistence == CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL && $_SESSION['captcha']['success'] === TRUE || $persistence == CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM && $_SESSION['captcha'][$form_id]['success'] === TRUE;
}

/**
 * Implementation of hook_form_alter().
 *
 * This function adds a CAPTCHA to forms for untrusted users if needed and adds
 * CAPTCHA administration links for site administrators if this option is enabled.
 */
function captcha_form_alter($form_id, &$form) {
  if (!user_access('skip CAPTCHA')) {

    // Visitor does not have permission to skip the CAPTCHA
    // Get CAPTCHA type and module for this form. Return if no CAPTCHA was set.
    $result = db_query("SELECT module, type FROM {captcha_points} WHERE form_id = '%s'", $form_id);
    if (!$result) {
      return;
    }
    $captcha_point = db_fetch_object($result);
    if (!$captcha_point || !$captcha_point->type) {
      return;
    }

    // Prevent caching of the page with this CAPTCHA enabled form.
    // This needs to be done even if the CAPTCHA will be skipped (because of
    // persistence): other untrusted users should not get a cached page when
    // the current untrusted user can skip the current CAPTCHA.
    global $conf;
    $conf['cache'] = FALSE;

    // Do not present CAPTCHA if not CAPTCHA-persistent and user has already solved a CAPTCHA for this form
    if (_captcha_persistence_skip($form_id)) {
      return;
    }

    // Generate a CAPTCHA and its solution
    $captcha = module_invoke($captcha_point->module, 'captcha', 'generate', $captcha_point->type);
    if (!$captcha) {

      //The selected module returned nothing, maybe it is disabled or it's wrong, we should watchdog that and then quit.
      watchdog('CAPTCHA', t('CAPTCHA problem: hook_captcha() of module %module returned nothing when trying to retrieve challenge type %type for form %form_id.', array(
        '%type' => $captcha_point->type,
        '%module' => $captcha_point->module,
        '%form_id' => $form_id,
      )), WATCHDOG_ERROR);
      return;
    }

    // Add a CAPTCHA part to the form (depends on value of captcha_description)
    $captcha_description = _captcha_get_description();
    if ($captcha_description) {

      // $captcha_description is not empty: CAPTCHA part is a fieldset with description
      $form['captcha'] = array(
        '#type' => 'fieldset',
        '#title' => t('CAPTCHA'),
        '#description' => $captcha_description,
        '#attributes' => array(
          'class' => 'captcha',
        ),
      );
    }
    else {

      // $captcha_description is empty: CAPTCHA part is an empty markup form element
      $form['captcha'] = array(
        '#type' => 'markup',
        '#prefix' => '<div class="captcha">',
        '#suffix' => '</div>',
      );
    }

    // Add the form elements of the generated CAPTCHA to the form
    $form['captcha'] = array_merge($form['captcha'], $captcha['form']);

    // Store the solution of the generated CAPTCHA as an internal form value.
    // This will be stored later in $_SESSION during the pre_render phase.
    // It can't be saved at this point because hook_form_alter is not only run
    // before form rendering, but also before form validation (which happens
    // in a new (POST) request. Consequently the right CAPTCHA solution would be
    // overwritten just before validation. The pre_render functions are not run
    // before validation and are the right place to store the solution in $_SESSION.
    $form['captcha']['captcha_solution'] = array(
      '#type' => 'value',
      '#value' => $captcha['solution'],
    );

    // The CAPTCHA token is used to differentiate between different instances
    // of the same form. This makes it possible to request the same form a
    // couple of times before submitting them. The solution of the CAPTCHA of
    // each of these form instances will be stored at the pre_render phase in
    // $_SESSION['captcha'][$form_id][$captcha_token]
    $form['captcha']['captcha_token'] = array(
      '#type' => 'hidden',
      '#value' => md5(mt_rand()),
    );

    // other internal values needed for the validation phase
    $form['captcha']['validationdata'] = array(
      '#type' => 'value',
      '#value' => array(
        'form_id' => $form_id,
        'preprocess' => isset($captcha['preprocess']) ? $captcha['preprocess'] : FALSE,
        'module' => $captcha_point->module,
        'type' => $captcha_point->type,
      ),
    );

    // handle the pre_render functions
    $form['#pre_render'][] = 'captcha_pre_render';
    $form['#pre_render'][] = 'captcha_pre_render_place_captcha';

    // Add a validation function for the CAPTCHA part of the form
    $form['captcha']['#validate']['captcha_validate'] = array();
  }
  elseif (user_access('administer CAPTCHA settings') && variable_get('captcha_administration_mode', FALSE) && arg(0) != 'admin') {

    // For administrators: show CAPTCHA info and offer link to configure it
    $result = db_query("SELECT module, type FROM {captcha_points} WHERE form_id = '%s'", $form_id);
    if (!$result) {
      return;
    }
    $captcha_point = db_fetch_object($result);
    $form['captcha'] = array(
      '#type' => 'fieldset',
      '#title' => t('CAPTCHA'),
      '#collapsible' => TRUE,
      '#collapsed' => TRUE,
    );
    if ($captcha_point && $captcha_point->type) {
      $form['captcha']['#description'] = t('Untrusted users will see a CAPTCHA here (!settings).', array(
        '!settings' => l(t('general CAPTCHA settings'), 'admin/user/captcha'),
      ));
      $form['captcha']['challenge'] = array(
        '#type' => 'item',
        '#title' => t('Enabled challenge'),
        '#value' => t('"@type" by module "@module" (!change, !disable)', array(
          '@type' => $captcha_point->type,
          '@module' => $captcha_point->module,
          '!change' => l(t('change'), "admin/user/captcha/captcha/captcha_point/{$form_id}", array(), drupal_get_destination()),
          '!disable' => l(t('disable'), "admin/user/captcha/captcha/captcha_point/{$form_id}/disable", array(), drupal_get_destination()),
        )),
      );
    }
    else {
      $form['captcha']['add_captcha'] = array(
        '#value' => l(t('Place a CAPTCHA here for untrusted users.'), "admin/user/captcha/captcha/captcha_point/{$form_id}", array(), drupal_get_destination()),
      );
    }

    // Add pre_render function for placing the CAPTCHA just above the submit button
    $form['#pre_render'] = (array) $form['#pre_render'] + array(
      'captcha_pre_render_place_captcha',
    );
  }
}

/**
 * Implementation of form #validate.
 */
function captcha_validate($form_values) {

  // Check if there is CAPTCHA data available in $_SESSION
  // If not, the user has most likely disabled cookies
  if (!isset($_SESSION['captcha'])) {
    form_set_error('captcha', t('Cookies should be enabled in your browser for CAPTCHA validation.'));
    return;
  }

  // Get answer and preprocess if needed
  $captcha_response = $form_values['#post']['captcha_response'];
  $validationdata = $form_values['validationdata']['#value'];
  if ($validationdata['preprocess']) {
    $captcha_response = module_invoke($validationdata['module'], 'captcha', 'preprocess', $validationdata['type'], $captcha_response);
  }
  $form_id = $validationdata['form_id'];
  $captcha_token = $form_values['#post']['captcha_token'];

  // Check if captcha_token exists
  if (!isset($_SESSION['captcha'][$form_id][$captcha_token])) {
    form_set_error('captcha_token', t('Invalid CAPTCHA token.'));
  }

  // Check answer
  if ($captcha_response === $_SESSION['captcha'][$form_id][$captcha_token]) {
    $_SESSION['captcha'][$form_id]['success'] = TRUE;
    $_SESSION['captcha']['success'] = TRUE;
  }
  else {

    // set form error
    form_set_error('captcha_response', t('The answer you entered for the CAPTCHA was not correct.'));

    // update wrong response counter
    variable_set('captcha_wrong_response_counter', variable_get('captcha_wrong_response_counter', 0) + 1);

    // log to watchdog if needed
    if (variable_get('captcha_log_wrong_responses', FALSE)) {
      watchdog('CAPTCHA', t('%form_id post blocked by CAPTCHA module: challenge "%challenge" (by module "%module"), user answered "%response", but the solution was "%solution".', array(
        '%form_id' => $form_id,
        '%response' => $captcha_response,
        '%solution' => $_SESSION['captcha'][$form_id][$captcha_token],
        '%challenge' => $validationdata['type'],
        '%module' => $validationdata['module'],
      )), WATCHDOG_NOTICE);
    }

    // If CAPTCHA was on a login form: stop validating, quit the current request
    // and forward to the current page (like a reload) to prevent loging in.
    // We do that because the log in procedure, which happens after
    // captcha_validate(), does not check error conditions of extra form
    // elements like the CAPTCHA.
    if ($form_id == 'user_login' || $form_id == 'user_login_block') {
      drupal_goto($_GET['q']);
    }
  }

  // Unset the solution to prevent reuse of the same CAPTCHA solution
  // by a spammer that repeats posting a form without requesting
  // (and thus rendering) a new form. Note that a new CAPTCHA solution is only
  // set at the pre_render phase.
  unset($_SESSION['captcha'][$form_id][$captcha_token]);
}

/**
 * Implementation of form #pre_render.
 *
 * The main purpose of this function is to store the solution of the CAPTCHA
 * in the $_SESSION variable.
 */
function captcha_pre_render($form_id, &$form) {

  // Unset the CAPTCHA if non-CAPTCHA persistent and the CAPTCHA has
  // already been successfully solved for this form.
  // This needs to be done in this pre_render phase when previewing for example
  // nodes and comments before submission.
  // On submission of such a forms for preview, captcha_form_alter() is called
  // *before* the CAPTCHA validation function (which sets
  // $_SESSION['captcha'][$form_id]['success'] to TRUE on a correctly answered
  // CAPTCHA). After this the form_values are entered in the generated form
  // and this form is presented with the preview.
  // This means that captcha_form_alter() can't know if the CAPTCHA was
  // correctly answered and consequently adds a CAPTCHA to the form.
  // The pre_render phase happens after the validation phase and makes it
  // possible to remove the CAPTCHA from the form after all.
  if (_captcha_persistence_skip($form_id)) {
    unset($form['captcha']);
    return;
  }

  // count the number of unsolved CAPTCHAs and unset the oldest if too many
  // minus 1 is needed because 'success' is also an item of $_SESSION['captcha'][$form_id]
  if (count($_SESSION['captcha'][$form_id]) - 1 > CAPTCHA_UNSOLVED_CHALLENGES_MAX) {
    foreach (array_keys($_SESSION['captcha'][$form_id]) as $captcha_token) {
      if ($captcha_token != 'success') {
        unset($_SESSION['captcha'][$form_id][$captcha_token]);
        break;
      }
    }
  }

  // store the current CAPTCHA solution in $_SESSION
  $captcha_token = $form['captcha']['captcha_token']['#value'];
  $_SESSION['captcha'][$form_id][$captcha_token] = $form['captcha']['captcha_solution']['#value'];
  $_SESSION['captcha'][$form_id]['success'] = FALSE;

  // empty the value of the captcha_response form item before rendering
  $form['captcha']['captcha_response']['#value'] = '';
}

/**
 * Pre_render function to place the CAPTCHA form element just above the last submit button
 */
function captcha_pre_render_place_captcha($form_id, &$form) {

  // search the weights of the buttons in the form
  $button_weights = array();
  foreach (element_children($form) as $key) {
    if ($form[$key]['#type'] == 'submit' || $form[$key]['#type'] == 'button') {
      $button_weights[] = $form[$key]['#weight'];
    }
  }
  if ($button_weights) {

    // set the weight of the CAPTCHA element a tiny bit smaller than the lightest button weight
    // (note that the default resolution of #weight values is 1/1000 (see drupal/includes/form.inc))
    $first_button_weight = min($button_weights);
    $form['captcha']['#weight'] = $first_button_weight - 0.5 / 1000.0;

    // make sure the form gets sorted before rendering
    unset($form['#sorted']);
  }
}

/**
 * Funtion for generating a page with CAPTCHA examples
 * If the arguments $module and $challenge are not set, generate a list with
 * examples of the available CAPTCHA types.
 * If $module and $challenge are set, generate 10 examples of the concerning
 * CAPTCHA.
 */
function captcha_examples($module = NULL, $challenge = NULL) {
  if ($module && $challenge) {

    // generate 10 examples
    $output = '';
    for ($i = 0; $i < 10; $i++) {

      // generate CAPTCHA
      $captcha = call_user_func_array($module . '_captcha', array(
        'generate',
        $challenge,
      ));
      $form = $captcha['form'];
      $id = "captcha_examples_{$module_}{$challenge_}{$i}";
      drupal_process_form($id, $form);
      $output .= drupal_render_form($id, $form);
    }
  }
  else {

    // generate a list with examples of the available CAPTCHA types
    $output = t('This page gives an overview of all available challenge types, generated with their current settings.');
    foreach (module_implements('captcha') as $module) {
      $challenges = call_user_func_array($module . '_captcha', array(
        'list',
      ));
      if ($challenges) {
        foreach ($challenges as $challenge) {

          // generate CAPTCHA
          $captcha = call_user_func_array($module . '_captcha', array(
            'generate',
            $challenge,
          ));

          // build form
          $form = array();
          $form['captcha'] = array(
            '#type' => 'fieldset',
            '#title' => t('Challenge "%challenge" by module "%module"', array(
              '%challenge' => $challenge,
              '%module' => $module,
            )),
          );
          $form['captcha'] = array_merge($form['captcha'], $captcha['form']);
          $form['captcha']['more_examples'] = array(
            '#type' => 'markup',
            '#value' => l(t('10 more examples of this challenge.'), "admin/user/captcha/captcha/examples/{$module}/{$challenge}"),
          );

          // return rendered form
          $id = "captcha_examples_{$module_}{$challenge}";
          drupal_process_form($id, $form);
          $output .= drupal_render_form($id, $form);
        }
      }
    }
  }
  return $output;
}

/**
 * Default implementation of hook_captcha
 */
function captcha_captcha($op, $captcha_type = '') {
  switch ($op) {
    case 'list':
      return array(
        'Math',
      );
    case 'generate':
      if ($captcha_type == 'Math') {
        $result = array();
        $answer = mt_rand(1, 20);
        $x = mt_rand(1, $answer);
        $y = $answer - $x;
        $result['solution'] = "{$answer}";
        $result['form']['captcha_response'] = array(
          '#type' => 'textfield',
          '#title' => t('Math Question'),
          '#description' => t('Solve this simple math problem and enter the result. E.g. for 1+3, enter 4.'),
          '#field_prefix' => t('@x + @y = ', array(
            '@x' => $x,
            '@y' => $y,
          )),
          '#size' => 4,
          '#maxlength' => 2,
          '#required' => TRUE,
        );
        return $result;
      }
  }
}

Functions

Namesort descending Description
captcha_admin_settings Form builder function for the general CAPTCHA configuration
captcha_admin_settings_submit Submission function for captcha_admin_settings form
captcha_captcha Default implementation of hook_captcha
captcha_examples Funtion for generating a page with CAPTCHA examples If the arguments $module and $challenge are not set, generate a list with examples of the available CAPTCHA types. If $module and $challenge are set, generate 10 examples of the concerning CAPTCHA.
captcha_form_alter Implementation of hook_form_alter().
captcha_help Implementation of hook_help().
captcha_menu Implementation of hook_menu().
captcha_perm Implementation of hook_perm().
captcha_point_admin_form
captcha_point_admin_form_submit submit function for captcha_point_admin_form
captcha_point_admin_form_validate validation function for captcha_point_admin_form
captcha_point_disable_confirm Confirm dialog for disabling/deleting a CAPTCHA point
captcha_point_disable_confirm_submit submission handler of CAPTCHA point disabling/deleting confirm_form
captcha_pre_render Implementation of form #pre_render.
captcha_pre_render_place_captcha Pre_render function to place the CAPTCHA form element just above the last submit button
captcha_requirements Implementation of hook_requirements().
captcha_validate Implementation of form #validate.
theme_captcha_admin_settings_captcha_points Custom theme function for a table of (form_id -> CAPTCHA type) settings
_captcha_available_challenge_types Return an array with the available CAPTCHA types, for use as options array for a select form elements. The array is an associative array mapping "$module/$type" to "$type ($module)" with $module the module name implementing the…
_captcha_get_description Get the description which appears above the CAPTCHA in forms. If the locale module is enabled, an optional language code can be given
_captcha_persistence_skip Helper function for checking if the CAPTCHA for the given form_id should be skipped because of CAPTCHA persistence.

Constants

Namesort descending Description
CAPTCHA_PERSISTENCE_SHOW_ALWAYS
CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL
CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM
CAPTCHA_UNSOLVED_CHALLENGES_MAX @file This module enables basic CAPTCHA functionality: administrators can add a CAPTCHA to desired forms that users without the 'skip CAPTCHA' permission (typically anonymous visitors) have to solve.