includes/Revision/RevisionRenderer.php

   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 Html;
  26 use InvalidArgumentException;
  27 use MediaWiki\Storage\RevisionRecord;
  28 use MediaWiki\Storage\SlotRecord;
  29 use ParserOptions;
  30 use ParserOutput;
  31 use Psr\Log\LoggerInterface;
  32 use Psr\Log\NullLogger;
  33 use Title;
  34 use User;
  35 use Wikimedia\Rdbms\ILoadBalancer;
  36
  37 /**
  38  * The RevisionRenderer service provides access to rendered output for revisions.
  39  * It does so be acting as a factory for RenderedRevision instances, which in turn
  40  * provide lazy access to ParserOutput objects.
  41  *
  42  * One key responsibility of RevisionRenderer is implementing the layout used to combine
  43  * the output of multiple slots.
  44  *
  45  * @since 1.32
  46  */
  47 class RevisionRenderer {
  48
  49         /** @var LoggerInterface */
  50         private $saveParseLogger;
  51
  52         /** @var ILoadBalancer */
  53         private $loadBalancer;
  54
  55         /** @var string|bool */
  56         private $wikiId;
  57
  58         /**
  59          * @param ILoadBalancer $loadBalancer
  60          * @param bool|string $wikiId
  61          */
  62         public function __construct( ILoadBalancer $loadBalancer, $wikiId = false ) {
  63                 $this->loadBalancer = $loadBalancer;
  64                 $this->wikiId = $wikiId;
  65
  66                 $this->saveParseLogger = new NullLogger();
  67         }
  68
  69         /**
  70          * @param RevisionRecord $rev
  71          * @param ParserOptions|null $options
  72          * @param User|null $forUser User for privileged access. Default is unprivileged (public)
  73          *        access, unless the 'audience' hint is set to something else RevisionRecord::RAW.
  74          * @param array $hints Hints given as an associative array. Known keys:
  75          *      - 'use-master' Use master when rendering for the parser cache during save.
  76          *        Default is to use a replica.
  77          *      - 'audience' the audience to use for content access. Default is
  78          *        RevisionRecord::FOR_PUBLIC if $forUser is not set, RevisionRecord::FOR_THIS_USER
  79          *        if $forUser is set. Can be set to RevisionRecord::RAW to disable audience checks.
  80          *
  81          * @return RenderedRevision|null The rendered revision, or null if the audience checks fails.
  82          */
  83         public function getRenderedRevision(
  84                 RevisionRecord $rev,
  85                 ParserOptions $options = null,
  86                 User $forUser = null,
  87                 array $hints = []
  88         ) {
  89                 if ( $rev->getWikiId() !== $this->wikiId ) {
  90                         throw new InvalidArgumentException( 'Mismatching wiki ID ' . $rev->getWikiId() );
  91                 }
  92
  93                 $audience = $hints['audience']
  94                         ?? ( $forUser ? RevisionRecord::FOR_THIS_USER : RevisionRecord::FOR_PUBLIC );
  95
  96                 if ( !$rev->audienceCan( RevisionRecord::DELETED_TEXT, $audience, $forUser ) ) {
  97                         // Returning null here is awkward, but consist with the signature of
  98                         // Revision::getContent() and RevisionRecord::getContent().
  99                         return null;
 100                 }
 101
 102                 if ( !$options ) {
 103                         $options = ParserOptions::newCanonical( $forUser ?: 'canonical' );
 104                 }
 105
 106                 $useMaster = $hints['use-master'] ?? false;
 107
 108                 $dbIndex = $useMaster
 109                         ? DB_MASTER // use latest values
 110                         : DB_REPLICA; // T154554
 111
 112                 $options->setSpeculativeRevIdCallback( function () use ( $dbIndex ) {
 113                         return $this->getSpeculativeRevId( $dbIndex );
 114                 } );
 115
 116                 $title = Title::newFromLinkTarget( $rev->getPageAsLinkTarget() );
 117
 118                 $renderedRevision = new RenderedRevision(
 119                         $title,
 120                         $rev,
 121                         $options,
 122                         function ( RenderedRevision $rrev, array $hints ) {
 123                                 return $this->combineSlotOutput( $rrev, $hints );
 124                         },
 125                         $audience,
 126                         $forUser
 127                 );
 128
 129                 $renderedRevision->setSaveParseLogger( $this->saveParseLogger );
 130
 131                 return $renderedRevision;
 132         }
 133
 134         private function getSpeculativeRevId( $dbIndex ) {
 135                 // Use a fresh master connection in order to see the latest data, by avoiding
 136                 // stale data from REPEATABLE-READ snapshots.
 137                 // HACK: But don't use a fresh connection in unit tests, since it would not have
 138                 // the fake tables. This should be handled by the LoadBalancer!
 139                 $flags = defined( 'MW_PHPUNIT_TEST' ) || $dbIndex === DB_REPLICA
 140                         ? 0 : ILoadBalancer::CONN_TRX_AUTOCOMMIT;
 141
 142                 $db = $this->loadBalancer->getConnectionRef( $dbIndex, [], $this->wikiId, $flags );
 143
 144                 return 1 + (int)$db->selectField(
 145                         'revision',
 146                         'MAX(rev_id)',
 147                         [],
 148                         __METHOD__
 149                 );
 150         }
 151
 152         /**
 153          * This implements the layout for combining the output of multiple slots.
 154          *
 155          * @todo Use placement hints from SlotRoleHandlers instead of hard-coding the layout.
 156          *
 157          * @param RenderedRevision $rrev
 158          * @param array $hints see RenderedRevision::getRevisionParserOutput()
 159          *
 160          * @return ParserOutput
 161          */
 162         private function combineSlotOutput( RenderedRevision $rrev, array $hints = [] ) {
 163                 $revision = $rrev->getRevision();
 164                 $slots = $revision->getSlots()->getSlots();
 165
 166                 $withHtml = $hints['generate-html'] ?? true;
 167
 168                 // short circuit if there is only the main slot
 169                 if ( array_keys( $slots ) === [ SlotRecord::MAIN ] ) {
 170                         return $rrev->getSlotParserOutput( SlotRecord::MAIN );
 171                 }
 172
 173                 // TODO: put fancy layout logic here, see T200915.
 174
 175                 // move main slot to front
 176                 if ( isset( $slots[SlotRecord::MAIN] ) ) {
 177                         $slots = [ SlotRecord::MAIN => $slots[SlotRecord::MAIN] ] + $slots;
 178                 }
 179
 180                 $combinedOutput = new ParserOutput( null );
 181                 $slotOutput = [];
 182
 183                 $options = $rrev->getOptions();
 184                 $options->registerWatcher( [ $combinedOutput, 'recordOption' ] );
 185
 186                 foreach ( $slots as $role => $slot ) {
 187                         $out = $rrev->getSlotParserOutput( $role, $hints );
 188                         $slotOutput[$role] = $out;
 189
 190                         $combinedOutput->mergeInternalMetaDataFrom( $out, $role );
 191                         $combinedOutput->mergeTrackingMetaDataFrom( $out );
 192                 }
 193
 194                 if ( $withHtml ) {
 195                         $html = '';
 196                         $first = true;
 197                         /** @var ParserOutput $out */
 198                         foreach ( $slotOutput as $role => $out ) {
 199                                 if ( $first ) {
 200                                         // skip header for the first slot
 201                                         $first = false;
 202                                 } else {
 203                                         // NOTE: this placeholder is hydrated by ParserOutput::getText().
 204                                         $headText = Html::element( 'mw:slotheader', [], $role );
 205                                         $html .= Html::rawElement( 'h1', [ 'class' => 'mw-slot-header' ], $headText );
 206                                 }
 207
 208                                 $html .= $out->getRawText();
 209                                 $combinedOutput->mergeHtmlMetaDataFrom( $out );
 210                         }
 211
 212                         $combinedOutput->setText( $html );
 213                 }
 214
 215                 $options->registerWatcher( null );
 216                 return $combinedOutput;
 217         }
 218
 219 }