includes/Storage/RevisionRecord.php

   1 <?php
   2 /**
   3  * Page revision base class.
   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\Storage;
  24
  25 use CommentStoreComment;
  26 use Content;
  27 use InvalidArgumentException;
  28 use LogicException;
  29 use MediaWiki\Linker\LinkTarget;
  30 use MediaWiki\User\UserIdentity;
  31 use MWException;
  32 use Title;
  33 use User;
  34 use Wikimedia\Assert\Assert;
  35
  36 /**
  37  * Page revision base class.
  38  *
  39  * RevisionRecords are considered value objects, but they may use callbacks for lazy loading.
  40  * Note that while the base class has no setters, subclasses may offer a mutable interface.
  41  *
  42  * @since 1.31
  43  */
  44 abstract class RevisionRecord {
  45
  46         // RevisionRecord deletion constants
  47         const DELETED_TEXT = 1;
  48         const DELETED_COMMENT = 2;
  49         const DELETED_USER = 4;
  50         const DELETED_RESTRICTED = 8;
  51         const SUPPRESSED_USER = self::DELETED_USER | self::DELETED_RESTRICTED; // convenience
  52         const SUPPRESSED_ALL = self::DELETED_TEXT | self::DELETED_COMMENT | self::DELETED_USER |
  53                 self::DELETED_RESTRICTED; // convenience
  54
  55         // Audience options for accessors
  56         const FOR_PUBLIC = 1;
  57         const FOR_THIS_USER = 2;
  58         const RAW = 3;
  59
  60         /** @var string Wiki ID; false means the current wiki */
  61         protected $mWiki = false;
  62         /** @var int|null */
  63         protected $mId;
  64         /** @var int|null */
  65         protected $mPageId;
  66         /** @var UserIdentity|null */
  67         protected $mUser;
  68         /** @var bool */
  69         protected $mMinorEdit = false;
  70         /** @var string|null */
  71         protected $mTimestamp;
  72         /** @var int using the DELETED_XXX and SUPPRESSED_XXX flags */
  73         protected $mDeleted = 0;
  74         /** @var int|null */
  75         protected $mSize;
  76         /** @var string|null */
  77         protected $mSha1;
  78         /** @var int|null */
  79         protected $mParentId;
  80         /** @var CommentStoreComment|null */
  81         protected $mComment;
  82
  83         /**  @var Title */
  84         protected $mTitle; // TODO: we only need the title for permission checks!
  85
  86         /** @var RevisionSlots */
  87         protected $mSlots;
  88
  89         /**
  90          * @note Avoid calling this constructor directly. Use the appropriate methods
  91          * in RevisionStore instead.
  92          *
  93          * @param Title $title The title of the page this Revision is associated with.
  94          * @param RevisionSlots $slots The slots of this revision.
  95          * @param bool|string $wikiId the wiki ID of the site this Revision belongs to,
  96          *        or false for the local site.
  97          *
  98          * @throws MWException
  99          */
 100         function __construct( Title $title, RevisionSlots $slots, $wikiId = false ) {
 101                 Assert::parameterType( 'string|boolean', $wikiId, '$wikiId' );
 102
 103                 $this->mTitle = $title;
 104                 $this->mSlots = $slots;
 105                 $this->mWiki = $wikiId;
 106
 107                 // XXX: this is a sensible default, but we may not have a Title object here in the future.
 108                 $this->mPageId = $title->getArticleID();
 109         }
 110
 111         /**
 112          * Implemented to defy serialization.
 113          *
 114          * @throws LogicException always
 115          */
 116         public function __sleep() {
 117                 throw new LogicException( __CLASS__ . ' is not serializable.' );
 118         }
 119
 120         /**
 121          * @param RevisionRecord $rec
 122          *
 123          * @return bool True if this RevisionRecord is known to have same content as $rec.
 124          *         False if the content is different (or not known to be the same).
 125          */
 126         public function hasSameContent( RevisionRecord $rec ) {
 127                 if ( $rec === $this ) {
 128                         return true;
 129                 }
 130
 131                 if ( $this->getId() !== null && $this->getId() === $rec->getId() ) {
 132                         return true;
 133                 }
 134
 135                 // check size before hash, since size is quicker to compute
 136                 if ( $this->getSize() !== $rec->getSize() ) {
 137                         return false;
 138                 }
 139
 140                 // instead of checking the hash, we could also check the content addresses of all slots.
 141
 142                 if ( $this->getSha1() === $rec->getSha1() ) {
 143                         return true;
 144                 }
 145
 146                 return false;
 147         }
 148
 149         /**
 150          * Returns the Content of the given slot of this revision.
 151          * Call getSlotNames() to get a list of available slots.
 152          *
 153          * Note that for mutable Content objects, each call to this method will return a
 154          * fresh clone.
 155          *
 156          * MCR migration note: this replaces Revision::getContent
 157          *
 158          * @param string $role The role name of the desired slot
 159          * @param int $audience
 160          * @param User|null $user
 161          *
 162          * @throws RevisionAccessException if the slot does not exist or slot data
 163          *        could not be lazy-loaded.
 164          * @return Content|null The content of the given slot, or null if access is forbidden.
 165          */
 166         public function getContent( $role, $audience = self::FOR_PUBLIC, User $user = null ) {
 167                 // XXX: throwing an exception would be nicer, but would a further
 168                 // departure from the signature of Revision::getContent(), and thus
 169                 // more complex and error prone refactoring.
 170                 if ( !$this->audienceCan( self::DELETED_TEXT, $audience, $user ) ) {
 171                         return null;
 172                 }
 173
 174                 $content = $this->getSlot( $role, $audience, $user )->getContent();
 175                 return $content->copy();
 176         }
 177
 178         /**
 179          * Returns meta-data for the given slot.
 180          *
 181          * @param string $role The role name of the desired slot
 182          * @param int $audience
 183          * @param User|null $user
 184          *
 185          * @throws RevisionAccessException if the slot does not exist or slot data
 186          *        could not be lazy-loaded.
 187          * @return SlotRecord The slot meta-data. If access to the slot content is forbidden,
 188          *         calling getContent() on the SlotRecord will throw an exception.
 189          */
 190         public function getSlot( $role, $audience = self::FOR_PUBLIC, User $user = null ) {
 191                 $slot = $this->mSlots->getSlot( $role );
 192
 193                 if ( !$this->audienceCan( self::DELETED_TEXT, $audience, $user ) ) {
 194                         return SlotRecord::newWithSuppressedContent( $slot );
 195                 }
 196
 197                 return $slot;
 198         }
 199
 200         /**
 201          * Returns whether the given slot is defined in this revision.
 202          *
 203          * @param string $role The role name of the desired slot
 204          *
 205          * @return bool
 206          */
 207         public function hasSlot( $role ) {
 208                 return $this->mSlots->hasSlot( $role );
 209         }
 210
 211         /**
 212          * Returns the slot names (roles) of all slots present in this revision.
 213          * getContent() will succeed only for the names returned by this method.
 214          *
 215          * @return string[]
 216          */
 217         public function getSlotRoles() {
 218                 return $this->mSlots->getSlotRoles();
 219         }
 220
 221         /**
 222          * Returns the slots defined for this revision.
 223          *
 224          * @return RevisionSlots
 225          */
 226         public function getSlots() {
 227                 return $this->mSlots;
 228         }
 229
 230         /**
 231          * Returns the slots that originate in this revision.
 232          *
 233          * Note that this does not include any slots inherited from some earlier revision,
 234          * even if they are different from the slots in the immediate parent revision.
 235          * This is the case for rollbacks: slots of a rollback revision are inherited from
 236          * the rollback target, and are different from the slots in the parent revision,
 237          * which was rolled back.
 238          *
 239          * To find all slots modified by this revision against its immediate parent
 240          * revision, use RevisionSlotsUpdate::newFromRevisionSlots().
 241          *
 242          * @return RevisionSlots
 243          */
 244         public function getOriginalSlots() {
 245                 return new RevisionSlots( $this->mSlots->getOriginalSlots() );
 246         }
 247
 248         /**
 249          * Returns slots inherited from some previous revision.
 250          *
 251          * "Inherited" slots are all slots that do not originate in this revision.
 252          * Note that these slots may still differ from the one in the parent revision.
 253          * This is the case for rollbacks: slots of a rollback revision are inherited from
 254          * the rollback target, and are different from the slots in the parent revision,
 255          * which was rolled back.
 256          *
 257          * @return RevisionSlots
 258          */
 259         public function getInheritedSlots() {
 260                 return new RevisionSlots( $this->mSlots->getInheritedSlots() );
 261         }
 262
 263         /**
 264          * Get revision ID. Depending on the concrete subclass, this may return null if
 265          * the revision ID is not known (e.g. because the revision does not yet exist
 266          * in the database).
 267          *
 268          * MCR migration note: this replaces Revision::getId
 269          *
 270          * @return int|null
 271          */
 272         public function getId() {
 273                 return $this->mId;
 274         }
 275
 276         /**
 277          * Get parent revision ID (the original previous page revision).
 278          * If there is no parent revision, this returns 0.
 279          * If the parent revision is undefined or unknown, this returns null.
 280          *
 281          * @note As of MW 1.31, the database schema allows the parent ID to be
 282          * NULL to indicate that it is unknown.
 283          *
 284          * MCR migration note: this replaces Revision::getParentId
 285          *
 286          * @return int|null
 287          */
 288         public function getParentId() {
 289                 return $this->mParentId;
 290         }
 291
 292         /**
 293          * Returns the nominal size of this revision, in bogo-bytes.
 294          * May be calculated on the fly if not known, which may in the worst
 295          * case may involve loading all content.
 296          *
 297          * MCR migration note: this replaces Revision::getSize
 298          *
 299          * @throws RevisionAccessException if the size was unknown and could not be calculated.
 300          * @return int
 301          */
 302         abstract public function getSize();
 303
 304         /**
 305          * Returns the base36 sha1 of this revision. This hash is derived from the
 306          * hashes of all slots associated with the revision.
 307          * May be calculated on the fly if not known, which may in the worst
 308          * case may involve loading all content.
 309          *
 310          * MCR migration note: this replaces Revision::getSha1
 311          *
 312          * @throws RevisionAccessException if the hash was unknown and could not be calculated.
 313          * @return string
 314          */
 315         abstract public function getSha1();
 316
 317         /**
 318          * Get the page ID. If the page does not yet exist, the page ID is 0.
 319          *
 320          * MCR migration note: this replaces Revision::getPage
 321          *
 322          * @return int
 323          */
 324         public function getPageId() {
 325                 return $this->mPageId;
 326         }
 327
 328         /**
 329          * Get the ID of the wiki this revision belongs to.
 330          *
 331          * @return string|false The wiki's logical name, of false to indicate the local wiki.
 332          */
 333         public function getWikiId() {
 334                 return $this->mWiki;
 335         }
 336
 337         /**
 338          * Returns the title of the page this revision is associated with as a LinkTarget object.
 339          *
 340          * MCR migration note: this replaces Revision::getTitle
 341          *
 342          * @return LinkTarget
 343          */
 344         public function getPageAsLinkTarget() {
 345                 return $this->mTitle;
 346         }
 347
 348         /**
 349          * Fetch revision's author's user identity, if it's available to the specified audience.
 350          * If the specified audience does not have access to it, null will be
 351          * returned. Depending on the concrete subclass, null may also be returned if the user is
 352          * not yet specified.
 353          *
 354          * MCR migration note: this replaces Revision::getUser
 355          *
 356          * @param int $audience One of:
 357          *   RevisionRecord::FOR_PUBLIC       to be displayed to all users
 358          *   RevisionRecord::FOR_THIS_USER    to be displayed to the given user
 359          *   RevisionRecord::RAW              get the ID regardless of permissions
 360          * @param User|null $user User object to check for, only if FOR_THIS_USER is passed
 361          *   to the $audience parameter
 362          * @return UserIdentity|null
 363          */
 364         public function getUser( $audience = self::FOR_PUBLIC, User $user = null ) {
 365                 if ( !$this->audienceCan( self::DELETED_USER, $audience, $user ) ) {
 366                         return null;
 367                 } else {
 368                         return $this->mUser;
 369                 }
 370         }
 371
 372         /**
 373          * Fetch revision comment, if it's available to the specified audience.
 374          * If the specified audience does not have access to the comment,
 375          * this will return null. Depending on the concrete subclass, null may also be returned
 376          * if the comment is not yet specified.
 377          *
 378          * MCR migration note: this replaces Revision::getComment
 379          *
 380          * @param int $audience One of:
 381          *   RevisionRecord::FOR_PUBLIC       to be displayed to all users
 382          *   RevisionRecord::FOR_THIS_USER    to be displayed to the given user
 383          *   RevisionRecord::RAW              get the text regardless of permissions
 384          * @param User|null $user User object to check for, only if FOR_THIS_USER is passed
 385          *   to the $audience parameter
 386          *
 387          * @return CommentStoreComment|null
 388          */
 389         public function getComment( $audience = self::FOR_PUBLIC, User $user = null ) {
 390                 if ( !$this->audienceCan( self::DELETED_COMMENT, $audience, $user ) ) {
 391                         return null;
 392                 } else {
 393                         return $this->mComment;
 394                 }
 395         }
 396
 397         /**
 398          * MCR migration note: this replaces Revision::isMinor
 399          *
 400          * @return bool
 401          */
 402         public function isMinor() {
 403                 return (bool)$this->mMinorEdit;
 404         }
 405
 406         /**
 407          * MCR migration note: this replaces Revision::isDeleted
 408          *
 409          * @param int $field One of DELETED_* bitfield constants
 410          *
 411          * @return bool
 412          */
 413         public function isDeleted( $field ) {
 414                 return ( $this->getVisibility() & $field ) == $field;
 415         }
 416
 417         /**
 418          * Get the deletion bitfield of the revision
 419          *
 420          * MCR migration note: this replaces Revision::getVisibility
 421          *
 422          * @return int
 423          */
 424         public function getVisibility() {
 425                 return (int)$this->mDeleted;
 426         }
 427
 428         /**
 429          * MCR migration note: this replaces Revision::getTimestamp.
 430          *
 431          * May return null if the timestamp was not specified.
 432          *
 433          * @return string|null
 434          */
 435         public function getTimestamp() {
 436                 return $this->mTimestamp;
 437         }
 438
 439         /**
 440          * Check that the given audience has access to the given field.
 441          *
 442          * MCR migration note: this corresponds to Revision::userCan
 443          *
 444          * @param int $field One of self::DELETED_TEXT,
 445          *        self::DELETED_COMMENT,
 446          *        self::DELETED_USER
 447          * @param int $audience One of:
 448          *        RevisionRecord::FOR_PUBLIC       to be displayed to all users
 449          *        RevisionRecord::FOR_THIS_USER    to be displayed to the given user
 450          *        RevisionRecord::RAW              get the text regardless of permissions
 451          * @param User|null $user User object to check. Required if $audience is FOR_THIS_USER,
 452          *        ignored otherwise.
 453          *
 454          * @return bool
 455          */
 456         public function audienceCan( $field, $audience, User $user = null ) {
 457                 if ( $audience == self::FOR_PUBLIC && $this->isDeleted( $field ) ) {
 458                         return false;
 459                 } elseif ( $audience == self::FOR_THIS_USER ) {
 460                         if ( !$user ) {
 461                                 throw new InvalidArgumentException(
 462                                         'A User object must be given when checking FOR_THIS_USER audience.'
 463                                 );
 464                         }
 465
 466                         if ( !$this->userCan( $field, $user ) ) {
 467                                 return false;
 468                         }
 469                 }
 470
 471                 return true;
 472         }
 473
 474         /**
 475          * Determine if the current user is allowed to view a particular
 476          * field of this revision, if it's marked as deleted.
 477          *
 478          * MCR migration note: this corresponds to Revision::userCan
 479          *
 480          * @param int $field One of self::DELETED_TEXT,
 481          *                              self::DELETED_COMMENT,
 482          *                              self::DELETED_USER
 483          * @param User $user User object to check
 484          * @return bool
 485          */
 486         protected function userCan( $field, User $user ) {
 487                 // TODO: use callback for permission checks, so we don't need to know a Title object!
 488                 return self::userCanBitfield( $this->getVisibility(), $field, $user, $this->mTitle );
 489         }
 490
 491         /**
 492          * Determine if the current user is allowed to view a particular
 493          * field of this revision, if it's marked as deleted. This is used
 494          * by various classes to avoid duplication.
 495          *
 496          * MCR migration note: this replaces Revision::userCanBitfield
 497          *
 498          * @param int $bitfield Current field
 499          * @param int $field One of self::DELETED_TEXT = File::DELETED_FILE,
 500          *                               self::DELETED_COMMENT = File::DELETED_COMMENT,
 501          *                               self::DELETED_USER = File::DELETED_USER
 502          * @param User $user User object to check
 503          * @param Title|null $title A Title object to check for per-page restrictions on,
 504          *                          instead of just plain userrights
 505          * @return bool
 506          */
 507         public static function userCanBitfield( $bitfield, $field, User $user, Title $title = null ) {
 508                 if ( $bitfield & $field ) { // aspect is deleted
 509                         if ( $bitfield & self::DELETED_RESTRICTED ) {
 510                                 $permissions = [ 'suppressrevision', 'viewsuppressed' ];
 511                         } elseif ( $field & self::DELETED_TEXT ) {
 512                                 $permissions = [ 'deletedtext' ];
 513                         } else {
 514                                 $permissions = [ 'deletedhistory' ];
 515                         }
 516                         $permissionlist = implode( ', ', $permissions );
 517                         if ( $title === null ) {
 518                                 wfDebug( "Checking for $permissionlist due to $field match on $bitfield\n" );
 519                                 return $user->isAllowedAny( ...$permissions );
 520                         } else {
 521                                 $text = $title->getPrefixedText();
 522                                 wfDebug( "Checking for $permissionlist on $text due to $field match on $bitfield\n" );
 523                                 foreach ( $permissions as $perm ) {
 524                                         if ( $title->userCan( $perm, $user ) ) {
 525                                                 return true;
 526                                         }
 527                                 }
 528                                 return false;
 529                         }
 530                 } else {
 531                         return true;
 532                 }
 533         }
 534
 535         /**
 536          * Returns whether this RevisionRecord is ready for insertion, that is, whether it contains all
 537          * information needed to save it to the database. This should trivially be true for
 538          * RevisionRecords loaded from the database.
 539          *
 540          * Note that this may return true even if getId() or getPage() return null or 0, since these
 541          * are generally assigned while the revision is saved to the database, and may not be available
 542          * before.
 543          *
 544          * @return bool
 545          */
 546         public function isReadyForInsertion() {
 547                 // NOTE: don't check getSize() and getSha1(), since that may cause the full content to
 548                 // be loaded in order to calculate the values. Just assume these methods will not return
 549                 // null if mSlots is not empty.
 550
 551                 // NOTE: getId() and getPageId() may return null before a revision is saved, so don't
 552                 //check them.
 553
 554                 return $this->getTimestamp() !== null
 555                         && $this->getComment( self::RAW ) !== null
 556                         && $this->getUser( self::RAW ) !== null
 557                         && $this->mSlots->getSlotRoles() !== [];
 558         }
 559
 560 }