MediaWiki master
MediaWiki\Watchlist\WatchedItemStore Class Reference

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, StatsFactory $statsFactory)
 
 addWatch (UserIdentity $user, $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 ( $target, $threshold)
 
 countVisitingWatchersMultiple (array $targetsWithVisitThresholds, $minimumWatchers=null)
 
 countWatchedItems (UserIdentity $user)
 
 countWatchers ( $target)
 
 countWatchersMultiple (array $targets, array $options=[])
 
 duplicateAllAssociatedEntries ( $oldTarget, $newTarget)
 
 duplicateEntry ( $oldTarget, $newTarget)
 
 getLatestNotificationTimestamp ( $timestamp, UserIdentity $user, $target)
 
 getMaxId ()
 
 getNotificationTimestampsBatch (UserIdentity $user, array $targets)
 
 getWatchedItem (UserIdentity $user, $target)
 
 getWatchedItemsForUser (UserIdentity $user, array $options=[])
 
 isTempWatched (UserIdentity $user, $target)
 Check if the user is temporarily watching the page.
 
 isWatched (UserIdentity $user, $target)
 
 loadWatchedItem (UserIdentity $user, $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)
 
 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$limitThe number of items to remove.
bool$deleteOrphansWhether 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.

 
 removeWatch (UserIdentity $user, $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, $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, $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,
StatsFactory $statsFactory )
Parameters
ServiceOptions$options
ILBFactory$lbFactory
JobQueueGroup$queueGroup
BagOStuff$stash
HashBagOStuff$cache
ReadOnlyMode$readOnlyMode
NamespaceInfo$nsInfo
RevisionLookup$revisionLookup
LinkBatchFactory$linkBatchFactory
StatsFactory$statsFactory

Definition at line 146 of file WatchedItemStore.php.

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

Member Function Documentation

◆ addWatch()

MediaWiki\Watchlist\WatchedItemStore::addWatch ( UserIdentity $user,
$target,
?string $expiry = null )
Since
1.27 Method added.
1.35 Accepts $expiry parameter.
Parameters
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
string | null$expiryOptional 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 1004 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
LinkTarget[]$targets
string | null$expiryOptional 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 1040 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 323 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 406 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 1805 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 1610 of file WatchedItemStore.php.

References MediaWiki\User\UserIdentity\getId().

◆ countVisitingWatchers()

MediaWiki\Watchlist\WatchedItemStore::countVisitingWatchers ( $target,
$threshold )
Since
1.27
Parameters
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
string | int$threshold
Returns
int

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 484 of file WatchedItemStore.php.

◆ countVisitingWatchersMultiple()

MediaWiki\Watchlist\WatchedItemStore::countVisitingWatchersMultiple ( array $targetsWithVisitThresholds,
$minimumWatchers = null )
Since
1.27
Parameters
array$targetsWithVisitThresholdsarray of LinkTarget[]|PageIdentity[] (not type hinted since it annoys phan) - deprecated passing LinkTarget[] since 1.36
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 620 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 444 of file WatchedItemStore.php.

◆ countWatchers()

MediaWiki\Watchlist\WatchedItemStore::countWatchers ( $target)
Since
1.27
Parameters
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
int

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 462 of file WatchedItemStore.php.

◆ countWatchersMultiple()

MediaWiki\Watchlist\WatchedItemStore::countWatchersMultiple ( array $targets,
array $options = [] )
Since
1.27
Parameters
LinkTarget[] | PageIdentity[]$targetsdeprecated passing LinkTarget[] since 1.36
array$optionsSupported options are:
  • 'minimumWatchers': filter for pages that have at least a minimum number of watchers
Returns
array

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 575 of file WatchedItemStore.php.

◆ duplicateAllAssociatedEntries()

MediaWiki\Watchlist\WatchedItemStore::duplicateAllAssociatedEntries ( $oldTarget,
$newTarget )
Since
1.27
Parameters
LinkTarget | PageIdentity$oldTargetdeprecated passing LinkTarget since 1.36
LinkTarget | PageIdentity$newTargetdeprecated passing LinkTarget since 1.36

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1642 of file WatchedItemStore.php.

◆ duplicateEntry()

MediaWiki\Watchlist\WatchedItemStore::duplicateEntry ( $oldTarget,
$newTarget )
Since
1.27
Parameters
LinkTarget | PageIdentity$oldTargetdeprecated passing LinkTarget since 1.36
LinkTarget | PageIdentity$newTargetdeprecated passing LinkTarget since 1.36

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1660 of file WatchedItemStore.php.

◆ getLatestNotificationTimestamp()

MediaWiki\Watchlist\WatchedItemStore::getLatestNotificationTimestamp ( $timestamp,
UserIdentity $user,
$target )
Parameters
string | null$timestamp
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
bool|string|null

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1282 of file WatchedItemStore.php.

References wfTimestampOrNull().

◆ getMaxId()

MediaWiki\Watchlist\WatchedItemStore::getMaxId ( )
Since
1.31
Returns
int The maximum current wl_id

Definition at line 431 of file WatchedItemStore.php.

◆ getNotificationTimestampsBatch()

MediaWiki\Watchlist\WatchedItemStore::getNotificationTimestampsBatch ( UserIdentity $user,
array $targets )
Since
1.27
Parameters
UserIdentity$user
LinkTarget[]$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 947 of file WatchedItemStore.php.

◆ getWatchedItem()

MediaWiki\Watchlist\WatchedItemStore::getWatchedItem ( UserIdentity $user,
$target )
Since
1.27
Parameters
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
WatchedItem|false

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 707 of file WatchedItemStore.php.

References MediaWiki\User\UserIdentity\isRegistered().

Referenced by WatchAction\__construct().

◆ getWatchedItemsForUser()

MediaWiki\Watchlist\WatchedItemStore::getWatchedItemsForUser ( UserIdentity $user,
array $options = [] )
Since
1.27
Parameters
UserIdentity$user
array$optionsSupported options are:
  • 'forWrite': whether to use the primary database instead of a replica
  • 'sort': how to sort the titles, either SORT_ASC or SORT_DESC
  • 'sortByExpiry': whether to also sort results by expiration, with temporarily watched titles above titles watched indefinitely and titles expiring soonest at the top
Returns
WatchedItem[]

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 786 of file WatchedItemStore.php.

◆ isTempWatched()

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

Check if the user is temporarily watching the page.

Since
1.35
Parameters
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 935 of file WatchedItemStore.php.

◆ isWatched()

MediaWiki\Watchlist\WatchedItemStore::isWatched ( UserIdentity $user,
$target )
Since
1.27
Parameters
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 924 of file WatchedItemStore.php.

◆ loadWatchedItem()

MediaWiki\Watchlist\WatchedItemStore::loadWatchedItem ( UserIdentity $user,
$target )
Since
1.27
Parameters
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
WatchedItem|false

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 733 of file WatchedItemStore.php.

◆ loadWatchedItemsBatch()

MediaWiki\Watchlist\WatchedItemStore::loadWatchedItemsBatch ( UserIdentity $user,
array $targets )
Since
1.36
Parameters
UserIdentity$user
LinkTarget[] | PageIdentity[]$targetsdeprecated passing LinkTarget[] since 1.36
Returns
WatchedItem[]|false

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 744 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 414 of file WatchedItemStore.php.

◆ mustClearWatchedItemsUsingJobQueue()

MediaWiki\Watchlist\WatchedItemStore::mustClearWatchedItemsUsingJobQueue ( UserIdentity $user)
Parameters
UserIdentity$user
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 368 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 signiture
Returns
ScopedCallback to reset the overridden value

Definition at line 189 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$limitThe number of items to remove.
bool$deleteOrphansWhether 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 1818 of file WatchedItemStore.php.

◆ removeWatch()

MediaWiki\Watchlist\WatchedItemStore::removeWatch ( UserIdentity $user,
$target )
Since
1.27
Parameters
UserIdentity$user
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1192 of file WatchedItemStore.php.

◆ removeWatchBatchForUser()

MediaWiki\Watchlist\WatchedItemStore::removeWatchBatchForUser ( UserIdentity $user,
array $titles )
Parameters
UserIdentity$user
LinkTarget[] | PageIdentity[]$titlesdeprecated passing LinkTarget[] since 1.36
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 508 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$timestampValue to set all timestamps to, null to clear them

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1310 of file WatchedItemStore.php.

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

◆ resetNotificationTimestamp()

MediaWiki\Watchlist\WatchedItemStore::resetNotificationTimestamp ( UserIdentity $user,
$title,
$force = '',
$oldid = 0 )
Since
1.27
Parameters
UserIdentity$user
LinkTarget | PageIdentity$titledeprecated passing LinkTarget since 1.36
string$force
int$oldid
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1408 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$timestampValue to set the "last viewed" timestamp to (null to clear)
LinkTarget[]$targetsTitles to set the timestamp for; [] means the entire watchlist
Returns
bool

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1213 of file WatchedItemStore.php.

◆ updateNotificationTimestamp()

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

Update wl_notificationtimestamp for all watching users except the editor.

Since
1.27
Parameters
UserIdentity$editor
LinkTarget | PageIdentity$targetdeprecated passing LinkTarget since 1.36
string | int$timestamp
Returns
int[]

Implements MediaWiki\Watchlist\WatchedItemStoreInterface.

Definition at line 1339 of file WatchedItemStore.php.

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS

const MediaWiki\Watchlist\WatchedItemStore::CONSTRUCTOR_OPTIONS
Initial value:
= [
]
const UpdateRowsPerQuery
Name constant for the UpdateRowsPerQuery setting, for use with Config::get()
const WatchlistPurgeRate
Name constant for the WatchlistPurgeRate setting, for use with Config::get()
const WatchlistExpiry
Name constant for the WatchlistExpiry setting, for use with Config::get()
const WatchlistExpiryMaxDuration
Name constant for the WatchlistExpiryMaxDuration setting, for use with Config::get()
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: