From f64d43c9d65fc9b6e99386c86d6ff8b9450eb960 Mon Sep 17 00:00:00 2001 From: Matthias Schmidt Date: Mon, 2 Nov 2020 13:37:27 +0100 Subject: [PATCH] Document new flood control API (#101) MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * Document new flood control API Close #95 * Improve flood control API documentation Co-authored-by: Tim Düsterhus Co-authored-by: Tim Düsterhus --- _data/sidebars/sidebar.yml | 2 + .../migration/wsc-53/migration_wsc-53_php.md | 40 +++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 pages/migration/wsc-53/migration_wsc-53_php.md diff --git a/_data/sidebars/sidebar.yml b/_data/sidebars/sidebar.yml index d4a3548d..6f4c4b81 100644 --- a/_data/sidebars/sidebar.yml +++ b/_data/sidebars/sidebar.yml @@ -122,6 +122,8 @@ entries: - title: Migrating from WSC 5.3 subfolderitems: + - title: PHP API + url: /migration_wsc-53_php.html - title: JavaScript url: /migration_wsc-53_javascript.html - title: Templates diff --git a/pages/migration/wsc-53/migration_wsc-53_php.md b/pages/migration/wsc-53/migration_wsc-53_php.md new file mode 100644 index 00000000..2cac1467 --- /dev/null +++ b/pages/migration/wsc-53/migration_wsc-53_php.md @@ -0,0 +1,40 @@ +--- +title: Migrating from WSC 5.3 - PHP +sidebar: sidebar +permalink: migration_wsc-53_php.html +folder: migration/wsc-53 +--- + +## Flood Control + +To prevent users from creating massive amounts of contents in short periods of time, i.e., spam, existing systems already use flood control mechanisms to limit the amount of contents created within a certain period of time. +With WoltLab Suite 5.4, we have added a general API that manages such rate limiting. +Leveraging this API is easily done. + +1. Register an object type for the definition `com.woltlab.wcf.floodControl`: `com.example.foo.myContent`. +2. Whenever the active user creates content of this type, call + ```php + FloodControl::getInstance()->registerContent('com.example.foo.myContent'); + ``` + You should only call this method if the user creates the content themselves. + If the content is automatically created by the system, for example when copying / duplicating existing content, no activity should be registered. +3. To check the last time when the active user created content of the relevant type, use + ```php + FloodControl::getInstance()->getLastTime('com.example.foo.myContent'); + ``` + If you want to limit the number of content items created within a certain period of time, for example within one day, use + ```php + $data = FloodControl::getInstance()->countContent('com.example.foo.myContent', new \DateInterval('P1D')); + // number of content items created within the last day + $count = $data['count']; + // timestamp when the earliest content item was created within the last day + $earliestTime = $data['earliestTime']; + ``` + The method also returns `earliestTime` so that you can tell the user in the error message when they are able again to create new content of the relevant type. + {% include callout.html content="Flood control entries are only stored for 31 days and older entries are cleaned up daily." type="info" %} + +The previously mentioned methods of `FloodControl` use the active user and the current timestamp as reference point. +`FloodControl` also provides methods to register content or check flood control for other registered users or for guests via their IP address. +For further details on these methods, please refer to the [documentation in the FloodControl class](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/flood/FloodControl.class.php). + +{% include callout.html content="Do not interact directly with the flood control database table but only via the `FloodControl` class!" type="warning" %} -- 2.20.1