MediaWiki  master
ApiWatch.php
Go to the documentation of this file.
1 <?php
28 class ApiWatch extends ApiBase {
29  private $mPageSet = null;
30 
31  public function execute() {
32  $user = $this->getUser();
33  if ( !$user->isLoggedIn() ) {
34  $this->dieWithError( 'watchlistanontext', 'notloggedin' );
35  }
36 
37  $this->checkUserRightsAny( 'editmywatchlist' );
38 
39  $params = $this->extractRequestParams();
40 
41  $continuationManager = new ApiContinuationManager( $this, [], [] );
42  $this->setContinuationManager( $continuationManager );
43 
44  $pageSet = $this->getPageSet();
45  // by default we use pageset to extract the page to work on.
46  // title is still supported for backward compatibility
47  if ( !isset( $params['title'] ) ) {
48  $pageSet->execute();
49  $res = $pageSet->getInvalidTitlesAndRevisions( [
50  'invalidTitles',
51  'special',
52  'missingIds',
53  'missingRevIds',
54  'interwikiTitles'
55  ] );
56 
57  foreach ( $pageSet->getMissingTitles() as $title ) {
58  $r = $this->watchTitle( $title, $user, $params );
59  $r['missing'] = true;
60  $res[] = $r;
61  }
62 
63  foreach ( $pageSet->getGoodTitles() as $title ) {
64  $r = $this->watchTitle( $title, $user, $params );
65  $res[] = $r;
66  }
68  } else {
69  // dont allow use of old title parameter with new pageset parameters.
70  $extraParams = array_keys( array_filter( $pageSet->extractRequestParams(), function ( $x ) {
71  return $x !== null && $x !== false;
72  } ) );
73 
74  if ( $extraParams ) {
75  $this->dieWithError(
76  [
77  'apierror-invalidparammix-cannotusewith',
78  $this->encodeParamName( 'title' ),
79  $pageSet->encodeParamName( $extraParams[0] )
80  ],
81  'invalidparammix'
82  );
83  }
84 
85  $title = Title::newFromText( $params['title'] );
86  if ( !$title || !$title->isWatchable() ) {
87  $this->dieWithError( [ 'invalidtitle', $params['title'] ] );
88  }
89  $res = $this->watchTitle( $title, $user, $params, true );
90  }
91  $this->getResult()->addValue( null, $this->getModuleName(), $res );
92 
93  $this->setContinuationManager( null );
94  $continuationManager->setContinuationIntoResult( $this->getResult() );
95  }
96 
97  private function watchTitle( Title $title, User $user, array $params,
98  $compatibilityMode = false
99  ) {
100  $res = [ 'title' => $title->getPrefixedText(), 'ns' => $title->getNamespace() ];
101 
102  if ( !$title->isWatchable() ) {
103  $res['watchable'] = 0;
104  return $res;
105  }
106 
107  if ( $params['unwatch'] ) {
108  $status = UnwatchAction::doUnwatch( $title, $user );
109  $res['unwatched'] = $status->isOK();
110  } else {
111  $status = WatchAction::doWatch( $title, $user );
112  $res['watched'] = $status->isOK();
113  }
114 
115  if ( !$status->isOK() ) {
116  if ( $compatibilityMode ) {
117  $this->dieStatus( $status );
118  }
119  $res['errors'] = $this->getErrorFormatter()->arrayFromStatus( $status, 'error' );
120  $res['warnings'] = $this->getErrorFormatter()->arrayFromStatus( $status, 'warning' );
121  if ( !$res['warnings'] ) {
122  unset( $res['warnings'] );
123  }
124  }
125 
126  return $res;
127  }
128 
133  private function getPageSet() {
134  if ( $this->mPageSet === null ) {
135  $this->mPageSet = new ApiPageSet( $this );
136  }
137 
138  return $this->mPageSet;
139  }
140 
141  public function mustBePosted() {
142  return true;
143  }
144 
145  public function isWriteMode() {
146  return true;
147  }
148 
149  public function needsToken() {
150  return 'watch';
151  }
152 
153  public function getAllowedParams( $flags = 0 ) {
154  $result = [
155  'title' => [
156  ApiBase::PARAM_TYPE => 'string',
158  ],
159  'unwatch' => false,
160  'continue' => [
161  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
162  ],
163  ];
164  if ( $flags ) {
165  $result += $this->getPageSet()->getFinalParams( $flags );
166  }
167 
168  return $result;
169  }
170 
171  protected function getExamplesMessages() {
172  return [
173  'action=watch&titles=Main_Page&token=123ABC'
174  => 'apihelp-watch-example-watch',
175  'action=watch&titles=Main_Page&unwatch=&token=123ABC'
176  => 'apihelp-watch-example-unwatch',
177  'action=watch&generator=allpages&gapnamespace=0&token=123ABC'
178  => 'apihelp-watch-example-generator',
179  ];
180  }
181 
182  public function getHelpUrls() {
183  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Watch';
184  }
185 }
watchTitle(Title $title, User $user, array $params, $compatibilityMode=false)
Definition: ApiWatch.php:97
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below...
Definition: ApiBase.php:94
isWriteMode()
Definition: ApiWatch.php:145
getErrorFormatter()
Get the error formatter.
Definition: ApiBase.php:654
getResult()
Get the result object.
Definition: ApiBase.php:640
This class contains a list of pages that the client has requested.
Definition: ApiPageSet.php:40
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition: ApiBase.php:2078
isWatchable()
Can this title be added to a user&#39;s watchlist?
Definition: Title.php:1233
This manages continuation state.
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition: ApiBase.php:2006
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:761
getPrefixedText()
Get the prefixed title with spaces.
Definition: Title.php:1853
getAllowedParams( $flags=0)
Definition: ApiWatch.php:153
static setIndexedTagName(array &$arr, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:616
getHelpUrls()
Definition: ApiWatch.php:182
The User object encapsulates all of the user-specific settings (user_id, name, rights, email address, options, last login time).
Definition: User.php:51
getExamplesMessages()
Definition: ApiWatch.php:171
setContinuationManager(ApiContinuationManager $manager=null)
Set the continuation manager.
Definition: ApiBase.php:694
static doWatch(Title $title, User $user, $checkRights=User::CHECK_USER_RIGHTS)
Watch a page.
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:520
getNamespace()
Get the namespace index, i.e.
Definition: Title.php:1035
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter...
Definition: ApiBase.php:131
needsToken()
Definition: ApiWatch.php:149
execute()
Definition: ApiWatch.php:31
encodeParamName( $paramName)
This method mangles parameter name based on the prefix supplied to the constructor.
Definition: ApiBase.php:739
API module to allow users to watch a page.
Definition: ApiWatch.php:28
getPageSet()
Get a cached instance of an ApiPageSet object.
Definition: ApiWatch.php:133
This abstract class implements many basic API functions, and is the base of all API classes...
Definition: ApiBase.php:42
mustBePosted()
Definition: ApiWatch.php:141
const PARAM_DEPRECATED
(boolean) Is the parameter deprecated (will show a warning)?
Definition: ApiBase.php:112
checkUserRightsAny( $rights, $user=null)
Helper function for permission-denied errors.
Definition: ApiBase.php:2122
return true
Definition: router.php:92
static doUnwatch(Title $title, User $user)
Unwatch a page.
static newFromText( $text, $defaultNamespace=NS_MAIN)
Create a new Title from text, such as what one would find in a link.
Definition: Title.php:317