Storage layer class for WatchedItems. More...

Inherits MediaWiki\Watchlist\WatchedItemStoreInterface.

Collaboration diagram for MediaWiki\Watchlist\WatchedItemStore:

Public Member Functions

__construct (ServiceOptions $options, ILBFactory $lbFactory, JobQueueGroup $queueGroup, BagOStuff $stash, HashBagOStuff $cache, ReadOnlyMode $readOnlyMode, NamespaceInfo $nsInfo, RevisionLookup $revisionLookup, LinkBatchFactory $linkBatchFactory, WatchlistLabelStore $labelStore,)

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

addWatch (UserIdentity $user, PageReference $target, ?string $expiry=null)

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

Add multiple items to the user's watchlist.

clearUserWatchedItems (UserIdentity $user)

Deletes ALL watched items for the given user when under $updateRowsPerQuery entries exist.

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.

Since: 1.35

Returns: int

countUnreadNotifications (UserIdentity $user, $unreadLimit=null)

countVisitingWatchers (PageReference $target, $threshold)

countVisitingWatchersMultiple (array $targetsWithVisitThresholds, $minimumWatchers=null)

countWatchedItems (UserIdentity $user)

countWatchers (PageReference $target)

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

duplicateAllAssociatedEntries (PageReference $oldTarget, PageReference $newTarget)

duplicateEntry (PageReference $oldTarget, PageReference $newTarget)

getLatestNotificationTimestamp ( $timestamp, UserIdentity $user, PageReference $target)

getMaxId ()

getNotificationTimestampsBatch (UserIdentity $user, array $targets)

getWatchedItem (UserIdentity $user, PageReference $target)

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

isTempWatched (UserIdentity $user, PageReference $target)

Check if the user is temporarily watching the page.

isWatched (UserIdentity $user, PageReference $target)

loadWatchedItem (UserIdentity $user, PageReference $target)

loadWatchedItemsBatch (UserIdentity $user, array $targets)

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

mustClearWatchedItemsUsingJobQueue (UserIdentity $user)

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

overrideDeferredUpdatesAddCallableUpdateCallback (callable $callback)

Overrides the DeferredUpdates::addCallableUpdate callback This is intended for use while testing and will fail if MW_PHPUNIT_TEST is not defined.

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.

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

removeWatch (UserIdentity $user, PageReference $target)

removeWatchBatchForUser (UserIdentity $user, array $titles)

resetAllNotificationTimestampsForUser (UserIdentity $user, $timestamp=null)

Schedule a DeferredUpdate that sets all of the "last viewed" timestamps for a given user to the same value.

resetNotificationTimestamp (UserIdentity $user, PageReference $title, $force='', $oldid=0)

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

Set the "last viewed" timestamps for certain titles on a user's watchlist.

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

Update wl_notificationtimestamp for all watching users except the editor.

Public Attributes
const	CONSTRUCTOR_OPTIONS

Public Attributes inherited from MediaWiki\Watchlist\WatchedItemStoreInterface
const	SORT_ASC = 'ASC'

const	SORT_DESC = 'DESC'

Detailed Description

Storage layer class for WatchedItems.

Database interaction & caching TODO caching should be factored out into a CachingWatchedItemStore class

Author: Addshore

Since: 1.27

Definition at line 42 of file WatchedItemStore.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Watchlist\WatchedItemStore::__construct	(	ServiceOptions	$options,
		ILBFactory	$lbFactory,
		JobQueueGroup	$queueGroup,
		BagOStuff	$stash,
		HashBagOStuff	$cache,
		ReadOnlyMode	$readOnlyMode,
		NamespaceInfo	$nsInfo,
		RevisionLookup	$revisionLookup,
		LinkBatchFactory	$linkBatchFactory,
		WatchlistLabelStore	$labelStore )

Definition at line 137 of file WatchedItemStore.php.

References MediaWiki\Config\ServiceOptions\assertRequiredOptions(), MediaWiki\MainConfigNames\EnableWatchlistLabels, MediaWiki\Config\ServiceOptions\get(), MediaWiki\MainConfigNames\UpdateRowsPerQuery, MediaWiki\MainConfigNames\WatchlistExpiry, MediaWiki\MainConfigNames\WatchlistExpiryMaxDuration, and MediaWiki\MainConfigNames\WatchlistPurgeRate.

Member Function Documentation

◆ addLabels()

MediaWiki\Watchlist\WatchedItemStore::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

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1833 of file WatchedItemStore.php.

◆ addWatch()

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

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

Parameters

UserIdentity	$user
PageReference	$target
string \| null	$expiry	Optional expiry in any format acceptable to wfTimestamp(). null will not create an expiry, or leave it unchanged should one already exist.

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 950 of file WatchedItemStore.php.

◆ addWatchBatchForUser()

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

Add multiple items to the user's watchlist.

If you know you're adding a single page (and/or its talk page) use self::addWatch(), since it will add the WatchedItem to the process cache.

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

Parameters

UserIdentity	$user
PageReference[]	$targets
string \| null	$expiry	Optional expiry in a format acceptable to wfTimestamp(), null will not create expiries, or leave them unchanged should they already exist.

