4 * API for MediaWiki 1.14+
6 * Created on Jun 18, 2012
8 * Copyright © 2012 Brad Jorsch
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License along
21 * with this program; if not, write to the Free Software Foundation, Inc.,
22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23 * http://www.gnu.org/copyleft/gpl.html
29 * API interface for setting the wl_notificationtimestamp field
32 class ApiSetNotificationTimestamp
extends ApiBase
{
36 public function execute() {
37 $user = $this->getUser();
39 if ( $user->isAnon() ) {
40 $this->dieUsage( 'Anonymous users cannot use watchlist change notifications', 'notloggedin' );
42 if ( !$user->isAllowed( 'editmywatchlist' ) ) {
43 $this->dieUsage( 'You don\'t have permission to edit your watchlist', 'permissiondenied' );
46 $params = $this->extractRequestParams();
47 $this->requireMaxOneParameter( $params, 'timestamp', 'torevid', 'newerthanrevid' );
49 $pageSet = $this->getPageSet();
50 if ( $params['entirewatchlist'] && $pageSet->getDataSource() !== null ) {
52 "Cannot use 'entirewatchlist' at the same time as '{$pageSet->getDataSource()}'",
57 $dbw = wfGetDB( DB_MASTER
, 'api' );
60 if ( isset( $params['timestamp'] ) ) {
61 $timestamp = $dbw->timestamp( $params['timestamp'] );
64 if ( !$params['entirewatchlist'] ) {
68 if ( isset( $params['torevid'] ) ) {
69 if ( $params['entirewatchlist'] ||
$pageSet->getGoodTitleCount() > 1 ) {
70 $this->dieUsage( 'torevid may only be used with a single page', 'multpages' );
72 $title = reset( $pageSet->getGoodTitles() );
74 $timestamp = Revision
::getTimestampFromId( $title, $params['torevid'] );
76 $timestamp = $dbw->timestamp( $timestamp );
81 } elseif ( isset( $params['newerthanrevid'] ) ) {
82 if ( $params['entirewatchlist'] ||
$pageSet->getGoodTitleCount() > 1 ) {
83 $this->dieUsage( 'newerthanrevid may only be used with a single page', 'multpages' );
85 $title = reset( $pageSet->getGoodTitles() );
87 $revid = $title->getNextRevisionID( $params['newerthanrevid'] );
89 $timestamp = $dbw->timestamp( Revision
::getTimestampFromId( $title, $revid ) );
96 $apiResult = $this->getResult();
98 if ( $params['entirewatchlist'] ) {
99 // Entire watchlist mode: Just update the thing and return a success indicator
100 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
101 array( 'wl_user' => $user->getID() ),
105 $result['notificationtimestamp'] = is_null( $timestamp )
107 : wfTimestamp( TS_ISO_8601
, $timestamp );
109 // First, log the invalid titles
110 foreach ( $pageSet->getInvalidTitles() as $title ) {
112 $r['title'] = $title;
116 foreach ( $pageSet->getMissingPageIDs() as $p ) {
118 $page['pageid'] = $p;
119 $page['missing'] = '';
120 $page['notwatched'] = '';
123 foreach ( $pageSet->getMissingRevisionIDs() as $r ) {
126 $rev['missing'] = '';
127 $rev['notwatched'] = '';
131 if ( $pageSet->getTitles() ) {
132 // Now process the valid titles
133 $lb = new LinkBatch( $pageSet->getTitles() );
134 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
135 array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
139 // Query the results of our update
140 $timestamps = array();
143 array( 'wl_namespace', 'wl_title', 'wl_notificationtimestamp' ),
144 array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
147 foreach ( $res as $row ) {
148 $timestamps[$row->wl_namespace
][$row->wl_title
] = $row->wl_notificationtimestamp
;
151 // Now, put the valid titles into the result
152 /** @var $title Title */
153 foreach ( $pageSet->getTitles() as $title ) {
154 $ns = $title->getNamespace();
155 $dbkey = $title->getDBkey();
157 'ns' => intval( $ns ),
158 'title' => $title->getPrefixedText(),
160 if ( !$title->exists() ) {
163 if ( isset( $timestamps[$ns] ) && array_key_exists( $dbkey, $timestamps[$ns] ) ) {
164 $r['notificationtimestamp'] = '';
165 if ( $timestamps[$ns][$dbkey] !== null ) {
166 $r['notificationtimestamp'] = wfTimestamp( TS_ISO_8601
, $timestamps[$ns][$dbkey] );
169 $r['notwatched'] = '';
175 $apiResult->setIndexedTagName( $result, 'page' );
177 $apiResult->addValue( null, $this->getModuleName(), $result );
181 * Get a cached instance of an ApiPageSet object
184 private function getPageSet() {
185 if ( !isset( $this->mPageSet
) ) {
186 $this->mPageSet
= new ApiPageSet( $this );
189 return $this->mPageSet
;
192 public function mustBePosted() {
196 public function isWriteMode() {
200 public function needsToken() {
204 public function getTokenSalt() {
208 public function getAllowedParams( $flags = 0 ) {
210 'entirewatchlist' => array(
211 ApiBase
::PARAM_TYPE
=> 'boolean'
214 'timestamp' => array(
215 ApiBase
::PARAM_TYPE
=> 'timestamp'
218 ApiBase
::PARAM_TYPE
=> 'integer'
220 'newerthanrevid' => array(
221 ApiBase
::PARAM_TYPE
=> 'integer'
225 $result +
= $this->getPageSet()->getFinalParams( $flags );
231 public function getParamDescription() {
232 return $this->getPageSet()->getFinalParamDescription() +
array(
233 'entirewatchlist' => 'Work on all watched pages',
234 'timestamp' => 'Timestamp to which to set the notification timestamp',
235 'torevid' => 'Revision to set the notification timestamp to (one page only)',
236 'newerthanrevid' => 'Revision to set the notification timestamp newer than (one page only)',
237 'token' => 'A token previously acquired via prop=info',
241 public function getResultProperties() {
243 ApiBase
::PROP_LIST
=> true,
244 ApiBase
::PROP_ROOT
=> array(
245 'notificationtimestamp' => array(
246 ApiBase
::PROP_TYPE
=> 'timestamp',
247 ApiBase
::PROP_NULLABLE
=> true
252 ApiBase
::PROP_TYPE
=> 'namespace',
253 ApiBase
::PROP_NULLABLE
=> true
256 ApiBase
::PROP_TYPE
=> 'string',
257 ApiBase
::PROP_NULLABLE
=> true
260 ApiBase
::PROP_TYPE
=> 'integer',
261 ApiBase
::PROP_NULLABLE
=> true
264 ApiBase
::PROP_TYPE
=> 'integer',
265 ApiBase
::PROP_NULLABLE
=> true
267 'invalid' => 'boolean',
268 'missing' => 'boolean',
269 'notwatched' => 'boolean',
270 'notificationtimestamp' => array(
271 ApiBase
::PROP_TYPE
=> 'timestamp',
272 ApiBase
::PROP_NULLABLE
=> true
278 public function getDescription() {
279 return array( 'Update the notification timestamp for watched pages.',
280 'This affects the highlighting of changed pages in the watchlist and history,',
281 'and the sending of email when the "Email me when a page on my watchlist is',
282 'changed" preference is enabled.'
286 public function getPossibleErrors() {
287 $ps = $this->getPageSet();
290 parent
::getPossibleErrors(),
291 $ps->getFinalPossibleErrors(),
292 $this->getRequireMaxOneParameterErrorMessages(
293 array( 'timestamp', 'torevid', 'newerthanrevid' ) ),
294 $this->getRequireOnlyOneParameterErrorMessages(
295 array_merge( array( 'entirewatchlist' ), array_keys( $ps->getFinalParams() ) ) ),
297 array( 'code' => 'notloggedin', 'info'
298 => 'Anonymous users cannot use watchlist change notifications' ),
299 array( 'code' => 'multpages', 'info' => 'torevid may only be used with a single page' ),
300 array( 'code' => 'multpages', 'info' => 'newerthanrevid may only be used with a single page' ),
305 public function getExamples() {
307 'api.php?action=setnotificationtimestamp&entirewatchlist=&token=123ABC'
308 => 'Reset the notification status for the entire watchlist',
309 'api.php?action=setnotificationtimestamp&titles=Main_page&token=123ABC'
310 => 'Reset the notification status for "Main page"',
311 'api.php?action=setnotificationtimestamp&titles=Main_page&' .
312 'timestamp=2012-01-01T00:00:00Z&token=123ABC'
313 => 'Set the notification timestamp for "Main page" so all edits ' .
314 'since 1 January 2012 are unviewed',
318 public function getHelpUrls() {
319 return 'https://www.mediawiki.org/wiki/API:SetNotificationTimestamp';