Add migration guide for board and thread subscriptions

diff --git a/docs/migration/wsc54/forum_subscriptions.md b/docs/migration/wsc54/forum_subscriptions.md
new file mode 100644 (file)
index 0000000..deed61e
--- /dev/null
+++ b/docs/migration/wsc54/forum_subscriptions.md
@@ -0,0 +1,98 @@
+# Migrating from WSC 5.4 - WoltLab Suite Forum
+
+## Subscriptions
+
+With WoltLab Suite Forum 5.5 we introduced a new system to subscribe threads and boards including the possibility to ignore threads and boards.
+[You can read more about this feature in our blog](https://www.woltlab.com/article/260-new-features-in-woltlab-suite-5-5-revision-of-buttons-and-ignoring-threads/).
+The new system uses an own system to manage the subscribed forums as well as the subscribed threads.
+This has made the previously used object type `com.woltlab.wcf.user.objectWatch` obsolete, as it no longer meets the requirements we need for the new more flexible system.
+In addition, having our own implementation also makes it much easier to use, as we work with our own tables and we can thus create correct foreign keys.
+Therefore, we had to create a new API to manage subscriptions.
+
+### Subscribe to threads
+
+#### Previously
+
+```php
+$action = new UserObjectWatchAction([], 'subscribe', [
+    'data' => [
+        'objectID' => $threadID,
+        'objectType' => 'com.woltlab.wbb.thread',
+    ]
+]);
+$action->executeAction();
+```
+
+#### Now
+```php
+ThreadStatusHandler::saveSubscriptionStatus(
+    $threadID,
+    ThreadStatusHandler::SUBSCRIPTION_MODE_WATCHING
+);
+```
+
+### Filter Ignored Threads
+
+To filter ignored threads from a given `ThreadList`, you can use the method `ThreadStatusHandler::addFilterForIgnoredThreads()` to append the filter for ignored threads.
+The `ViewableThreadList` filters ignored threads by default.
+
+As an example:
+
+```php
+$threadList = new ThreadList();
+ThreadStatusHandler::addFilterForIgnoredThreads(
+    $threadList,
+    // This parameter is optional. If null, the current user will be used. Otherwise, the filter is executed
+    // for the given user.
+    WCF::getUser()
+);
+$threadList->readObjects();
+```
+
+### Filter Ignored Users
+
+Ignoring threads should surpress the notifications for the user.
+Therefore we ship also a method, which can filter the `userIDs`, which are ignoring a specific thread.
+
+```php
+$userIDs = [1, 2, 3];
+$users = ThreadStatusHandler::filterIgnoredUserIDs(
+    $userIDs,
+    $thread->threadID
+);
+```
+
+### Subscribe to boards
+
+#### Previously
+
+```php
+$action = new UserObjectWatchAction([], 'subscribe', [
+    'data' => [
+        'objectID' => $boardID,
+        'objectType' => 'com.woltlab.wbb.board',
+    ]
+]);
+$action->executeAction();
+```
+
+#### Now
+```php
+BoardStatusHandler::saveSubscriptionStatus(
+    $boardID,
+    ThreadStatusHandler::SUBSCRIPTION_MODE_WATCHING
+);
+```
+
+### Filter Ignored Boards
+
+With the new system, notifications from ignored boards should be surpressed.
+Therefore, we introduced a method, which filters userIDs which ignoring a specific board.
+
+```php
+$userIDs = [1, 2, 3];
+$users = BoardStatusHandler::filterIgnoredUserIDs(
+    $userIDs,
+    $board->boardID
+);
+```
\ No newline at end of file

diff --git a/docs/migration/wsc54/php.md b/docs/migration/wsc54/php.md
index fbc7f11305a57cdf8608650f7a4e877026f3e4bd..55157152124fc112d2a2087077e86f2c391378c8 100644 (file)
--- a/docs/migration/wsc54/php.md
+++ b/docs/migration/wsc54/php.md
@@ -272,7 +272,7 @@ See [WoltLab/WCF#4398](https://github.com/WoltLab/WCF/pull/4398) for details.
 
 ### Search Form
 
-After the overhaul of the search form, search providers are no longer bound to `SearchForm` and `SearchResultPage`. 
+After the overhaul of the search form, search providers are no longer bound to `SearchForm` and `SearchResultPage`.
 The interface `ISearchObjectType` and the abstract implementation `AbstractSearchableObjectType` have been replaced by `ISearchProvider` and `AbstractSearchProvider`.
 
 Please use [`ArticleSearch`](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/search/ArticleSearch.class.php) as a template for your own implementation
@@ -337,7 +337,7 @@ is deprecated and should be replaced with the new structure with an explicit `<i
     filepath="migration/wsc54/en_new.xml",
 ) }}
 
-Additionally, to now also support deleting phrases with this package installation plugin, support for a `<delete>` element has been added: 
+Additionally, to now also support deleting phrases with this package installation plugin, support for a `<delete>` element has been added:
 
 {jinja{ codebox(
     language="xml",
@@ -349,6 +349,10 @@ Note that when deleting phrases, the category does not have to be specified beca
 
 !!! warning "Mixing the old structure and the new structure is not supported and will result in an error message during the import!"
 
+## Board and Thread Subscriptions
+
+See [here](form_subscriptions.md) for details.
+
 ## Miscellaneous Changes
 
 ### View Counters