MediaWiki master
ApiWatchlistTrait.php
Go to the documentation of this file.
1<?php
2
3namespace MediaWiki\Api;
4
14
27
29 private $watchlistExpiryEnabled;
30
32 private $watchlistMaxDuration;
33
34 private ?WatchlistManager $watchlistManager = null;
35 private ?UserOptionsLookup $userOptionsLookup = null;
36
37 private function initServices() {
38 // This trait is used outside of core and therefor fallback to global state - T263904
39 $this->watchlistManager ??= MediaWikiServices::getInstance()->getWatchlistManager();
40 $this->userOptionsLookup ??= MediaWikiServices::getInstance()->getUserOptionsLookup();
41 }
42
53 protected function getWatchlistParams( array $watchOptions = [] ): array {
54 if ( !$watchOptions ) {
55 $watchOptions = [
56 'watch',
57 'unwatch',
58 'preferences',
59 'nochange',
60 ];
61 }
62
63 $result = [
64 'watchlist' => [
65 ParamValidator::PARAM_DEFAULT => 'preferences',
66 ParamValidator::PARAM_TYPE => $watchOptions,
67 ],
68 ];
69
70 if ( $this->watchlistExpiryEnabled ) {
71 $result['watchlistexpiry'] = [
72 ParamValidator::PARAM_TYPE => 'expiry',
73 ExpiryDef::PARAM_MAX => $this->watchlistMaxDuration,
74 ExpiryDef::PARAM_USE_MAX => true,
75 ];
76 }
77
78 return $result;
79 }
80
90 protected function setWatch(
91 string $watch,
92 PageIdentity $page,
93 User $user,
94 ?string $userOption = null,
95 ?string $expiry = null
96 ): void {
97 $value = $this->getWatchlistValue( $watch, $page, $user, $userOption );
98 $this->watchlistManager->setWatch( $value, $user, $page, $expiry );
99 }
100
110 protected function getWatchlistValue(
111 string $watchlist,
112 PageIdentity $page,
113 User $user,
114 ?string $userOption = null
115 ): bool {
116 $this->initServices();
117 $userWatching = $this->watchlistManager->isWatchedIgnoringRights( $user, $page );
118
119 switch ( $watchlist ) {
120 case 'watch':
121 return true;
122
123 case 'unwatch':
124 return false;
125
126 case 'preferences':
127 // If the user is already watching, don't bother checking
128 if ( $userWatching ) {
129 return true;
130 }
131 // If the user is a bot, act as 'nochange' to avoid big watchlists on single users
132 if ( $user->isBot() ) {
133 return $userWatching;
134 }
135 // If no user option was passed, use watchdefault and watchcreations
136 if ( $userOption === null ) {
137 return $this->userOptionsLookup->getBoolOption( $user, 'watchdefault' ) ||
138 ( $this->userOptionsLookup->getBoolOption( $user, 'watchcreations' ) && !$page->exists() );
139 }
140
141 // Watch the article based on the user preference
142 return $this->userOptionsLookup->getBoolOption( $user, $userOption );
143
144 // case 'nochange':
145 default:
146 return $userWatching;
147 }
148 }
149
160 protected function getExpiryFromParams(
161 array $params,
162 ?UserIdentity $user = null,
163 string $userOption = 'watchdefault-expiry'
164 ): ?string {
165 $watchlistExpiry = null;
166 if ( $this->watchlistExpiryEnabled ) {
167 // At this point, the ParamValidator has already normalized $params['watchlistexpiry'].
168 $watchlistExpiry = $params['watchlistexpiry'] ?? null;
169 if ( $user && $watchlistExpiry === null ) {
170 $watchlistExpiry = ExpiryDef::normalizeExpiry(
171 $this->userOptionsLookup->getOption( $user, $userOption )
172 );
173 } elseif ( $watchlistExpiry === null ) {
174 return null;
175 }
176 }
177
178 return ApiResult::formatExpiry( $watchlistExpiry );
179 }
180
189 protected function getWatchlistExpiry(
191 PageIdentity $page,
192 UserIdentity $user
193 ): ?string {
194 $watchedItem = $store->getWatchedItem( $user, $page );
195
196 if ( $watchedItem ) {
197 $expiry = $watchedItem->getExpiry();
198
199 if ( $expiry !== null ) {
200 return ApiResult::formatExpiry( $expiry );
201 }
202 }
203
204 return null;
205 }
206}
207
209class_alias( ApiWatchlistTrait::class, 'ApiWatchlistTrait' );
if(!defined('MW_SETUP_CALLBACK'))
Definition WebStart.php:82
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
Service locator for MediaWiki core services.
static getInstance()
Returns the global default instance of the top level service locator.
Provides access to user options.
User class for the MediaWiki software.
Definition User.php:123
Service for formatting and validating API parameters.
Type definition for expiry timestamps.
Definition ExpiryDef.php:17
trait ApiWatchlistTrait
An ApiWatchlistTrait adds class properties and convenience methods for APIs that allow you to watch a...
Interface for objects (potentially) representing an editable wiki page.
exists()
Checks if the page currently exists.
Interface for objects representing user identity.
setWatch(string $watch, PageIdentity $page, User $user, ?string $userOption=null, ?string $expiry=null)
Set a watch (or unwatch) based the based on a watchlist parameter.
getWatchlistValue(string $watchlist, PageIdentity $page, User $user, ?string $userOption=null)
Return true if we're to watch the page, false if not.
getWatchlistParams(array $watchOptions=[])
Get additional allow params specific to watchlisting.
getExpiryFromParams(array $params, ?UserIdentity $user=null, string $userOption='watchdefault-expiry')
Get formatted expiry from the given parameters.
getWatchlistExpiry(WatchedItemStoreInterface $store, PageIdentity $page, UserIdentity $user)
Get existing expiry from the database.