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