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