MediaWiki  master
WatchedItemStoreInterface Interface Reference
Inheritance diagram for WatchedItemStoreInterface:

Public Member Functions

 addWatch (UserIdentity $user, LinkTarget $target, ?string $expiry=null)
 Must be called separately for Subject & Talk namespaces. More...
 
 addWatchBatchForUser (UserIdentity $user, array $targets, ?string $expiry=null)
 
 clearUserWatchedItems (UserIdentity $user)
 Synchronously clear the users watchlist. More...
 
 clearUserWatchedItemsUsingJobQueue (UserIdentity $user)
 Queues a job that will clear the users watchlist using the Job Queue. More...
 
 countExpired ()
 Get the number of watchlist items that expire before the current time. More...
 
 countUnreadNotifications (UserIdentity $user, $unreadLimit=null)
 
 countVisitingWatchers (LinkTarget $target, $threshold)
 Number of page watchers who also visited a "recent" edit. More...
 
 countVisitingWatchersMultiple (array $targetsWithVisitThresholds, $minimumWatchers=null)
 Number of watchers of each page who have visited recent edits to that page. More...
 
 countWatchedItems (UserIdentity $user)
 Count the number of individual items that are watched by the user. More...
 
 countWatchers (LinkTarget $target)
 
 countWatchersMultiple (array $targets, array $options=[])
 
 duplicateAllAssociatedEntries (LinkTarget $oldTarget, LinkTarget $newTarget)
 Check if the given title already is watched by the user, and if so add a watch for the new title. More...
 
 duplicateEntry (LinkTarget $oldTarget, LinkTarget $newTarget)
 Check if the given title already is watched by the user, and if so add a watch for the new title. More...
 
 enqueueWatchlistExpiryJob (float $watchlistPurgeRate)
 Probabilistically add a job to purge the expired watchlist items. More...
 
 getLatestNotificationTimestamp ( $timestamp, UserIdentity $user, LinkTarget $target)
 Convert $timestamp to TS_MW or return null if the page was visited since then by $user. More...
 
 getNotificationTimestampsBatch (UserIdentity $user, array $targets)
 
 getWatchedItem (UserIdentity $user, LinkTarget $target)
 Get an item (may be cached) More...
 
 getWatchedItemsForUser (UserIdentity $user, array $options=[])
 
 isTempWatched (UserIdentity $user, LinkTarget $target)
 Whether the page is only being watched temporarily (has expiry). More...
 
 isWatched (UserIdentity $user, LinkTarget $target)
 Must be called separately for Subject & Talk namespaces. More...
 
 loadWatchedItem (UserIdentity $user, LinkTarget $target)
 Loads an item from the db. More...
 
 mustClearWatchedItemsUsingJobQueue (UserIdentity $user)
 Does the size of the users watchlist require clearUserWatchedItemsUsingJobQueue() to be used instead of clearUserWatchedItems() More...
 
 removeExpired (int $limit, bool $deleteOrphans=false)
 Remove some number of expired watchlist items. More...
 
 removeWatch (UserIdentity $user, LinkTarget $target)
 Removes an entry for the UserIdentity watching the LinkTarget Must be called separately for Subject & Talk namespaces. More...
 
 removeWatchBatchForUser (UserIdentity $user, array $targets)
 
 resetAllNotificationTimestampsForUser (UserIdentity $user, $timestamp=null)
 Reset all watchlist notificaton timestamps for a user using the job queue. More...
 
 resetNotificationTimestamp (UserIdentity $user, LinkTarget $title, $force='', $oldid=0)
 Reset the notification timestamp of this entry. More...
 
 setNotificationTimestampsForUser (UserIdentity $user, $timestamp, array $targets=[])
 
 updateNotificationTimestamp (UserIdentity $editor, LinkTarget $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 30 of file WatchedItemStoreInterface.php.

Member Function Documentation

◆ addWatch()

WatchedItemStoreInterface::addWatch ( UserIdentity  $user,
LinkTarget  $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
LinkTarget$target
string | null$expiryOptional expiry timestamp in any format acceptable to wfTimestamp(). null will not create an expiry, or leave it unchanged should one already exist.

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ addWatchBatchForUser()

WatchedItemStoreInterface::addWatchBatchForUser ( UserIdentity  $user,
array  $targets,
?string  $expiry = null 
)
Since
1.31 Method added.
1.35 Accepts $expiry parameter.
Parameters
UserIdentity$user
LinkTarget[]$targets
string | null$expiryOptional 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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ clearUserWatchedItems()

WatchedItemStoreInterface::clearUserWatchedItems ( UserIdentity  $user)

Synchronously clear the users watchlist.

Since
1.31
Parameters
UserIdentity$user

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ clearUserWatchedItemsUsingJobQueue()

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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ countExpired()

WatchedItemStoreInterface::countExpired ( )

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

Since
1.35
Returns
int

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ countUnreadNotifications()

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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ countVisitingWatchers()

WatchedItemStoreInterface::countVisitingWatchers ( LinkTarget  $target,
  $threshold 
)

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

Since
1.31
Parameters
LinkTarget$target
mixed$thresholdtimestamp accepted by wfTimestamp
Returns
int
Exceptions
DBUnexpectedError
MWException

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ countVisitingWatchersMultiple()

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$targetsWithVisitThresholdsarray of pairs (LinkTarget $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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ countWatchedItems()

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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ countWatchers()

WatchedItemStoreInterface::countWatchers ( LinkTarget  $target)
Since
1.31
Parameters
LinkTarget$target
Returns
int

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ countWatchersMultiple()

WatchedItemStoreInterface::countWatchersMultiple ( array  $targets,
array  $options = [] 
)
Since
1.31
Parameters
LinkTarget[]$targets
array$optionsAllowed 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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ duplicateAllAssociatedEntries()

WatchedItemStoreInterface::duplicateAllAssociatedEntries ( LinkTarget  $oldTarget,
LinkTarget  $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
LinkTarget$oldTarget
LinkTarget$newTarget

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ duplicateEntry()

WatchedItemStoreInterface::duplicateEntry ( LinkTarget  $oldTarget,
LinkTarget  $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
LinkTarget$oldTarget
LinkTarget$newTarget

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ enqueueWatchlistExpiryJob()

WatchedItemStoreInterface::enqueueWatchlistExpiryJob ( float  $watchlistPurgeRate)

Probabilistically add a job to purge the expired watchlist items.

Since
1.35
Parameters
float$watchlistPurgeRateThe value of the $wgWatchlistPurgeRate configuration variable.

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ getLatestNotificationTimestamp()

WatchedItemStoreInterface::getLatestNotificationTimestamp (   $timestamp,
UserIdentity  $user,
LinkTarget  $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$timestampValue of wl_notificationtimestamp from the DB
UserIdentity$user
LinkTarget$target
Returns
string|null TS_MW timestamp of first unseen revision or null if there isn't one

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ getNotificationTimestampsBatch()

WatchedItemStoreInterface::getNotificationTimestampsBatch ( UserIdentity  $user,
array  $targets 
)
Since
1.31
Parameters
UserIdentity$user
LinkTarget[]$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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ getWatchedItem()

WatchedItemStoreInterface::getWatchedItem ( UserIdentity  $user,
LinkTarget  $target 
)

Get an item (may be cached)

Since
1.31
Parameters
UserIdentity$user
LinkTarget$target
Returns
WatchedItem|false

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

Referenced by getWatchlistExpiry().

◆ getWatchedItemsForUser()

WatchedItemStoreInterface::getWatchedItemsForUser ( UserIdentity  $user,
array  $options = [] 
)
Since
1.31 Method Added
1.35 Allows 'sortByExpiry' as a key in $options
Parameters
UserIdentity$user
array$optionsAllowed 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.
Returns
WatchedItem[]

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ isTempWatched()

WatchedItemStoreInterface::isTempWatched ( UserIdentity  $user,
LinkTarget  $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
LinkTarget$target
Returns
bool

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ isWatched()

WatchedItemStoreInterface::isWatched ( UserIdentity  $user,
LinkTarget  $target 
)

Must be called separately for Subject & Talk namespaces.

Since
1.31
Parameters
UserIdentity$user
LinkTarget$target
Returns
bool

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ loadWatchedItem()

WatchedItemStoreInterface::loadWatchedItem ( UserIdentity  $user,
LinkTarget  $target 
)

Loads an item from the db.

Since
1.31
Parameters
UserIdentity$user
LinkTarget$target
Returns
WatchedItem|false

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ mustClearWatchedItemsUsingJobQueue()

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 WatchedItemStore, and NoWriteWatchedItemStore.

◆ removeExpired()

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

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ removeWatch()

WatchedItemStoreInterface::removeWatch ( UserIdentity  $user,
LinkTarget  $target 
)

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

Since
1.31
Parameters
UserIdentity$user
LinkTarget$target
Returns
bool success
Exceptions
DBUnexpectedError
MWException

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ removeWatchBatchForUser()

WatchedItemStoreInterface::removeWatchBatchForUser ( UserIdentity  $user,
array  $targets 
)
Since
1.32
Parameters
UserIdentity$user
LinkTarget[]$targets
Returns
bool success

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ resetAllNotificationTimestampsForUser()

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

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

Since
1.31
Parameters
UserIdentity$userThe user to reset the timestamps for
string | int | null$timestampValue to set all timestamps to, null to clear them

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ resetNotificationTimestamp()

WatchedItemStoreInterface::resetNotificationTimestamp ( UserIdentity  $user,
LinkTarget  $title,
  $force = '',
  $oldid = 0 
)

Reset the notification timestamp of this entry.

Since
1.31
Parameters
UserIdentity$user
LinkTarget$title
string$forceWhether 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$oldidThe revision id being viewed. If not given or 0, latest revision is assumed.
Returns
bool success Whether a job was enqueued

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ setNotificationTimestampsForUser()

WatchedItemStoreInterface::setNotificationTimestampsForUser ( UserIdentity  $user,
  $timestamp,
array  $targets = [] 
)
Since
1.31
Parameters
UserIdentity$userThe user to set the timestamps for
string | null$timestampSet the update timestamp to this value
LinkTarget[]$targetsList of targets to update. Default to all targets
Returns
bool success

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

◆ updateNotificationTimestamp()

WatchedItemStoreInterface::updateNotificationTimestamp ( UserIdentity  $editor,
LinkTarget  $target,
  $timestamp 
)
Since
1.31
Parameters
UserIdentity$editorThe editor that triggered the update. Their notification timestamp will not be updated(they have already seen it)
LinkTarget$targetThe target to update timestamps for
string$timestampSet the update (first unseen revision) timestamp to this value
Returns
int[] Array of user IDs the timestamp has been updated for

Implemented in WatchedItemStore, and NoWriteWatchedItemStore.

Member Data Documentation

◆ SORT_ASC

const WatchedItemStoreInterface::SORT_ASC = 'ASC'

◆ SORT_DESC

const WatchedItemStoreInterface::SORT_DESC = 'DESC'
Since
1.31

Definition at line 40 of file WatchedItemStoreInterface.php.

Referenced by ApiQueryWatchlistRaw\run().


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