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 use Wikimedia\Rdbms\DBUnexpectedError;
  23
  24 /**
  25  * @author Addshore
  26  * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
  27  */
  28 interface WatchedItemStoreInterface {
  29
  30         /**
  31          * @since 1.31
  32          */
  33         const SORT_ASC = 'ASC';
  34
  35         /**
  36          * @since 1.31
  37          */
  38         const SORT_DESC = 'DESC';
  39
  40         /**
  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.
  43          *
  44          * @since 1.31
  45          *
  46          * @param User $user
  47          *
  48          * @return int
  49          */
  50         public function countWatchedItems( User $user );
  51
  52         /**
  53          * @since 1.31
  54          *
  55          * @param LinkTarget $target
  56          *
  57          * @return int
  58          */
  59         public function countWatchers( LinkTarget $target );
  60
  61         /**
  62          * Number of page watchers who also visited a "recent" edit
  63          *
  64          * @since 1.31
  65          *
  66          * @param LinkTarget $target
  67          * @param mixed $threshold timestamp accepted by wfTimestamp
  68          *
  69          * @return int
  70          * @throws DBUnexpectedError
  71          * @throws MWException
  72          */
  73         public function countVisitingWatchers( LinkTarget $target, $threshold );
  74
  75         /**
  76          * @since 1.31
  77          *
  78          * @param LinkTarget[] $targets
  79          * @param array $options Allowed keys:
  80          *        'minimumWatchers' => int
  81          *
  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.
  85          */
  86         public function countWatchersMultiple( array $targets, array $options = [] );
  87
  88         /**
  89          * Number of watchers of each page who have visited recent edits to that page
  90          *
  91          * @since 1.31
  92          *
  93          * @param array $targetsWithVisitThresholds array of pairs (LinkTarget $target, mixed
  94          *     $threshold),
  95          *        $threshold is:
  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
  99          *
 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
 105          *     minimumWatchers
 106          *         option (if passed).
 107          */
 108         public function countVisitingWatchersMultiple(
 109                 array $targetsWithVisitThresholds,
 110                 $minimumWatchers = null
 111         );
 112
 113         /**
 114          * Get an item (may be cached)
 115          *
 116          * @since 1.31
 117          *
 118          * @param User $user
 119          * @param LinkTarget $target
 120          *
 121          * @return WatchedItem|false
 122          */
 123         public function getWatchedItem( User $user, LinkTarget $target );
 124
 125         /**
 126          * Loads an item from the db
 127          *
 128          * @since 1.31
 129          *
 130          * @param User $user
 131          * @param LinkTarget $target
 132          *
 133          * @return WatchedItem|false
 134          */
 135         public function loadWatchedItem( User $user, LinkTarget $target );
 136
 137         /**
 138          * @since 1.31
 139          *
 140          * @param User $user
 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
 145          *
 146          * @return WatchedItem[]
 147          */
 148         public function getWatchedItemsForUser( User $user, array $options = [] );
 149
 150         /**
 151          * Must be called separately for Subject & Talk namespaces
 152          *
 153          * @since 1.31
 154          *
 155          * @param User $user
 156          * @param LinkTarget $target
 157          *
 158          * @return bool
 159          */
 160         public function isWatched( User $user, LinkTarget $target );
 161
 162         /**
 163          * @since 1.31
 164          *
 165          * @param User $user
 166          * @param LinkTarget[] $targets
 167          *
 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.
 172          */
 173         public function getNotificationTimestampsBatch( User $user, array $targets );
 174
 175         /**
 176          * Must be called separately for Subject & Talk namespaces
 177          *
 178          * @since 1.31
 179          *
 180          * @param User $user
 181          * @param LinkTarget $target
 182          */
 183         public function addWatch( User $user, LinkTarget $target );
 184
 185         /**
 186          * @since 1.31
 187          *
 188          * @param User $user
 189          * @param LinkTarget[] $targets
 190          *
 191          * @return bool success
 192          */
 193         public function addWatchBatchForUser( User $user, array $targets );
 194
 195         /**
 196          * Removes an entry for the User watching the LinkTarget
 197          * Must be called separately for Subject & Talk namespaces
 198          *
 199          * @since 1.31
 200          *
 201          * @param User $user
 202          * @param LinkTarget $target
 203          *
 204          * @return bool success
 205          * @throws DBUnexpectedError
 206          * @throws MWException
 207          */
 208         public function removeWatch( User $user, LinkTarget $target );
 209
 210         /**
 211          * @since 1.31
 212          *
 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
 216          *
 217          * @return bool success
 218          */
 219         public function setNotificationTimestampsForUser(
 220                 User $user,
 221                 $timestamp,
 222                 array $targets = []
 223         );
 224
 225         /**
 226          * Reset all watchlist notificaton timestamps for a user using the job queue
 227          *
 228          * @since 1.31
 229          *
 230          * @param User $user The user to reset the timestamps for
 231          */
 232         public function resetAllNotificationTimestampsForUser( User $user );
 233
 234         /**
 235          * @since 1.31
 236          *
 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
 241          *
 242          * @return int[] Array of user IDs the timestamp has been updated for
 243          */
 244         public function updateNotificationTimestamp( User $editor, LinkTarget $target, $timestamp );
 245
 246         /**
 247          * Reset the notification timestamp of this entry
 248          *
 249          * @since 1.31
 250          *
 251          * @param User $user
 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
 257          *     assumed.
 258          *
 259          * @return bool success Whether a job was enqueued
 260          */
 261         public function resetNotificationTimestamp( User $user, Title $title, $force = '', $oldid = 0 );
 262
 263         /**
 264          * @since 1.31
 265          *
 266          * @param User $user
 267          * @param int|null $unreadLimit
 268          *
 269          * @return int|bool The number of unread notifications
 270          *                  true if greater than or equal to $unreadLimit
 271          */
 272         public function countUnreadNotifications( User $user, $unreadLimit = null );
 273
 274         /**
 275          * Check if the given title already is watched by the user, and if so
 276          * add a watch for the new title.
 277          *
 278          * To be used for page renames and such.
 279          *
 280          * @since 1.31
 281          *
 282          * @param LinkTarget $oldTarget
 283          * @param LinkTarget $newTarget
 284          */
 285         public function duplicateAllAssociatedEntries( LinkTarget $oldTarget, LinkTarget $newTarget );
 286
 287         /**
 288          * Check if the given title already is watched by the user, and if so
 289          * add a watch for the new title.
 290          *
 291          * To be used for page renames and such.
 292          * This must be called separately for Subject and Talk pages
 293          *
 294          * @since 1.31
 295          *
 296          * @param LinkTarget $oldTarget
 297          * @param LinkTarget $newTarget
 298          */
 299         public function duplicateEntry( LinkTarget $oldTarget, LinkTarget $newTarget );
 300
 301         /**
 302          * Queues a job that will clear the users watchlist using the Job Queue.
 303          *
 304          * @since 1.31
 305          *
 306          * @param User $user
 307          */
 308         public function clearUserWatchedItems( User $user );
 309
 310         /**
 311          * Queues a job that will clear the users watchlist using the Job Queue.
 312          *
 313          * @since 1.31
 314          *
 315          * @param User $user
 316          */
 317         public function clearUserWatchedItemsUsingJobQueue( User $user );
 318
 319         /**
 320          * @since 1.32
 321          *
 322          * @param User $user
 323          * @param LinkTarget[] $targets
 324          *
 325          * @return bool success
 326          */
 327         public function removeWatchBatchForUser( User $user, array $targets );
 328
 329         /**
 330          * Convert $timestamp to TS_MW or return null if the page was visited since then by $user
 331          *
 332          * Use this only on single-user methods (having higher read-after-write expectations)
 333          * and not in places involving arbitrary batches of different users
 334          *
 335          * Usage of this method should be limited to WatchedItem* classes
 336          *
 337          * @param string|null $timestamp Value of wl_notificationtimestamp from the DB
 338          * @param User $user
 339          * @param LinkTarget $target
 340          * @return string TS_MW timestamp or null
 341          */
 342         public function getLatestNotificationTimestamp( $timestamp, User $user, LinkTarget $target );
 343 }