Inherited by MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

Public Member Functions
	addLabels (UserIdentity $user, array $targets, array $labels)
	Add a labels to a set of watchlist items.

	addWatch (UserIdentity $user, PageReference $target, ?string $expiry=null)
	Must be called separately for Subject & Talk namespaces.

	addWatchBatchForUser (UserIdentity $user, array $targets, ?string $expiry=null)

	clearUserWatchedItems (UserIdentity $user)
	Synchronously clear the users watchlist.

	clearUserWatchedItemsUsingJobQueue (UserIdentity $user)
	Queues a job that will clear the users watchlist using the Job Queue.

	countExpired ()
	Get the number of watchlist items that expire before the current time.

	countUnreadNotifications (UserIdentity $user, $unreadLimit=null)

	countVisitingWatchers (PageReference $target, $threshold)
	Number of page watchers who also visited a "recent" edit.

	countVisitingWatchersMultiple (array $targetsWithVisitThresholds, $minimumWatchers=null)
	Number of watchers of each page who have visited recent edits to that page.

	countWatchedItems (UserIdentity $user)
	Count the number of individual items that are watched by the user.

	countWatchers (PageReference $target)

	countWatchersMultiple (array $targets, array $options=[])

	duplicateAllAssociatedEntries (PageReference $oldTarget, PageReference $newTarget)
	Check if the given title already is watched by the user, and if so add a watch for the new title.

	duplicateEntry (PageReference $oldTarget, PageReference $newTarget)
	Check if the given title already is watched by the user, and if so add a watch for the new title.

	getLatestNotificationTimestamp ( $timestamp, UserIdentity $user, PageReference $target)
	Convert $timestamp to TS::MW or return null if the page was visited since then by $user.

	getNotificationTimestampsBatch (UserIdentity $user, array $targets)

	getWatchedItem (UserIdentity $user, PageReference $target)
	Get an item (may be cached)

	getWatchedItemsForUser (UserIdentity $user, array $options=[])

	isTempWatched (UserIdentity $user, PageReference $target)
	Whether the page is only being watched temporarily (has expiry).

	isWatched (UserIdentity $user, PageReference $target)
	Must be called separately for Subject & Talk namespaces.

	loadWatchedItem (UserIdentity $user, PageReference $target)
	Loads an item from the db.

	loadWatchedItemsBatch (UserIdentity $user, array $targets)
	Loads a set of WatchedItems from the db.

	maybeEnqueueWatchlistExpiryJob ()
	Probabilistically add a job to purge the expired watchlist items, if watchlist expiration is enabled, based on the value of $wgWatchlistPurgeRate.

	mustClearWatchedItemsUsingJobQueue (UserIdentity $user)
	Does the size of the users watchlist require clearUserWatchedItemsUsingJobQueue() to be used instead of clearUserWatchedItems()

	removeExpired (int $limit, bool $deleteOrphans=false)
	Remove some number of expired watchlist items.

	removeLabels (UserIdentity $user, array $targets, array $labels)
	Remove labels from a set of watchlist items.

	removeWatch (UserIdentity $user, PageReference $target)
	Removes an entry for the UserIdentity watching the target Must be called separately for Subject & Talk namespaces.

	removeWatchBatchForUser (UserIdentity $user, array $targets)

	resetAllNotificationTimestampsForUser (UserIdentity $user, $timestamp=null)
	Reset all watchlist notification timestamps for a user using the job queue.

	resetNotificationTimestamp (UserIdentity $user, PageReference $title, $force='', $oldid=0)
	Reset the notification timestamp of this entry.

	setNotificationTimestampsForUser (UserIdentity $user, $timestamp, array $targets=[])

	updateNotificationTimestamp (UserIdentity $editor, PageReference $target, $timestamp)

Public Attributes
const	SORT_ASC = 'ASC'

const	SORT_DESC = 'DESC'

Detailed Description

Author: Addshore

Since: 1.31 interface created. WatchedItemStore implementation available since 1.27

Definition at line 17 of file WatchedItemStoreInterface.php.

Member Function Documentation

◆ addLabels()

MediaWiki\Watchlist\WatchedItemStoreInterface::addLabels	(	UserIdentity	$user,
		array	$targets,
		array	$labels )

Add a labels to a set of watchlist items.

The same labels are applied to each item. Ignore existing labels.

Since: 1.46

Parameters

UserIdentity	$user
PageReference[]	$targets
	(WatchlistLabel\|int)[]	$labels The label objects or IDs

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ addWatch()

