12660db261
This adds MediaWiki\Watchlist namespace to the classes of watchlist directory and adds deprecation notice since 1.43 to the just created unnamespaced aliases of the classes. Bug: T353458 Change-Id: I4234f8fe62bb3bde6f5271c7ba31a2420b0f4b90
428 lines
14 KiB
PHP
428 lines
14 KiB
PHP
<?php
|
|
/**
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
* @ingroup Watchlist
|
|
*/
|
|
|
|
namespace MediaWiki\Watchlist;
|
|
|
|
use MediaWiki\Linker\LinkTarget;
|
|
use MediaWiki\Page\PageIdentity;
|
|
use MediaWiki\User\UserIdentity;
|
|
|
|
/**
|
|
* @author Addshore
|
|
* @since 1.31 interface created. WatchedItemStore implementation available since 1.27
|
|
*/
|
|
interface WatchedItemStoreInterface {
|
|
|
|
/**
|
|
* @since 1.31
|
|
*/
|
|
public const SORT_ASC = 'ASC';
|
|
|
|
/**
|
|
* @since 1.31
|
|
*/
|
|
public const SORT_DESC = 'DESC';
|
|
|
|
/**
|
|
* Count the number of individual items that are watched by the user.
|
|
* If a subject and corresponding talk page are watched this will return 2.
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
*
|
|
* @return int
|
|
*/
|
|
public function countWatchedItems( UserIdentity $user );
|
|
|
|
/**
|
|
* @since 1.31
|
|
*
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
*
|
|
* @return int
|
|
*/
|
|
public function countWatchers( $target );
|
|
|
|
/**
|
|
* Number of page watchers who also visited a "recent" edit
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
* @param mixed $threshold timestamp accepted by wfTimestamp
|
|
*
|
|
* @return int
|
|
*/
|
|
public function countVisitingWatchers( $target, $threshold );
|
|
|
|
/**
|
|
* @since 1.31
|
|
*
|
|
* @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
|
|
* @param array $options Allowed keys:
|
|
* 'minimumWatchers' => int
|
|
*
|
|
* @return array multi dimensional like $return[$namespaceId][$titleString] = int $watchers
|
|
* All targets will be present in the result. 0 either means no watchers or the number
|
|
* of watchers was below the minimumWatchers option if passed.
|
|
*/
|
|
public function countWatchersMultiple( array $targets, array $options = [] );
|
|
|
|
/**
|
|
* Number of watchers of each page who have visited recent edits to that page
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param array $targetsWithVisitThresholds array of pairs (LinkTarget|PageIdentity $target,
|
|
* mixed $threshold),
|
|
* $threshold is:
|
|
* - a timestamp of the recent edit if $target exists (format accepted by wfTimestamp)
|
|
* - null if $target doesn't exist
|
|
* deprecated passing LinkTarget since 1.36
|
|
* @param int|null $minimumWatchers
|
|
*
|
|
* @return array multi-dimensional like $return[$namespaceId][$titleString] = $watchers,
|
|
* where $watchers is an int:
|
|
* - if the page exists, number of users watching who have visited the page recently
|
|
* - if the page doesn't exist, number of users that have the page on their watchlist
|
|
* - 0 means there are no visiting watchers or their number is below the
|
|
* minimumWatchers
|
|
* option (if passed).
|
|
*/
|
|
public function countVisitingWatchersMultiple(
|
|
array $targetsWithVisitThresholds,
|
|
$minimumWatchers = null
|
|
);
|
|
|
|
/**
|
|
* Get an item (may be cached)
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
*
|
|
* @return WatchedItem|false
|
|
*/
|
|
public function getWatchedItem( UserIdentity $user, $target );
|
|
|
|
/**
|
|
* Loads an item from the db
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
*
|
|
* @return WatchedItem|false
|
|
*/
|
|
public function loadWatchedItem( UserIdentity $user, $target );
|
|
|
|
/**
|
|
* Loads a set of WatchedItems from the db.
|
|
*
|
|
* @since 1.36
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
|
|
*
|
|
* @return WatchedItem[]|false
|
|
*/
|
|
public function loadWatchedItemsBatch( UserIdentity $user, array $targets );
|
|
|
|
/**
|
|
* @since 1.31 Method Added
|
|
* @since 1.35 Allows 'sortByExpiry' as a key in $options
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param array $options Allowed keys:
|
|
* 'forWrite' => bool defaults to false
|
|
* 'sort' => string optional sorting by namespace ID and title
|
|
* one of the self::SORT_* constants
|
|
* 'sortByExpiry' => bool optional sorts by expiration date, with the titles
|
|
* that will expire soonest at the top.
|
|
*
|
|
* @return WatchedItem[]
|
|
*/
|
|
public function getWatchedItemsForUser( UserIdentity $user, array $options = [] );
|
|
|
|
/**
|
|
* Must be called separately for Subject & Talk namespaces
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isWatched( UserIdentity $user, $target );
|
|
|
|
/**
|
|
* Whether the page is only being watched temporarily (has expiry).
|
|
* Must be called separately for Subject & Talk namespaces.
|
|
*
|
|
* @since 1.35
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isTempWatched( UserIdentity $user, $target ): bool;
|
|
|
|
/**
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
|
|
*
|
|
* @return array multi-dimensional like $return[$namespaceId][$titleString] = $timestamp,
|
|
* where $timestamp is:
|
|
* - string|null value of wl_notificationtimestamp,
|
|
* - false if $target is not watched by $user.
|
|
*/
|
|
public function getNotificationTimestampsBatch( UserIdentity $user, array $targets );
|
|
|
|
/**
|
|
* Must be called separately for Subject & Talk namespaces
|
|
*
|
|
* @since 1.31 Method added.
|
|
* @since 1.35 Accepts $expiry parameter.
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
* @param string|null $expiry Optional expiry timestamp in any format acceptable to wfTimestamp().
|
|
* null will not create an expiry, or leave it unchanged should one already exist.
|
|
*/
|
|
public function addWatch( UserIdentity $user, $target, ?string $expiry = null );
|
|
|
|
/**
|
|
* @since 1.31 Method added.
|
|
* @since 1.35 Accepts $expiry parameter.
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
|
|
* @param string|null $expiry Optional expiry timestamp in any format acceptable to wfTimestamp(),
|
|
* null will not create expiries, or leave them unchanged should they already exist.
|
|
*
|
|
* @return bool success
|
|
*/
|
|
public function addWatchBatchForUser( UserIdentity $user, array $targets, ?string $expiry = null );
|
|
|
|
/**
|
|
* Removes an entry for the UserIdentity watching the target (LinkTarget or PageIdentity)
|
|
* Must be called separately for Subject & Talk namespaces
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
*
|
|
* @return bool success
|
|
*/
|
|
public function removeWatch( UserIdentity $user, $target );
|
|
|
|
/**
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user The user to set the timestamps for
|
|
* @param string|null $timestamp Set the update timestamp to this value
|
|
* @param LinkTarget[]|PageIdentity[] $targets List of targets to update. Default to all targets.
|
|
* deprecated passing LinkTarget[] since 1.36
|
|
*
|
|
* @return bool success
|
|
*/
|
|
public function setNotificationTimestampsForUser(
|
|
UserIdentity $user,
|
|
$timestamp,
|
|
array $targets = []
|
|
);
|
|
|
|
/**
|
|
* Reset all watchlist notification timestamps for a user using the job queue
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user The user to reset the timestamps for
|
|
* @param string|int|null $timestamp Value to set all timestamps to, null to clear them
|
|
*/
|
|
public function resetAllNotificationTimestampsForUser( UserIdentity $user, $timestamp = null );
|
|
|
|
/**
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $editor The editor that triggered the update. Their notification
|
|
* timestamp will not be updated(they have already seen it)
|
|
* @param LinkTarget|PageIdentity $target The target to update timestamps for
|
|
* deprecated passing LinkTarget since 1.36
|
|
* @param string $timestamp Set the update (first unseen revision) timestamp to this value
|
|
*
|
|
* @return int[] Array of user IDs the timestamp has been updated for
|
|
*/
|
|
public function updateNotificationTimestamp(
|
|
UserIdentity $editor, $target, $timestamp );
|
|
|
|
/**
|
|
* Reset the notification timestamp of this entry
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $title deprecated passing LinkTarget since 1.36
|
|
* @param string $force Whether to force the write query to be executed even if the
|
|
* page is not watched or the notification timestamp is already NULL.
|
|
* 'force' in order to force
|
|
* @param int $oldid The revision id being viewed. If not given or 0, latest revision is
|
|
* assumed.
|
|
*
|
|
* @return bool success Whether a job was enqueued
|
|
*/
|
|
public function resetNotificationTimestamp(
|
|
UserIdentity $user, $title, $force = '', $oldid = 0 );
|
|
|
|
/**
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param int|null $unreadLimit
|
|
*
|
|
* @return int|bool The number of unread notifications
|
|
* true if greater than or equal to $unreadLimit
|
|
*/
|
|
public function countUnreadNotifications( UserIdentity $user, $unreadLimit = null );
|
|
|
|
/**
|
|
* Check if the given title already is watched by the user, and if so
|
|
* add a watch for the new title.
|
|
*
|
|
* To be used for page renames and such.
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param LinkTarget|PageIdentity $oldTarget deprecated passing LinkTarget since 1.36
|
|
* @param LinkTarget|PageIdentity $newTarget deprecated passing LinkTarget since 1.36
|
|
*/
|
|
public function duplicateAllAssociatedEntries( $oldTarget, $newTarget );
|
|
|
|
/**
|
|
* Check if the given title already is watched by the user, and if so
|
|
* add a watch for the new title.
|
|
*
|
|
* To be used for page renames and such.
|
|
* This must be called separately for Subject and Talk pages
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param LinkTarget|PageIdentity $oldTarget deprecated passing LinkTarget since 1.36
|
|
* @param LinkTarget|PageIdentity $newTarget deprecated passing LinkTarget since 1.36
|
|
*/
|
|
public function duplicateEntry( $oldTarget, $newTarget );
|
|
|
|
/**
|
|
* Synchronously clear the users watchlist.
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
* @return bool True on success, false if {@see clearUserWatchedItemsUsingJobQueue} must be used
|
|
* instead
|
|
*/
|
|
public function clearUserWatchedItems( UserIdentity $user );
|
|
|
|
/**
|
|
* Does the size of the users watchlist require clearUserWatchedItemsUsingJobQueue() to be used
|
|
* instead of clearUserWatchedItems()
|
|
*
|
|
* @since 1.35
|
|
*
|
|
* @param UserIdentity $user
|
|
* @return bool
|
|
*/
|
|
public function mustClearWatchedItemsUsingJobQueue( UserIdentity $user ): bool;
|
|
|
|
/**
|
|
* Queues a job that will clear the users watchlist using the Job Queue.
|
|
*
|
|
* @since 1.31
|
|
*
|
|
* @param UserIdentity $user
|
|
*/
|
|
public function clearUserWatchedItemsUsingJobQueue( UserIdentity $user );
|
|
|
|
/**
|
|
* Probabilistically add a job to purge the expired watchlist items, if watchlist
|
|
* expiration is enabled, based on the value of $wgWatchlistPurgeRate
|
|
*
|
|
* @since 1.36
|
|
*/
|
|
public function maybeEnqueueWatchlistExpiryJob(): void;
|
|
|
|
/**
|
|
* @since 1.32
|
|
*
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
|
|
*
|
|
* @return bool success
|
|
*/
|
|
public function removeWatchBatchForUser( UserIdentity $user, array $targets );
|
|
|
|
/**
|
|
* Convert $timestamp to TS_MW or return null if the page was visited since then by $user
|
|
*
|
|
* Use this only on single-user methods (having higher read-after-write expectations)
|
|
* and not in places involving arbitrary batches of different users
|
|
*
|
|
* Usage of this method should be limited to WatchedItem* classes
|
|
*
|
|
* @param string|null $timestamp Value of wl_notificationtimestamp from the DB
|
|
* @param UserIdentity $user
|
|
* @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
|
|
* @return string|null TS_MW timestamp of first unseen revision or null if there isn't one
|
|
*/
|
|
public function getLatestNotificationTimestamp(
|
|
$timestamp, UserIdentity $user, $target );
|
|
|
|
/**
|
|
* Get the number of watchlist items that expire before the current time.
|
|
*
|
|
* @since 1.35
|
|
*
|
|
* @return int
|
|
*/
|
|
public function countExpired(): int;
|
|
|
|
/**
|
|
* Remove some number of expired watchlist items.
|
|
*
|
|
* @since 1.35
|
|
*
|
|
* @param int $limit The number of items to remove.
|
|
* @param bool $deleteOrphans Whether to also delete `watchlist_expiry` rows that have no
|
|
* related `watchlist` rows (because not all code knows about the expiry table yet). This runs
|
|
* two extra queries, so is only done from the purgeExpiredWatchlistItems.php maintenance script.
|
|
*/
|
|
public function removeExpired( int $limit, bool $deleteOrphans = false ): void;
|
|
}
|
|
/** @deprecated class alias since 1.43 */
|
|
class_alias( WatchedItemStoreInterface::class, 'WatchedItemStoreInterface' );
|