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