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