Returns: bool Whether database transactions were performed.

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 991 of file WatchedItemStore.php.

◆ clearUserWatchedItems()

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

Deletes ALL watched items for the given user when under $updateRowsPerQuery entries exist.

Since: 1.30

Parameters

UserIdentity $user

Returns: bool true on success, false when too many items are watched

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 297 of file WatchedItemStore.php.

◆ clearUserWatchedItemsUsingJobQueue()

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

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

Since: 1.31

Parameters

UserIdentity $user

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 373 of file WatchedItemStore.php.

References $job.

◆ countExpired()

MediaWiki\Watchlist\WatchedItemStore::countExpired ( )

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

Since: 1.35

Returns: int

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1763 of file WatchedItemStore.php.

◆ countUnreadNotifications()

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

Since: 1.27

Parameters

UserIdentity	$user
int \| null	$unreadLimit

Returns: int|bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1533 of file WatchedItemStore.php.

References MediaWiki\User\UserIdentity\getId().

◆ countVisitingWatchers()

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

Since: 1.27

Parameters

PageReference	$target
string \| int	$threshold

Returns: int

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 451 of file WatchedItemStore.php.

◆ countVisitingWatchersMultiple()

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

Since: 1.27

Parameters

array	$targetsWithVisitThresholds	array of pairs (PageReference, last visit threshold)
int \| null	$minimumWatchers

Returns: int[][] two dimensional array, first is namespace, second is database key, value is the number of watchers

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 565 of file WatchedItemStore.php.

◆ countWatchedItems()

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

Since: 1.31

Parameters

UserIdentity $user

Returns: int

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 411 of file WatchedItemStore.php.

◆ countWatchers()

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

Since: 1.27

Parameters

PageReference $target

Returns: int

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 429 of file WatchedItemStore.php.

◆ countWatchersMultiple()

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

Since: 1.27

Parameters

PageReference[]	$targets
array	$options	Supported options are: 'minimumWatchers': filter for pages that have at least a minimum number of watchers

Returns: array

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 526 of file WatchedItemStore.php.

◆ duplicateAllAssociatedEntries()

MediaWiki\Watchlist\WatchedItemStore::duplicateAllAssociatedEntries	(	PageReference	$oldTarget,
		PageReference	$newTarget )

Since: 1.27

Parameters

PageReference	$oldTarget
PageReference	$newTarget

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1565 of file WatchedItemStore.php.

References MediaWiki\Page\PageReference\getDBkey(), and MediaWiki\Page\PageReference\getNamespace().

◆ duplicateEntry()

MediaWiki\Watchlist\WatchedItemStore::duplicateEntry	(	PageReference	$oldTarget,
		PageReference	$newTarget )

Since: 1.27

Parameters

PageReference	$oldTarget
PageReference	$newTarget

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1597 of file WatchedItemStore.php.

References MediaWiki\Page\PageReference\getDBkey(), and MediaWiki\Page\PageReference\getNamespace().

◆ getLatestNotificationTimestamp()

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

Parameters

string \| null	$timestamp
UserIdentity	$user
PageReference	$target

Returns: bool|string|null

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1214 of file WatchedItemStore.php.

References wfTimestampOrNull().

◆ getMaxId()

MediaWiki\Watchlist\WatchedItemStore::getMaxId ( )

Since: 1.31

Returns: int The maximum current wl_id

Definition at line 398 of file WatchedItemStore.php.

◆ getNotificationTimestampsBatch()

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

Since: 1.27

Parameters

UserIdentity	$user
PageReference[]	$targets

Returns: (string|null|false)[][] two dimensional array, first is namespace, second is database key, value is the notification timestamp or null, or false if not available

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 895 of file WatchedItemStore.php.

◆ getWatchedItem()

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

Since: 1.27

Parameters

UserIdentity	$user
PageReference	$target

Returns: WatchedItem|false

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 649 of file WatchedItemStore.php.

References MediaWiki\User\UserIdentity\isRegistered().

◆ getWatchedItemsForUser()

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

Since: 1.27

Parameters

UserIdentity	$user
array	$options	Supported options are: '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 self::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[]

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 726 of file WatchedItemStore.php.

◆ isTempWatched()

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

Check if the user is temporarily watching the page.

Since: 1.35

Parameters

UserIdentity	$user
PageReference	$target

Returns: bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 883 of file WatchedItemStore.php.

◆ isWatched()

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

Since: 1.27

Parameters

UserIdentity	$user
PageReference	$target

Returns: bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 872 of file WatchedItemStore.php.

◆ loadWatchedItem()

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

Since: 1.27

Parameters

UserIdentity	$user
PageReference	$target

Returns: WatchedItem|false

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 667 of file WatchedItemStore.php.

◆ loadWatchedItemsBatch()

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

Since: 1.36

Parameters

UserIdentity	$user
PageReference[]	$targets

Returns: WatchedItem[]

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 678 of file WatchedItemStore.php.

References MediaWiki\User\UserIdentity\isRegistered().

