honeypot.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  *
   6  * API Functionality for Honeypot module.
   7  */
   8
   9 /**
  10  * @addtogroup hooks
  11  * @{
  12  */
  13
  14 /**
  15  * Alter the honeypot protections added to a particular form.
  16  *
  17  * @param (array) $options
  18  *   Protections that will be applied to the form. May be empty, or may include
  19  *   'honeypot' and/or 'time_restriction'.
  20  * @param (array) $form
  21  *   The Form API form to which protections will be added.
  22  */
  23 function hook_honeypot_form_protections_alter(&$options, $form) {
  24   // Add 'time_restriction' protection to 'mymodule-form' if it's not set.
  25   if ($form['form_id']['#value'] == 'mymodule_form' && !in_array('time_restriction', $options)) {
  26     $options[] = 'time_restriction';
  27   }
  28 }
  29
  30 /**
  31  * React to an addition of honeypot form protections for a given form_id.
  32  *
  33  * After honeypot has added its protections to a form, this hook will be called.
  34  * You can use this hook to track when and how many times certain protected
  35  * forms are displayed to certain users, or for other tracking purposes.
  36  *
  37  * @param (array) $options
  38  *   Protections that were applied to the form. Includes 'honeypot' and/or
  39  *   'time_restriction'.
  40  * @param (array) $form
  41  *   The Form API form to which protections were added.
  42  */
  43 function hook_honeypot_add_form_protection($options, $form) {
  44   if ($form['form_id']['#value'] == 'mymodule_form') {
  45     // Do something...
  46   }
  47 }
  48
  49 /**
  50  * React to the rejection of a form submission.
  51  *
  52  * When honeypot rejects a form submission, it calls this hook with the form ID
  53  * and the user ID (0 if anonymous) of the user that was disallowed from
  54  * submitting the form.
  55  *
  56  * @param (string) $form_id
  57  *   Form ID of the form the user was disallowed from submitting.
  58  * @param (int) $uid
  59  *   0 for anonymous users, otherwise the user ID of the user.
  60  */
  61 function hook_honeypot_reject($form_id, $uid) {
  62   if ($form_id == 'mymodule_form') {
  63     // Do something...
  64   }
  65 }
  66
  67 /**
  68  * Add time to the Honeypot time limit.
  69  *
  70  * In certain circumstances (for example, on forms routinely targeted by
  71  * spammers), you may want to add an additional time delay. You can use this
  72  * hook to return additional time (in seconds) to honeypot when it is calculates
  73  * the time limit for a particular form.
  74  *
  75  * @param (int) $honeypot_time_limit
  76  *   The current honeypot time limit (in seconds), to which any additions you
  77  *   return will be added.
  78  * @param (array) $form_values
  79  *   Array of form values (may be empty).
  80  * @param (int) $number
  81  *   Number of times the current user has already fallen into the honeypot trap.
  82  *
  83  * @return (int) $additions
  84  *   Additional time to add to the honeypot_time_limit, in seconds (integer).
  85  */
  86 function hook_honeypot_time_limit($honeypot_time_limit, $form_values, $number) {
  87   $additions = 0;
  88   // If 'some_interesting_value' is set in your form, add 10 seconds to limit.
  89   if (!empty($form_values['some_interesting_value']) && $form_values['some_interesting_value']) {
  90     $additions = 10;
  91   }
  92   return $additions;
  93 }
  94
  95 /**
  96  * @} End of "addtogroup hooks".
  97  */