aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Flood/FloodInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Flood;
   4
   5 /**
   6  * Defines an interface for flood controllers.
   7  */
   8 interface FloodInterface {
   9
  10   /**
  11    * Registers an event for the current visitor to the flood control mechanism.
  12    *
  13    * @param string $name
  14    *   The name of an event. To prevent unintended name clashes, it is recommended
  15    *   to use the module name first in the event name, optionally followed by
  16    *   a dot and the actual event name (e.g. "mymodule.my_event").
  17    * @param int $window
  18    *   (optional) Number of seconds before this event expires. Defaults to 3600
  19    *   (1 hour). Typically uses the same value as the isAllowed() $window
  20    *   parameter. Expired events are purged on cron run to prevent the flood
  21    *   table from growing indefinitely.
  22    * @param string $identifier
  23    *   (optional) Unique identifier of the current user. Defaults to the current
  24    *   user's IP address).
  25    */
  26   public function register($name, $window = 3600, $identifier = NULL);
  27
  28   /**
  29    * Makes the flood control mechanism forget an event for the current visitor.
  30    *
  31    * @param string $name
  32    *   The name of an event.
  33    * @param string $identifier
  34    *   (optional) Unique identifier of the current user. Defaults to the current
  35    *   user's IP address).
  36    */
  37   public function clear($name, $identifier = NULL);
  38
  39   /**
  40    * Checks whether a user is allowed to proceed with the specified event.
  41    *
  42    * Events can have thresholds saying that each user can only do that event
  43    * a certain number of times in a time window. This function verifies that
  44    * the current user has not exceeded this threshold.
  45    *
  46    * @param string $name
  47    *   The name of an event.
  48    * @param int $threshold
  49    *   The maximum number of times each user can do this event per time window.
  50    * @param int $window
  51    *   (optional) Number of seconds in the time window for this event (default is 3600
  52    *   seconds, or 1 hour).
  53    * @param string $identifier
  54    *   (optional) Unique identifier of the current user. Defaults to the current
  55    *   user's IP address).
  56    *
  57    * @return
  58    *   TRUE if the user is allowed to proceed. FALSE if they have exceeded the
  59    *   threshold and should not be allowed to proceed.
  60    */
  61   public function isAllowed($name, $threshold, $window = 3600, $identifier = NULL);
  62
  63   /**
  64    * Cleans up expired flood events. This method is called automatically on
  65    * cron run.
  66    *
  67    * @see system_cron()
  68    */
  69   public function garbageCollection();
  70
  71 }