5 * Created on Jul 2, 2007
7 * Copyright © 2007 Roan Kattouw <Firstname>.<Lastname>@gmail.com
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
27 if ( !defined( 'MEDIAWIKI' ) ) {
28 // Eclipse helper - will be ignored in production
29 require_once( 'ApiQueryBase.php' );
33 * Query module to enumerate all deleted revisions.
37 class ApiQueryDeletedrevs
extends ApiQueryBase
{
39 public function __construct( $query, $moduleName ) {
40 parent
::__construct( $query, $moduleName, 'dr' );
43 public function execute() {
45 // Before doing anything at all, let's check permissions
46 if ( !$wgUser->isAllowed( 'deletedhistory' ) ) {
47 $this->dieUsage( 'You don\'t have permission to view deleted revision information', 'permissiondenied' );
51 $params = $this->extractRequestParams( false );
52 $prop = array_flip( $params['prop'] );
53 $fld_parentid = isset( $prop['parentid'] );
54 $fld_revid = isset( $prop['revid'] );
55 $fld_user = isset( $prop['user'] );
56 $fld_userid = isset( $prop['userid'] );
57 $fld_comment = isset( $prop['comment'] );
58 $fld_parsedcomment = isset ( $prop['parsedcomment'] );
59 $fld_minor = isset( $prop['minor'] );
60 $fld_len = isset( $prop['len'] );
61 $fld_content = isset( $prop['content'] );
62 $fld_token = isset( $prop['token'] );
64 $result = $this->getResult();
65 $pageSet = $this->getPageSet();
66 $titles = $pageSet->getTitles();
68 // This module operates in three modes:
69 // 'revs': List deleted revs for certain titles
70 // 'user': List deleted revs by a certain user
71 // 'all': List all deleted revs
73 if ( count( $titles ) > 0 ) {
75 } elseif ( !is_null( $params['user'] ) ) {
79 if ( !is_null( $params['user'] ) && !is_null( $params['excludeuser'] ) ) {
80 $this->dieUsage( 'user and excludeuser cannot be used together', 'badparams' );
83 $this->addTables( 'archive' );
84 $this->addWhere( 'ar_deleted = 0' );
85 $this->addFields( array( 'ar_title', 'ar_namespace', 'ar_timestamp' ) );
87 if ( $fld_parentid ) {
88 $this->addFields( 'ar_parent_id' );
91 $this->addFields( 'ar_rev_id' );
94 $this->addFields( 'ar_user_text' );
97 $this->addFields( 'ar_user' );
99 if ( $fld_comment ||
$fld_parsedcomment ) {
100 $this->addFields( 'ar_comment' );
103 $this->addFields( 'ar_minor_edit' );
106 $this->addFields( 'ar_len' );
108 if ( $fld_content ) {
109 $this->addTables( 'text' );
110 $this->addFields( array( 'ar_text', 'ar_text_id', 'old_text', 'old_flags' ) );
111 $this->addWhere( 'ar_text_id = old_id' );
113 // This also means stricter restrictions
114 if ( !$wgUser->isAllowed( 'undelete' ) ) {
115 $this->dieUsage( 'You don\'t have permission to view deleted revision content', 'permissiondenied' );
119 $userMax = $fld_content ? ApiBase
::LIMIT_SML1
: ApiBase
::LIMIT_BIG1
;
120 $botMax = $fld_content ? ApiBase
::LIMIT_SML2
: ApiBase
::LIMIT_BIG2
;
122 $limit = $params['limit'];
124 if ( $limit == 'max' ) {
125 $limit = $this->getMain()->canApiHighLimits() ?
$botMax : $userMax;
126 $this->getResult()->setParsedLimit( $this->getModuleName(), $limit );
129 $this->validateLimit( 'limit', $limit, 1, $userMax, $botMax );
132 // Undelete tokens are identical for all pages, so we cache one here
133 $token = $wgUser->editToken( '', $this->getMain()->getRequest() );
136 $dir = $params['dir'];
138 // We need a custom WHERE clause that matches all titles.
139 if ( $mode == 'revs' ) {
140 $lb = new LinkBatch( $titles );
141 $where = $lb->constructSet( 'ar', $db );
142 $this->addWhere( $where );
143 } elseif ( $mode == 'all' ) {
144 $this->addWhereFld( 'ar_namespace', $params['namespace'] );
146 $from = is_null( $params['from'] ) ?
null : $this->titleToKey( $params['from'] );
147 $to = is_null( $params['to'] ) ?
null : $this->titleToKey( $params['to'] );
148 $this->addWhereRange( 'ar_title', $dir, $from, $to );
151 if ( !is_null( $params['user'] ) ) {
152 $this->addWhereFld( 'ar_user_text', $params['user'] );
153 } elseif ( !is_null( $params['excludeuser'] ) ) {
154 $this->addWhere( 'ar_user_text != ' .
155 $this->getDB()->addQuotes( $params['excludeuser'] ) );
158 if ( !is_null( $params['continue'] ) && ( $mode == 'all' ||
$mode == 'revs' ) ) {
159 $cont = explode( '|', $params['continue'] );
160 if ( count( $cont ) != 3 ) {
161 $this->dieUsage( 'Invalid continue param. You should pass the original value returned by the previous query', 'badcontinue' );
163 $ns = intval( $cont[0] );
164 $title = $this->getDB()->strencode( $this->titleToKey( $cont[1] ) );
165 $ts = $this->getDB()->strencode( $cont[2] );
166 $op = ( $dir == 'newer' ?
'>' : '<' );
167 $this->addWhere( "ar_namespace $op $ns OR " .
168 "(ar_namespace = $ns AND " .
169 "(ar_title $op '$title' OR " .
170 "(ar_title = '$title' AND " .
171 "ar_timestamp $op= '$ts')))" );
174 $this->addOption( 'LIMIT', $limit +
1 );
175 $this->addOption( 'USE INDEX', array( 'archive' => ( $mode == 'user' ?
'usertext_timestamp' : 'name_title_timestamp' ) ) );
176 if ( $mode == 'all' ) {
177 if ( $params['unique'] ) {
178 $this->addOption( 'GROUP BY', 'ar_title' );
180 $this->addOption( 'ORDER BY', 'ar_title, ar_timestamp' );
183 if ( $mode == 'revs' ) {
184 // Sort by ns and title in the same order as timestamp for efficiency
185 $this->addWhereRange( 'ar_namespace', $dir, null, null );
186 $this->addWhereRange( 'ar_title', $dir, null, null );
188 $this->addWhereRange( 'ar_timestamp', $dir, $params['start'], $params['end'] );
190 $res = $this->select( __METHOD__
);
191 $pageMap = array(); // Maps ns&title to (fake) pageid
194 foreach ( $res as $row ) {
195 if ( ++
$count > $limit ) {
197 if ( $mode == 'all' ||
$mode == 'revs' ) {
198 $this->setContinueEnumParameter( 'continue', intval( $row->ar_namespace
) . '|' .
199 $this->keyToTitle( $row->ar_title
) . '|' . $row->ar_timestamp
);
201 $this->setContinueEnumParameter( 'start', wfTimestamp( TS_ISO_8601
, $row->ar_timestamp
) );
207 $rev['timestamp'] = wfTimestamp( TS_ISO_8601
, $row->ar_timestamp
);
209 $rev['revid'] = intval( $row->ar_rev_id
);
211 if ( $fld_parentid ) {
212 $rev['parentid'] = intval( $row->ar_parent_id
);
215 $rev['user'] = $row->ar_user_text
;
218 $rev['userid'] = $row->ar_user
;
220 if ( $fld_comment ) {
221 $rev['comment'] = $row->ar_comment
;
224 $title = Title
::makeTitle( $row->ar_namespace
, $row->ar_title
);
226 if ( $fld_parsedcomment ) {
227 $rev['parsedcomment'] = $wgUser->getSkin()->formatComment( $row->ar_comment
, $title );
229 if ( $fld_minor && $row->ar_minor_edit
== 1 ) {
233 $rev['len'] = $row->ar_len
;
235 if ( $fld_content ) {
236 ApiResult
::setContent( $rev, Revision
::getRevisionText( $row ) );
239 if ( !isset( $pageMap[$row->ar_namespace
][$row->ar_title
] ) ) {
240 $pageID = $newPageID++
;
241 $pageMap[$row->ar_namespace
][$row->ar_title
] = $pageID;
242 $a['revisions'] = array( $rev );
243 $result->setIndexedTagName( $a['revisions'], 'rev' );
244 ApiQueryBase
::addTitleInfo( $a, $title );
246 $a['token'] = $token;
248 $fit = $result->addValue( array( 'query', $this->getModuleName() ), $pageID, $a );
250 $pageID = $pageMap[$row->ar_namespace
][$row->ar_title
];
251 $fit = $result->addValue(
252 array( 'query', $this->getModuleName(), $pageID, 'revisions' ),
256 if ( $mode == 'all' ||
$mode == 'revs' ) {
257 $this->setContinueEnumParameter( 'continue', intval( $row->ar_namespace
) . '|' .
258 $this->keyToTitle( $row->ar_title
) . '|' . $row->ar_timestamp
);
260 $this->setContinueEnumParameter( 'start', wfTimestamp( TS_ISO_8601
, $row->ar_timestamp
) );
265 $result->setIndexedTagName_internal( array( 'query', $this->getModuleName() ), 'page' );
268 public function getAllowedParams() {
271 ApiBase
::PARAM_TYPE
=> 'timestamp'
274 ApiBase
::PARAM_TYPE
=> 'timestamp',
277 ApiBase
::PARAM_TYPE
=> array(
281 ApiBase
::PARAM_DFLT
=> 'older'
288 ApiBase
::PARAM_TYPE
=> 'user'
290 'excludeuser' => array(
291 ApiBase
::PARAM_TYPE
=> 'user'
293 'namespace' => array(
294 ApiBase
::PARAM_TYPE
=> 'namespace',
295 ApiBase
::PARAM_DFLT
=> 0,
298 ApiBase
::PARAM_DFLT
=> 10,
299 ApiBase
::PARAM_TYPE
=> 'limit',
300 ApiBase
::PARAM_MIN
=> 1,
301 ApiBase
::PARAM_MAX
=> ApiBase
::LIMIT_BIG1
,
302 ApiBase
::PARAM_MAX2
=> ApiBase
::LIMIT_BIG2
305 ApiBase
::PARAM_DFLT
=> 'user|comment',
306 ApiBase
::PARAM_TYPE
=> array(
318 ApiBase
::PARAM_ISMULTI
=> true
323 public function getParamDescription() {
325 'start' => 'The timestamp to start enumerating from (1,2)',
326 'end' => 'The timestamp to stop enumerating at (1,2)',
327 'dir' => $this->getDirectionDescription( $this->getModulePrefix(), ' (1,2)' ),
328 'from' => 'Start listing at this title (3)',
329 'to' => 'Stop listing at this title (3)',
330 'limit' => 'The maximum amount of revisions to list',
332 'Which properties to get',
333 ' revid - Adds the revision ID of the deleted revision',
334 ' parentid - Adds the revision ID of the previous revision to the page',
335 ' user - Adds the user who made the revision',
336 ' userid - Adds the user ID whom made the revision',
337 ' comment - Adds the comment of the revision',
338 ' parsedcomment - Adds the parsed comment of the revision',
339 ' minor - Tags if the revision is minor',
340 ' len - Adds the length of the revision',
341 ' content - Adds the content of the revision',
342 ' token - Gives the edit token',
344 'namespace' => 'Only list pages in this namespace (3)',
345 'user' => 'Only list revisions by this user',
346 'excludeuser' => 'Don\'t list revisions by this user',
347 'continue' => 'When more results are available, use this to continue (3)',
348 'unique' => 'List only one revision for each page (3)',
352 public function getDescription() {
354 'List deleted revisions.',
355 'This module operates in three modes:',
356 '1) List deleted revisions for the given title(s), sorted by timestamp',
357 '2) List deleted contributions for the given user, sorted by timestamp (no titles specified)',
358 '3) List all deleted revisions in the given namespace, sorted by title and timestamp (no titles specified, druser not set)',
359 'Certain parameters only apply to some modes and are ignored in others.',
360 'For instance, a parameter marked (1) only applies to mode 1 and is ignored in modes 2 and 3',
364 public function getPossibleErrors() {
365 return array_merge( parent
::getPossibleErrors(), array(
366 array( 'code' => 'permissiondenied', 'info' => 'You don\'t have permission to view deleted revision information' ),
367 array( 'code' => 'badparams', 'info' => 'user and excludeuser cannot be used together' ),
368 array( 'code' => 'permissiondenied', 'info' => 'You don\'t have permission to view deleted revision content' ),
369 array( 'code' => 'badcontinue', 'info' => 'Invalid continue param. You should pass the original value returned by the previous query' ),
373 protected function getExamples() {
375 'List the last deleted revisions of Main Page and Talk:Main Page, with content (mode 1):',
376 ' api.php?action=query&list=deletedrevs&titles=Main%20Page|Talk:Main%20Page&drprop=user|comment|content',
377 'List the last 50 deleted contributions by Bob (mode 2):',
378 ' api.php?action=query&list=deletedrevs&druser=Bob&drlimit=50',
379 'List the first 50 deleted revisions in the main namespace (mode 3):',
380 ' api.php?action=query&list=deletedrevs&drdir=newer&drlimit=50',
381 'List the first 50 deleted pages in the Talk namespace (mode 3):',
382 ' api.php?action=query&list=deletedrevs&drdir=newer&drlimit=50&drnamespace=1&drunique=',
386 public function getVersion() {
387 return __CLASS__
. ': $Id$';