MediaWiki\Watchlist\WatchedItemStoreInterface::addWatch	(	UserIdentity	$user,
		PageReference	$target,
		?string	$expiry = null )

Must be called separately for Subject & Talk namespaces.

Since: 1.31 Method added.; 1.35 Accepts $expiry parameter.

Parameters

UserIdentity	$user
PageReference	$target
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.

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ addWatchBatchForUser()

MediaWiki\Watchlist\WatchedItemStoreInterface::addWatchBatchForUser	(	UserIdentity	$user,
		array	$targets,
		?string	$expiry = null )

Since: 1.31 Method added.; 1.35 Accepts $expiry parameter.

Parameters

UserIdentity	$user
PageReference[]	$targets
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.

Returns: bool success

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ clearUserWatchedItems()

MediaWiki\Watchlist\WatchedItemStoreInterface::clearUserWatchedItems ( UserIdentity $user )

Synchronously clear the users watchlist.

Since: 1.31

Parameters

UserIdentity $user

Returns: bool True on success, false if {

See also: clearUserWatchedItemsUsingJobQueue} must be used instead

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ clearUserWatchedItemsUsingJobQueue()

MediaWiki\Watchlist\WatchedItemStoreInterface::clearUserWatchedItemsUsingJobQueue ( UserIdentity $user )

Queues a job that will clear the users watchlist using the Job Queue.

Since: 1.31

Parameters

UserIdentity $user

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ countExpired()

MediaWiki\Watchlist\WatchedItemStoreInterface::countExpired ( )

Get the number of watchlist items that expire before the current time.

Since: 1.35

Returns: int

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

Referenced by PurgeExpiredWatchlistItems\execute(), and MediaWiki\Watchlist\WatchlistExpiryJob\run().

◆ countUnreadNotifications()

MediaWiki\Watchlist\WatchedItemStoreInterface::countUnreadNotifications	(	UserIdentity	$user,
			$unreadLimit = null )

Since: 1.31

Parameters

UserIdentity	$user
int \| null	$unreadLimit

Returns: int|bool The number of unread notifications true if greater than or equal to $unreadLimit

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ countVisitingWatchers()

MediaWiki\Watchlist\WatchedItemStoreInterface::countVisitingWatchers	(	PageReference	$target,
			$threshold )

Number of page watchers who also visited a "recent" edit.

Since: 1.31

Parameters

PageReference	$target
mixed	$threshold	timestamp accepted by wfTimestamp

Returns: int

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ countVisitingWatchersMultiple()

MediaWiki\Watchlist\WatchedItemStoreInterface::countVisitingWatchersMultiple	(	array	$targetsWithVisitThresholds,
			$minimumWatchers = null )

Number of watchers of each page who have visited recent edits to that page.

Since: 1.31

Parameters

array	$targetsWithVisitThresholds	array of pairs (PageReference $target, mixed $threshold), $threshold is: a timestamp of the recent edit if $target exists (format accepted by wfTimestamp) null if $target doesn't exist
int \| null	$minimumWatchers

Returns

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).

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ countWatchedItems()

MediaWiki\Watchlist\WatchedItemStoreInterface::countWatchedItems ( UserIdentity $user )

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

Parameters

UserIdentity $user

Returns: int

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ countWatchers()

MediaWiki\Watchlist\WatchedItemStoreInterface::countWatchers ( PageReference $target )

Since: 1.31

Parameters

PageReference $target

Returns: int

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ countWatchersMultiple()

MediaWiki\Watchlist\WatchedItemStoreInterface::countWatchersMultiple	(	array	$targets,
		array	$options = [] )

Since: 1.31

Parameters

PageReference[]	$targets
array	$options	Allowed keys: 'minimumWatchers' => int

Returns: 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.

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ duplicateAllAssociatedEntries()

