includes/watchlist/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
  22 namespace MediaWiki\Watchlist;
  23
  24 use MediaWiki\Linker\LinkTarget;
  25 use MediaWiki\Page\PageIdentity;
  26 use MediaWiki\User\UserIdentity;
  27
  28 /**
  29  * @author Addshore
  30  * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
  31  */
  32 interface WatchedItemStoreInterface {
  33
  34         /**
  35          * @since 1.31
  36          */
  37         public const SORT_ASC = 'ASC';
  38
  39         /**
  40          * @since 1.31
  41          */
  42         public const SORT_DESC = 'DESC';
  43
  44         /**
  45          * Count the number of individual items that are watched by the user.
  46          * If a subject and corresponding talk page are watched this will return 2.
  47          *
  48          * @since 1.31
  49          *
  50          * @param UserIdentity $user
  51          *
  52          * @return int
  53          */
  54         public function countWatchedItems( UserIdentity $user );
  55
  56         /**
  57          * @since 1.31
  58          *
  59          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
  60          *
  61          * @return int
  62          */
  63         public function countWatchers( $target );
  64
  65         /**
  66          * Number of page watchers who also visited a "recent" edit
  67          *
  68          * @since 1.31
  69          *
  70          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
  71          * @param mixed $threshold timestamp accepted by wfTimestamp
  72          *
  73          * @return int
  74          */
  75         public function countVisitingWatchers( $target, $threshold );
  76
  77         /**
  78          * @since 1.31
  79          *
  80          * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
  81          * @param array $options Allowed keys:
  82          *        'minimumWatchers' => int
  83          *
  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.
  87          */
  88         public function countWatchersMultiple( array $targets, array $options = [] );
  89
  90         /**
  91          * Number of watchers of each page who have visited recent edits to that page
  92          *
  93          * @since 1.31
  94          *
  95          * @param array $targetsWithVisitThresholds array of pairs (LinkTarget|PageIdentity $target,
  96          *     mixed $threshold),
  97          *        $threshold is:
  98          *        - a timestamp of the recent edit if $target exists (format accepted by wfTimestamp)
  99          *        - null if $target doesn't exist
 100          *      deprecated passing LinkTarget since 1.36
 101          * @param int|null $minimumWatchers
 102          *
 103          * @return array multi-dimensional like $return[$namespaceId][$titleString] = $watchers,
 104          *         where $watchers is an int:
 105          *         - if the page exists, number of users watching who have visited the page recently
 106          *         - if the page doesn't exist, number of users that have the page on their watchlist
 107          *         - 0 means there are no visiting watchers or their number is below the
 108          *     minimumWatchers
 109          *         option (if passed).
 110          */
 111         public function countVisitingWatchersMultiple(
 112                 array $targetsWithVisitThresholds,
 113                 $minimumWatchers = null
 114         );
 115
 116         /**
 117          * Get an item (may be cached)
 118          *
 119          * @since 1.31
 120          *
 121          * @param UserIdentity $user
 122          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 123          *
 124          * @return WatchedItem|false
 125          */
 126         public function getWatchedItem( UserIdentity $user, $target );
 127
 128         /**
 129          * Loads an item from the db
 130          *
 131          * @since 1.31
 132          *
 133          * @param UserIdentity $user
 134          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 135          *
 136          * @return WatchedItem|false
 137          */
 138         public function loadWatchedItem( UserIdentity $user, $target );
 139
 140         /**
 141          * Loads a set of WatchedItems from the db.
 142          *
 143          * @since 1.36
 144          *
 145          * @param UserIdentity $user
 146          * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
 147          *
 148          * @return WatchedItem[]|false
 149          */
 150         public function loadWatchedItemsBatch( UserIdentity $user, array $targets );
 151
 152         /**
 153          * @since 1.31 Method Added
 154          * @since 1.35 Allows 'sortByExpiry' as a key in $options
 155          *
 156          * @param UserIdentity $user
 157          * @param array $options Allowed keys:
 158          *        'forWrite' => bool defaults to false
 159          *        'sort' => string optional sorting by namespace ID and title
 160          *                     one of the self::SORT_* constants
 161          *        'sortByExpiry' => bool optional sorts by expiration date, with the titles
 162          *                     that will expire soonest at the top.
 163          *
 164          * @return WatchedItem[]
 165          */
 166         public function getWatchedItemsForUser( UserIdentity $user, array $options = [] );
 167
 168         /**
 169          * Must be called separately for Subject & Talk namespaces
 170          *
 171          * @since 1.31
 172          *
 173          * @param UserIdentity $user
 174          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 175          *
 176          * @return bool
 177          */
 178         public function isWatched( UserIdentity $user, $target );
 179
 180         /**
 181          * Whether the page is only being watched temporarily (has expiry).
 182          * Must be called separately for Subject & Talk namespaces.
 183          *
 184          * @since 1.35
 185          *
 186          * @param UserIdentity $user
 187          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 188          *
 189          * @return bool
 190          */
 191         public function isTempWatched( UserIdentity $user, $target ): bool;
 192
 193         /**
 194          * @since 1.31
 195          *
 196          * @param UserIdentity $user
 197          * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
 198          *
 199          * @return array multi-dimensional like $return[$namespaceId][$titleString] = $timestamp,
 200          *         where $timestamp is:
 201          *         - string|null value of wl_notificationtimestamp,
 202          *         - false if $target is not watched by $user.
 203          */
 204         public function getNotificationTimestampsBatch( UserIdentity $user, array $targets );
 205
 206         /**
 207          * Must be called separately for Subject & Talk namespaces
 208          *
 209          * @since 1.31 Method added.
 210          * @since 1.35 Accepts $expiry parameter.
 211          *
 212          * @param UserIdentity $user
 213          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 214          * @param string|null $expiry Optional expiry timestamp in any format acceptable to wfTimestamp().
 215          *   null will not create an expiry, or leave it unchanged should one already exist.
 216          */
 217         public function addWatch( UserIdentity $user, $target, ?string $expiry = null );
 218
 219         /**
 220          * @since 1.31 Method added.
 221          * @since 1.35 Accepts $expiry parameter.
 222          *
 223          * @param UserIdentity $user
 224          * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
 225          * @param string|null $expiry Optional expiry timestamp in any format acceptable to wfTimestamp(),
 226          *   null will not create expiries, or leave them unchanged should they already exist.
 227          *
 228          * @return bool success
 229          */
 230         public function addWatchBatchForUser( UserIdentity $user, array $targets, ?string $expiry = null );
 231
 232         /**
 233          * Removes an entry for the UserIdentity watching the target (LinkTarget or PageIdentity)
 234          * Must be called separately for Subject & Talk namespaces
 235          *
 236          * @since 1.31
 237          *
 238          * @param UserIdentity $user
 239          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 240          *
 241          * @return bool success
 242          */
 243         public function removeWatch( UserIdentity $user, $target );
 244
 245         /**
 246          * @since 1.31
 247          *
 248          * @param UserIdentity $user The user to set the timestamps for
 249          * @param string|null $timestamp Set the update timestamp to this value
 250          * @param LinkTarget[]|PageIdentity[] $targets List of targets to update. Default to all targets.
 251          *        deprecated passing LinkTarget[] since 1.36
 252          *
 253          * @return bool success
 254          */
 255         public function setNotificationTimestampsForUser(
 256                 UserIdentity $user,
 257                 $timestamp,
 258                 array $targets = []
 259         );
 260
 261         /**
 262          * Reset all watchlist notification timestamps for a user using the job queue
 263          *
 264          * @since 1.31
 265          *
 266          * @param UserIdentity $user The user to reset the timestamps for
 267          * @param string|int|null $timestamp Value to set all timestamps to, null to clear them
 268          */
 269         public function resetAllNotificationTimestampsForUser( UserIdentity $user, $timestamp = null );
 270
 271         /**
 272          * @since 1.31
 273          *
 274          * @param UserIdentity $editor The editor that triggered the update. Their notification
 275          *  timestamp will not be updated(they have already seen it)
 276          * @param LinkTarget|PageIdentity $target The target to update timestamps for
 277          *        deprecated passing LinkTarget since 1.36
 278          * @param string $timestamp Set the update (first unseen revision) timestamp to this value
 279          *
 280          * @return int[] Array of user IDs the timestamp has been updated for
 281          */
 282         public function updateNotificationTimestamp(
 283                 UserIdentity $editor, $target, $timestamp );
 284
 285         /**
 286          * Reset the notification timestamp of this entry
 287          *
 288          * @since 1.31
 289          *
 290          * @param UserIdentity $user
 291          * @param LinkTarget|PageIdentity $title deprecated passing LinkTarget since 1.36
 292          * @param string $force Whether to force the write query to be executed even if the
 293          *    page is not watched or the notification timestamp is already NULL.
 294          *    'force' in order to force
 295          * @param int $oldid The revision id being viewed. If not given or 0, latest revision is
 296          *     assumed.
 297          *
 298          * @return bool success Whether a job was enqueued
 299          */
 300         public function resetNotificationTimestamp(
 301                 UserIdentity $user, $title, $force = '', $oldid = 0 );
 302
 303         /**
 304          * @since 1.31
 305          *
 306          * @param UserIdentity $user
 307          * @param int|null $unreadLimit
 308          *
 309          * @return int|bool The number of unread notifications
 310          *                  true if greater than or equal to $unreadLimit
 311          */
 312         public function countUnreadNotifications( UserIdentity $user, $unreadLimit = null );
 313
 314         /**
 315          * Check if the given title already is watched by the user, and if so
 316          * add a watch for the new title.
 317          *
 318          * To be used for page renames and such.
 319          *
 320          * @since 1.31
 321          *
 322          * @param LinkTarget|PageIdentity $oldTarget deprecated passing LinkTarget since 1.36
 323          * @param LinkTarget|PageIdentity $newTarget deprecated passing LinkTarget since 1.36
 324          */
 325         public function duplicateAllAssociatedEntries( $oldTarget, $newTarget );
 326
 327         /**
 328          * Check if the given title already is watched by the user, and if so
 329          * add a watch for the new title.
 330          *
 331          * To be used for page renames and such.
 332          * This must be called separately for Subject and Talk pages
 333          *
 334          * @since 1.31
 335          *
 336          * @param LinkTarget|PageIdentity $oldTarget deprecated passing LinkTarget since 1.36
 337          * @param LinkTarget|PageIdentity $newTarget deprecated passing LinkTarget since 1.36
 338          */
 339         public function duplicateEntry( $oldTarget, $newTarget );
 340
 341         /**
 342          * Synchronously clear the users watchlist.
 343          *
 344          * @since 1.31
 345          *
 346          * @param UserIdentity $user
 347          * @return bool True on success, false if {@see clearUserWatchedItemsUsingJobQueue} must be used
 348          *  instead
 349          */
 350         public function clearUserWatchedItems( UserIdentity $user );
 351
 352         /**
 353          * Does the size of the users watchlist require clearUserWatchedItemsUsingJobQueue() to be used
 354          * instead of clearUserWatchedItems()
 355          *
 356          * @since 1.35
 357          *
 358          * @param UserIdentity $user
 359          * @return bool
 360          */
 361         public function mustClearWatchedItemsUsingJobQueue( UserIdentity $user ): bool;
 362
 363         /**
 364          * Queues a job that will clear the users watchlist using the Job Queue.
 365          *
 366          * @since 1.31
 367          *
 368          * @param UserIdentity $user
 369          */
 370         public function clearUserWatchedItemsUsingJobQueue( UserIdentity $user );
 371
 372         /**
 373          * Probabilistically add a job to purge the expired watchlist items, if watchlist
 374          * expiration is enabled, based on the value of $wgWatchlistPurgeRate
 375          *
 376          * @since 1.36
 377          */
 378         public function maybeEnqueueWatchlistExpiryJob(): void;
 379
 380         /**
 381          * @since 1.32
 382          *
 383          * @param UserIdentity $user
 384          * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
 385          *
 386          * @return bool success
 387          */
 388         public function removeWatchBatchForUser( UserIdentity $user, array $targets );
 389
 390         /**
 391          * Convert $timestamp to TS_MW or return null if the page was visited since then by $user
 392          *
 393          * Use this only on single-user methods (having higher read-after-write expectations)
 394          * and not in places involving arbitrary batches of different users
 395          *
 396          * Usage of this method should be limited to WatchedItem* classes
 397          *
 398          * @param string|null $timestamp Value of wl_notificationtimestamp from the DB
 399          * @param UserIdentity $user
 400          * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
 401          * @return string|null TS_MW timestamp of first unseen revision or null if there isn't one
 402          */
 403         public function getLatestNotificationTimestamp(
 404                 $timestamp, UserIdentity $user, $target );
 405
 406         /**
 407          * Get the number of watchlist items that expire before the current time.
 408          *
 409          * @since 1.35
 410          *
 411          * @return int
 412          */
 413         public function countExpired(): int;
 414
 415         /**
 416          * Remove some number of expired watchlist items.
 417          *
 418          * @since 1.35
 419          *
 420          * @param int $limit The number of items to remove.
 421          * @param bool $deleteOrphans Whether to also delete `watchlist_expiry` rows that have no
 422          * related `watchlist` rows (because not all code knows about the expiry table yet). This runs
 423          * two extra queries, so is only done from the purgeExpiredWatchlistItems.php maintenance script.
 424          */
 425         public function removeExpired( int $limit, bool $deleteOrphans = false ): void;
 426 }
 427 /** @deprecated class alias since 1.43 */
 428 class_alias( WatchedItemStoreInterface::class, 'WatchedItemStoreInterface' );