◆ maybeEnqueueWatchlistExpiryJob()

MediaWiki\Watchlist\WatchedItemStore::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

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 381 of file WatchedItemStore.php.

◆ mustClearWatchedItemsUsingJobQueue()

MediaWiki\Watchlist\WatchedItemStore::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

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 338 of file WatchedItemStore.php.

◆ overrideDeferredUpdatesAddCallableUpdateCallback()

MediaWiki\Watchlist\WatchedItemStore::overrideDeferredUpdatesAddCallableUpdateCallback ( callable $callback )

Overrides the DeferredUpdates::addCallableUpdate callback This is intended for use while testing and will fail if MW_PHPUNIT_TEST is not defined.

Parameters

callable $callback

See also: DeferredUpdates::addCallableUpdate for callback signature

Definition at line 180 of file WatchedItemStore.php.

◆ removeExpired()

MediaWiki\Watchlist\WatchedItemStore::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.

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1776 of file WatchedItemStore.php.

◆ removeLabels()

MediaWiki\Watchlist\WatchedItemStore::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

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1866 of file WatchedItemStore.php.

◆ removeWatch()

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

Since: 1.27

Parameters

UserIdentity	$user
PageReference	$target

Returns: bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1143 of file WatchedItemStore.php.

◆ removeWatchBatchForUser()

MediaWiki\Watchlist\WatchedItemStore::removeWatchBatchForUser	(	UserIdentity	$user,
		array	$titles )

Parameters

UserIdentity	$user
PageReference[]	$titles

Returns: bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 474 of file WatchedItemStore.php.

◆ resetAllNotificationTimestampsForUser()

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

Schedule a DeferredUpdate that sets all of the "last viewed" timestamps for a given user to the same value.

Parameters

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

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1242 of file WatchedItemStore.php.

References $job, MediaWiki\User\UserIdentity\getId(), and MediaWiki\User\UserIdentity\isRegistered().

◆ resetNotificationTimestamp()

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

Since: 1.27

Parameters

UserIdentity	$user
PageReference	$title
string	$force
int	$oldid

Returns: bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1338 of file WatchedItemStore.php.

◆ setNotificationTimestampsForUser()

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

Set the "last viewed" timestamps for certain titles on a user's watchlist.

If the $targets parameter is omitted or set to [], this method simply wraps resetAllNotificationTimestampsForUser(), and in that case you should instead call that method directly; support for omitting $targets is for backwards compatibility.

If $targets is omitted or set to [], timestamps will be updated for every title on the user's watchlist, and this will be done through a DeferredUpdate. If $targets is a non-empty array, only the specified titles will be updated, and this will be done immediately (not deferred).

Since: 1.27

Parameters

UserIdentity	$user
string \| int	$timestamp	Value to set the "last viewed" timestamp to (null to clear)
PageReference[]	$targets	Titles to set the timestamp for; [] means the entire watchlist

Returns: bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1164 of file WatchedItemStore.php.

◆ updateNotificationTimestamp()

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

Update wl_notificationtimestamp for all watching users except the editor.

Since: 1.27

Parameters

UserIdentity	$editor
PageReference	$target
string \| int	$timestamp

Returns: int[]

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1270 of file WatchedItemStore.php.

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS

const MediaWiki\Watchlist\WatchedItemStore::CONSTRUCTOR_OPTIONS

Initial value:

= [
        MainConfigNames::UpdateRowsPerQuery,
        MainConfigNames::WatchlistExpiry,
        MainConfigNames::WatchlistExpiryMaxDuration,
        MainConfigNames::WatchlistPurgeRate,
        MainConfigNames::EnableWatchlistLabels,
    ]

Access: internal: For use by ServiceWiring

Definition at line 47 of file WatchedItemStore.php.

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

includes/Watchlist/WatchedItemStore.php

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addLabels()

◆ addWatch()

◆ addWatchBatchForUser()

◆ clearUserWatchedItems()

◆ clearUserWatchedItemsUsingJobQueue()

◆ countExpired()

◆ countUnreadNotifications()

◆ countVisitingWatchers()

◆ countVisitingWatchersMultiple()

◆ countWatchedItems()

◆ countWatchers()

◆ countWatchersMultiple()

◆ duplicateAllAssociatedEntries()

◆ duplicateEntry()

◆ getLatestNotificationTimestamp()

◆ getMaxId()

◆ getNotificationTimestampsBatch()

◆ getWatchedItem()

◆ getWatchedItemsForUser()

◆ isTempWatched()

◆ isWatched()

◆ loadWatchedItem()

◆ loadWatchedItemsBatch()

◆ maybeEnqueueWatchlistExpiryJob()

◆ mustClearWatchedItemsUsingJobQueue()

◆ overrideDeferredUpdatesAddCallableUpdateCallback()

◆ removeExpired()

◆ removeLabels()

◆ removeWatch()

◆ removeWatchBatchForUser()

◆ resetAllNotificationTimestampsForUser()

◆ resetNotificationTimestamp()

◆ setNotificationTimestampsForUser()

◆ updateNotificationTimestamp()

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS