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, $fetchContent, $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, $fld_parsetree = 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'] );
107 $this->fld_parsetree
= isset( $prop['parsetree'] );
109 if ( !empty( $params['contentformat'] ) ) {
110 $this->contentFormat
= $params['contentformat'];
113 $this->limit
= $params['limit'];
115 $this->fetchContent
= $this->fld_content ||
!is_null( $this->diffto
)
116 ||
!is_null( $this->difftotext
) ||
$this->fld_parsetree
;
119 if ( $this->fetchContent
) {
121 $this->expandTemplates
= $params['expandtemplates'];
122 $this->generateXML
= $params['generatexml'];
123 $this->parseContent
= $params['parse'];
124 if ( $this->parseContent
) {
125 // Must manually initialize unset limit
126 if ( is_null( $this->limit
) ) {
130 if ( isset( $params['section'] ) ) {
131 $this->section
= $params['section'];
133 $this->section
= false;
137 $userMax = $this->parseContent ?
1 : ( $smallLimit ? ApiBase
::LIMIT_SML1
: ApiBase
::LIMIT_BIG1
);
138 $botMax = $this->parseContent ?
1 : ( $smallLimit ? ApiBase
::LIMIT_SML2
: ApiBase
::LIMIT_BIG2
);
139 if ( $this->limit
== 'max' ) {
140 $this->limit
= $this->getMain()->canApiHighLimits() ?
$botMax : $userMax;
141 if ( $this->setParsedLimit
) {
142 $this->getResult()->addParsedLimit( $this->getModuleName(), $this->limit
);
146 if ( is_null( $this->limit
) ) {
149 $this->validateLimit( 'limit', $this->limit
, 1, $userMax, $botMax );
153 * Extract information from the Revision
155 * @param Revision $revision
156 * @param object $row Should have a field 'ts_tags' if $this->fld_tags is set
159 protected function extractRevisionInfo( Revision
$revision, $row ) {
160 $title = $revision->getTitle();
161 $user = $this->getUser();
165 if ( $this->fld_ids
) {
166 $vals['revid'] = intval( $revision->getId() );
167 if ( !is_null( $revision->getParentId() ) ) {
168 $vals['parentid'] = intval( $revision->getParentId() );
172 if ( $this->fld_flags
) {
173 $vals['minor'] = $revision->isMinor();
176 if ( $this->fld_user ||
$this->fld_userid
) {
177 if ( $revision->isDeleted( Revision
::DELETED_USER
) ) {
178 $vals['userhidden'] = true;
181 if ( $revision->userCan( Revision
::DELETED_USER
, $user ) ) {
182 if ( $this->fld_user
) {
183 $vals['user'] = $revision->getUserText( Revision
::RAW
);
185 $userid = $revision->getUser( Revision
::RAW
);
187 $vals['anon'] = true;
190 if ( $this->fld_userid
) {
191 $vals['userid'] = $userid;
196 if ( $this->fld_timestamp
) {
197 $vals['timestamp'] = wfTimestamp( TS_ISO_8601
, $revision->getTimestamp() );
200 if ( $this->fld_size
) {
201 if ( !is_null( $revision->getSize() ) ) {
202 $vals['size'] = intval( $revision->getSize() );
208 if ( $this->fld_sha1
) {
209 if ( $revision->isDeleted( Revision
::DELETED_TEXT
) ) {
210 $vals['sha1hidden'] = true;
213 if ( $revision->userCan( Revision
::DELETED_TEXT
, $user ) ) {
214 if ( $revision->getSha1() != '' ) {
215 $vals['sha1'] = wfBaseConvert( $revision->getSha1(), 36, 16, 40 );
222 if ( $this->fld_contentmodel
) {
223 $vals['contentmodel'] = $revision->getContentModel();
226 if ( $this->fld_comment ||
$this->fld_parsedcomment
) {
227 if ( $revision->isDeleted( Revision
::DELETED_COMMENT
) ) {
228 $vals['commenthidden'] = true;
231 if ( $revision->userCan( Revision
::DELETED_COMMENT
, $user ) ) {
232 $comment = $revision->getComment( Revision
::RAW
);
234 if ( $this->fld_comment
) {
235 $vals['comment'] = $comment;
238 if ( $this->fld_parsedcomment
) {
239 $vals['parsedcomment'] = Linker
::formatComment( $comment, $title );
244 if ( $this->fld_tags
) {
245 if ( $row->ts_tags
) {
246 $tags = explode( ',', $row->ts_tags
);
247 ApiResult
::setIndexedTagName( $tags, 'tag' );
248 $vals['tags'] = $tags;
250 $vals['tags'] = array();
256 if ( $this->fetchContent
) {
257 $content = $revision->getContent( Revision
::FOR_THIS_USER
, $this->getUser() );
258 // Expand templates after getting section content because
259 // template-added sections don't count and Parser::preprocess()
260 // will have less input
261 if ( $content && $this->section
!== false ) {
262 $content = $content->getSection( $this->section
, false );
265 "There is no section {$this->section} in r" . $revision->getId(),
270 if ( $revision->isDeleted( Revision
::DELETED_TEXT
) ) {
271 $vals['texthidden'] = true;
273 } elseif ( !$content ) {
274 $vals['textmissing'] = true;
277 if ( $this->fld_parsetree ||
( $this->fld_content
&& $this->generateXML
) ) {
278 if ( !$this->fld_parsetree
) {
279 $this->logFeatureUsage( 'action=query&prop=revisions+base&generatexml' );
282 if ( $content->getModel() === CONTENT_MODEL_WIKITEXT
) {
283 $t = $content->getNativeData(); # note: don't set $text
285 $wgParser->startExternalParse(
287 ParserOptions
::newFromContext( $this->getContext() ),
288 Parser
::OT_PREPROCESS
290 $dom = $wgParser->preprocessToDom( $t );
291 if ( is_callable( array( $dom, 'saveXML' ) ) ) {
292 $xml = $dom->saveXML();
294 $xml = $dom->__toString();
296 $vals['parsetree'] = $xml;
298 $vals['badcontentformatforparsetree'] = true;
299 $this->setWarning( "Conversion to XML is supported for wikitext only, " .
300 $title->getPrefixedDBkey() .
301 " uses content model " . $content->getModel() );
306 if ( $this->fld_content
&& $content ) {
309 if ( $this->expandTemplates
&& !$this->parseContent
) {
310 #XXX: implement template expansion for all content types in ContentHandler?
311 if ( $content->getModel() === CONTENT_MODEL_WIKITEXT
) {
312 $text = $content->getNativeData();
314 $text = $wgParser->preprocess(
317 ParserOptions
::newFromContext( $this->getContext() )
320 $this->setWarning( "Template expansion is supported for wikitext only, " .
321 $title->getPrefixedDBkey() .
322 " uses content model " . $content->getModel() );
323 $vals['badcontentformat'] = true;
327 if ( $this->parseContent
) {
328 $po = $content->getParserOutput(
331 ParserOptions
::newFromContext( $this->getContext() )
333 $text = $po->getText();
336 if ( $text === null ) {
337 $format = $this->contentFormat ?
$this->contentFormat
: $content->getDefaultFormat();
338 $model = $content->getModel();
340 if ( !$content->isSupportedFormat( $format ) ) {
341 $name = $title->getPrefixedDBkey();
342 $this->setWarning( "The requested format {$this->contentFormat} is not " .
343 "supported for content model $model used by $name" );
344 $vals['badcontentformat'] = true;
347 $text = $content->serialize( $format );
348 // always include format and model.
349 // Format is needed to deserialize, model is needed to interpret.
350 $vals['contentformat'] = $format;
351 $vals['contentmodel'] = $model;
355 if ( $text !== false ) {
356 ApiResult
::setContentValue( $vals, 'content', $text );
360 if ( $content && ( !is_null( $this->diffto
) ||
!is_null( $this->difftotext
) ) ) {
361 static $n = 0; // Number of uncached diffs we've had
363 if ( $n < $this->getConfig()->get( 'APIMaxUncachedDiffs' ) ) {
364 $vals['diff'] = array();
365 $context = new DerivativeContext( $this->getContext() );
366 $context->setTitle( $title );
367 $handler = $revision->getContentHandler();
369 if ( !is_null( $this->difftotext
) ) {
370 $model = $title->getContentModel();
372 if ( $this->contentFormat
373 && !ContentHandler
::getForModelID( $model )->isSupportedFormat( $this->contentFormat
)
375 $name = $title->getPrefixedDBkey();
376 $this->setWarning( "The requested format {$this->contentFormat} is not " .
377 "supported for content model $model used by $name" );
378 $vals['diff']['badcontentformat'] = true;
381 $difftocontent = ContentHandler
::makeContent(
388 $engine = $handler->createDifferenceEngine( $context );
389 $engine->setContent( $content, $difftocontent );
392 $engine = $handler->createDifferenceEngine( $context, $revision->getID(), $this->diffto
);
393 $vals['diff']['from'] = $engine->getOldid();
394 $vals['diff']['to'] = $engine->getNewid();
397 $difftext = $engine->getDiffBody();
398 ApiResult
::setContentValue( $vals['diff'], 'body', $difftext );
399 if ( !$engine->wasCacheHit() ) {
404 $vals['diff']['notcached'] = true;
408 if ( $anyHidden && $revision->isDeleted( Revision
::DELETED_RESTRICTED
) ) {
409 $vals['suppressed'] = true;
415 public function getCacheMode( $params ) {
416 if ( $this->userCanSeeRevDel() ) {
423 public function getAllowedParams() {
426 ApiBase
::PARAM_ISMULTI
=> true,
427 ApiBase
::PARAM_DFLT
=> 'ids|timestamp|flags|comment|user',
428 ApiBase
::PARAM_TYPE
=> array(
443 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-prop',
444 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> array(
445 'ids' => 'apihelp-query+revisions+base-paramvalue-prop-ids',
446 'flags' => 'apihelp-query+revisions+base-paramvalue-prop-flags',
447 'timestamp' => 'apihelp-query+revisions+base-paramvalue-prop-timestamp',
448 'user' => 'apihelp-query+revisions+base-paramvalue-prop-user',
449 'userid' => 'apihelp-query+revisions+base-paramvalue-prop-userid',
450 'size' => 'apihelp-query+revisions+base-paramvalue-prop-size',
451 'sha1' => 'apihelp-query+revisions+base-paramvalue-prop-sha1',
452 'contentmodel' => 'apihelp-query+revisions+base-paramvalue-prop-contentmodel',
453 'comment' => 'apihelp-query+revisions+base-paramvalue-prop-comment',
454 'parsedcomment' => 'apihelp-query+revisions+base-paramvalue-prop-parsedcomment',
455 'content' => 'apihelp-query+revisions+base-paramvalue-prop-content',
456 'tags' => 'apihelp-query+revisions+base-paramvalue-prop-tags',
457 'parsetree' => array( 'apihelp-query+revisions+base-paramvalue-prop-parsetree',
458 CONTENT_MODEL_WIKITEXT
),
462 ApiBase
::PARAM_TYPE
=> 'limit',
463 ApiBase
::PARAM_MIN
=> 1,
464 ApiBase
::PARAM_MAX
=> ApiBase
::LIMIT_BIG1
,
465 ApiBase
::PARAM_MAX2
=> ApiBase
::LIMIT_BIG2
,
466 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-limit',
468 'expandtemplates' => array(
469 ApiBase
::PARAM_DFLT
=> false,
470 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-expandtemplates',
472 'generatexml' => array(
473 ApiBase
::PARAM_DFLT
=> false,
474 ApiBase
::PARAM_DEPRECATED
=> true,
475 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-generatexml',
478 ApiBase
::PARAM_DFLT
=> false,
479 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-parse',
482 ApiBase
::PARAM_DFLT
=> null,
483 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-section',
486 ApiBase
::PARAM_DFLT
=> null,
487 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-diffto',
489 'difftotext' => array(
490 ApiBase
::PARAM_DFLT
=> null,
491 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-difftotext',
493 'contentformat' => array(
494 ApiBase
::PARAM_TYPE
=> ContentHandler
::getAllContentFormats(),
495 ApiBase
::PARAM_DFLT
=> null,
496 ApiBase
::PARAM_HELP_MSG
=> 'apihelp-query+revisions+base-param-contentformat',