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 ParserOptions;
  28 use ParserOutput;
  29 use Psr\Log\LoggerInterface;
  30 use Psr\Log\NullLogger;
  31 use Title;
  32 use User;
  33 use Wikimedia\Rdbms\ILoadBalancer;
  34
  35 /**
  36  * The RevisionRenderer service provides access to rendered output for revisions.
  37  * It does so be acting as a factory for RenderedRevision instances, which in turn
  38  * provide lazy access to ParserOutput objects.
  39  *
  40  * One key responsibility of RevisionRenderer is implementing the layout used to combine
  41  * the output of multiple slots.
  42  *
  43  * @since 1.32
  44  */
  45 class RevisionRenderer {
  46
  47         /** @var LoggerInterface */
  48         private $saveParseLogger;
  49
  50         /** @var ILoadBalancer */
  51         private $loadBalancer;
  52
  53         /** @var SlotRoleRegistry */
  54         private $roleRegistery;
  55
  56         /** @var string|bool */
  57         private $dbDomain;
  58
  59         /**
  60          * @param ILoadBalancer $loadBalancer
  61          * @param SlotRoleRegistry $roleRegistry
  62          * @param bool|string $dbDomain DB domain of the relevant wiki or false for the current one
  63          */
  64         public function __construct(
  65                 ILoadBalancer $loadBalancer,
  66                 SlotRoleRegistry $roleRegistry,
  67                 $dbDomain = false
  68         ) {
  69                 $this->loadBalancer = $loadBalancer;
  70                 $this->roleRegistery = $roleRegistry;
  71                 $this->dbDomain = $dbDomain;
  72                 $this->saveParseLogger = new NullLogger();
  73         }
  74
  75         /**
  76          * @param LoggerInterface $saveParseLogger
  77          */
  78         public function setLogger( LoggerInterface $saveParseLogger ) {
  79                 $this->saveParseLogger = $saveParseLogger;
  80         }
  81
  82         /**
  83          * @param RevisionRecord $rev
  84          * @param ParserOptions|null $options
  85          * @param User|null $forUser User for privileged access. Default is unprivileged (public)
  86          *        access, unless the 'audience' hint is set to something else RevisionRecord::RAW.
  87          * @param array $hints Hints given as an associative array. Known keys:
  88          *      - 'use-master' Use master when rendering for the parser cache during save.
  89          *        Default is to use a replica.
  90          *      - 'audience' the audience to use for content access. Default is
  91          *        RevisionRecord::FOR_PUBLIC if $forUser is not set, RevisionRecord::FOR_THIS_USER
  92          *        if $forUser is set. Can be set to RevisionRecord::RAW to disable audience checks.
  93          *      - 'known-revision-output' a combined ParserOutput for the revision, perhaps from
  94          *        some cache. the caller is responsible for ensuring that the ParserOutput indeed
  95          *        matched the $rev and $options. This mechanism is intended as a temporary stop-gap,
  96          *        for the time until caches have been changed to store RenderedRevision states instead
  97          *        of ParserOutput objects.
  98          * @phan-param array{use-master?:bool,audience?:int,known-revision-output?:ParserOutput} $hints
  99          *
 100          * @return RenderedRevision|null The rendered revision, or null if the audience checks fails.
 101          */
 102         public function getRenderedRevision(
 103                 RevisionRecord $rev,
 104                 ParserOptions $options = null,
 105                 User $forUser = null,
 106                 array $hints = []
 107         ) {
 108                 if ( $rev->getWikiId() !== $this->dbDomain ) {
 109                         throw new InvalidArgumentException( 'Mismatching wiki ID ' . $rev->getWikiId() );
 110                 }
 111
 112                 // @phan-suppress-next-line PhanTypeInvalidDimOffset
 113                 $audience = $hints['audience']
 114                         ?? ( $forUser ? RevisionRecord::FOR_THIS_USER : RevisionRecord::FOR_PUBLIC );
 115
 116                 if ( !$rev->audienceCan( RevisionRecord::DELETED_TEXT, $audience, $forUser ) ) {
 117                         // Returning null here is awkward, but consist with the signature of
 118                         // Revision::getContent() and RevisionRecord::getContent().
 119                         return null;
 120                 }
 121
 122                 if ( !$options ) {
 123                         $options = ParserOptions::newCanonical( $forUser ?: 'canonical' );
 124                 }
 125
 126                 // @phan-suppress-next-line PhanTypeInvalidDimOffset
 127                 $useMaster = $hints['use-master'] ?? false;
 128
 129                 $dbIndex = $useMaster
 130                         ? DB_MASTER // use latest values
 131                         : DB_REPLICA; // T154554
 132
 133                 $options->setSpeculativeRevIdCallback( function () use ( $dbIndex ) {
 134                         return $this->getSpeculativeRevId( $dbIndex );
 135                 } );
 136                 $options->setSpeculativePageIdCallback( function () use ( $dbIndex ) {
 137                         return $this->getSpeculativePageId( $dbIndex );
 138                 } );
 139
 140                 if ( !$rev->getId() && $rev->getTimestamp() ) {
 141                         // This is an unsaved revision with an already determined timestamp.
 142                         // Make the "current" time used during parsing match that of the revision.
 143                         // Any REVISION* parser variables will match up if the revision is saved.
 144                         $options->setTimestamp( $rev->getTimestamp() );
 145                 }
 146
 147                 $title = Title::newFromLinkTarget( $rev->getPageAsLinkTarget() );
 148
 149                 $renderedRevision = new RenderedRevision(
 150                         $title,
 151                         $rev,
 152                         $options,
 153                         function ( RenderedRevision $rrev, array $hints ) {
 154                                 return $this->combineSlotOutput( $rrev, $hints );
 155                         },
 156                         $audience,
 157                         $forUser
 158                 );
 159
 160                 $renderedRevision->setSaveParseLogger( $this->saveParseLogger );
 161
 162                 if ( isset( $hints['known-revision-output'] ) ) {
 163                         $renderedRevision->setRevisionParserOutput( $hints['known-revision-output'] );
 164                 }
 165
 166                 return $renderedRevision;
 167         }
 168
 169         private function getSpeculativeRevId( $dbIndex ) {
 170                 // Use a separate master connection in order to see the latest data, by avoiding
 171                 // stale data from REPEATABLE-READ snapshots.
 172                 $flags = ILoadBalancer::CONN_TRX_AUTOCOMMIT;
 173
 174                 $db = $this->loadBalancer->getConnectionRef( $dbIndex, [], $this->dbDomain, $flags );
 175
 176                 return 1 + (int)$db->selectField(
 177                         'revision',
 178                         'MAX(rev_id)',
 179                         [],
 180                         __METHOD__
 181                 );
 182         }
 183
 184         private function getSpeculativePageId( $dbIndex ) {
 185                 // Use a separate master connection in order to see the latest data, by avoiding
 186                 // stale data from REPEATABLE-READ snapshots.
 187                 $flags = ILoadBalancer::CONN_TRX_AUTOCOMMIT;
 188
 189                 $db = $this->loadBalancer->getConnectionRef( $dbIndex, [], $this->dbDomain, $flags );
 190
 191                 return 1 + (int)$db->selectField(
 192                         'page',
 193                         'MAX(page_id)',
 194                         [],
 195                         __METHOD__
 196                 );
 197         }
 198
 199         /**
 200          * This implements the layout for combining the output of multiple slots.
 201          *
 202          * @todo Use placement hints from SlotRoleHandlers instead of hard-coding the layout.
 203          *
 204          * @param RenderedRevision $rrev
 205          * @param array $hints see RenderedRevision::getRevisionParserOutput()
 206          *
 207          * @return ParserOutput
 208          */
 209         private function combineSlotOutput( RenderedRevision $rrev, array $hints = [] ) {
 210                 $revision = $rrev->getRevision();
 211                 $slots = $revision->getSlots()->getSlots();
 212
 213                 $withHtml = $hints['generate-html'] ?? true;
 214
 215                 // short circuit if there is only the main slot
 216                 if ( array_keys( $slots ) === [ SlotRecord::MAIN ] ) {
 217                         return $rrev->getSlotParserOutput( SlotRecord::MAIN );
 218                 }
 219
 220                 // move main slot to front
 221                 if ( isset( $slots[SlotRecord::MAIN] ) ) {
 222                         $slots = [ SlotRecord::MAIN => $slots[SlotRecord::MAIN] ] + $slots;
 223                 }
 224
 225                 $combinedOutput = new ParserOutput( null );
 226                 $slotOutput = [];
 227
 228                 $options = $rrev->getOptions();
 229                 $options->registerWatcher( [ $combinedOutput, 'recordOption' ] );
 230
 231                 foreach ( $slots as $role => $slot ) {
 232                         $out = $rrev->getSlotParserOutput( $role, $hints );
 233                         $slotOutput[$role] = $out;
 234
 235                         // XXX: should the SlotRoleHandler be able to intervene here?
 236                         $combinedOutput->mergeInternalMetaDataFrom( $out );
 237                         $combinedOutput->mergeTrackingMetaDataFrom( $out );
 238                 }
 239
 240                 if ( $withHtml ) {
 241                         $html = '';
 242                         $first = true;
 243                         /** @var ParserOutput $out */
 244                         foreach ( $slotOutput as $role => $out ) {
 245                                 $roleHandler = $this->roleRegistery->getRoleHandler( $role );
 246
 247                                 // TODO: put more fancy layout logic here, see T200915.
 248                                 $layout = $roleHandler->getOutputLayoutHints();
 249                                 $display = $layout['display'] ?? 'section';
 250
 251                                 if ( $display === 'none' ) {
 252                                         continue;
 253                                 }
 254
 255                                 if ( $first ) {
 256                                         // skip header for the first slot
 257                                         $first = false;
 258                                 } else {
 259                                         // NOTE: this placeholder is hydrated by ParserOutput::getText().
 260                                         $headText = Html::element( 'mw:slotheader', [], $role );
 261                                         $html .= Html::rawElement( 'h1', [ 'class' => 'mw-slot-header' ], $headText );
 262                                 }
 263
 264                                 // XXX: do we want to put a wrapper div around the output?
 265                                 // Do we want to let $roleHandler do that?
 266                                 $html .= $out->getRawText();
 267                                 $combinedOutput->mergeHtmlMetaDataFrom( $out );
 268                         }
 269
 270                         $combinedOutput->setText( $html );
 271                 }
 272
 273                 $options->registerWatcher( null );
 274                 return $combinedOutput;
 275         }
 276
 277 }