5 * Created on Oct 3, 2014 as a split from ApiQueryRevisions
7 * Copyright © 2006 Yuri Astrakhan "<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
28 * A base class for functions common to producing a list of revisions.
32 abstract class ApiQueryRevisionsBase
extends ApiQueryGeneratorBase
{
34 protected $limit, $diffto, $difftotext, $expandTemplates, $generateXML, $section,
35 $parseContent, $contentFormat, $setParsedLimit = true;
37 protected $fld_ids = false, $fld_flags = false, $fld_timestamp = false,
38 $fld_size = false, $fld_sha1 = false, $fld_comment = false,
39 $fld_parsedcomment = false, $fld_user = false, $fld_userid = false,
40 $fld_content = false, $fld_tags = false, $fld_contentmodel = false;
42 public function execute() {
46 public function executeGenerator( $resultPageSet ) {
47 $this->run( $resultPageSet );
51 * @param ApiPageSet $resultPageSet
54 abstract protected function run( ApiPageSet
$resultPageSet = null );
57 * Parse the parameters into the various instance fields.
59 * @param array $params
61 protected function parseParameters( $params ) {
62 if ( !is_null( $params['difftotext'] ) ) {
63 $this->difftotext
= $params['difftotext'];
64 } elseif ( !is_null( $params['diffto'] ) ) {
65 if ( $params['diffto'] == 'cur' ) {
66 $params['diffto'] = 0;
68 if ( ( !ctype_digit( $params['diffto'] ) ||
$params['diffto'] < 0 )
69 && $params['diffto'] != 'prev' && $params['diffto'] != 'next'
71 $p = $this->getModulePrefix();
73 "{$p}diffto must be set to a non-negative number, \"prev\", \"next\" or \"cur\"",
77 // Check whether the revision exists and is readable,
78 // DifferenceEngine returns a rather ambiguous empty
79 // string if that's not the case
80 if ( $params['diffto'] != 0 ) {
81 $difftoRev = Revision
::newFromID( $params['diffto'] );
83 $this->dieUsageMsg( array( 'nosuchrevid', $params['diffto'] ) );
85 if ( !$difftoRev->userCan( Revision
::DELETED_TEXT
, $this->getUser() ) ) {
86 $this->setWarning( "Couldn't diff to r{$difftoRev->getID()}: content is hidden" );
87 $params['diffto'] = null;
90 $this->diffto
= $params['diffto'];
93 $prop = array_flip( $params['prop'] );
95 $this->fld_ids
= isset( $prop['ids'] );
96 $this->fld_flags
= isset( $prop['flags'] );
97 $this->fld_timestamp
= isset( $prop['timestamp'] );
98 $this->fld_comment
= isset( $prop['comment'] );
99 $this->fld_parsedcomment
= isset( $prop['parsedcomment'] );
100 $this->fld_size
= isset( $prop['size'] );
101 $this->fld_sha1
= isset( $prop['sha1'] );
102 $this->fld_content
= isset( $prop['content'] );
103 $this->fld_contentmodel
= isset( $prop['contentmodel'] );
104 $this->fld_userid
= isset( $prop['userid'] );
105 $this->fld_user
= isset( $prop['user'] );
106 $this->fld_tags
= isset( $prop['tags'] );
108 if ( !empty( $params['contentformat'] ) ) {
109 $this->contentFormat
= $params['contentformat'];
112 $this->limit
= $params['limit'];
115 if ( $this->fld_content ||
!is_null( $this->diffto
) ||
!is_null( $this->difftotext
) ) {
117 $this->expandTemplates
= $params['expandtemplates'];
118 $this->generateXML
= $params['generatexml'];
119 $this->parseContent
= $params['parse'];
120 if ( $this->parseContent
) {
121 // Must manually initialize unset limit
122 if ( is_null( $this->limit
) ) {
126 if ( isset( $params['section'] ) ) {
127 $this->section
= $params['section'];
129 $this->section
= false;
133 $userMax = $this->parseContent ?
1 : ( $smallLimit ? ApiBase
::LIMIT_SML1
: ApiBase
::LIMIT_BIG1
);
134 $botMax = $this->parseContent ?
1 : ( $smallLimit ? ApiBase
::LIMIT_SML2
: ApiBase
::LIMIT_BIG2
);
135 if ( $this->limit
== 'max' ) {
136 $this->limit
= $this->getMain()->canApiHighLimits() ?
$botMax : $userMax;
137 if ( $this->setParsedLimit
) {
138 $this->getResult()->setParsedLimit( $this->getModuleName(), $this->limit
);
142 if ( is_null( $this->limit
) ) {
145 $this->validateLimit( 'limit', $this->limit
, 1, $userMax, $botMax );
149 * Extract information from the Revision
151 * @param Revision $revision
152 * @param object $row Should have a field 'ts_tags' if $this->fld_tags is set
155 protected function extractRevisionInfo( Revision
$revision, $row ) {
156 $title = $revision->getTitle();
157 $user = $this->getUser();
161 if ( $this->fld_ids
) {
162 $vals['revid'] = intval( $revision->getId() );
163 if ( !is_null( $revision->getParentId() ) ) {
164 $vals['parentid'] = intval( $revision->getParentId() );
168 if ( $this->fld_flags
&& $revision->isMinor() ) {
172 if ( $this->fld_user ||
$this->fld_userid
) {
173 if ( $revision->isDeleted( Revision
::DELETED_USER
) ) {
174 $vals['userhidden'] = '';
177 if ( $revision->userCan( Revision
::DELETED_USER
, $user ) ) {
178 if ( $this->fld_user
) {
179 $vals['user'] = $revision->getRawUserText();
181 $userid = $revision->getRawUser();
186 if ( $this->fld_userid
) {
187 $vals['userid'] = $userid;
192 if ( $this->fld_timestamp
) {
193 $vals['timestamp'] = wfTimestamp( TS_ISO_8601
, $revision->getTimestamp() );
196 if ( $this->fld_size
) {
197 if ( !is_null( $revision->getSize() ) ) {
198 $vals['size'] = intval( $revision->getSize() );
204 if ( $this->fld_sha1
) {
205 if ( $revision->isDeleted( Revision
::DELETED_TEXT
) ) {
206 $vals['sha1hidden'] = '';
209 if ( $revision->userCan( Revision
::DELETED_TEXT
, $user ) ) {
210 if ( $revision->getSha1() != '' ) {
211 $vals['sha1'] = wfBaseConvert( $revision->getSha1(), 36, 16, 40 );
218 if ( $this->fld_contentmodel
) {
219 $vals['contentmodel'] = $revision->getContentModel();
222 if ( $this->fld_comment ||
$this->fld_parsedcomment
) {
223 if ( $revision->isDeleted( Revision
::DELETED_COMMENT
) ) {
224 $vals['commenthidden'] = '';
227 if ( $revision->userCan( Revision
::DELETED_COMMENT
, $user ) ) {
228 $comment = $revision->getRawComment();
230 if ( $this->fld_comment
) {
231 $vals['comment'] = $comment;
234 if ( $this->fld_parsedcomment
) {
235 $vals['parsedcomment'] = Linker
::formatComment( $comment, $title );
240 if ( $this->fld_tags
) {
241 if ( $row->ts_tags
) {
242 $tags = explode( ',', $row->ts_tags
);
243 $this->getResult()->setIndexedTagName( $tags, 'tag' );
244 $vals['tags'] = $tags;
246 $vals['tags'] = array();
252 if ( $this->fld_content ||
!is_null( $this->diffto
) ||
!is_null( $this->difftotext
) ) {
253 $content = $revision->getContent( Revision
::FOR_THIS_USER
, $this->getUser() );
254 // Expand templates after getting section content because
255 // template-added sections don't count and Parser::preprocess()
256 // will have less input
257 if ( $content && $this->section
!== false ) {
258 $content = $content->getSection( $this->section
, false );
261 "There is no section {$this->section} in r" . $revision->getId(),
266 if ( $revision->isDeleted( Revision
::DELETED_TEXT
) ) {
267 $vals['texthidden'] = '';
269 } elseif ( !$content ) {
270 $vals['textmissing'] = '';
273 if ( $this->fld_content
&& $content ) {
276 if ( $this->generateXML
) {
277 if ( $content->getModel() === CONTENT_MODEL_WIKITEXT
) {
278 $t = $content->getNativeData(); # note: don't set $text
280 $wgParser->startExternalParse(
282 ParserOptions
::newFromContext( $this->getContext() ),
283 Parser
::OT_PREPROCESS
285 $dom = $wgParser->preprocessToDom( $t );
286 if ( is_callable( array( $dom, 'saveXML' ) ) ) {
287 $xml = $dom->saveXML();
289 $xml = $dom->__toString();
291 $vals['parsetree'] = $xml;
293 $vals['badcontentformatforparsetree'] = '';
294 $this->setWarning( "Conversion to XML is supported for wikitext only, " .
295 $title->getPrefixedDBkey() .
296 " uses content model " . $content->getModel() );
300 if ( $this->expandTemplates
&& !$this->parseContent
) {
301 #XXX: implement template expansion for all content types in ContentHandler?
302 if ( $content->getModel() === CONTENT_MODEL_WIKITEXT
) {
303 $text = $content->getNativeData();
305 $text = $wgParser->preprocess(
308 ParserOptions
::newFromContext( $this->getContext() )
311 $this->setWarning( "Template expansion is supported for wikitext only, " .
312 $title->getPrefixedDBkey() .
313 " uses content model " . $content->getModel() );
314 $vals['badcontentformat'] = '';
318 if ( $this->parseContent
) {
319 $po = $content->getParserOutput(
322 ParserOptions
::newFromContext( $this->getContext() )
324 $text = $po->getText();
327 if ( $text === null ) {
328 $format = $this->contentFormat ?
$this->contentFormat
: $content->getDefaultFormat();
329 $model = $content->getModel();
331 if ( !$content->isSupportedFormat( $format ) ) {
332 $name = $title->getPrefixedDBkey();
333 $this->setWarning( "The requested format {$this->contentFormat} is not " .
334 "supported for content model $model used by $name" );
335 $vals['badcontentformat'] = '';
338 $text = $content->serialize( $format );
339 // always include format and model.
340 // Format is needed to deserialize, model is needed to interpret.
341 $vals['contentformat'] = $format;
342 $vals['contentmodel'] = $model;
346 if ( $text !== false ) {
347 ApiResult
::setContent( $vals, $text );
351 if ( $content && ( !is_null( $this->diffto
) ||
!is_null( $this->difftotext
) ) ) {
352 static $n = 0; // Number of uncached diffs we've had
354 if ( $n < $this->getConfig()->get( 'APIMaxUncachedDiffs' ) ) {
355 $vals['diff'] = array();
356 $context = new DerivativeContext( $this->getContext() );
357 $context->setTitle( $title );
358 $handler = $revision->getContentHandler();
360 if ( !is_null( $this->difftotext
) ) {
361 $model = $title->getContentModel();
363 if ( $this->contentFormat
364 && !ContentHandler
::getForModelID( $model )->isSupportedFormat( $this->contentFormat
)
366 $name = $title->getPrefixedDBkey();
367 $this->setWarning( "The requested format {$this->contentFormat} is not " .
368 "supported for content model $model used by $name" );
369 $vals['diff']['badcontentformat'] = '';
372 $difftocontent = ContentHandler
::makeContent(
379 $engine = $handler->createDifferenceEngine( $context );
380 $engine->setContent( $content, $difftocontent );
383 $engine = $handler->createDifferenceEngine( $context, $revision->getID(), $this->diffto
);
384 $vals['diff']['from'] = $engine->getOldid();
385 $vals['diff']['to'] = $engine->getNewid();
388 $difftext = $engine->getDiffBody();
389 ApiResult
::setContent( $vals['diff'], $difftext );
390 if ( !$engine->wasCacheHit() ) {
395 $vals['diff']['notcached'] = '';
399 if ( $anyHidden && $revision->isDeleted( Revision
::DELETED_RESTRICTED
) ) {
400 $vals['suppressed'] = '';
406 public function getCacheMode( $params ) {
407 if ( $this->userCanSeeRevDel() ) {
414 public function getAllowedParams() {
417 ApiBase
::PARAM_ISMULTI
=> true,
418 ApiBase
::PARAM_DFLT
=> 'ids|timestamp|flags|comment|user',
419 ApiBase
::PARAM_TYPE
=> array(
433 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-prop',
436 ApiBase
::PARAM_TYPE
=> 'limit',
437 ApiBase
::PARAM_MIN
=> 1,
438 ApiBase
::PARAM_MAX
=> ApiBase
::LIMIT_BIG1
,
439 ApiBase
::PARAM_MAX2
=> ApiBase
::LIMIT_BIG2
,
440 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-limit',
442 'expandtemplates' => array(
443 ApiBase
::PARAM_DFLT
=> false,
444 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-expandtemplates',
446 'generatexml' => array(
447 ApiBase
::PARAM_DFLT
=> false,
448 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-generatexml',
451 ApiBase
::PARAM_DFLT
=> false,
452 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-parse',
455 ApiBase
::PARAM_DFLT
=> null,
456 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-section',
459 ApiBase
::PARAM_DFLT
=> null,
460 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-diffto',
462 'difftotext' => array(
463 ApiBase
::PARAM_DFLT
=> null,
464 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-difftotext',
466 'contentformat' => array(
467 ApiBase
::PARAM_TYPE
=> ContentHandler
::getAllContentFormats(),
468 ApiBase
::PARAM_DFLT
=> null,
469 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-contentformat',