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
22 use MediaWiki\Linker\LinkTarget
;
23 use MediaWiki\User\UserIdentity
;
24 use Wikimedia\Rdbms\DBUnexpectedError
;
28 * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
30 interface WatchedItemStoreInterface
{
35 const SORT_ASC
= 'ASC';
40 const SORT_DESC
= 'DESC';
43 * Count the number of individual items that are watched by the user.
44 * If a subject and corresponding talk page are watched this will return 2.
48 * @param UserIdentity $user
52 public function countWatchedItems( UserIdentity
$user );
57 * @param LinkTarget $target
61 public function countWatchers( LinkTarget
$target );
64 * Number of page watchers who also visited a "recent" edit
68 * @param LinkTarget $target
69 * @param mixed $threshold timestamp accepted by wfTimestamp
72 * @throws DBUnexpectedError
75 public function countVisitingWatchers( LinkTarget
$target, $threshold );
80 * @param LinkTarget[] $targets
81 * @param array $options Allowed keys:
82 * 'minimumWatchers' => int
84 * @return array multi dimensional like $return[$namespaceId][$titleString] = int $watchers
85 * All targets will be present in the result. 0 either means no watchers or the number
86 * of watchers was below the minimumWatchers option if passed.
88 public function countWatchersMultiple( array $targets, array $options = [] );
91 * Number of watchers of each page who have visited recent edits to that page
95 * @param array $targetsWithVisitThresholds array of pairs (LinkTarget $target, mixed
98 * - a timestamp of the recent edit if $target exists (format accepted by wfTimestamp)
99 * - null if $target doesn't exist
100 * @param int|null $minimumWatchers
102 * @return array multi-dimensional like $return[$namespaceId][$titleString] = $watchers,
103 * where $watchers is an int:
104 * - if the page exists, number of users watching who have visited the page recently
105 * - if the page doesn't exist, number of users that have the page on their watchlist
106 * - 0 means there are no visiting watchers or their number is below the
108 * option (if passed).
110 public function countVisitingWatchersMultiple(
111 array $targetsWithVisitThresholds,
112 $minimumWatchers = null
116 * Get an item (may be cached)
120 * @param UserIdentity $user
121 * @param LinkTarget $target
123 * @return WatchedItem|false
125 public function getWatchedItem( UserIdentity
$user, LinkTarget
$target );
128 * Loads an item from the db
132 * @param UserIdentity $user
133 * @param LinkTarget $target
135 * @return WatchedItem|false
137 public function loadWatchedItem( UserIdentity
$user, LinkTarget
$target );
142 * @param UserIdentity $user
143 * @param array $options Allowed keys:
144 * 'forWrite' => bool defaults to false
145 * 'sort' => string optional sorting by namespace ID and title
146 * one of the self::SORT_* constants
148 * @return WatchedItem[]
150 public function getWatchedItemsForUser( UserIdentity
$user, array $options = [] );
153 * Must be called separately for Subject & Talk namespaces
157 * @param UserIdentity $user
158 * @param LinkTarget $target
162 public function isWatched( UserIdentity
$user, LinkTarget
$target );
167 * @param UserIdentity $user
168 * @param LinkTarget[] $targets
170 * @return array multi-dimensional like $return[$namespaceId][$titleString] = $timestamp,
171 * where $timestamp is:
172 * - string|null value of wl_notificationtimestamp,
173 * - false if $target is not watched by $user.
175 public function getNotificationTimestampsBatch( UserIdentity
$user, array $targets );
178 * Must be called separately for Subject & Talk namespaces
182 * @param UserIdentity $user
183 * @param LinkTarget $target
185 public function addWatch( UserIdentity
$user, LinkTarget
$target );
190 * @param UserIdentity $user
191 * @param LinkTarget[] $targets
193 * @return bool success
195 public function addWatchBatchForUser( UserIdentity
$user, array $targets );
198 * Removes an entry for the UserIdentity watching the LinkTarget
199 * Must be called separately for Subject & Talk namespaces
203 * @param UserIdentity $user
204 * @param LinkTarget $target
206 * @return bool success
207 * @throws DBUnexpectedError
208 * @throws MWException
210 public function removeWatch( UserIdentity
$user, LinkTarget
$target );
215 * @param UserIdentity $user The user to set the timestamps for
216 * @param string|null $timestamp Set the update timestamp to this value
217 * @param LinkTarget[] $targets List of targets to update. Default to all targets
219 * @return bool success
221 public function setNotificationTimestampsForUser(
228 * Reset all watchlist notificaton timestamps for a user using the job queue
232 * @param UserIdentity $user The user to reset the timestamps for
234 public function resetAllNotificationTimestampsForUser( UserIdentity
$user );
239 * @param UserIdentity $editor The editor that triggered the update. Their notification
240 * timestamp will not be updated(they have already seen it)
241 * @param LinkTarget $target The target to update timestamps for
242 * @param string $timestamp Set the update timestamp to this value
244 * @return int[] Array of user IDs the timestamp has been updated for
246 public function updateNotificationTimestamp(
247 UserIdentity
$editor, LinkTarget
$target, $timestamp );
250 * Reset the notification timestamp of this entry
254 * @param UserIdentity $user
255 * @param LinkTarget $title
256 * @param string $force Whether to force the write query to be executed even if the
257 * page is not watched or the notification timestamp is already NULL.
258 * 'force' in order to force
259 * @param int $oldid The revision id being viewed. If not given or 0, latest revision is
262 * @return bool success Whether a job was enqueued
264 public function resetNotificationTimestamp(
265 UserIdentity
$user, LinkTarget
$title, $force = '', $oldid = 0 );
270 * @param UserIdentity $user
271 * @param int|null $unreadLimit
273 * @return int|bool The number of unread notifications
274 * true if greater than or equal to $unreadLimit
276 public function countUnreadNotifications( UserIdentity
$user, $unreadLimit = null );
279 * Check if the given title already is watched by the user, and if so
280 * add a watch for the new title.
282 * To be used for page renames and such.
286 * @param LinkTarget $oldTarget
287 * @param LinkTarget $newTarget
289 public function duplicateAllAssociatedEntries( LinkTarget
$oldTarget, LinkTarget
$newTarget );
292 * Check if the given title already is watched by the user, and if so
293 * add a watch for the new title.
295 * To be used for page renames and such.
296 * This must be called separately for Subject and Talk pages
300 * @param LinkTarget $oldTarget
301 * @param LinkTarget $newTarget
303 public function duplicateEntry( LinkTarget
$oldTarget, LinkTarget
$newTarget );
306 * Queues a job that will clear the users watchlist using the Job Queue.
310 * @param UserIdentity $user
312 public function clearUserWatchedItems( UserIdentity
$user );
315 * Queues a job that will clear the users watchlist using the Job Queue.
319 * @param UserIdentity $user
321 public function clearUserWatchedItemsUsingJobQueue( UserIdentity
$user );
326 * @param UserIdentity $user
327 * @param LinkTarget[] $targets
329 * @return bool success
331 public function removeWatchBatchForUser( UserIdentity
$user, array $targets );
334 * Convert $timestamp to TS_MW or return null if the page was visited since then by $user
336 * Use this only on single-user methods (having higher read-after-write expectations)
337 * and not in places involving arbitrary batches of different users
339 * Usage of this method should be limited to WatchedItem* classes
341 * @param string|null $timestamp Value of wl_notificationtimestamp from the DB
342 * @param UserIdentity $user
343 * @param LinkTarget $target
344 * @return string|null TS_MW timestamp or null if all revision were seen
346 public function getLatestNotificationTimestamp(
347 $timestamp, UserIdentity
$user, LinkTarget
$target );