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
{
34 public function __construct( $main, $action ) {
35 parent
::__construct( $main, $action );
38 public function execute() {
39 $user = $this->getUser();
41 if ( $user->isAnon() ) {
42 $this->dieUsage( 'Anonymous users cannot use watchlist change notifications', 'notloggedin' );
45 $params = $this->extractRequestParams();
46 $this->requireMaxOneParameter( $params, 'timestamp', 'torevid', 'newerthanrevid' );
48 $pageSet = new ApiPageSet( $this );
49 $args = array_merge( array( $params, 'entirewatchlist' ), array_keys( $pageSet->getAllowedParams() ) );
50 call_user_func_array( array( $this, 'requireOnlyOneParameter' ), $args );
53 $dbw = $this->getDB( DB_MASTER
);
56 if ( isset( $params['timestamp'] ) ) {
57 $timestamp = $dbw->timestamp( $params['timestamp'] );
60 if ( !$params['entirewatchlist'] ) {
64 if ( isset( $params['torevid'] ) ) {
65 if ( $params['entirewatchlist'] ||
$pageSet->getGoodTitleCount() > 1 ) {
66 $this->dieUsage( 'torevid may only be used with a single page', 'multpages' );
68 $title = reset( $pageSet->getGoodTitles() );
69 $timestamp = Revision
::getTimestampFromId( $title, $params['torevid'] );
71 $timestamp = $dbw->timestamp( $timestamp );
75 } elseif ( isset( $params['newerthanrevid'] ) ) {
76 if ( $params['entirewatchlist'] ||
$pageSet->getGoodTitleCount() > 1 ) {
77 $this->dieUsage( 'newerthanrevid may only be used with a single page', 'multpages' );
79 $title = reset( $pageSet->getGoodTitles() );
80 $revid = $title->getNextRevisionID( $params['newerthanrevid'] );
82 $timestamp = $dbw->timestamp( Revision
::getTimestampFromId( $title, $revid ) );
88 $apiResult = $this->getResult();
90 if ( $params['entirewatchlist'] ) {
91 // Entire watchlist mode: Just update the thing and return a success indicator
92 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
93 array( 'wl_user' => $user->getID() ),
97 $result['notificationtimestamp'] = ( is_null( $timestamp ) ?
'' : wfTimestamp( TS_ISO_8601
, $timestamp ) );
99 // First, log the invalid titles
100 foreach( $pageSet->getInvalidTitles() as $title ) {
102 $r['title'] = $title;
106 foreach( $pageSet->getMissingPageIDs() as $p ) {
108 $page['pageid'] = $p;
109 $page['missing'] = '';
110 $page['notwatched'] = '';
113 foreach( $pageSet->getMissingRevisionIDs() as $r ) {
116 $rev['missing'] = '';
117 $rev['notwatched'] = '';
121 // Now process the valid titles
122 $lb = new LinkBatch( $pageSet->getTitles() );
123 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
124 array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
128 // Query the results of our update
129 $timestamps = array();
130 $res = $dbw->select( 'watchlist', array( 'wl_namespace', 'wl_title', 'wl_notificationtimestamp' ),
131 array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
134 foreach ( $res as $row ) {
135 $timestamps[$row->wl_namespace
][$row->wl_title
] = $row->wl_notificationtimestamp
;
138 // Now, put the valid titles into the result
140 foreach ( $pageSet->getTitles() as $title ) {
141 $ns = $title->getNamespace();
142 $dbkey = $title->getDBkey();
144 'ns' => intval( $ns ),
145 'title' => $title->getPrefixedText(),
147 if ( !$title->exists() ) {
150 if ( isset( $timestamps[$ns] ) && array_key_exists( $dbkey, $timestamps[$ns] ) ) {
151 $r['notificationtimestamp'] = '';
152 if ( $timestamps[$ns][$dbkey] !== null ) {
153 $r['notificationtimestamp'] = wfTimestamp( TS_ISO_8601
, $timestamps[$ns][$dbkey] );
156 $r['notwatched'] = '';
161 $apiResult->setIndexedTagName( $result, 'page' );
163 $apiResult->addValue( null, $this->getModuleName(), $result );
166 public function mustBePosted() {
170 public function isWriteMode() {
174 public function needsToken() {
178 public function getTokenSalt() {
182 public function getAllowedParams() {
183 $psModule = new ApiPageSet( $this );
184 return $psModule->getAllowedParams() +
array(
185 'entirewatchlist' => array(
186 ApiBase
::PARAM_TYPE
=> 'boolean'
189 'timestamp' => array(
190 ApiBase
::PARAM_TYPE
=> 'timestamp'
193 ApiBase
::PARAM_TYPE
=> 'integer'
195 'newerthanrevid' => array(
196 ApiBase
::PARAM_TYPE
=> 'integer'
201 public function getParamDescription() {
202 $psModule = new ApiPageSet( $this );
203 return $psModule->getParamDescription() +
array(
204 'entirewatchlist' => 'Work on all watched pages',
205 'timestamp' => 'Timestamp to which to set the notification timestamp',
206 'torevid' => 'Revision to set the notification timestamp to (one page only)',
207 'newerthanrevid' => 'Revision to set the notification timestamp newer than (one page only)',
208 'token' => 'A token previously acquired via prop=info',
212 public function getResultProperties() {
214 ApiBase
::PROP_LIST
=> true,
215 ApiBase
::PROP_ROOT
=> array(
216 'notificationtimestamp' => array(
217 ApiBase
::PROP_TYPE
=> 'timestamp',
218 ApiBase
::PROP_NULLABLE
=> true
223 ApiBase
::PROP_TYPE
=> 'namespace',
224 ApiBase
::PROP_NULLABLE
=> true
227 ApiBase
::PROP_TYPE
=> 'string',
228 ApiBase
::PROP_NULLABLE
=> true
231 ApiBase
::PROP_TYPE
=> 'integer',
232 ApiBase
::PROP_NULLABLE
=> true
235 ApiBase
::PROP_TYPE
=> 'integer',
236 ApiBase
::PROP_NULLABLE
=> true
238 'invalid' => 'boolean',
239 'missing' => 'boolean',
240 'notwatched' => 'boolean',
241 'notificationtimestamp' => array(
242 ApiBase
::PROP_TYPE
=> 'timestamp',
243 ApiBase
::PROP_NULLABLE
=> true
249 public function getDescription() {
250 return array( 'Update the notification timestamp for watched pages.',
251 'This affects the highlighting of changed pages in the watchlist and history,',
252 'and the sending of email when the "E-mail me when a page on my watchlist is',
253 'changed" preference is enabled.'
257 public function getPossibleErrors() {
258 $psModule = new ApiPageSet( $this );
260 parent
::getPossibleErrors(),
261 $psModule->getPossibleErrors(),
262 $this->getRequireMaxOneParameterErrorMessages( array( 'timestamp', 'torevid', 'newerthanrevid' ) ),
263 $this->getRequireOnlyOneParameterErrorMessages( array_merge( array( 'entirewatchlist' ), array_keys( $psModule->getAllowedParams() ) ) ),
265 array( 'code' => 'notloggedin', 'info' => 'Anonymous users cannot use watchlist change notifications' ),
266 array( 'code' => 'multpages', 'info' => 'torevid may only be used with a single page' ),
267 array( 'code' => 'multpages', 'info' => 'newerthanrevid may only be used with a single page' ),
272 public function getExamples() {
274 'api.php?action=setnotificationtimestamp&entirewatchlist=&token=ABC123' => 'Reset the notification status for the entire watchlist',
275 'api.php?action=setnotificationtimestamp&titles=Main_page&token=ABC123' => 'Reset the notification status for "Main page"',
276 'api.php?action=setnotificationtimestamp&titles=Main_page×tamp=2012-01-01T00:00:00Z&token=ABC123' => 'Set the notification timestamp for "Main page" so all edits since 1 January 2012 are unviewed',
280 public function getHelpUrls() {
281 return 'https://www.mediawiki.org/wiki/API:SetNotificationTimestamp';
284 public function getVersion() {
285 return __CLASS__
. ': $Id$';