includes/Revision.php

   1 <?php
   2 /**
   3  * @package MediaWiki
   4  * @todo document
   5  */
   6
   7 /** */
   8 require_once( 'Database.php' );
   9 require_once( 'Article.php' );
  10
  11 /**
  12  * @package MediaWiki
  13  * @todo document
  14  */
  15 class Revision {
  16         /**
  17          * Load a page revision from a given revision ID number.
  18          * Returns null if no such revision can be found.
  19          *
  20          * @param int $id
  21          * @static
  22          * @access public
  23          */
  24         function newFromId( $id ) {
  25                 return Revision::newFromConds(
  26                         array( 'page_id=rev_page',
  27                                'rev_id' => intval( $id ) ) );
  28         }
  29
  30         /**
  31          * Load either the current, or a specified, revision
  32          * that's attached to a given title. If not attached
  33          * to that title, will return null.
  34          *
  35          * @param Title $title
  36          * @param int $id
  37          * @return Revision
  38          * @access public
  39          * @static
  40          */
  41         function newFromTitle( &$title, $id = 0 ) {
  42                 if( $id ) {
  43                         $matchId = intval( $id );
  44                 } else {
  45                         $matchId = 'page_latest';
  46                 }
  47                 return Revision::newFromConds(
  48                         array( "rev_id=$matchId",
  49                                'page_id=rev_page',
  50                                'page_namespace' => $title->getNamespace(),
  51                                'page_title'     => $title->getDbkey() ) );
  52         }
  53
  54         /**
  55          * Load either the current, or a specified, revision
  56          * that's attached to a given page. If not attached
  57          * to that page, will return null.
  58          *
  59          * @param Database $db
  60          * @param int $pageid
  61          * @param int $id
  62          * @return Revision
  63          * @access public
  64          */
  65         function loadFromPageId( &$db, $pageid, $id = 0 ) {
  66                 $conds=array('page_id=rev_page','rev_page'=>intval( $pageid ), 'page_id'=>intval( $pageid ));
  67                 if( $id ) {
  68                         $conds['rev_id']=intval($id);
  69                 } else {
  70                         $conds[]='rev_id=page_latest';
  71                 }
  72                 return Revision::loadFromConds( $db, $conds );
  73         }
  74
  75         /**
  76          * Load either the current, or a specified, revision
  77          * that's attached to a given page. If not attached
  78          * to that page, will return null.
  79          *
  80          * @param Database $db
  81          * @param Title $title
  82          * @param int $id
  83          * @return Revision
  84          * @access public
  85          */
  86         function loadFromTitle( &$db, $title, $id = 0 ) {
  87                 if( $id ) {
  88                         $matchId = intval( $id );
  89                 } else {
  90                         $matchId = 'page_latest';
  91                 }
  92                 return Revision::loadFromConds(
  93                         $db,
  94                         array( "rev_id=$matchId",
  95                                'page_id=rev_page',
  96                                'page_namespace' => $title->getNamespace(),
  97                                'page_title'     => $title->getDbkey() ) );
  98         }
  99
 100         /**
 101          * Load the revision for the given title with the given timestamp.
 102          * WARNING: Timestamps may in some circumstances not be unique,
 103          * so this isn't the best key to use.
 104          *
 105          * @param Database $db
 106          * @param Title $title
 107          * @param string $timestamp
 108          * @return Revision
 109          * @access public
 110          * @static
 111          */
 112         function loadFromTimestamp( &$db, &$title, $timestamp ) {
 113                 return Revision::loadFromConds(
 114                         $db,
 115                         array( 'rev_timestamp'  => $db->timestamp( $timestamp ),
 116                                'page_id=rev_page',
 117                                'page_namespace' => $title->getNamespace(),
 118                                'page_title'     => $title->getDbkey() ) );
 119         }
 120
 121         /**
 122          * Given a set of conditions, fetch a revision.
 123          *
 124          * @param array $conditions
 125          * @return Revision
 126          * @static
 127          * @access private
 128          */
 129         function newFromConds( $conditions ) {
 130                 $db =& wfGetDB( DB_SLAVE );
 131                 $row = Revision::loadFromConds( $db, $conditions );
 132                 if( is_null( $row ) ) {
 133                         $dbw =& wfGetDB( DB_MASTER );
 134                         $row = Revision::loadFromConds( $dbw, $conditions );
 135                 }
 136                 return $row;
 137         }
 138
 139         /**
 140          * Given a set of conditions, fetch a revision from
 141          * the given database connection.
 142          *
 143          * @param Database $db
 144          * @param array $conditions
 145          * @return Revision
 146          * @static
 147          * @access private
 148          */
 149         function loadFromConds( &$db, $conditions ) {
 150                 $res = Revision::fetchFromConds( $db, $conditions );
 151                 if( $res ) {
 152                         $row = $res->fetchObject();
 153                         $res->free();
 154                         if( $row ) {
 155                                 $ret = new Revision( $row );
 156                                 return $ret;
 157                         }
 158                 }
 159                 $ret = null;
 160                 return $ret;
 161         }
 162
 163         /**
 164          * Return a wrapper for a series of database rows to
 165          * fetch all of a given page's revisions in turn.
 166          * Each row can be fed to the constructor to get objects.
 167          *
 168          * @param Title $title
 169          * @return ResultWrapper
 170          * @static
 171          * @access public
 172          */
 173         function fetchAllRevisions( &$title ) {
 174                 return Revision::fetchFromConds(
 175                         wfGetDB( DB_SLAVE ),
 176                         array( 'page_namespace' => $title->getNamespace(),
 177                                'page_title'     => $title->getDbkey(),
 178                                'page_id=rev_page' ) );
 179         }
 180
 181         /**
 182          * Return a wrapper for a series of database rows to
 183          * fetch all of a given page's revisions in turn.
 184          * Each row can be fed to the constructor to get objects.
 185          *
 186          * @param Title $title
 187          * @return ResultWrapper
 188          * @static
 189          * @access public
 190          */
 191         function fetchRevision( &$title ) {
 192                 return Revision::fetchFromConds(
 193                         wfGetDB( DB_SLAVE ),
 194                         array( 'rev_id=page_latest',
 195                                'page_namespace' => $title->getNamespace(),
 196                                'page_title'     => $title->getDbkey(),
 197                                'page_id=rev_page' ) );
 198         }
 199
 200         /**
 201          * Given a set of conditions, return a ResultWrapper
 202          * which will return matching database rows with the
 203          * fields necessary to build Revision objects.
 204          *
 205          * @param Database $db
 206          * @param array $conditions
 207          * @return ResultWrapper
 208          * @static
 209          * @access private
 210          */
 211         function fetchFromConds( &$db, $conditions ) {
 212                 $res = $db->select(
 213                         array( 'page', 'revision' ),
 214                         array( 'page_namespace',
 215                                'page_title',
 216                                'page_latest',
 217                                'rev_id',
 218                                'rev_page',
 219                                'rev_text_id',
 220                                'rev_comment',
 221                                'rev_user_text',
 222                                'rev_user',
 223                                'rev_minor_edit',
 224                                'rev_timestamp',
 225                                'rev_deleted' ),
 226                         $conditions,
 227                         'Revision::fetchRow',
 228                         array( 'LIMIT' => 1 ) );
 229                 $ret = $db->resultObject( $res );
 230                 return $ret;
 231         }
 232
 233         /**
 234          * @param object $row
 235          * @access private
 236          */
 237         function Revision( $row ) {
 238                 if( is_object( $row ) ) {
 239                         $this->mId        = intval( $row->rev_id );
 240                         $this->mPage      = intval( $row->rev_page );
 241                         $this->mTextId    = intval( $row->rev_text_id );
 242                         $this->mComment   =         $row->rev_comment;
 243                         $this->mUserText  =         $row->rev_user_text;
 244                         $this->mUser      = intval( $row->rev_user );
 245                         $this->mMinorEdit = intval( $row->rev_minor_edit );
 246                         $this->mTimestamp =         $row->rev_timestamp;
 247                         $this->mDeleted   = intval( $row->rev_deleted );
 248
 249                         $this->mCurrent   = ( $row->rev_id == $row->page_latest );
 250                         $this->mTitle     = Title::makeTitle( $row->page_namespace,
 251                                                               $row->page_title );
 252
 253                         if( isset( $row->old_text ) ) {
 254                                 $this->mText  = $this->getRevisionText( $row );
 255                         } else {
 256                                 $this->mText  = null;
 257                         }
 258                 } elseif( is_array( $row ) ) {
 259                         // Build a new revision to be saved...
 260                         global $wgUser;
 261
 262                         $this->mId        = isset( $row['id']         ) ? intval( $row['id']         ) : null;
 263                         $this->mPage      = isset( $row['page']       ) ? intval( $row['page']       ) : null;
 264                         $this->mTextId    = isset( $row['text_id']    ) ? intval( $row['text_id']    ) : null;
 265                         $this->mUserText  = isset( $row['user_text']  ) ? strval( $row['user_text']  ) : $wgUser->getName();
 266                         $this->mUser      = isset( $row['user']       ) ? intval( $row['user']       ) : $wgUser->getId();
 267                         $this->mMinorEdit = isset( $row['minor_edit'] ) ? intval( $row['minor_edit'] ) : 0;
 268                         $this->mTimestamp = isset( $row['timestamp']  ) ? strval( $row['timestamp']  ) : wfTimestamp( TS_MW );
 269                         $this->mDeleted   = isset( $row['deleted']    ) ? intval( $row['deleted']    ) : 0;
 270
 271                         // Enforce spacing trimming on supplied text
 272                         $this->mComment   = isset( $row['comment']    ) ?  trim( strval( $row['comment'] ) ) : null;
 273                         $this->mText      = isset( $row['text']       ) ? rtrim( strval( $row['text']    ) ) : null;
 274
 275                         $this->mTitle     = null; # Load on demand if needed
 276                         $this->mCurrent   = false;
 277                 } else {
 278                         wfDebugDieBacktrace( 'Revision constructor passed invalid row format.' );
 279                 }
 280         }
 281
 282         /**#@+
 283          * @access public
 284          */
 285
 286         /**
 287          * @return int
 288          */
 289         function getId() {
 290                 return $this->mId;
 291         }
 292
 293         /**
 294          * @return int
 295          */
 296         function getTextId() {
 297                 return $this->mTextId;
 298         }
 299
 300         /**
 301          * Returns the title of the page associated with this entry.
 302          * @return Title
 303          */
 304         function getTitle() {
 305                 if( isset( $this->mTitle ) ) {
 306                         return $this->mTitle;
 307                 }
 308                 $dbr =& wfGetDB( DB_SLAVE );
 309                 $row = $dbr->selectRow(
 310                         array( 'page', 'revision' ),
 311                         array( 'page_namespace', 'page_title' ),
 312                         array( 'page_id=rev_page',
 313                                'rev_id' => $this->mId ),
 314                         'Revision::getTItle' );
 315                 if( $row ) {
 316                         $this->mTitle = Title::makeTitle( $row->page_namespace,
 317                                                            $row->page_title );
 318                 }
 319                 return $this->mTitle;
 320         }
 321
 322         /**
 323          * @return int
 324          */
 325         function getPage() {
 326                 return $this->mPage;
 327         }
 328
 329         /**
 330          * @return int
 331          */
 332         function getUser() {
 333                 return $this->mUser;
 334         }
 335
 336         /**
 337          * @return string
 338          */
 339         function getUserText() {
 340                 return $this->mUserText;
 341         }
 342
 343         /**
 344          * @return string
 345          */
 346         function getComment() {
 347                 return $this->mComment;
 348         }
 349
 350         /**
 351          * @return bool
 352          */
 353         function isMinor() {
 354                 return (bool)$this->mMinorEdit;
 355         }
 356
 357         /**
 358          * @return bool
 359          */
 360         function isDeleted() {
 361                 return (bool)$this->mDeleted;
 362         }
 363
 364         /**
 365          * @return string
 366          */
 367         function getText() {
 368                 if( is_null( $this->mText ) ) {
 369                         // Revision text is immutable. Load on demand:
 370                         $this->mText = $this->loadText();
 371                 }
 372                 return $this->mText;
 373         }
 374
 375         /**
 376          * @return string
 377          */
 378         function getTimestamp() {
 379                 return wfTimestamp(TS_MW, $this->mTimestamp);
 380         }
 381
 382         /**
 383          * @return bool
 384          */
 385         function isCurrent() {
 386                 return $this->mCurrent;
 387         }
 388
 389         /**
 390          * @return Revision
 391          */
 392         function getPrevious() {
 393                 $prev = $this->mTitle->getPreviousRevisionID( $this->mId );
 394                 if ( $prev ) {
 395                         return Revision::newFromTitle( $this->mTitle, $prev );
 396                 } else {
 397                         return null;
 398                 }
 399         }
 400
 401         /**
 402          * @return Revision
 403          */
 404         function getNext() {
 405                 $next = $this->mTitle->getNextRevisionID( $this->mId );
 406                 if ( $next ) {
 407                         return Revision::newFromTitle( $this->mTitle, $next );
 408                 } else {
 409                         return null;
 410                 }
 411         }
 412         /**#@-*/
 413
 414         /**
 415           * Get revision text associated with an old or archive row
 416           * $row is usually an object from wfFetchRow(), both the flags and the text
 417           * field must be included
 418           * @static
 419           * @param integer $row Id of a row
 420           * @param string $prefix table prefix (default 'old_')
 421           * @return string $text|false the text requested
 422           */
 423         function getRevisionText( $row, $prefix = 'old_' ) {
 424                 $fname = 'Revision::getRevisionText';
 425                 wfProfileIn( $fname );
 426
 427                 # Get data
 428                 $textField = $prefix . 'text';
 429                 $flagsField = $prefix . 'flags';
 430
 431                 if( isset( $row->$flagsField ) ) {
 432                         $flags = explode( ',', $row->$flagsField );
 433                 } else {
 434                         $flags = array();
 435                 }
 436
 437                 if( isset( $row->$textField ) ) {
 438                         $text = $row->$textField;
 439                 } else {
 440                         wfProfileOut( $fname );
 441                         return false;
 442                 }
 443
 444                 # Use external methods for external objects, text in table is URL-only then
 445                 if ( in_array( 'external', $flags ) ) {
 446                         $url=$text;
 447                         @list($proto,$path)=explode('://',$url,2);
 448                         if ($path=="") {
 449                                 wfProfileOut( $fname );
 450                                 return false;
 451                         }
 452                         require_once('ExternalStore.php');
 453                         $text=ExternalStore::fetchFromURL($url);
 454                 }
 455
 456                 // If the text was fetched without an error, convert it
 457                 if ( $text !== false ) {
 458                         if( in_array( 'gzip', $flags ) ) {
 459                                 # Deal with optional compression of archived pages.
 460                                 # This can be done periodically via maintenance/compressOld.php, and
 461                                 # as pages are saved if $wgCompressRevisions is set.
 462                                 $text = gzinflate( $text );
 463                         }
 464
 465                         if( in_array( 'object', $flags ) ) {
 466                                 # Generic compressed storage
 467                                 $obj = unserialize( $text );
 468                                 $text = $obj->getText();
 469                         }
 470
 471                         global $wgLegacyEncoding;
 472                         if( $wgLegacyEncoding && !in_array( 'utf-8', $flags ) ) {
 473                                 # Old revisions kept around in a legacy encoding?
 474                                 # Upconvert on demand.
 475                                 global $wgInputEncoding, $wgContLang;
 476                                 $text = $wgContLang->iconv( $wgLegacyEncoding, $wgInputEncoding . '//IGNORE', $text );
 477                         }
 478                 }
 479                 wfProfileOut( $fname );
 480                 return $text;
 481         }
 482
 483         /**
 484          * If $wgCompressRevisions is enabled, we will compress data.
 485          * The input string is modified in place.
 486          * Return value is the flags field: contains 'gzip' if the
 487          * data is compressed, and 'utf-8' if we're saving in UTF-8
 488          * mode.
 489          *
 490          * @static
 491          * @param mixed $text reference to a text
 492          * @return string
 493          */
 494         function compressRevisionText( &$text ) {
 495                 global $wgCompressRevisions;
 496                 $flags = array();
 497
 498                 # Revisions not marked this way will be converted
 499                 # on load if $wgLegacyCharset is set in the future.
 500                 $flags[] = 'utf-8';
 501
 502                 if( $wgCompressRevisions ) {
 503                         if( function_exists( 'gzdeflate' ) ) {
 504                                 $text = gzdeflate( $text );
 505                                 $flags[] = 'gzip';
 506                         } else {
 507                                 wfDebug( "Revision::compressRevisionText() -- no zlib support, not compressing\n" );
 508                         }
 509                 }
 510                 return implode( ',', $flags );
 511         }
 512
 513         /**
 514          * Insert a new revision into the database, returning the new revision ID
 515          * number on success and dies horribly on failure.
 516          *
 517          * @param Database $dbw
 518          * @return int
 519          */
 520         function insertOn( &$dbw ) {
 521                 global $wgDefaultExternalStore;
 522
 523                 $fname = 'Revision::insertOn';
 524                 wfProfileIn( $fname );
 525
 526                 $data = $this->mText;
 527                 $flags = Revision::compressRevisionText( $data );
 528
 529                 # Write to external storage if required
 530                 if ( $wgDefaultExternalStore ) {
 531                         require_once('ExternalStore.php');
 532                         // Store and get the URL
 533                         $data = ExternalStore::insert( $wgDefaultExternalStore, $data );
 534                         if ( !$data ) {
 535                                 # This should only happen in the case of a configuration error, where the external store is not valid
 536                                 wfDebugDieBacktrace( "Unable to store text to external storage $wgDefaultExternalStore" );
 537                         }
 538                         if ( $flags ) {
 539                                 $flags .= ',';
 540                         }
 541                         $flags .= 'external';
 542                 }
 543
 544                 # Record the text (or external storage URL) to the text table
 545                 if( !isset( $this->mTextId ) ) {
 546                         $old_id = $dbw->nextSequenceValue( 'text_old_id_val' );
 547                         $dbw->insert( 'text',
 548                                 array(
 549                                         'old_id'    => $old_id,
 550                                         'old_text'  => $data,
 551                                         'old_flags' => $flags,
 552                                 ), $fname
 553                         );
 554                         $this->mTextId = $dbw->insertId();
 555                 }
 556
 557                 # Record the edit in revisions
 558                 $rev_id = isset( $this->mId )
 559                         ? $this->mId
 560                         : $dbw->nextSequenceValue( 'rev_rev_id_val' );
 561                 $dbw->insert( 'revision',
 562                         array(
 563                                 'rev_id'         => $rev_id,
 564                                 'rev_page'       => $this->mPage,
 565                                 'rev_text_id'    => $this->mTextId,
 566                                 'rev_comment'    => $this->mComment,
 567                                 'rev_minor_edit' => $this->mMinorEdit ? 1 : 0,
 568                                 'rev_user'       => $this->mUser,
 569                                 'rev_user_text'  => $this->mUserText,
 570                                 'rev_timestamp'  => $dbw->timestamp( $this->mTimestamp ),
 571                                 'rev_deleted'    => $this->mDeleted,
 572                         ), $fname
 573                 );
 574
 575                 $this->mId = !is_null($rev_id) ? $rev_id : $dbw->insertId();
 576
 577                 wfProfileOut( $fname );
 578                 return $this->mId;
 579         }
 580
 581         /**
 582          * Lazy-load the revision's text.
 583          * Currently hardcoded to the 'text' table storage engine.
 584          *
 585          * @return string
 586          * @access private
 587          */
 588         function loadText() {
 589                 $fname = 'Revision::loadText';
 590                 wfProfileIn( $fname );
 591
 592                 $dbr =& wfGetDB( DB_SLAVE );
 593                 $row = $dbr->selectRow( 'text',
 594                         array( 'old_text', 'old_flags' ),
 595                         array( 'old_id' => $this->getTextId() ),
 596                         $fname);
 597
 598                 if( !$row ) {
 599                         $dbw =& wfGetDB( DB_MASTER );
 600                         $row = $dbw->selectRow( 'text',
 601                                 array( 'old_text', 'old_flags' ),
 602                                 array( 'old_id' => $this->getTextId() ),
 603                                 $fname);
 604                 }
 605
 606                 $text = Revision::getRevisionText( $row );
 607                 wfProfileOut( $fname );
 608
 609                 return $text;
 610         }
 611
 612         /**
 613          * Create a new null-revision for insertion into a page's
 614          * history. This will not re-save the text, but simply refer
 615          * to the text from the previous version.
 616          *
 617          * Such revisions can for instance identify page rename
 618          * operations and other such meta-modifications.
 619          *
 620          * @param Database $dbw
 621          * @param int      $pageId ID number of the page to read from
 622          * @param string   $summary
 623          * @param bool     $minor
 624          * @return Revision
 625          */
 626         function newNullRevision( &$dbw, $pageId, $summary, $minor ) {
 627                 $fname = 'Revision::newNullRevision';
 628                 wfProfileIn( $fname );
 629
 630                 $current = $dbw->selectRow(
 631                         array( 'page', 'revision' ),
 632                         array( 'page_latest', 'rev_text_id' ),
 633                         array(
 634                                 'page_id' => $pageId,
 635                                 'page_latest=rev_id',
 636                                 ),
 637                         $fname );
 638
 639                 if( $current ) {
 640                         $revision = new Revision( array(
 641                                 'page'       => $pageId,
 642                                 'comment'    => $summary,
 643                                 'minor_edit' => $minor,
 644                                 'text_id'    => $current->rev_text_id,
 645                                 ) );
 646                 } else {
 647                         $revision = null;
 648                 }
 649
 650                 wfProfileOut( $fname );
 651                 return $revision;
 652         }
 653
 654 }
 655 ?>