3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
21 use MediaWiki\Linker\LinkTarget
;
25 * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
27 interface WatchedItemStoreInterface
{
32 const SORT_ASC
= 'ASC';
37 const SORT_DESC
= 'DESC';
40 * Count the number of individual items that are watched by the user.
41 * If a subject and corresponding talk page are watched this will return 2.
49 public function countWatchedItems( User
$user );
54 * @param LinkTarget $target
58 public function countWatchers( LinkTarget
$target );
61 * Number of page watchers who also visited a "recent" edit
65 * @param LinkTarget $target
66 * @param mixed $threshold timestamp accepted by wfTimestamp
69 * @throws DBUnexpectedError
72 public function countVisitingWatchers( LinkTarget
$target, $threshold );
77 * @param LinkTarget[] $targets
78 * @param array $options Allowed keys:
79 * 'minimumWatchers' => int
81 * @return array multi dimensional like $return[$namespaceId][$titleString] = int $watchers
82 * All targets will be present in the result. 0 either means no watchers or the number
83 * of watchers was below the minimumWatchers option if passed.
85 public function countWatchersMultiple( array $targets, array $options = [] );
88 * Number of watchers of each page who have visited recent edits to that page
92 * @param array $targetsWithVisitThresholds array of pairs (LinkTarget $target, mixed
95 * - a timestamp of the recent edit if $target exists (format accepted by wfTimestamp)
96 * - null if $target doesn't exist
97 * @param int|null $minimumWatchers
99 * @return array multi-dimensional like $return[$namespaceId][$titleString] = $watchers,
100 * where $watchers is an int:
101 * - if the page exists, number of users watching who have visited the page recently
102 * - if the page doesn't exist, number of users that have the page on their watchlist
103 * - 0 means there are no visiting watchers or their number is below the
105 * option (if passed).
107 public function countVisitingWatchersMultiple(
108 array $targetsWithVisitThresholds,
109 $minimumWatchers = null
113 * Get an item (may be cached)
118 * @param LinkTarget $target
120 * @return WatchedItem|false
122 public function getWatchedItem( User
$user, LinkTarget
$target );
125 * Loads an item from the db
130 * @param LinkTarget $target
132 * @return WatchedItem|false
134 public function loadWatchedItem( User
$user, LinkTarget
$target );
140 * @param array $options Allowed keys:
141 * 'forWrite' => bool defaults to false
142 * 'sort' => string optional sorting by namespace ID and title
143 * one of the self::SORT_* constants
145 * @return WatchedItem[]
147 public function getWatchedItemsForUser( User
$user, array $options = [] );
150 * Must be called separately for Subject & Talk namespaces
155 * @param LinkTarget $target
159 public function isWatched( User
$user, LinkTarget
$target );
165 * @param LinkTarget[] $targets
167 * @return array multi-dimensional like $return[$namespaceId][$titleString] = $timestamp,
168 * where $timestamp is:
169 * - string|null value of wl_notificationtimestamp,
170 * - false if $target is not watched by $user.
172 public function getNotificationTimestampsBatch( User
$user, array $targets );
175 * Must be called separately for Subject & Talk namespaces
180 * @param LinkTarget $target
182 public function addWatch( User
$user, LinkTarget
$target );
188 * @param LinkTarget[] $targets
190 * @return bool success
192 public function addWatchBatchForUser( User
$user, array $targets );
195 * Removes the an entry for the User watching the LinkTarget
196 * Must be called separately for Subject & Talk namespaces
201 * @param LinkTarget $target
203 * @return bool success
204 * @throws DBUnexpectedError
205 * @throws MWException
207 public function removeWatch( User
$user, LinkTarget
$target );
212 * @param User $user The user to set the timestamp for
213 * @param string|null $timestamp Set the update timestamp to this value
214 * @param LinkTarget[] $targets List of targets to update. Default to all targets
216 * @return bool success
218 public function setNotificationTimestampsForUser(
227 * @param User $editor The editor that triggered the update. Their notification
228 * timestamp will not be updated(they have already seen it)
229 * @param LinkTarget $target The target to update timestamps for
230 * @param string $timestamp Set the update timestamp to this value
232 * @return int[] Array of user IDs the timestamp has been updated for
234 public function updateNotificationTimestamp( User
$editor, LinkTarget
$target, $timestamp );
237 * Reset the notification timestamp of this entry
242 * @param Title $title
243 * @param string $force Whether to force the write query to be executed even if the
244 * page is not watched or the notification timestamp is already NULL.
245 * 'force' in order to force
246 * @param int $oldid The revision id being viewed. If not given or 0, latest revision is
249 * @return bool success
251 public function resetNotificationTimestamp( User
$user, Title
$title, $force = '', $oldid = 0 );
257 * @param int $unreadLimit
259 * @return int|bool The number of unread notifications
260 * true if greater than or equal to $unreadLimit
262 public function countUnreadNotifications( User
$user, $unreadLimit = null );
265 * Check if the given title already is watched by the user, and if so
266 * add a watch for the new title.
268 * To be used for page renames and such.
272 * @param LinkTarget $oldTarget
273 * @param LinkTarget $newTarget
275 public function duplicateAllAssociatedEntries( LinkTarget
$oldTarget, LinkTarget
$newTarget );
278 * Check if the given title already is watched by the user, and if so
279 * add a watch for the new title.
281 * To be used for page renames and such.
282 * This must be called separately for Subject and Talk pages
286 * @param LinkTarget $oldTarget
287 * @param LinkTarget $newTarget
289 public function duplicateEntry( LinkTarget
$oldTarget, LinkTarget
$newTarget );
292 * Queues a job that will clear the users watchlist using the Job Queue.
298 public function clearUserWatchedItems( User
$user );
301 * Queues a job that will clear the users watchlist using the Job Queue.
307 public function clearUserWatchedItemsUsingJobQueue( User
$user );