Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | |
83.47% |
101 / 121 |
|
53.85% |
7 / 13 |
CRAP | |
0.00% |
0 / 1 |
RenderedRevision | |
83.47% |
101 / 121 |
|
53.85% |
7 / 13 |
61.29 | |
0.00% |
0 / 1 |
__construct | |
100.00% |
11 / 11 |
|
100.00% |
1 / 1 |
3 | |||
setSaveParseLogger | |
0.00% |
0 / 1 |
|
0.00% |
0 / 1 |
2 | |||
isContentDeleted | |
100.00% |
1 / 1 |
|
100.00% |
1 / 1 |
1 | |||
getRevision | |
100.00% |
1 / 1 |
|
100.00% |
1 / 1 |
1 | |||
getOptions | |
100.00% |
1 / 1 |
|
100.00% |
1 / 1 |
1 | |||
setRevisionParserOutput | |
100.00% |
3 / 3 |
|
100.00% |
1 / 1 |
2 | |||
getRevisionParserOutput | |
100.00% |
10 / 10 |
|
100.00% |
1 / 1 |
4 | |||
getSlotParserOutput | |
60.00% |
9 / 15 |
|
0.00% |
0 / 1 |
8.30 | |||
getSlotParserOutputUncached | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
1 | |||
updateRevision | |
92.31% |
12 / 13 |
|
0.00% |
0 / 1 |
4.01 | |||
pruneRevisionSensitiveOutput | |
94.12% |
16 / 17 |
|
0.00% |
0 / 1 |
5.01 | |||
setRevisionInternal | |
90.00% |
9 / 10 |
|
0.00% |
0 / 1 |
4.02 | |||
outputVariesOnRevisionMetaData | |
67.74% |
21 / 31 |
|
0.00% |
0 / 1 |
26.70 |
1 | <?php |
2 | /** |
3 | * This file is part of MediaWiki. |
4 | * |
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. |
9 | * |
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. |
14 | * |
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 |
19 | * |
20 | * @file |
21 | */ |
22 | |
23 | namespace MediaWiki\Revision; |
24 | |
25 | use Content; |
26 | use InvalidArgumentException; |
27 | use LogicException; |
28 | use MediaWiki\Content\Renderer\ContentRenderer; |
29 | use MediaWiki\Page\PageReference; |
30 | use MediaWiki\Parser\ParserOutput; |
31 | use MediaWiki\Parser\ParserOutputFlags; |
32 | use MediaWiki\Permissions\Authority; |
33 | use ParserOptions; |
34 | use Psr\Log\LoggerInterface; |
35 | use Psr\Log\NullLogger; |
36 | use Wikimedia\Assert\Assert; |
37 | |
38 | /** |
39 | * RenderedRevision represents the rendered representation of a revision. It acts as a lazy provider |
40 | * of ParserOutput objects for the revision's individual slots, as well as a combined ParserOutput |
41 | * of all slots. |
42 | * |
43 | * @since 1.32 |
44 | */ |
45 | class RenderedRevision implements SlotRenderingProvider { |
46 | |
47 | /** @var RevisionRecord */ |
48 | private $revision; |
49 | |
50 | /** |
51 | * @var ParserOptions |
52 | */ |
53 | private $options; |
54 | |
55 | /** |
56 | * @var int Audience to check when accessing content. |
57 | */ |
58 | private $audience = RevisionRecord::FOR_PUBLIC; |
59 | |
60 | /** |
61 | * @var Authority|null The user to use for audience checks during content access. |
62 | */ |
63 | private $performer = null; |
64 | |
65 | /** |
66 | * @var ParserOutput|null The combined ParserOutput for the revision, |
67 | * initialized lazily by getRevisionParserOutput(). |
68 | */ |
69 | private $revisionOutput = null; |
70 | |
71 | /** |
72 | * @var ParserOutput[] The ParserOutput for each slot, |
73 | * initialized lazily by getSlotParserOutput(). |
74 | */ |
75 | private $slotsOutput = []; |
76 | |
77 | /** |
78 | * @var callable Callback for combining slot output into revision output. |
79 | * Signature: function ( RenderedRevision $this ): ParserOutput. |
80 | */ |
81 | private $combineOutput; |
82 | |
83 | /** |
84 | * @var LoggerInterface For profiling ParserOutput re-use. |
85 | */ |
86 | private $saveParseLogger; |
87 | |
88 | /** |
89 | * @var ContentRenderer Service to render content. |
90 | */ |
91 | private $contentRenderer; |
92 | |
93 | /** |
94 | * @note Application logic should not instantiate RenderedRevision instances directly, |
95 | * but should use a RevisionRenderer instead. |
96 | * |
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 ContentRenderer $contentRenderer |
104 | * @param callable $combineOutput Callback for combining slot output into revision output. |
105 | * Signature: function ( RenderedRevision $this ): ParserOutput. |
106 | * @param int $audience Use RevisionRecord::FOR_PUBLIC, FOR_THIS_USER, or RAW. |
107 | * @param Authority|null $performer Required if $audience is FOR_THIS_USER. |
108 | */ |
109 | public function __construct( |
110 | RevisionRecord $revision, |
111 | ParserOptions $options, |
112 | ContentRenderer $contentRenderer, |
113 | callable $combineOutput, |
114 | $audience = RevisionRecord::FOR_PUBLIC, |
115 | Authority $performer = null |
116 | ) { |
117 | $this->options = $options; |
118 | |
119 | $this->setRevisionInternal( $revision ); |
120 | |
121 | $this->contentRenderer = $contentRenderer; |
122 | $this->combineOutput = $combineOutput; |
123 | $this->saveParseLogger = new NullLogger(); |
124 | |
125 | if ( $audience === RevisionRecord::FOR_THIS_USER && !$performer ) { |
126 | throw new InvalidArgumentException( |
127 | 'User must be specified when setting audience to FOR_THIS_USER' |
128 | ); |
129 | } |
130 | |
131 | $this->audience = $audience; |
132 | $this->performer = $performer; |
133 | } |
134 | |
135 | /** |
136 | * @param LoggerInterface $saveParseLogger |
137 | */ |
138 | public function setSaveParseLogger( LoggerInterface $saveParseLogger ) { |
139 | $this->saveParseLogger = $saveParseLogger; |
140 | } |
141 | |
142 | /** |
143 | * @return bool Whether the revision's content has been hidden from unprivileged users. |
144 | */ |
145 | public function isContentDeleted() { |
146 | return $this->revision->isDeleted( RevisionRecord::DELETED_TEXT ); |
147 | } |
148 | |
149 | /** |
150 | * @return RevisionRecord |
151 | */ |
152 | public function getRevision() { |
153 | return $this->revision; |
154 | } |
155 | |
156 | /** |
157 | * @return ParserOptions |
158 | */ |
159 | public function getOptions() { |
160 | return $this->options; |
161 | } |
162 | |
163 | /** |
164 | * Sets a ParserOutput to be returned by getRevisionParserOutput(). |
165 | * |
166 | * @note For internal use by RevisionRenderer only! This method may be modified |
167 | * or removed without notice per the deprecation policy. |
168 | * |
169 | * @internal |
170 | * |
171 | * @param ParserOutput $output |
172 | */ |
173 | public function setRevisionParserOutput( ParserOutput $output ) { |
174 | $this->revisionOutput = $output; |
175 | |
176 | // If there is only one slot, we assume that the combined output is identical |
177 | // with the main slot's output. This is intended to prevent a redundant re-parse of |
178 | // the content in case getSlotParserOutput( SlotRecord::MAIN ) is called, for instance |
179 | // from ContentHandler::getSecondaryDataUpdates. |
180 | if ( $this->revision->getSlotRoles() === [ SlotRecord::MAIN ] ) { |
181 | $this->slotsOutput[ SlotRecord::MAIN ] = $output; |
182 | } |
183 | } |
184 | |
185 | /** |
186 | * @param array $hints Hints given as an associative array. Known keys: |
187 | * - 'generate-html' => bool: Whether the caller is interested in output HTML (as opposed |
188 | * to just meta-data). Default is to generate HTML. |
189 | * @phan-param array{generate-html?:bool} $hints |
190 | * |
191 | * @return ParserOutput |
192 | */ |
193 | public function getRevisionParserOutput( array $hints = [] ) { |
194 | $withHtml = $hints['generate-html'] ?? true; |
195 | |
196 | if ( !$this->revisionOutput |
197 | || ( $withHtml && !$this->revisionOutput->hasText() ) |
198 | ) { |
199 | $output = call_user_func( $this->combineOutput, $this, $hints ); |
200 | |
201 | Assert::postcondition( |
202 | $output instanceof ParserOutput, |
203 | 'Callback did not return a ParserOutput object!' |
204 | ); |
205 | |
206 | $this->revisionOutput = $output; |
207 | } |
208 | |
209 | return $this->revisionOutput; |
210 | } |
211 | |
212 | /** |
213 | * @param string $role |
214 | * @param array $hints Hints given as an associative array. Known keys: |
215 | * - 'generate-html' => bool: Whether the caller is interested in output HTML (as opposed |
216 | * to just meta-data). Default is to generate HTML. |
217 | * @phan-param array{generate-html?:bool} $hints |
218 | * |
219 | * @throws SuppressedDataException if the content is not accessible for the audience |
220 | * specified in the constructor. |
221 | * @return ParserOutput |
222 | */ |
223 | public function getSlotParserOutput( $role, array $hints = [] ) { |
224 | $withHtml = $hints['generate-html'] ?? true; |
225 | |
226 | if ( !isset( $this->slotsOutput[ $role ] ) |
227 | || ( $withHtml && !$this->slotsOutput[ $role ]->hasText() ) |
228 | ) { |
229 | $content = $this->revision->getContentOrThrow( $role, $this->audience, $this->performer ); |
230 | |
231 | // XXX: allow SlotRoleHandler to control the ParserOutput? |
232 | $output = $this->getSlotParserOutputUncached( $content, $withHtml ); |
233 | |
234 | if ( $withHtml && !$output->hasText() ) { |
235 | throw new LogicException( |
236 | 'HTML generation was requested, but ' |
237 | . get_class( $content ) |
238 | . ' that passed to ' |
239 | . 'ContentRenderer::getParserOutput() returns a ParserOutput with no text set.' |
240 | ); |
241 | } |
242 | |
243 | // Detach watcher, to ensure option use is not recorded in the wrong ParserOutput. |
244 | $this->options->registerWatcher( null ); |
245 | |
246 | $this->slotsOutput[ $role ] = $output; |
247 | } |
248 | |
249 | return $this->slotsOutput[$role]; |
250 | } |
251 | |
252 | /** |
253 | * @note This method exists to make duplicate parses easier to see during profiling |
254 | * @param Content $content |
255 | * @param bool $withHtml |
256 | * @return ParserOutput |
257 | */ |
258 | private function getSlotParserOutputUncached( Content $content, $withHtml ) { |
259 | return $this->contentRenderer->getParserOutput( |
260 | $content, |
261 | $this->revision->getPage(), |
262 | $this->revision, |
263 | $this->options, |
264 | $withHtml |
265 | ); |
266 | } |
267 | |
268 | /** |
269 | * Updates the RevisionRecord after the revision has been saved. This can be used to discard |
270 | * and cached ParserOutput so parser functions like {{REVISIONTIMESTAMP}} or {{REVISIONID}} |
271 | * are re-evaluated. |
272 | * |
273 | * @note There should be no need to call this for null-edits. |
274 | * |
275 | * @param RevisionRecord $rev |
276 | */ |
277 | public function updateRevision( RevisionRecord $rev ) { |
278 | if ( $rev->getId() === $this->revision->getId() ) { |
279 | return; |
280 | } |
281 | |
282 | if ( $this->revision->getId() ) { |
283 | throw new LogicException( 'RenderedRevision already has a revision with ID ' |
284 | . $this->revision->getId() . ', can\'t update to revision with ID ' . $rev->getId() ); |
285 | } |
286 | |
287 | if ( !$this->revision->getSlots()->hasSameContent( $rev->getSlots() ) ) { |
288 | throw new LogicException( 'Cannot update to a revision with different content!' ); |
289 | } |
290 | |
291 | $this->setRevisionInternal( $rev ); |
292 | |
293 | $this->pruneRevisionSensitiveOutput( |
294 | $this->revision->getPageId(), |
295 | $this->revision->getId(), |
296 | $this->revision->getTimestamp() |
297 | ); |
298 | } |
299 | |
300 | /** |
301 | * Prune any output that depends on the revision ID. |
302 | * |
303 | * @param int|bool $actualPageId The actual page id, to check the used speculative page ID |
304 | * against; false, to not purge on vary-page-id; true, to purge on vary-page-id |
305 | * unconditionally. |
306 | * @param int|bool $actualRevId The actual rev id, to check the used speculative rev ID |
307 | * against,; false, to not purge on vary-revision-id; true, to purge on |
308 | * vary-revision-id unconditionally. |
309 | * @param string|bool $actualRevTimestamp The actual rev timestamp, to check against the |
310 | * parser output revision timestamp; false, to not purge on vary-revision-timestamp; |
311 | * true, to purge on vary-revision-timestamp unconditionally. |
312 | */ |
313 | private function pruneRevisionSensitiveOutput( |
314 | $actualPageId, |
315 | $actualRevId, |
316 | $actualRevTimestamp |
317 | ) { |
318 | if ( $this->revisionOutput ) { |
319 | if ( $this->outputVariesOnRevisionMetaData( |
320 | $this->revisionOutput, |
321 | $actualPageId, |
322 | $actualRevId, |
323 | $actualRevTimestamp |
324 | ) ) { |
325 | $this->revisionOutput = null; |
326 | } |
327 | } else { |
328 | $this->saveParseLogger->debug( __METHOD__ . ": no prepared revision output" ); |
329 | } |
330 | |
331 | foreach ( $this->slotsOutput as $role => $output ) { |
332 | if ( $this->outputVariesOnRevisionMetaData( |
333 | $output, |
334 | $actualPageId, |
335 | $actualRevId, |
336 | $actualRevTimestamp |
337 | ) ) { |
338 | unset( $this->slotsOutput[$role] ); |
339 | } |
340 | } |
341 | } |
342 | |
343 | /** |
344 | * @param RevisionRecord $revision |
345 | */ |
346 | private function setRevisionInternal( RevisionRecord $revision ) { |
347 | $this->revision = $revision; |
348 | |
349 | // Force the parser to use $this->revision to resolve magic words like {{REVISIONUSER}} |
350 | // if the revision is either known to be complete, or it doesn't have a revision ID set. |
351 | // If it's incomplete and we have a revision ID, the parser can do better by loading |
352 | // the revision from the database if needed to handle a magic word. |
353 | // |
354 | // The following considerations inform the logic described above: |
355 | // |
356 | // 1) If we have a saved revision already loaded, we want the parser to use it, instead of |
357 | // loading it again. |
358 | // |
359 | // 2) If the revision is a fake that wraps some kind of synthetic content, such as an |
360 | // error message from Article, it should be used directly and things like {{REVISIONUSER}} |
361 | // should not expected to work, since there may not even be an actual revision to |
362 | // refer to. |
363 | // |
364 | // 3) If the revision is a fake constructed around a page, a Content object, and |
365 | // a revision ID, to provide backwards compatibility to code that has access to those |
366 | // but not to a complete RevisionRecord for rendering, then we want the Parser to |
367 | // load the actual revision from the database when it encounters a magic word like |
368 | // {{REVISIONUSER}}, but we don't want to load that revision ahead of time just in case. |
369 | // |
370 | // 4) Previewing an edit to a template should use the submitted unsaved |
371 | // MutableRevisionRecord for self-transclusions in the template's documentation (see T7278). |
372 | // That revision would be complete except for the ID field. |
373 | // |
374 | // 5) Pre-save transform would provide a RevisionRecord that has all meta-data but is |
375 | // incomplete due to not yet having content set. However, since it doesn't have a revision |
376 | // ID either, the below code would still force it to be used, allowing |
377 | // {{subst::REVISIONUSER}} to function as expected. |
378 | |
379 | if ( $this->revision->isReadyForInsertion() || !$this->revision->getId() ) { |
380 | $oldCallback = $this->options->getCurrentRevisionRecordCallback(); |
381 | $this->options->setCurrentRevisionRecordCallback( |
382 | function ( PageReference $parserPage, $parser = null ) use ( $oldCallback ) { |
383 | if ( $this->revision->getPage()->isSamePageAs( $parserPage ) ) { |
384 | return $this->revision; |
385 | } else { |
386 | return call_user_func( $oldCallback, $parserPage, $parser ); |
387 | } |
388 | } |
389 | ); |
390 | } |
391 | } |
392 | |
393 | /** |
394 | * @param ParserOutput $parserOutput |
395 | * @param int|bool $actualPageId The actual page id, to check the used speculative page ID |
396 | * against; false, to not purge on vary-page-id; true, to purge on vary-page-id |
397 | * unconditionally. |
398 | * @param int|bool $actualRevId The actual rev id, to check the used speculative rev ID |
399 | * against,; false, to not purge on vary-revision-id; true, to purge on |
400 | * vary-revision-id unconditionally. |
401 | * @param string|bool $actualRevTimestamp The actual rev timestamp, to check against the |
402 | * parser output revision timestamp; false, to not purge on vary-revision-timestamp; |
403 | * true, to purge on vary-revision-timestamp unconditionally. |
404 | * @return bool |
405 | */ |
406 | private function outputVariesOnRevisionMetaData( |
407 | ParserOutput $parserOutput, |
408 | $actualPageId, |
409 | $actualRevId, |
410 | $actualRevTimestamp |
411 | ) { |
412 | $logger = $this->saveParseLogger; |
413 | $varyMsg = __METHOD__ . ": cannot use prepared output for '{title}'"; |
414 | $context = [ 'title' => (string)$this->revision->getPage() ]; |
415 | |
416 | if ( $parserOutput->getOutputFlag( ParserOutputFlags::VARY_REVISION ) ) { |
417 | // If {{PAGEID}} resolved to 0, then that word need to resolve to the actual page ID |
418 | $logger->info( "$varyMsg (vary-revision)", $context ); |
419 | return true; |
420 | } elseif ( |
421 | $parserOutput->getOutputFlag( ParserOutputFlags::VARY_REVISION_ID ) |
422 | && $actualRevId !== false |
423 | && ( $actualRevId === true || $parserOutput->getSpeculativeRevIdUsed() !== $actualRevId ) |
424 | ) { |
425 | $logger->info( "$varyMsg (vary-revision-id and wrong ID)", $context ); |
426 | return true; |
427 | } elseif ( |
428 | $parserOutput->getOutputFlag( ParserOutputFlags::VARY_REVISION_TIMESTAMP ) |
429 | && $actualRevTimestamp !== false |
430 | && ( $actualRevTimestamp === true || |
431 | $parserOutput->getRevisionTimestampUsed() !== $actualRevTimestamp ) |
432 | ) { |
433 | $logger->info( "$varyMsg (vary-revision-timestamp and wrong timestamp)", $context ); |
434 | return true; |
435 | } elseif ( |
436 | $parserOutput->getOutputFlag( ParserOutputFlags::VARY_PAGE_ID ) |
437 | && $actualPageId !== false |
438 | && ( $actualPageId === true || $parserOutput->getSpeculativePageIdUsed() !== $actualPageId ) |
439 | ) { |
440 | $logger->info( "$varyMsg (vary-page-id and wrong ID)", $context ); |
441 | return true; |
442 | } elseif ( $parserOutput->getOutputFlag( ParserOutputFlags::VARY_REVISION_EXISTS ) ) { |
443 | // If {{REVISIONID}} resolved to '', it now needs to resolve to '-'. |
444 | // Note that edit stashing always uses '-', which can be used for both |
445 | // edit filter checks and canonical parser cache. |
446 | $logger->info( "$varyMsg (vary-revision-exists)", $context ); |
447 | return true; |
448 | } elseif ( |
449 | $parserOutput->getOutputFlag( ParserOutputFlags::VARY_REVISION_SHA1 ) && |
450 | $parserOutput->getRevisionUsedSha1Base36() !== $this->revision->getSha1() |
451 | ) { |
452 | // If a self-transclusion used the proposed page text, it must match the final |
453 | // page content after PST transformations and automatically merged edit conflicts |
454 | $logger->info( "$varyMsg (vary-revision-sha1 with wrong SHA-1)", $context ); |
455 | return true; |
456 | } |
457 | |
458 | // NOTE: In the original fix for T135261, the output was discarded if ParserOutputFlags::VARY_USER was |
459 | // set for a null-edit. The reason was that the original rendering in that case was |
460 | // targeting the user making the null-edit, not the user who made the original edit, |
461 | // causing {{REVISIONUSER}} to return the wrong name. |
462 | // This case is now expected to be handled by the code in RevisionRenderer that |
463 | // constructs the ParserOptions: For a null-edit, setCurrentRevisionRecordCallback is |
464 | // called with the old, existing revision. |
465 | $logger->debug( __METHOD__ . ": reusing prepared output for '{title}'", $context ); |
466 | return false; |
467 | } |
468 | } |