MediaWiki\Watchlist\WatchedItemStoreInterface::duplicateAllAssociatedEntries	(	PageReference	$oldTarget,
		PageReference	$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.

Since: 1.31

Parameters

PageReference	$oldTarget
PageReference	$newTarget

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ duplicateEntry()

MediaWiki\Watchlist\WatchedItemStoreInterface::duplicateEntry	(	PageReference	$oldTarget,
		PageReference	$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

Parameters

PageReference	$oldTarget
PageReference	$newTarget

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ getLatestNotificationTimestamp()

MediaWiki\Watchlist\WatchedItemStoreInterface::getLatestNotificationTimestamp	(		$timestamp,
		UserIdentity	$user,
		PageReference	$target )

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

Parameters

string \| null	$timestamp	Value of wl_notificationtimestamp from the DB
UserIdentity	$user
PageReference	$target

Returns: string|null TS::MW timestamp of first unseen revision or null if there isn't one

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ getNotificationTimestampsBatch()

MediaWiki\Watchlist\WatchedItemStoreInterface::getNotificationTimestampsBatch	(	UserIdentity	$user,
		array	$targets )

Since: 1.31

Parameters

UserIdentity	$user
PageReference[]	$targets

Returns

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.

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ getWatchedItem()

MediaWiki\Watchlist\WatchedItemStoreInterface::getWatchedItem	(	UserIdentity	$user,
		PageReference	$target )

Get an item (may be cached)

Since: 1.31

Parameters

UserIdentity	$user
PageReference	$target

Returns: WatchedItem|false

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

Referenced by MediaWiki\Actions\WatchAction\__construct().

◆ getWatchedItemsForUser()

MediaWiki\Watchlist\WatchedItemStoreInterface::getWatchedItemsForUser	(	UserIdentity	$user,
		array	$options = [] )

Since: 1.31 Method Added

Parameters

UserIdentity	$user
array	$options	Allowed keys: 'forWrite': bool optional whether to use the primary database instead of a replica (defaults to false) 'sort': string optional self::SORT_ASC or self:SORT_DESC (defaults to SORT_ASC) 'offsetConds': optional array SQL conditions that the watched items must match 'namespaces': array 'limit': int max number of watched items to return

Returns: WatchedItem[]

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ isTempWatched()

MediaWiki\Watchlist\WatchedItemStoreInterface::isTempWatched	(	UserIdentity	$user,
		PageReference	$target )

Whether the page is only being watched temporarily (has expiry).

Must be called separately for Subject & Talk namespaces.

Since: 1.35

Parameters

UserIdentity	$user
PageReference	$target

Returns: bool

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ isWatched()

MediaWiki\Watchlist\WatchedItemStoreInterface::isWatched	(	UserIdentity	$user,
		PageReference	$target )

Must be called separately for Subject & Talk namespaces.

Since: 1.31

Parameters

UserIdentity	$user
PageReference	$target

Returns: bool

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ loadWatchedItem()

MediaWiki\Watchlist\WatchedItemStoreInterface::loadWatchedItem	(	UserIdentity	$user,
		PageReference	$target )

Loads an item from the db.

Since: 1.31

Parameters

UserIdentity	$user
PageReference	$target

Returns: WatchedItem|false

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ loadWatchedItemsBatch()

MediaWiki\Watchlist\WatchedItemStoreInterface::loadWatchedItemsBatch	(	UserIdentity	$user,
		array	$targets )

Loads a set of WatchedItems from the db.

Since: 1.36

Parameters

UserIdentity	$user
PageReference[]	$targets

Returns: WatchedItem[]

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ maybeEnqueueWatchlistExpiryJob()

MediaWiki\Watchlist\WatchedItemStoreInterface::maybeEnqueueWatchlistExpiryJob ( )

Probabilistically add a job to purge the expired watchlist items, if watchlist expiration is enabled, based on the value of $wgWatchlistPurgeRate.

Since: 1.36

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ mustClearWatchedItemsUsingJobQueue()

MediaWiki\Watchlist\WatchedItemStoreInterface::mustClearWatchedItemsUsingJobQueue ( UserIdentity $user )

Does the size of the users watchlist require clearUserWatchedItemsUsingJobQueue() to be used instead of clearUserWatchedItems()

Since: 1.35

Parameters

UserIdentity $user

Returns: bool

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ removeExpired()

MediaWiki\Watchlist\WatchedItemStoreInterface::removeExpired	(	int	$limit,
		bool	$deleteOrphans = false )

Remove some number of expired watchlist items.

Since: 1.35

Parameters

int	$limit	The number of items to remove.
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.

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

Referenced by PurgeExpiredWatchlistItems\execute(), and MediaWiki\Watchlist\WatchlistExpiryJob\run().

◆ removeLabels()

MediaWiki\Watchlist\WatchedItemStoreInterface::removeLabels	(	UserIdentity	$user,
		array	$targets,
		array	$labels )

Remove labels from a set of watchlist items.

The same labels are removed from each item. Ignore missing label members.

Since: 1.46

Parameters

UserIdentity	$user
PageReference[]	$targets
	(WatchlistLabel\|int)[]	$labels

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ removeWatch()

MediaWiki\Watchlist\WatchedItemStoreInterface::removeWatch	(	UserIdentity	$user,
		PageReference	$target )

Removes an entry for the UserIdentity watching the target Must be called separately for Subject & Talk namespaces.

Since: 1.31

Parameters

UserIdentity	$user
PageReference	$target

Returns: bool success

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ removeWatchBatchForUser()

MediaWiki\Watchlist\WatchedItemStoreInterface::removeWatchBatchForUser	(	UserIdentity	$user,
		array	$targets )

Since: 1.32

Parameters

UserIdentity	$user
PageReference[]	$targets

Returns: bool Whether any watched items were removed

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ resetAllNotificationTimestampsForUser()

MediaWiki\Watchlist\WatchedItemStoreInterface::resetAllNotificationTimestampsForUser	(	UserIdentity	$user,
			$timestamp = null )

Reset all watchlist notification timestamps for a user using the job queue.

Since: 1.31

Parameters

UserIdentity	$user	The user to reset the timestamps for
string \| int \| null	$timestamp	Value to set all timestamps to, null to clear them

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ resetNotificationTimestamp()

MediaWiki\Watchlist\WatchedItemStoreInterface::resetNotificationTimestamp	(	UserIdentity	$user,
		PageReference	$title,
			$force = '',
			$oldid = 0 )

Reset the notification timestamp of this entry.

Since: 1.31

Parameters

UserIdentity	$user
PageReference	$title
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
int	$oldid	The revision id being viewed. If not given or 0, latest revision is assumed.

Returns: bool success Whether a job was enqueued

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ setNotificationTimestampsForUser()

MediaWiki\Watchlist\WatchedItemStoreInterface::setNotificationTimestampsForUser	(	UserIdentity	$user,
			$timestamp,
		array	$targets = [] )

Since: 1.31

Parameters

UserIdentity	$user	The user to set the timestamps for
string \| null	$timestamp	Set the update timestamp to this value
PageReference[]	$targets	List of targets to update. Default to all targets.

Returns: bool success

Implemented in MediaWiki\Watchlist\NoWriteWatchedItemStore, and MediaWiki\Watchlist\WatchedItemStore.

◆ updateNotificationTimestamp()

MediaWiki\Watchlist\WatchedItemStoreInterface::updateNotificationTimestamp	(	UserIdentity	$editor,
		PageReference	$target,
			$timestamp )

Since: 1.31

Parameters

UserIdentity	$editor	The editor that triggered the update. Their notification timestamp will not be updated(they have already seen it)
PageReference	$target	The target to update timestamps for
string	$timestamp	Set the update (first unseen revision) timestamp to this value

Returns: int[] Array of user IDs the timestamp has been updated for

Implemented in MediaWiki\Watchlist\WatchedItemStore.

Member Data Documentation

◆ SORT_ASC

const MediaWiki\Watchlist\WatchedItemStoreInterface::SORT_ASC = 'ASC'

Since: 1.31

Definition at line 22 of file WatchedItemStoreInterface.php.

◆ SORT_DESC

const MediaWiki\Watchlist\WatchedItemStoreInterface::SORT_DESC = 'DESC'

Since: 1.31

Definition at line 27 of file WatchedItemStoreInterface.php.

The documentation for this interface was generated from the following file:

includes/Watchlist/WatchedItemStoreInterface.php

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ addLabels()

◆ addWatch()

◆ addWatchBatchForUser()

◆ clearUserWatchedItems()

◆ clearUserWatchedItemsUsingJobQueue()

◆ countExpired()

◆ countUnreadNotifications()

◆ countVisitingWatchers()

◆ countVisitingWatchersMultiple()

◆ countWatchedItems()

◆ countWatchers()

◆ countWatchersMultiple()

◆ duplicateAllAssociatedEntries()

◆ duplicateEntry()

◆ getLatestNotificationTimestamp()

◆ getNotificationTimestampsBatch()

◆ getWatchedItem()

◆ getWatchedItemsForUser()

◆ isTempWatched()

◆ isWatched()

◆ loadWatchedItem()

◆ loadWatchedItemsBatch()

◆ maybeEnqueueWatchlistExpiryJob()

◆ mustClearWatchedItemsUsingJobQueue()

◆ removeExpired()

◆ removeLabels()

◆ removeWatch()

◆ removeWatchBatchForUser()

◆ resetAllNotificationTimestampsForUser()

◆ resetNotificationTimestamp()

◆ setNotificationTimestampsForUser()

◆ updateNotificationTimestamp()

Member Data Documentation

◆ SORT_ASC

◆ SORT_DESC