3 * This file is part of MediaWiki.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
23 namespace MediaWiki\Revision
;
25 use InvalidArgumentException
;
29 use Psr\Log\LoggerInterface
;
30 use Psr\Log\NullLogger
;
35 use Wikimedia\Assert\Assert
;
38 * RenderedRevision represents the rendered representation of a revision. It acts as a lazy provider
39 * of ParserOutput objects for the revision's individual slots, as well as a combined ParserOutput
44 class RenderedRevision
implements SlotRenderingProvider
{
51 /** @var RevisionRecord */
60 * @var int Audience to check when accessing content.
62 private $audience = RevisionRecord
::FOR_PUBLIC
;
65 * @var User|null The user to use for audience checks during content access.
67 private $forUser = null;
70 * @var ParserOutput|null The combined ParserOutput for the revision,
71 * initialized lazily by getRevisionParserOutput().
73 private $revisionOutput = null;
76 * @var ParserOutput[] The ParserOutput for each slot,
77 * initialized lazily by getSlotParserOutput().
79 private $slotsOutput = [];
82 * @var callable Callback for combining slot output into revision output.
83 * Signature: function ( RenderedRevision $this ): ParserOutput.
85 private $combineOutput;
88 * @var LoggerInterface For profiling ParserOutput re-use.
90 private $saveParseLogger;
93 * @note Application logic should not instantiate RenderedRevision instances directly,
94 * but should use a RevisionRenderer instead.
97 * @param RevisionRecord $revision The revision to render. The content for rendering will be
98 * taken from this RevisionRecord. However, if the RevisionRecord is not complete
99 * according isReadyForInsertion(), but a revision ID is known, the parser may load
100 * the revision from the database if it needs revision meta data to handle magic
101 * words like {{REVISIONUSER}}.
102 * @param ParserOptions $options
103 * @param callable $combineOutput Callback for combining slot output into revision output.
104 * Signature: function ( RenderedRevision $this ): ParserOutput.
105 * @param int $audience Use RevisionRecord::FOR_PUBLIC, FOR_THIS_USER, or RAW.
106 * @param User|null $forUser Required if $audience is FOR_THIS_USER.
108 public function __construct(
110 RevisionRecord
$revision,
111 ParserOptions
$options,
112 callable
$combineOutput,
113 $audience = RevisionRecord
::FOR_PUBLIC
,
116 $this->title
= $title;
117 $this->options
= $options;
119 $this->setRevisionInternal( $revision );
121 $this->combineOutput
= $combineOutput;
122 $this->saveParseLogger
= new NullLogger();
124 if ( $audience === RevisionRecord
::FOR_THIS_USER
&& !$forUser ) {
125 throw new InvalidArgumentException(
126 'User must be specified when setting audience to FOR_THIS_USER'
130 $this->audience
= $audience;
131 $this->forUser
= $forUser;
135 * @param LoggerInterface $saveParseLogger
137 public function setSaveParseLogger( LoggerInterface
$saveParseLogger ) {
138 $this->saveParseLogger
= $saveParseLogger;
142 * @return bool Whether the revision's content has been hidden from unprivileged users.
144 public function isContentDeleted() {
145 return $this->revision
->isDeleted( RevisionRecord
::DELETED_TEXT
);
149 * @return RevisionRecord
151 public function getRevision() {
152 return $this->revision
;
156 * @return ParserOptions
158 public function getOptions() {
159 return $this->options
;
163 * Sets a ParserOutput to be returned by getRevisionParserOutput().
165 * @note For internal use by RevisionRenderer only! This method may be modified
166 * or removed without notice per the deprecation policy.
170 * @param ParserOutput $output
172 public function setRevisionParserOutput( ParserOutput
$output ) {
173 $this->revisionOutput
= $output;
175 // If there is only one slot, we assume that the combined output is identical
176 // with the main slot's output. This is intended to prevent a redundant re-parse of
177 // the content in case getSlotParserOutput( SlotRecord::MAIN ) is called, for instance
178 // from ContentHandler::getSecondaryDataUpdates.
179 if ( $this->revision
->getSlotRoles() === [ SlotRecord
::MAIN
] ) {
180 $this->slotsOutput
[ SlotRecord
::MAIN
] = $output;
185 * @param array $hints Hints given as an associative array. Known keys:
186 * - 'generate-html' => bool: Whether the caller is interested in output HTML (as opposed
187 * to just meta-data). Default is to generate HTML.
188 * @phan-param array{generate-html?:bool} $hints
190 * @return ParserOutput
192 public function getRevisionParserOutput( array $hints = [] ) {
193 $withHtml = $hints['generate-html'] ??
true;
195 if ( !$this->revisionOutput
196 ||
( $withHtml && !$this->revisionOutput
->hasText() )
198 $output = call_user_func( $this->combineOutput
, $this, $hints );
200 Assert
::postcondition(
201 $output instanceof ParserOutput
,
202 'Callback did not return a ParserOutput object!'
205 $this->revisionOutput
= $output;
208 return $this->revisionOutput
;
212 * @param string $role
213 * @param array $hints Hints given as an associative array. Known keys:
214 * - 'generate-html' => bool: Whether the caller is interested in output HTML (as opposed
215 * to just meta-data). Default is to generate HTML.
216 * @phan-param array{generate-html?:bool} $hints
218 * @throws SuppressedDataException if the content is not accessible for the audience
219 * specified in the constructor.
220 * @return ParserOutput
222 public function getSlotParserOutput( $role, array $hints = [] ) {
223 $withHtml = $hints['generate-html'] ??
true;
225 if ( !isset( $this->slotsOutput
[ $role ] )
226 ||
( $withHtml && !$this->slotsOutput
[ $role ]->hasText() )
228 $content = $this->revision
->getContent( $role, $this->audience
, $this->forUser
);
231 throw new SuppressedDataException(
232 'Access to the content has been suppressed for this audience'
235 // XXX: allow SlotRoleHandler to control the ParserOutput?
236 $output = $this->getSlotParserOutputUncached( $content, $withHtml );
238 if ( $withHtml && !$output->hasText() ) {
239 throw new LogicException(
240 'HTML generation was requested, but '
241 . get_class( $content )
242 . '::getParserOutput() returns a ParserOutput with no text set.'
246 // Detach watcher, to ensure option use is not recorded in the wrong ParserOutput.
247 $this->options
->registerWatcher( null );
250 $this->slotsOutput
[ $role ] = $output;
253 return $this->slotsOutput
[$role];
257 * @note This method exist to make duplicate parses easier to see during profiling
258 * @param Content $content
259 * @param bool $withHtml
260 * @return ParserOutput
262 private function getSlotParserOutputUncached( Content
$content, $withHtml ) {
263 return $content->getParserOutput(
265 $this->revision
->getId(),
272 * Updates the RevisionRecord after the revision has been saved. This can be used to discard
273 * and cached ParserOutput so parser functions like {{REVISIONTIMESTAMP}} or {{REVISIONID}}
276 * @note There should be no need to call this for null-edits.
278 * @param RevisionRecord $rev
280 public function updateRevision( RevisionRecord
$rev ) {
281 if ( $rev->getId() === $this->revision
->getId() ) {
285 if ( $this->revision
->getId() ) {
286 throw new LogicException( 'RenderedRevision already has a revision with ID '
287 . $this->revision
->getId(), ', can\'t update to revision with ID ' . $rev->getId() );
290 if ( !$this->revision
->getSlots()->hasSameContent( $rev->getSlots() ) ) {
291 throw new LogicException( 'Cannot update to a revision with different content!' );
294 $this->setRevisionInternal( $rev );
296 $this->pruneRevisionSensitiveOutput(
297 $this->revision
->getPageId(),
298 $this->revision
->getId(),
299 $this->revision
->getTimestamp()
304 * Prune any output that depends on the revision ID.
306 * @param int|bool $actualPageId The actual page id, to check the used speculative page ID
307 * against; false, to not purge on vary-page-id; true, to purge on vary-page-id
309 * @param int|bool $actualRevId The actual rev id, to check the used speculative rev ID
310 * against,; false, to not purge on vary-revision-id; true, to purge on
311 * vary-revision-id unconditionally.
312 * @param string|bool $actualRevTimestamp The actual rev timestamp, to check against the
313 * parser output revision timestamp; false, to not purge on vary-revision-timestamp;
314 * true, to purge on vary-revision-timestamp unconditionally.
316 private function pruneRevisionSensitiveOutput(
321 if ( $this->revisionOutput
) {
322 if ( $this->outputVariesOnRevisionMetaData(
323 $this->revisionOutput
,
328 $this->revisionOutput
= null;
331 $this->saveParseLogger
->debug( __METHOD__
. ": no prepared revision output" );
334 foreach ( $this->slotsOutput
as $role => $output ) {
335 if ( $this->outputVariesOnRevisionMetaData(
341 unset( $this->slotsOutput
[$role] );
347 * @param RevisionRecord $revision
349 private function setRevisionInternal( RevisionRecord
$revision ) {
350 $this->revision
= $revision;
352 // Force the parser to use $this->revision to resolve magic words like {{REVISIONUSER}}
353 // if the revision is either known to be complete, or it doesn't have a revision ID set.
354 // If it's incomplete and we have a revision ID, the parser can do better by loading
355 // the revision from the database if needed to handle a magic word.
357 // The following considerations inform the logic described above:
359 // 1) If we have a saved revision already loaded, we want the parser to use it, instead of
362 // 2) If the revision is a fake that wraps some kind of synthetic content, such as an
363 // error message from Article, it should be used directly and things like {{REVISIONUSER}}
364 // should not expected to work, since there may not even be an actual revision to
367 // 3) If the revision is a fake constructed around a Title, a Content object, and
368 // a revision ID, to provide backwards compatibility to code that has access to those
369 // but not to a complete RevisionRecord for rendering, then we want the Parser to
370 // load the actual revision from the database when it encounters a magic word like
371 // {{REVISIONUSER}}, but we don't want to load that revision ahead of time just in case.
373 // 4) Previewing an edit to a template should use the submitted unsaved
374 // MutableRevisionRecord for self-transclusions in the template's documentation (see T7278).
375 // That revision would be complete except for the ID field.
377 // 5) Pre-save transform would provide a RevisionRecord that has all meta-data but is
378 // incomplete due to not yet having content set. However, since it doesn't have a revision
379 // ID either, the below code would still force it to be used, allowing
380 // {{subst::REVISIONUSER}} to function as expected.
382 if ( $this->revision
->isReadyForInsertion() ||
!$this->revision
->getId() ) {
383 $title = $this->title
;
384 $oldCallback = $this->options
->getCurrentRevisionCallback();
385 $this->options
->setCurrentRevisionCallback(
386 function ( Title
$parserTitle, $parser = false ) use ( $title, $oldCallback ) {
387 if ( $title->equals( $parserTitle ) ) {
388 $legacyRevision = new Revision( $this->revision
);
389 return $legacyRevision;
391 return call_user_func( $oldCallback, $parserTitle, $parser );
399 * @param ParserOutput $out
400 * @param int|bool $actualPageId The actual page id, to check the used speculative page ID
401 * against; false, to not purge on vary-page-id; true, to purge on vary-page-id
403 * @param int|bool $actualRevId The actual rev id, to check the used speculative rev ID
404 * against,; false, to not purge on vary-revision-id; true, to purge on
405 * vary-revision-id unconditionally.
406 * @param string|bool $actualRevTimestamp The actual rev timestamp, to check against the
407 * parser output revision timestamp; false, to not purge on vary-revision-timestamp;
408 * true, to purge on vary-revision-timestamp unconditionally.
411 private function outputVariesOnRevisionMetaData(
417 $logger = $this->saveParseLogger
;
418 $varyMsg = __METHOD__
. ": cannot use prepared output for '{title}'";
419 $context = [ 'title' => $this->title
->getPrefixedText() ];
421 if ( $out->getFlag( 'vary-revision' ) ) {
422 // If {{PAGEID}} resolved to 0, then that word need to resolve to the actual page ID
423 $logger->info( "$varyMsg (vary-revision)", $context );
426 $out->getFlag( 'vary-revision-id' )
427 && $actualRevId !== false
428 && ( $actualRevId === true ||
$out->getSpeculativeRevIdUsed() !== $actualRevId )
430 $logger->info( "$varyMsg (vary-revision-id and wrong ID)", $context );
433 $out->getFlag( 'vary-revision-timestamp' )
434 && $actualRevTimestamp !== false
435 && ( $actualRevTimestamp === true ||
436 $out->getRevisionTimestampUsed() !== $actualRevTimestamp )
438 $logger->info( "$varyMsg (vary-revision-timestamp and wrong timestamp)", $context );
441 $out->getFlag( 'vary-page-id' )
442 && $actualPageId !== false
443 && ( $actualPageId === true ||
$out->getSpeculativePageIdUsed() !== $actualPageId )
445 $logger->info( "$varyMsg (vary-page-id and wrong ID)", $context );
447 } elseif ( $out->getFlag( 'vary-revision-exists' ) ) {
448 // If {{REVISIONID}} resolved to '', it now needs to resolve to '-'.
449 // Note that edit stashing always uses '-', which can be used for both
450 // edit filter checks and canonical parser cache.
451 $logger->info( "$varyMsg (vary-revision-exists)", $context );
454 $out->getFlag( 'vary-revision-sha1' ) &&
455 $out->getRevisionUsedSha1Base36() !== $this->revision
->getSha1()
457 // If a self-transclusion used the proposed page text, it must match the final
458 // page content after PST transformations and automatically merged edit conflicts
459 $logger->info( "$varyMsg (vary-revision-sha1 with wrong SHA-1)", $context );
463 // NOTE: In the original fix for T135261, the output was discarded if 'vary-user' was
464 // set for a null-edit. The reason was that the original rendering in that case was
465 // targeting the user making the null-edit, not the user who made the original edit,
466 // causing {{REVISIONUSER}} to return the wrong name.
467 // This case is now expected to be handled by the code in RevisionRenderer that
468 // constructs the ParserOptions: For a null-edit, setCurrentRevisionCallback is called
469 // with the old, existing revision.
470 $logger->debug( __METHOD__
. ": reusing prepared output for '{title}'", $context );