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
;
22 use Wikimedia\Rdbms\DBUnexpectedError
;
26 * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
28 interface WatchedItemStoreInterface
{
33 const SORT_ASC
= 'ASC';
38 const SORT_DESC
= 'DESC';
41 * Count the number of individual items that are watched by the user.
42 * If a subject and corresponding talk page are watched this will return 2.
50 public function countWatchedItems( User
$user );
55 * @param LinkTarget $target
59 public function countWatchers( LinkTarget
$target );
62 * Number of page watchers who also visited a "recent" edit
66 * @param LinkTarget $target
67 * @param mixed $threshold timestamp accepted by wfTimestamp
70 * @throws DBUnexpectedError
73 public function countVisitingWatchers( LinkTarget
$target, $threshold );
78 * @param LinkTarget[] $targets
79 * @param array $options Allowed keys:
80 * 'minimumWatchers' => int
82 * @return array multi dimensional like $return[$namespaceId][$titleString] = int $watchers
83 * All targets will be present in the result. 0 either means no watchers or the number
84 * of watchers was below the minimumWatchers option if passed.
86 public function countWatchersMultiple( array $targets, array $options = [] );
89 * Number of watchers of each page who have visited recent edits to that page
93 * @param array $targetsWithVisitThresholds array of pairs (LinkTarget $target, mixed
96 * - a timestamp of the recent edit if $target exists (format accepted by wfTimestamp)
97 * - null if $target doesn't exist
98 * @param int|null $minimumWatchers
100 * @return array multi-dimensional like $return[$namespaceId][$titleString] = $watchers,
101 * where $watchers is an int:
102 * - if the page exists, number of users watching who have visited the page recently
103 * - if the page doesn't exist, number of users that have the page on their watchlist
104 * - 0 means there are no visiting watchers or their number is below the
106 * option (if passed).
108 public function countVisitingWatchersMultiple(
109 array $targetsWithVisitThresholds,
110 $minimumWatchers = null
114 * Get an item (may be cached)
119 * @param LinkTarget $target
121 * @return WatchedItem|false
123 public function getWatchedItem( User
$user, LinkTarget
$target );
126 * Loads an item from the db
131 * @param LinkTarget $target
133 * @return WatchedItem|false
135 public function loadWatchedItem( User
$user, LinkTarget
$target );
141 * @param array $options Allowed keys:
142 * 'forWrite' => bool defaults to false
143 * 'sort' => string optional sorting by namespace ID and title
144 * one of the self::SORT_* constants
146 * @return WatchedItem[]
148 public function getWatchedItemsForUser( User
$user, array $options = [] );
151 * Must be called separately for Subject & Talk namespaces
156 * @param LinkTarget $target
160 public function isWatched( User
$user, LinkTarget
$target );
166 * @param LinkTarget[] $targets
168 * @return array multi-dimensional like $return[$namespaceId][$titleString] = $timestamp,
169 * where $timestamp is:
170 * - string|null value of wl_notificationtimestamp,
171 * - false if $target is not watched by $user.
173 public function getNotificationTimestampsBatch( User
$user, array $targets );
176 * Must be called separately for Subject & Talk namespaces
181 * @param LinkTarget $target
183 public function addWatch( User
$user, LinkTarget
$target );
189 * @param LinkTarget[] $targets
191 * @return bool success
193 public function addWatchBatchForUser( User
$user, array $targets );
196 * Removes an entry for the User watching the LinkTarget
197 * Must be called separately for Subject & Talk namespaces
202 * @param LinkTarget $target
204 * @return bool success
205 * @throws DBUnexpectedError
206 * @throws MWException
208 public function removeWatch( User
$user, LinkTarget
$target );
213 * @param User $user The user to set the timestamps for
214 * @param string|null $timestamp Set the update timestamp to this value
215 * @param LinkTarget[] $targets List of targets to update. Default to all targets
217 * @return bool success
219 public function setNotificationTimestampsForUser(
226 * Reset all watchlist notificaton timestamps for a user using the job queue
230 * @param User $user The user to reset the timestamps for
232 public function resetAllNotificationTimestampsForUser( User
$user );
237 * @param User $editor The editor that triggered the update. Their notification
238 * timestamp will not be updated(they have already seen it)
239 * @param LinkTarget $target The target to update timestamps for
240 * @param string $timestamp Set the update timestamp to this value
242 * @return int[] Array of user IDs the timestamp has been updated for
244 public function updateNotificationTimestamp( User
$editor, LinkTarget
$target, $timestamp );
247 * Reset the notification timestamp of this entry
252 * @param Title $title
253 * @param string $force Whether to force the write query to be executed even if the
254 * page is not watched or the notification timestamp is already NULL.
255 * 'force' in order to force
256 * @param int $oldid The revision id being viewed. If not given or 0, latest revision is
259 * @return bool success Whether a job was enqueued
261 public function resetNotificationTimestamp( User
$user, Title
$title, $force = '', $oldid = 0 );
267 * @param int|null $unreadLimit
269 * @return int|bool The number of unread notifications
270 * true if greater than or equal to $unreadLimit
272 public function countUnreadNotifications( User
$user, $unreadLimit = null );
275 * Check if the given title already is watched by the user, and if so
276 * add a watch for the new title.
278 * To be used for page renames and such.
282 * @param LinkTarget $oldTarget
283 * @param LinkTarget $newTarget
285 public function duplicateAllAssociatedEntries( LinkTarget
$oldTarget, LinkTarget
$newTarget );
288 * Check if the given title already is watched by the user, and if so
289 * add a watch for the new title.
291 * To be used for page renames and such.
292 * This must be called separately for Subject and Talk pages
296 * @param LinkTarget $oldTarget
297 * @param LinkTarget $newTarget
299 public function duplicateEntry( LinkTarget
$oldTarget, LinkTarget
$newTarget );
302 * Queues a job that will clear the users watchlist using the Job Queue.
308 public function clearUserWatchedItems( User
$user );
311 * Queues a job that will clear the users watchlist using the Job Queue.
317 public function clearUserWatchedItemsUsingJobQueue( User
$user );
323 * @param LinkTarget[] $targets
325 * @return bool success
327 public function removeWatchBatchForUser( User
$user, array $targets );