includes/watcheditem/WatchedItemStoreInterface.php

   1 <?php
   2 /**
   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.
   7  *
   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.
  12  *
  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
  17  *
  18  * @file
  19  * @ingroup Watchlist
  20  */
  21 use MediaWiki\Linker\LinkTarget;
  22
  23 /**
  24  * @author Addshore
  25  * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
  26  */
  27 interface WatchedItemStoreInterface {
  28
  29         /**
  30          * @since 1.31
  31          */
  32         const SORT_ASC = 'ASC';
  33
  34         /**
  35          * @since 1.31
  36          */
  37         const SORT_DESC = 'DESC';
  38
  39         /**
  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.
  42          *
  43          * @since 1.31
  44          *
  45          * @param User $user
  46          *
  47          * @return int
  48          */
  49         public function countWatchedItems( User $user );
  50
  51         /**
  52          * @since 1.31
  53          *
  54          * @param LinkTarget $target
  55          *
  56          * @return int
  57          */
  58         public function countWatchers( LinkTarget $target );
  59
  60         /**
  61          * Number of page watchers who also visited a "recent" edit
  62          *
  63          * @since 1.31
  64          *
  65          * @param LinkTarget $target
  66          * @param mixed $threshold timestamp accepted by wfTimestamp
  67          *
  68          * @return int
  69          * @throws DBUnexpectedError
  70          * @throws MWException
  71          */
  72         public function countVisitingWatchers( LinkTarget $target, $threshold );
  73
  74         /**
  75          * @since 1.31
  76          *
  77          * @param LinkTarget[] $targets
  78          * @param array $options Allowed keys:
  79          *        'minimumWatchers' => int
  80          *
  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.
  84          */
  85         public function countWatchersMultiple( array $targets, array $options = [] );
  86
  87         /**
  88          * Number of watchers of each page who have visited recent edits to that page
  89          *
  90          * @since 1.31
  91          *
  92          * @param array $targetsWithVisitThresholds array of pairs (LinkTarget $target, mixed
  93          *     $threshold),
  94          *        $threshold is:
  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
  98          *
  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
 104          *     minimumWatchers
 105          *         option (if passed).
 106          */
 107         public function countVisitingWatchersMultiple(
 108                 array $targetsWithVisitThresholds,
 109                 $minimumWatchers = null
 110         );
 111
 112         /**
 113          * Get an item (may be cached)
 114          *
 115          * @since 1.31
 116          *
 117          * @param User $user
 118          * @param LinkTarget $target
 119          *
 120          * @return WatchedItem|false
 121          */
 122         public function getWatchedItem( User $user, LinkTarget $target );
 123
 124         /**
 125          * Loads an item from the db
 126          *
 127          * @since 1.31
 128          *
 129          * @param User $user
 130          * @param LinkTarget $target
 131          *
 132          * @return WatchedItem|false
 133          */
 134         public function loadWatchedItem( User $user, LinkTarget $target );
 135
 136         /**
 137          * @since 1.31
 138          *
 139          * @param User $user
 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
 144          *
 145          * @return WatchedItem[]
 146          */
 147         public function getWatchedItemsForUser( User $user, array $options = [] );
 148
 149         /**
 150          * Must be called separately for Subject & Talk namespaces
 151          *
 152          * @since 1.31
 153          *
 154          * @param User $user
 155          * @param LinkTarget $target
 156          *
 157          * @return bool
 158          */
 159         public function isWatched( User $user, LinkTarget $target );
 160
 161         /**
 162          * @since 1.31
 163          *
 164          * @param User $user
 165          * @param LinkTarget[] $targets
 166          *
 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.
 171          */
 172         public function getNotificationTimestampsBatch( User $user, array $targets );
 173
 174         /**
 175          * Must be called separately for Subject & Talk namespaces
 176          *
 177          * @since 1.31
 178          *
 179          * @param User $user
 180          * @param LinkTarget $target
 181          */
 182         public function addWatch( User $user, LinkTarget $target );
 183
 184         /**
 185          * @since 1.31
 186          *
 187          * @param User $user
 188          * @param LinkTarget[] $targets
 189          *
 190          * @return bool success
 191          */
 192         public function addWatchBatchForUser( User $user, array $targets );
 193
 194         /**
 195          * Removes the an entry for the User watching the LinkTarget
 196          * Must be called separately for Subject & Talk namespaces
 197          *
 198          * @since 1.31
 199          *
 200          * @param User $user
 201          * @param LinkTarget $target
 202          *
 203          * @return bool success
 204          * @throws DBUnexpectedError
 205          * @throws MWException
 206          */
 207         public function removeWatch( User $user, LinkTarget $target );
 208
 209         /**
 210          * @since 1.31
 211          *
 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
 215          *
 216          * @return bool success
 217          */
 218         public function setNotificationTimestampsForUser(
 219                 User $user,
 220                 $timestamp,
 221                 array $targets = []
 222         );
 223
 224         /**
 225          * @since 1.31
 226          *
 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
 231          *
 232          * @return int[] Array of user IDs the timestamp has been updated for
 233          */
 234         public function updateNotificationTimestamp( User $editor, LinkTarget $target, $timestamp );
 235
 236         /**
 237          * Reset the notification timestamp of this entry
 238          *
 239          * @since 1.31
 240          *
 241          * @param User $user
 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
 247          *     assumed.
 248          *
 249          * @return bool success
 250          */
 251         public function resetNotificationTimestamp( User $user, Title $title, $force = '', $oldid = 0 );
 252
 253         /**
 254          * @since 1.31
 255          *
 256          * @param User $user
 257          * @param int $unreadLimit
 258          *
 259          * @return int|bool The number of unread notifications
 260          *                  true if greater than or equal to $unreadLimit
 261          */
 262         public function countUnreadNotifications( User $user, $unreadLimit = null );
 263
 264         /**
 265          * Check if the given title already is watched by the user, and if so
 266          * add a watch for the new title.
 267          *
 268          * To be used for page renames and such.
 269          *
 270          * @since 1.31
 271          *
 272          * @param LinkTarget $oldTarget
 273          * @param LinkTarget $newTarget
 274          */
 275         public function duplicateAllAssociatedEntries( LinkTarget $oldTarget, LinkTarget $newTarget );
 276
 277         /**
 278          * Check if the given title already is watched by the user, and if so
 279          * add a watch for the new title.
 280          *
 281          * To be used for page renames and such.
 282          * This must be called separately for Subject and Talk pages
 283          *
 284          * @since 1.31
 285          *
 286          * @param LinkTarget $oldTarget
 287          * @param LinkTarget $newTarget
 288          */
 289         public function duplicateEntry( LinkTarget $oldTarget, LinkTarget $newTarget );
 290
 291         /**
 292          * Queues a job that will clear the users watchlist using the Job Queue.
 293          *
 294          * @since 1.31
 295          *
 296          * @param User $user
 297          */
 298         public function clearUserWatchedItems( User $user );
 299
 300         /**
 301          * Queues a job that will clear the users watchlist using the Job Queue.
 302          *
 303          * @since 1.31
 304          *
 305          * @param User $user
 306          */
 307         public function clearUserWatchedItemsUsingJobQueue( User $user );
 308
 309 }