danielebarchiesi@2: <?php
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * @file
danielebarchiesi@2:  * General CAPTCHA functionality and helper functions.
danielebarchiesi@2:  */
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function for adding/updating a CAPTCHA point.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @param $form_id the form ID to configure.
danielebarchiesi@2:  * @param captcha_type the setting for the given form_id, can be:
danielebarchiesi@2:  *   - 'none' to disable CAPTCHA,
danielebarchiesi@2:  *   - 'default' to use the default challenge type
danielebarchiesi@2:  *   - NULL to remove the entry for the CAPTCHA type
danielebarchiesi@2:  *   - something of the form 'image_captcha/Image'
danielebarchiesi@2:  *   - an object with attributes $captcha_type->module and $captcha_type->captcha_type
danielebarchiesi@2:  * @return nothing
danielebarchiesi@2:  */
danielebarchiesi@2: function captcha_set_form_id_setting($form_id, $captcha_type) {
danielebarchiesi@2:   // Handle 'none'.
danielebarchiesi@2:   if ($captcha_type == 'none') {
danielebarchiesi@2:     db_merge('captcha_points')
danielebarchiesi@2:       ->key(array('form_id' => $form_id))
danielebarchiesi@2:       ->fields(array('module' => NULL, 'captcha_type' => NULL))
danielebarchiesi@2:       ->execute();
danielebarchiesi@2:   }
danielebarchiesi@2:   // Handle 'default'.
danielebarchiesi@2:   elseif ($captcha_type == 'default') {
danielebarchiesi@2:     db_merge('captcha_points')
danielebarchiesi@2:       ->key(array('form_id' => $form_id))
danielebarchiesi@2:       ->fields(array('module' => NULL, 'captcha_type' => 'default'))
danielebarchiesi@2:       ->execute();
danielebarchiesi@2:   }
danielebarchiesi@2:   // Handle NULL.
danielebarchiesi@2:   elseif ($captcha_type == NULL) {
danielebarchiesi@2:     db_delete('captcha_points')->condition('form_id', $form_id)->execute();
danielebarchiesi@2:   }
danielebarchiesi@2:   // Handle a captcha_type object.
danielebarchiesi@2:   elseif (is_object($captcha_type) && isset($captcha_type->module) && isset($captcha_type->captcha_type)) {
danielebarchiesi@2:     db_merge('captcha_points')
danielebarchiesi@2:       ->key(array('form_id' => $form_id))
danielebarchiesi@2:       ->fields(array('module' => $captcha_type->module, 'captcha_type' => $captcha_type->captcha_type))
danielebarchiesi@2:       ->execute();
danielebarchiesi@2:   }
danielebarchiesi@2:   // Handle a captcha_type string.
danielebarchiesi@2:   elseif (is_string($captcha_type) && substr_count($captcha_type, '/') == 1) {
danielebarchiesi@2:     list($module, $type) = explode('/', $captcha_type);
danielebarchiesi@2:     db_merge('captcha_points')
danielebarchiesi@2:       ->key(array('form_id' => $form_id))
danielebarchiesi@2:       ->fields(array('module' => $module, 'captcha_type' => $type))
danielebarchiesi@2:       ->execute();
danielebarchiesi@2:   }
danielebarchiesi@2:   else {
danielebarchiesi@2:     drupal_set_message(t('Failed to set a CAPTCHA type for form %form_id: could not interpret value "@captcha_type"',
danielebarchiesi@2:       array('%form_id' => $form_id, '@captcha_type' => (string)$captcha_type)), 'warning');
danielebarchiesi@2:   }
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Get the CAPTCHA setting for a given form_id.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @param $form_id the form_id to query for
danielebarchiesi@2:  * @param $symbolic flag to return as (symbolic) strings instead of object.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @return NULL if no setting is known
danielebarchiesi@2:  *   or a captcha_point object with fields 'module' and 'captcha_type'.
danielebarchiesi@2:  *   If argument $symbolic is true, returns (symbolic) as 'none', 'default'
danielebarchiesi@2:  *   or in the form 'captcha/Math'.
danielebarchiesi@2:  */
danielebarchiesi@2: function captcha_get_form_id_setting($form_id, $symbolic=FALSE) {
danielebarchiesi@2:   $result = db_query("SELECT module, captcha_type FROM {captcha_points} WHERE form_id = :form_id",
danielebarchiesi@2:     array(':form_id' =>  $form_id));
danielebarchiesi@2:   $captcha_point = $result->fetchObject();
danielebarchiesi@2:   if (!$captcha_point) {
danielebarchiesi@2:     $captcha_point = NULL;
danielebarchiesi@2:   }
danielebarchiesi@2:   elseif ($captcha_point->captcha_type == 'default') {
danielebarchiesi@2:     if (!$symbolic) {
danielebarchiesi@2:       list($module, $type) = explode('/', variable_get('captcha_default_challenge', 'captcha/Math'));
danielebarchiesi@2:       $captcha_point->module = $module;
danielebarchiesi@2:       $captcha_point->captcha_type = $type;
danielebarchiesi@2:     }
danielebarchiesi@2:     else {
danielebarchiesi@2:       $captcha_point = 'default';
danielebarchiesi@2:     }
danielebarchiesi@2:   }
danielebarchiesi@2:   elseif ($captcha_point->module == NULL && $captcha_point->captcha_type == NULL && $symbolic) {
danielebarchiesi@2:     $captcha_point = 'none';
danielebarchiesi@2:   }
danielebarchiesi@2:   elseif ($symbolic) {
danielebarchiesi@2:     $captcha_point = $captcha_point->module . '/' . $captcha_point->captcha_type;
danielebarchiesi@2:   }
danielebarchiesi@2:   return $captcha_point;
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function for generating a new CAPTCHA session.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @param $form_id the form_id of the form to add a CAPTCHA to.
danielebarchiesi@2:  * @param $status the initial status of the CAPTHCA session.
danielebarchiesi@2:  * @return the session ID of the new CAPTCHA session.
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_generate_captcha_session($form_id=NULL, $status=CAPTCHA_STATUS_UNSOLVED) {
danielebarchiesi@2:   global $user;
danielebarchiesi@2:   // Initialize solution with random data.
danielebarchiesi@2:   $solution = md5(mt_rand());
danielebarchiesi@2:   // Insert an entry and thankfully receive the value of the autoincrement field 'csid'.
danielebarchiesi@2:   $captcha_sid = db_insert('captcha_sessions')
danielebarchiesi@2:   ->fields(array(
danielebarchiesi@2:     'uid' => $user->uid,
danielebarchiesi@2:     'sid' => session_id(),
danielebarchiesi@2:     'ip_address' => ip_address(),
danielebarchiesi@2:     'timestamp' => REQUEST_TIME,
danielebarchiesi@2:     'form_id' => $form_id,
danielebarchiesi@2:     'solution' => $solution,
danielebarchiesi@2:     'status' => $status,
danielebarchiesi@2:     'attempts' => 0,
danielebarchiesi@2:   ))
danielebarchiesi@2:   ->execute();
danielebarchiesi@2:   return $captcha_sid;
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function for updating the solution in the CAPTCHA session table.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @param $captcha_sid the CAPTCHA session ID to update.
danielebarchiesi@2:  * @param $solution the new solution to associate with the given CAPTCHA session.
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_update_captcha_session($captcha_sid, $solution) {
danielebarchiesi@2:   db_update('captcha_sessions')
danielebarchiesi@2:     ->condition('csid', $captcha_sid)
danielebarchiesi@2:     ->fields(array(
danielebarchiesi@2:       'timestamp' => REQUEST_TIME,
danielebarchiesi@2:       'solution' => $solution,
danielebarchiesi@2:     ))
danielebarchiesi@2:     ->execute();
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function for checking if CAPTCHA is required for user,
danielebarchiesi@2:  * based on the CAPTCHA persistence setting, the CAPTCHA session ID and
danielebarchiesi@2:  * user session info.
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_required_for_user($captcha_sid, $form_id) {
danielebarchiesi@2:   // Get the CAPTCHA persistence setting.
danielebarchiesi@2:   $captcha_persistence = variable_get('captcha_persistence', CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM_INSTANCE);
danielebarchiesi@2: 
danielebarchiesi@2:   // First check: should we always add a CAPTCHA?
danielebarchiesi@2:   if ($captcha_persistence == CAPTCHA_PERSISTENCE_SHOW_ALWAYS) {
danielebarchiesi@2:     return TRUE;
danielebarchiesi@2:   }
danielebarchiesi@2: 
danielebarchiesi@2:   // Get the status of the current CAPTCHA session.
danielebarchiesi@2:   $captcha_session_status = db_query('SELECT status FROM {captcha_sessions} WHERE csid = :csid', array(':csid' => $captcha_sid))->fetchField();
danielebarchiesi@2:   // Second check: if the current session is already solved: omit further CAPTCHAs.
danielebarchiesi@2:   if ($captcha_session_status == CAPTCHA_STATUS_SOLVED) {
danielebarchiesi@2:     return FALSE;
danielebarchiesi@2:   }
danielebarchiesi@2: 
danielebarchiesi@2:   // Third check: look at the persistence level (per form instance, per form or per user).
danielebarchiesi@2:   if ($captcha_persistence == CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM_INSTANCE) {
danielebarchiesi@2:     return TRUE;
danielebarchiesi@2:   }
danielebarchiesi@2:   else {
danielebarchiesi@2:     $captcha_success_form_ids = isset($_SESSION['captcha_success_form_ids']) ? (array)($_SESSION['captcha_success_form_ids']) : array();
danielebarchiesi@2:     switch ($captcha_persistence) {
danielebarchiesi@2:       case CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL:
danielebarchiesi@2:         return (count($captcha_success_form_ids) == 0);
danielebarchiesi@2:       case CAPTCHA_PERSISTENCE_SKIP_ONCE_SUCCESSFUL_PER_FORM_TYPE:
danielebarchiesi@2:         return !isset($captcha_success_form_ids[$form_id]);
danielebarchiesi@2:     }
danielebarchiesi@2:   }
danielebarchiesi@2: 
danielebarchiesi@2:   // We should never get to this point, but to be sure, we return TRUE.
danielebarchiesi@2:   return TRUE;
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Get the CAPTCHA description as configured on the general CAPTCHA
danielebarchiesi@2:  * settings page.
danielebarchiesi@2:  *
danielebarchiesi@2:  * If the locale module is enabled, the description will be returned
danielebarchiesi@2:  * for the current language the page is rendered for. This language
danielebarchiesi@2:  * can optionally been overriden with the $lang_code argument.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @param $lang_code an optional language code to get the descripion for.
danielebarchiesi@2:  * @return a string with (localized) CAPTCHA description.
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_get_description($lang_code=NULL) {
danielebarchiesi@2:   // If no language code is given: use the language of the current page.
danielebarchiesi@2:   global $language;
danielebarchiesi@2:   $lang_code = isset($lang_code) ? $lang_code : $language->language;
danielebarchiesi@2:   // The hardcoded but localizable default.
danielebarchiesi@2:   $default = t('This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.', array(), array('langcode' => $lang_code));
danielebarchiesi@2:   // Look up the configured CAPTCHA description or fall back on the (localized) default.
danielebarchiesi@2:   if (module_exists('locale')) {
danielebarchiesi@2:     $description = variable_get("captcha_description_$lang_code", $default);
danielebarchiesi@2:   }
danielebarchiesi@2:   else {
danielebarchiesi@2:     $description = variable_get('captcha_description', $default);
danielebarchiesi@2:   }
danielebarchiesi@2:   return filter_xss_admin($description);
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Parse or interpret the given captcha_type.
danielebarchiesi@2:  * @param $captcha_type string representation of the CAPTCHA type,
danielebarchiesi@2:  *      e.g. 'default', 'none', 'captcha/Math', 'image_captcha/Image'
danielebarchiesi@2:  * @return list($captcha_module, $captcha_type)
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_parse_captcha_type($captcha_type) {
danielebarchiesi@2:   if ($captcha_type == 'none') {
danielebarchiesi@2:     return array(NULL, NULL);
danielebarchiesi@2:   }
danielebarchiesi@2:   if ($captcha_type == 'default') {
danielebarchiesi@2:     $captcha_type = variable_get('captcha_default_challenge', 'captcha/Math');
danielebarchiesi@2:   }
danielebarchiesi@2:   return explode('/', $captcha_type);
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function to get placement information for a given form_id.
danielebarchiesi@2:  * @param $form_id the form_id to get the placement information for.
danielebarchiesi@2:  * @param $form if a form corresponding to the given form_id, if there
danielebarchiesi@2:  *   is no placement info for the given form_id, this form is examined to
danielebarchiesi@2:  *   guess the placement.
danielebarchiesi@2:  * @return placement info array (@see _captcha_insert_captcha_element() for more
danielebarchiesi@2:  *   info about the fields 'path', 'key' and 'weight'.
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_get_captcha_placement($form_id, $form) {
danielebarchiesi@2:   // Get CAPTCHA placement map from cache. Two levels of cache:
danielebarchiesi@2:   // static variable in this function and storage in the variables table.
danielebarchiesi@2:   static $placement_map = NULL;
danielebarchiesi@2:   // Try first level cache.
danielebarchiesi@2:   if ($placement_map === NULL) {
danielebarchiesi@2:     // If first level cache missed: try second level cache.
danielebarchiesi@2:     $placement_map = variable_get('captcha_placement_map_cache', NULL);
danielebarchiesi@2: 
danielebarchiesi@2:     if ($placement_map === NULL) {
danielebarchiesi@2:       // If second level cache missed: initialize the placement map
danielebarchiesi@2:       // and let other modules hook into this with the hook_captcha_placement_map hook.
danielebarchiesi@2:       // By default however, probably all Drupal core forms are already correctly
danielebarchiesi@2:       // handled with the best effort guess based on the 'actions' element (see below).
danielebarchiesi@2:       $placement_map = module_invoke_all('captcha_placement_map');
danielebarchiesi@2:     }
danielebarchiesi@2:   }
danielebarchiesi@2: 
danielebarchiesi@2:   // Query the placement map.
danielebarchiesi@2:   if (array_key_exists($form_id, $placement_map)) {
danielebarchiesi@2:     $placement = $placement_map[$form_id];
danielebarchiesi@2:   }
danielebarchiesi@2:   // If no placement info is available in placement map: make a best effort guess.
danielebarchiesi@2:   else {
danielebarchiesi@2:     // If there is an "actions" button group, a good placement is just before that.
danielebarchiesi@2:     if (isset($form['actions']) && isset($form['actions']['#type']) && $form['actions']['#type'] === 'actions') {
danielebarchiesi@2:       $placement = array(
danielebarchiesi@2:         'path' => array(),
danielebarchiesi@2:         'key' => 'actions',
danielebarchiesi@2:         // #type 'actions' defaults to 100.
danielebarchiesi@2:         'weight' => (isset($form['actions']['#weight']) ? $form['actions']['#weight'] - 1 : 99),
danielebarchiesi@2:       );
danielebarchiesi@2:     }
danielebarchiesi@2:     else {
danielebarchiesi@2:       // Search the form for buttons and guess placement from it.
danielebarchiesi@2:       $buttons = _captcha_search_buttons($form);
danielebarchiesi@2:       if (count($buttons)) {
danielebarchiesi@2:         // Pick first button.
danielebarchiesi@2:         // TODO: make this more sofisticated? Use cases needed.
danielebarchiesi@2:         $placement = $buttons[0];
danielebarchiesi@2:       }
danielebarchiesi@2:       else {
danielebarchiesi@2:         // Use NULL when no buttons were found.
danielebarchiesi@2:         $placement = NULL;
danielebarchiesi@2:       }
danielebarchiesi@2:     }
danielebarchiesi@2: 
danielebarchiesi@2:     // Store calculated placement in cache.
danielebarchiesi@2:     $placement_map[$form_id] = $placement;
danielebarchiesi@2:     variable_set('captcha_placement_map_cache', $placement_map);
danielebarchiesi@2:   }
danielebarchiesi@2: 
danielebarchiesi@2:   return $placement;
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function for searching the buttons in a form.
danielebarchiesi@2:  *
danielebarchiesi@2:  * @param $form the form to search button elements in
danielebarchiesi@2:  * @return an array of paths to the buttons.
danielebarchiesi@2:  *   A path is an array of keys leading to the button, the last
danielebarchiesi@2:  *   item in the path is the weight of the button element
danielebarchiesi@2:  *   (or NULL if undefined).
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_search_buttons($form) {
danielebarchiesi@2:   $buttons = array();
danielebarchiesi@2:   foreach (element_children($form) as $key) {
danielebarchiesi@2:     // Look for submit or button type elements.
danielebarchiesi@2:     if (isset($form[$key]['#type']) && ($form[$key]['#type'] == 'submit' || $form[$key]['#type'] == 'button')) {
danielebarchiesi@2:       $weight = isset($form[$key]['#weight']) ? $form[$key]['#weight'] : NULL;
danielebarchiesi@2:       $buttons[] = array(
danielebarchiesi@2:         'path' => array(),
danielebarchiesi@2:         'key' => $key,
danielebarchiesi@2:         'weight' => $weight,
danielebarchiesi@2:       );
danielebarchiesi@2:     }
danielebarchiesi@2:     // Process children recurively.
danielebarchiesi@2:     $children_buttons = _captcha_search_buttons($form[$key]);
danielebarchiesi@2:     foreach ($children_buttons as $b) {
danielebarchiesi@2:       $b['path'] = array_merge(array($key), $b['path']);
danielebarchiesi@2:       $buttons[] = $b;
danielebarchiesi@2:     }
danielebarchiesi@2:   }
danielebarchiesi@2:   return $buttons;
danielebarchiesi@2: }
danielebarchiesi@2: 
danielebarchiesi@2: /**
danielebarchiesi@2:  * Helper function to insert a CAPTCHA element in a form before a given form element.
danielebarchiesi@2:  * @param $form the form to add the CAPTCHA element to.
danielebarchiesi@2:  * @param $placement information where the CAPTCHA element should be inserted.
danielebarchiesi@2:  *   $placement should be an associative array with fields:
danielebarchiesi@2:  *     - 'path': path (array of path items) of the container in the form where the
danielebarchiesi@2:  *       CAPTCHA element should be inserted.
danielebarchiesi@2:  *     - 'key': the key of the element before which the CAPTCHA element
danielebarchiesi@2:  *       should be inserted. If the field 'key' is undefined or NULL, the CAPTCHA will
danielebarchiesi@2:  *       just be appended in the container.
danielebarchiesi@2:  *     - 'weight': if 'key' is not NULL: should be the weight of the element defined by 'key'.
danielebarchiesi@2:  *       If 'key' is NULL and weight is not NULL: set the weight property of the CAPTCHA element
danielebarchiesi@2:  *       to this value.
danielebarchiesi@2:  * @param $captcha_element the CAPTCHA element to insert.
danielebarchiesi@2:  */
danielebarchiesi@2: function _captcha_insert_captcha_element(&$form, $placement, $captcha_element) {
danielebarchiesi@2:   // Get path, target and target weight or use defaults if not available.
danielebarchiesi@2:   $target_key = isset($placement['key']) ? $placement['key'] : NULL;
danielebarchiesi@2:   $target_weight = isset($placement['weight']) ? $placement['weight'] : NULL;
danielebarchiesi@2:   $path = isset($placement['path']) ? $placement['path'] : array();
danielebarchiesi@2: 
danielebarchiesi@2:   // Walk through the form along the path.
danielebarchiesi@2:   $form_stepper = &$form;
danielebarchiesi@2:   foreach ($path as $step) {
danielebarchiesi@2:     if (isset($form_stepper[$step])) {
danielebarchiesi@2:       $form_stepper = & $form_stepper[$step];
danielebarchiesi@2:     }
danielebarchiesi@2:     else {
danielebarchiesi@2:       // Given path is invalid: stop stepping and
danielebarchiesi@2:       // continue in best effort (append instead of insert).
danielebarchiesi@2:       $target_key = NULL;
danielebarchiesi@2:       break;
danielebarchiesi@2:     }
danielebarchiesi@2:   }
danielebarchiesi@2: 
danielebarchiesi@2:   // If no target is available: just append the CAPTCHA element to the container.
danielebarchiesi@2:   if ($target_key == NULL || !array_key_exists($target_key, $form_stepper)) {
danielebarchiesi@2:     // Optionally, set weight of CAPTCHA element.
danielebarchiesi@2:     if ($target_weight != NULL) {
danielebarchiesi@2:       $captcha_element['#weight'] = $target_weight;
danielebarchiesi@2:     }
danielebarchiesi@2:     $form_stepper['captcha'] =  $captcha_element;
danielebarchiesi@2:   }
danielebarchiesi@2:   // If there is a target available: make sure the CAPTCHA element comes right before it.
danielebarchiesi@2:   else {
danielebarchiesi@2:     // If target has a weight: set weight of CAPTCHA element a bit smaller
danielebarchiesi@2:     // and just append the CAPTCHA: sorting will fix the ordering anyway.
danielebarchiesi@2:     if ($target_weight != NULL) {
danielebarchiesi@2:       $captcha_element['#weight'] = $target_weight - .1;
danielebarchiesi@2:       $form_stepper['captcha'] =  $captcha_element;
danielebarchiesi@2:     }
danielebarchiesi@2:     else {
danielebarchiesi@2:       // If we can't play with weights: insert the CAPTCHA element at the right position.
danielebarchiesi@2:       // Because PHP lacks a function for this (array_splice() comes close,
danielebarchiesi@2:       // but it does not preserve the key of the inserted element), we do it by hand:
danielebarchiesi@2:       // chop of the end, append the CAPTCHA element and put the end back.
danielebarchiesi@2:       $offset = array_search($target_key, array_keys($form_stepper));
danielebarchiesi@2:       $end = array_splice($form_stepper, $offset);
danielebarchiesi@2:       $form_stepper['captcha'] =  $captcha_element;
danielebarchiesi@2:       foreach ($end as $k => $v) {
danielebarchiesi@2:         $form_stepper[$k] = $v;
danielebarchiesi@2:       }
danielebarchiesi@2:     }
danielebarchiesi@2:   }
danielebarchiesi@2: }
danielebarchiesi@2: