Document new flood control API (#101)

* Document new flood control API

Close #95

* Improve flood control API documentation

Co-authored-by: Tim Düsterhus <duesterhus@woltlab.com>
Co-authored-by: Tim Düsterhus <duesterhus@woltlab.com>

diff --git a/_data/sidebars/sidebar.yml b/_data/sidebars/sidebar.yml
index d4a3548db2d62453aa53baf4d486eb8b73e0c0bc..6f4c4b81fc098e6c211352e1ee3af2ce206ded73 100644 (file)
--- 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 (file)
index 0000000..2cac146
--- /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" %}