Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2/**
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
17 *
18 * @file
19 * @ingroup Watchlist
20 */
21
22namespace MediaWiki\Watchlist;
23
24use MediaWiki\Linker\LinkTarget;
25use MediaWiki\Page\PageIdentity;
26use MediaWiki\User\UserIdentity;
27
28/**
29 * @author Addshore
30 * @since 1.31 interface created. WatchedItemStore implementation available since 1.27
31 */
32interface WatchedItemStoreInterface {
33
34    /**
35     * @since 1.31
36     */
37    public const SORT_ASC = 'ASC';
38
39    /**
40     * @since 1.31
41     */
42    public const SORT_DESC = 'DESC';
43
44    /**
45     * Count the number of individual items that are watched by the user.
46     * If a subject and corresponding talk page are watched this will return 2.
47     *
48     * @since 1.31
49     *
50     * @param UserIdentity $user
51     *
52     * @return int
53     */
54    public function countWatchedItems( UserIdentity $user );
55
56    /**
57     * @since 1.31
58     *
59     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
60     *
61     * @return int
62     */
63    public function countWatchers( $target );
64
65    /**
66     * Number of page watchers who also visited a "recent" edit
67     *
68     * @since 1.31
69     *
70     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
71     * @param mixed $threshold timestamp accepted by wfTimestamp
72     *
73     * @return int
74     */
75    public function countVisitingWatchers( $target, $threshold );
76
77    /**
78     * @since 1.31
79     *
80     * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
81     * @param array $options Allowed keys:
82     *        'minimumWatchers' => int
83     *
84     * @return array multi dimensional like $return[$namespaceId][$titleString] = int $watchers
85     *         All targets will be present in the result. 0 either means no watchers or the number
86     *         of watchers was below the minimumWatchers option if passed.
87     */
88    public function countWatchersMultiple( array $targets, array $options = [] );
89
90    /**
91     * Number of watchers of each page who have visited recent edits to that page
92     *
93     * @since 1.31
94     *
95     * @param array $targetsWithVisitThresholds array of pairs (LinkTarget|PageIdentity $target,
96     *     mixed $threshold),
97     *        $threshold is:
98     *        - a timestamp of the recent edit if $target exists (format accepted by wfTimestamp)
99     *        - null if $target doesn't exist
100     *      deprecated passing LinkTarget since 1.36
101     * @param int|null $minimumWatchers
102     *
103     * @return array multi-dimensional like $return[$namespaceId][$titleString] = $watchers,
104     *         where $watchers is an int:
105     *         - if the page exists, number of users watching who have visited the page recently
106     *         - if the page doesn't exist, number of users that have the page on their watchlist
107     *         - 0 means there are no visiting watchers or their number is below the
108     *     minimumWatchers
109     *         option (if passed).
110     */
111    public function countVisitingWatchersMultiple(
112        array $targetsWithVisitThresholds,
113        $minimumWatchers = null
114    );
115
116    /**
117     * Get an item (may be cached)
118     *
119     * @since 1.31
120     *
121     * @param UserIdentity $user
122     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
123     *
124     * @return WatchedItem|false
125     */
126    public function getWatchedItem( UserIdentity $user, $target );
127
128    /**
129     * Loads an item from the db
130     *
131     * @since 1.31
132     *
133     * @param UserIdentity $user
134     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
135     *
136     * @return WatchedItem|false
137     */
138    public function loadWatchedItem( UserIdentity $user, $target );
139
140    /**
141     * Loads a set of WatchedItems from the db.
142     *
143     * @since 1.36
144     *
145     * @param UserIdentity $user
146     * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
147     *
148     * @return WatchedItem[]|false
149     */
150    public function loadWatchedItemsBatch( UserIdentity $user, array $targets );
151
152    /**
153     * @since 1.31 Method Added
154     * @since 1.35 Allows 'sortByExpiry' as a key in $options
155     *
156     * @param UserIdentity $user
157     * @param array $options Allowed keys:
158     *        'forWrite' => bool defaults to false
159     *        'sort' => string optional sorting by namespace ID and title
160     *                     one of the self::SORT_* constants
161     *        'sortByExpiry' => bool optional sorts by expiration date, with the titles
162     *                     that will expire soonest at the top.
163     *
164     * @return WatchedItem[]
165     */
166    public function getWatchedItemsForUser( UserIdentity $user, array $options = [] );
167
168    /**
169     * Must be called separately for Subject & Talk namespaces
170     *
171     * @since 1.31
172     *
173     * @param UserIdentity $user
174     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
175     *
176     * @return bool
177     */
178    public function isWatched( UserIdentity $user, $target );
179
180    /**
181     * Whether the page is only being watched temporarily (has expiry).
182     * Must be called separately for Subject & Talk namespaces.
183     *
184     * @since 1.35
185     *
186     * @param UserIdentity $user
187     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
188     *
189     * @return bool
190     */
191    public function isTempWatched( UserIdentity $user, $target ): bool;
192
193    /**
194     * @since 1.31
195     *
196     * @param UserIdentity $user
197     * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
198     *
199     * @return array multi-dimensional like $return[$namespaceId][$titleString] = $timestamp,
200     *         where $timestamp is:
201     *         - string|null value of wl_notificationtimestamp,
202     *         - false if $target is not watched by $user.
203     */
204    public function getNotificationTimestampsBatch( UserIdentity $user, array $targets );
205
206    /**
207     * Must be called separately for Subject & Talk namespaces
208     *
209     * @since 1.31 Method added.
210     * @since 1.35 Accepts $expiry parameter.
211     *
212     * @param UserIdentity $user
213     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
214     * @param string|null $expiry Optional expiry timestamp in any format acceptable to wfTimestamp().
215     *   null will not create an expiry, or leave it unchanged should one already exist.
216     */
217    public function addWatch( UserIdentity $user, $target, ?string $expiry = null );
218
219    /**
220     * @since 1.31 Method added.
221     * @since 1.35 Accepts $expiry parameter.
222     *
223     * @param UserIdentity $user
224     * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
225     * @param string|null $expiry Optional expiry timestamp in any format acceptable to wfTimestamp(),
226     *   null will not create expiries, or leave them unchanged should they already exist.
227     *
228     * @return bool success
229     */
230    public function addWatchBatchForUser( UserIdentity $user, array $targets, ?string $expiry = null );
231
232    /**
233     * Removes an entry for the UserIdentity watching the target (LinkTarget or PageIdentity)
234     * Must be called separately for Subject & Talk namespaces
235     *
236     * @since 1.31
237     *
238     * @param UserIdentity $user
239     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
240     *
241     * @return bool success
242     */
243    public function removeWatch( UserIdentity $user, $target );
244
245    /**
246     * @since 1.31
247     *
248     * @param UserIdentity $user The user to set the timestamps for
249     * @param string|null $timestamp Set the update timestamp to this value
250     * @param LinkTarget[]|PageIdentity[] $targets List of targets to update. Default to all targets.
251     *        deprecated passing LinkTarget[] since 1.36
252     *
253     * @return bool success
254     */
255    public function setNotificationTimestampsForUser(
256        UserIdentity $user,
257        $timestamp,
258        array $targets = []
259    );
260
261    /**
262     * Reset all watchlist notification timestamps for a user using the job queue
263     *
264     * @since 1.31
265     *
266     * @param UserIdentity $user The user to reset the timestamps for
267     * @param string|int|null $timestamp Value to set all timestamps to, null to clear them
268     */
269    public function resetAllNotificationTimestampsForUser( UserIdentity $user, $timestamp = null );
270
271    /**
272     * @since 1.31
273     *
274     * @param UserIdentity $editor The editor that triggered the update. Their notification
275     *  timestamp will not be updated(they have already seen it)
276     * @param LinkTarget|PageIdentity $target The target to update timestamps for
277     *        deprecated passing LinkTarget since 1.36
278     * @param string $timestamp Set the update (first unseen revision) timestamp to this value
279     *
280     * @return int[] Array of user IDs the timestamp has been updated for
281     */
282    public function updateNotificationTimestamp(
283        UserIdentity $editor, $target, $timestamp );
284
285    /**
286     * Reset the notification timestamp of this entry
287     *
288     * @since 1.31
289     *
290     * @param UserIdentity $user
291     * @param LinkTarget|PageIdentity $title deprecated passing LinkTarget since 1.36
292     * @param string $force Whether to force the write query to be executed even if the
293     *    page is not watched or the notification timestamp is already NULL.
294     *    'force' in order to force
295     * @param int $oldid The revision id being viewed. If not given or 0, latest revision is
296     *     assumed.
297     *
298     * @return bool success Whether a job was enqueued
299     */
300    public function resetNotificationTimestamp(
301        UserIdentity $user, $title, $force = '', $oldid = 0 );
302
303    /**
304     * @since 1.31
305     *
306     * @param UserIdentity $user
307     * @param int|null $unreadLimit
308     *
309     * @return int|bool The number of unread notifications
310     *                  true if greater than or equal to $unreadLimit
311     */
312    public function countUnreadNotifications( UserIdentity $user, $unreadLimit = null );
313
314    /**
315     * Check if the given title already is watched by the user, and if so
316     * add a watch for the new title.
317     *
318     * To be used for page renames and such.
319     *
320     * @since 1.31
321     *
322     * @param LinkTarget|PageIdentity $oldTarget deprecated passing LinkTarget since 1.36
323     * @param LinkTarget|PageIdentity $newTarget deprecated passing LinkTarget since 1.36
324     */
325    public function duplicateAllAssociatedEntries( $oldTarget, $newTarget );
326
327    /**
328     * Check if the given title already is watched by the user, and if so
329     * add a watch for the new title.
330     *
331     * To be used for page renames and such.
332     * This must be called separately for Subject and Talk pages
333     *
334     * @since 1.31
335     *
336     * @param LinkTarget|PageIdentity $oldTarget deprecated passing LinkTarget since 1.36
337     * @param LinkTarget|PageIdentity $newTarget deprecated passing LinkTarget since 1.36
338     */
339    public function duplicateEntry( $oldTarget, $newTarget );
340
341    /**
342     * Synchronously clear the users watchlist.
343     *
344     * @since 1.31
345     *
346     * @param UserIdentity $user
347     * @return bool True on success, false if {@see clearUserWatchedItemsUsingJobQueue} must be used
348     *  instead
349     */
350    public function clearUserWatchedItems( UserIdentity $user );
351
352    /**
353     * Does the size of the users watchlist require clearUserWatchedItemsUsingJobQueue() to be used
354     * instead of clearUserWatchedItems()
355     *
356     * @since 1.35
357     *
358     * @param UserIdentity $user
359     * @return bool
360     */
361    public function mustClearWatchedItemsUsingJobQueue( UserIdentity $user ): bool;
362
363    /**
364     * Queues a job that will clear the users watchlist using the Job Queue.
365     *
366     * @since 1.31
367     *
368     * @param UserIdentity $user
369     */
370    public function clearUserWatchedItemsUsingJobQueue( UserIdentity $user );
371
372    /**
373     * Probabilistically add a job to purge the expired watchlist items, if watchlist
374     * expiration is enabled, based on the value of $wgWatchlistPurgeRate
375     *
376     * @since 1.36
377     */
378    public function maybeEnqueueWatchlistExpiryJob(): void;
379
380    /**
381     * @since 1.32
382     *
383     * @param UserIdentity $user
384     * @param LinkTarget[]|PageIdentity[] $targets deprecated passing LinkTarget[] since 1.36
385     *
386     * @return bool success
387     */
388    public function removeWatchBatchForUser( UserIdentity $user, array $targets );
389
390    /**
391     * Convert $timestamp to TS_MW or return null if the page was visited since then by $user
392     *
393     * Use this only on single-user methods (having higher read-after-write expectations)
394     * and not in places involving arbitrary batches of different users
395     *
396     * Usage of this method should be limited to WatchedItem* classes
397     *
398     * @param string|null $timestamp Value of wl_notificationtimestamp from the DB
399     * @param UserIdentity $user
400     * @param LinkTarget|PageIdentity $target deprecated passing LinkTarget since 1.36
401     * @return string|null TS_MW timestamp of first unseen revision or null if there isn't one
402     */
403    public function getLatestNotificationTimestamp(
404        $timestamp, UserIdentity $user, $target );
405
406    /**
407     * Get the number of watchlist items that expire before the current time.
408     *
409     * @since 1.35
410     *
411     * @return int
412     */
413    public function countExpired(): int;
414
415    /**
416     * Remove some number of expired watchlist items.
417     *
418     * @since 1.35
419     *
420     * @param int $limit The number of items to remove.
421     * @param bool $deleteOrphans Whether to also delete `watchlist_expiry` rows that have no
422     * related `watchlist` rows (because not all code knows about the expiry table yet). This runs
423     * two extra queries, so is only done from the purgeExpiredWatchlistItems.php maintenance script.
424     */
425    public function removeExpired( int $limit, bool $deleteOrphans = false ): void;
426}
427/** @deprecated class alias since 1.43 */
428class_alias( WatchedItemStoreInterface::class, 'WatchedItemStoreInterface' );