dff469a408
During development a lot of classes were placed in MediaWiki\Storage\. The precedent set would mean that every class relating to something stored in a database table, plus all related value classes and such, would go into that namespace. Let's put them into MediaWiki\Revision\ instead. Then future classes related to the 'page' table can go into MediaWiki\Page\, future classes related to the 'user' table can go into MediaWiki\User\, and so on. Note I didn't move DerivedPageDataUpdater, PageUpdateException, PageUpdater, or RevisionSlotsUpdate in this patch. If these are kept long-term, they probably belong in MediaWiki\Page\ or MediaWiki\Edit\ instead. Bug: T204158 Change-Id: I16bea8927566a3c73c07e4f4afb3537e05aa04a5
567 lines
17 KiB
PHP
567 lines
17 KiB
PHP
<?php
|
|
/**
|
|
* Page revision base class.
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
namespace MediaWiki\Revision;
|
|
|
|
use CommentStoreComment;
|
|
use Content;
|
|
use InvalidArgumentException;
|
|
use LogicException;
|
|
use MediaWiki\Linker\LinkTarget;
|
|
use MediaWiki\User\UserIdentity;
|
|
use MWException;
|
|
use Title;
|
|
use User;
|
|
use Wikimedia\Assert\Assert;
|
|
|
|
/**
|
|
* Page revision base class.
|
|
*
|
|
* RevisionRecords are considered value objects, but they may use callbacks for lazy loading.
|
|
* Note that while the base class has no setters, subclasses may offer a mutable interface.
|
|
*
|
|
* @since 1.31
|
|
* @since 1.32 Renamed from MediaWiki\Storage\RevisionRecord
|
|
*/
|
|
abstract class RevisionRecord {
|
|
|
|
// RevisionRecord deletion constants
|
|
const DELETED_TEXT = 1;
|
|
const DELETED_COMMENT = 2;
|
|
const DELETED_USER = 4;
|
|
const DELETED_RESTRICTED = 8;
|
|
const SUPPRESSED_USER = self::DELETED_USER | self::DELETED_RESTRICTED; // convenience
|
|
const SUPPRESSED_ALL = self::DELETED_TEXT | self::DELETED_COMMENT | self::DELETED_USER |
|
|
self::DELETED_RESTRICTED; // convenience
|
|
|
|
// Audience options for accessors
|
|
const FOR_PUBLIC = 1;
|
|
const FOR_THIS_USER = 2;
|
|
const RAW = 3;
|
|
|
|
/** @var string Wiki ID; false means the current wiki */
|
|
protected $mWiki = false;
|
|
/** @var int|null */
|
|
protected $mId;
|
|
/** @var int|null */
|
|
protected $mPageId;
|
|
/** @var UserIdentity|null */
|
|
protected $mUser;
|
|
/** @var bool */
|
|
protected $mMinorEdit = false;
|
|
/** @var string|null */
|
|
protected $mTimestamp;
|
|
/** @var int using the DELETED_XXX and SUPPRESSED_XXX flags */
|
|
protected $mDeleted = 0;
|
|
/** @var int|null */
|
|
protected $mSize;
|
|
/** @var string|null */
|
|
protected $mSha1;
|
|
/** @var int|null */
|
|
protected $mParentId;
|
|
/** @var CommentStoreComment|null */
|
|
protected $mComment;
|
|
|
|
/** @var Title */
|
|
protected $mTitle; // TODO: we only need the title for permission checks!
|
|
|
|
/** @var RevisionSlots */
|
|
protected $mSlots;
|
|
|
|
/**
|
|
* @note Avoid calling this constructor directly. Use the appropriate methods
|
|
* in RevisionStore instead.
|
|
*
|
|
* @param Title $title The title of the page this Revision is associated with.
|
|
* @param RevisionSlots $slots The slots of this revision.
|
|
* @param bool|string $wikiId the wiki ID of the site this Revision belongs to,
|
|
* or false for the local site.
|
|
*
|
|
* @throws MWException
|
|
*/
|
|
function __construct( Title $title, RevisionSlots $slots, $wikiId = false ) {
|
|
Assert::parameterType( 'string|boolean', $wikiId, '$wikiId' );
|
|
|
|
$this->mTitle = $title;
|
|
$this->mSlots = $slots;
|
|
$this->mWiki = $wikiId;
|
|
|
|
// XXX: this is a sensible default, but we may not have a Title object here in the future.
|
|
$this->mPageId = $title->getArticleID();
|
|
}
|
|
|
|
/**
|
|
* Implemented to defy serialization.
|
|
*
|
|
* @throws LogicException always
|
|
*/
|
|
public function __sleep() {
|
|
throw new LogicException( __CLASS__ . ' is not serializable.' );
|
|
}
|
|
|
|
/**
|
|
* @param RevisionRecord $rec
|
|
*
|
|
* @return bool True if this RevisionRecord is known to have same content as $rec.
|
|
* False if the content is different (or not known to be the same).
|
|
*/
|
|
public function hasSameContent( RevisionRecord $rec ) {
|
|
if ( $rec === $this ) {
|
|
return true;
|
|
}
|
|
|
|
if ( $this->getId() !== null && $this->getId() === $rec->getId() ) {
|
|
return true;
|
|
}
|
|
|
|
// check size before hash, since size is quicker to compute
|
|
if ( $this->getSize() !== $rec->getSize() ) {
|
|
return false;
|
|
}
|
|
|
|
// instead of checking the hash, we could also check the content addresses of all slots.
|
|
|
|
if ( $this->getSha1() === $rec->getSha1() ) {
|
|
return true;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Returns the Content of the given slot of this revision.
|
|
* Call getSlotNames() to get a list of available slots.
|
|
*
|
|
* Note that for mutable Content objects, each call to this method will return a
|
|
* fresh clone.
|
|
*
|
|
* MCR migration note: this replaces Revision::getContent
|
|
*
|
|
* @param string $role The role name of the desired slot
|
|
* @param int $audience
|
|
* @param User|null $user
|
|
*
|
|
* @throws RevisionAccessException if the slot does not exist or slot data
|
|
* could not be lazy-loaded.
|
|
* @return Content|null The content of the given slot, or null if access is forbidden.
|
|
*/
|
|
public function getContent( $role, $audience = self::FOR_PUBLIC, User $user = null ) {
|
|
// XXX: throwing an exception would be nicer, but would a further
|
|
// departure from the signature of Revision::getContent(), and thus
|
|
// more complex and error prone refactoring.
|
|
if ( !$this->audienceCan( self::DELETED_TEXT, $audience, $user ) ) {
|
|
return null;
|
|
}
|
|
|
|
$content = $this->getSlot( $role, $audience, $user )->getContent();
|
|
return $content->copy();
|
|
}
|
|
|
|
/**
|
|
* Returns meta-data for the given slot.
|
|
*
|
|
* @param string $role The role name of the desired slot
|
|
* @param int $audience
|
|
* @param User|null $user
|
|
*
|
|
* @throws RevisionAccessException if the slot does not exist or slot data
|
|
* could not be lazy-loaded.
|
|
* @return SlotRecord The slot meta-data. If access to the slot content is forbidden,
|
|
* calling getContent() on the SlotRecord will throw an exception.
|
|
*/
|
|
public function getSlot( $role, $audience = self::FOR_PUBLIC, User $user = null ) {
|
|
$slot = $this->mSlots->getSlot( $role );
|
|
|
|
if ( !$this->audienceCan( self::DELETED_TEXT, $audience, $user ) ) {
|
|
return SlotRecord::newWithSuppressedContent( $slot );
|
|
}
|
|
|
|
return $slot;
|
|
}
|
|
|
|
/**
|
|
* Returns whether the given slot is defined in this revision.
|
|
*
|
|
* @param string $role The role name of the desired slot
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function hasSlot( $role ) {
|
|
return $this->mSlots->hasSlot( $role );
|
|
}
|
|
|
|
/**
|
|
* Returns the slot names (roles) of all slots present in this revision.
|
|
* getContent() will succeed only for the names returned by this method.
|
|
*
|
|
* @return string[]
|
|
*/
|
|
public function getSlotRoles() {
|
|
return $this->mSlots->getSlotRoles();
|
|
}
|
|
|
|
/**
|
|
* Returns the slots defined for this revision.
|
|
*
|
|
* @return RevisionSlots
|
|
*/
|
|
public function getSlots() {
|
|
return $this->mSlots;
|
|
}
|
|
|
|
/**
|
|
* Returns the slots that originate in this revision.
|
|
*
|
|
* Note that this does not include any slots inherited from some earlier revision,
|
|
* even if they are different from the slots in the immediate parent revision.
|
|
* This is the case for rollbacks: slots of a rollback revision are inherited from
|
|
* the rollback target, and are different from the slots in the parent revision,
|
|
* which was rolled back.
|
|
*
|
|
* To find all slots modified by this revision against its immediate parent
|
|
* revision, use RevisionSlotsUpdate::newFromRevisionSlots().
|
|
*
|
|
* @return RevisionSlots
|
|
*/
|
|
public function getOriginalSlots() {
|
|
return new RevisionSlots( $this->mSlots->getOriginalSlots() );
|
|
}
|
|
|
|
/**
|
|
* Returns slots inherited from some previous revision.
|
|
*
|
|
* "Inherited" slots are all slots that do not originate in this revision.
|
|
* Note that these slots may still differ from the one in the parent revision.
|
|
* This is the case for rollbacks: slots of a rollback revision are inherited from
|
|
* the rollback target, and are different from the slots in the parent revision,
|
|
* which was rolled back.
|
|
*
|
|
* @return RevisionSlots
|
|
*/
|
|
public function getInheritedSlots() {
|
|
return new RevisionSlots( $this->mSlots->getInheritedSlots() );
|
|
}
|
|
|
|
/**
|
|
* Get revision ID. Depending on the concrete subclass, this may return null if
|
|
* the revision ID is not known (e.g. because the revision does not yet exist
|
|
* in the database).
|
|
*
|
|
* MCR migration note: this replaces Revision::getId
|
|
*
|
|
* @return int|null
|
|
*/
|
|
public function getId() {
|
|
return $this->mId;
|
|
}
|
|
|
|
/**
|
|
* Get parent revision ID (the original previous page revision).
|
|
* If there is no parent revision, this returns 0.
|
|
* If the parent revision is undefined or unknown, this returns null.
|
|
*
|
|
* @note As of MW 1.31, the database schema allows the parent ID to be
|
|
* NULL to indicate that it is unknown.
|
|
*
|
|
* MCR migration note: this replaces Revision::getParentId
|
|
*
|
|
* @return int|null
|
|
*/
|
|
public function getParentId() {
|
|
return $this->mParentId;
|
|
}
|
|
|
|
/**
|
|
* Returns the nominal size of this revision, in bogo-bytes.
|
|
* May be calculated on the fly if not known, which may in the worst
|
|
* case may involve loading all content.
|
|
*
|
|
* MCR migration note: this replaces Revision::getSize
|
|
*
|
|
* @throws RevisionAccessException if the size was unknown and could not be calculated.
|
|
* @return int
|
|
*/
|
|
abstract public function getSize();
|
|
|
|
/**
|
|
* Returns the base36 sha1 of this revision. This hash is derived from the
|
|
* hashes of all slots associated with the revision.
|
|
* May be calculated on the fly if not known, which may in the worst
|
|
* case may involve loading all content.
|
|
*
|
|
* MCR migration note: this replaces Revision::getSha1
|
|
*
|
|
* @throws RevisionAccessException if the hash was unknown and could not be calculated.
|
|
* @return string
|
|
*/
|
|
abstract public function getSha1();
|
|
|
|
/**
|
|
* Get the page ID. If the page does not yet exist, the page ID is 0.
|
|
*
|
|
* MCR migration note: this replaces Revision::getPage
|
|
*
|
|
* @return int
|
|
*/
|
|
public function getPageId() {
|
|
return $this->mPageId;
|
|
}
|
|
|
|
/**
|
|
* Get the ID of the wiki this revision belongs to.
|
|
*
|
|
* @return string|false The wiki's logical name, of false to indicate the local wiki.
|
|
*/
|
|
public function getWikiId() {
|
|
return $this->mWiki;
|
|
}
|
|
|
|
/**
|
|
* Returns the title of the page this revision is associated with as a LinkTarget object.
|
|
*
|
|
* MCR migration note: this replaces Revision::getTitle
|
|
*
|
|
* @return LinkTarget
|
|
*/
|
|
public function getPageAsLinkTarget() {
|
|
return $this->mTitle;
|
|
}
|
|
|
|
/**
|
|
* Fetch revision's author's user identity, if it's available to the specified audience.
|
|
* If the specified audience does not have access to it, null will be
|
|
* returned. Depending on the concrete subclass, null may also be returned if the user is
|
|
* not yet specified.
|
|
*
|
|
* MCR migration note: this replaces Revision::getUser
|
|
*
|
|
* @param int $audience One of:
|
|
* RevisionRecord::FOR_PUBLIC to be displayed to all users
|
|
* RevisionRecord::FOR_THIS_USER to be displayed to the given user
|
|
* RevisionRecord::RAW get the ID regardless of permissions
|
|
* @param User|null $user User object to check for, only if FOR_THIS_USER is passed
|
|
* to the $audience parameter
|
|
* @return UserIdentity|null
|
|
*/
|
|
public function getUser( $audience = self::FOR_PUBLIC, User $user = null ) {
|
|
if ( !$this->audienceCan( self::DELETED_USER, $audience, $user ) ) {
|
|
return null;
|
|
} else {
|
|
return $this->mUser;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Fetch revision comment, if it's available to the specified audience.
|
|
* If the specified audience does not have access to the comment,
|
|
* this will return null. Depending on the concrete subclass, null may also be returned
|
|
* if the comment is not yet specified.
|
|
*
|
|
* MCR migration note: this replaces Revision::getComment
|
|
*
|
|
* @param int $audience One of:
|
|
* RevisionRecord::FOR_PUBLIC to be displayed to all users
|
|
* RevisionRecord::FOR_THIS_USER to be displayed to the given user
|
|
* RevisionRecord::RAW get the text regardless of permissions
|
|
* @param User|null $user User object to check for, only if FOR_THIS_USER is passed
|
|
* to the $audience parameter
|
|
*
|
|
* @return CommentStoreComment|null
|
|
*/
|
|
public function getComment( $audience = self::FOR_PUBLIC, User $user = null ) {
|
|
if ( !$this->audienceCan( self::DELETED_COMMENT, $audience, $user ) ) {
|
|
return null;
|
|
} else {
|
|
return $this->mComment;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* MCR migration note: this replaces Revision::isMinor
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isMinor() {
|
|
return (bool)$this->mMinorEdit;
|
|
}
|
|
|
|
/**
|
|
* MCR migration note: this replaces Revision::isDeleted
|
|
*
|
|
* @param int $field One of DELETED_* bitfield constants
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isDeleted( $field ) {
|
|
return ( $this->getVisibility() & $field ) == $field;
|
|
}
|
|
|
|
/**
|
|
* Get the deletion bitfield of the revision
|
|
*
|
|
* MCR migration note: this replaces Revision::getVisibility
|
|
*
|
|
* @return int
|
|
*/
|
|
public function getVisibility() {
|
|
return (int)$this->mDeleted;
|
|
}
|
|
|
|
/**
|
|
* MCR migration note: this replaces Revision::getTimestamp.
|
|
*
|
|
* May return null if the timestamp was not specified.
|
|
*
|
|
* @return string|null
|
|
*/
|
|
public function getTimestamp() {
|
|
return $this->mTimestamp;
|
|
}
|
|
|
|
/**
|
|
* Check that the given audience has access to the given field.
|
|
*
|
|
* MCR migration note: this corresponds to Revision::userCan
|
|
*
|
|
* @param int $field One of self::DELETED_TEXT,
|
|
* self::DELETED_COMMENT,
|
|
* self::DELETED_USER
|
|
* @param int $audience One of:
|
|
* RevisionRecord::FOR_PUBLIC to be displayed to all users
|
|
* RevisionRecord::FOR_THIS_USER to be displayed to the given user
|
|
* RevisionRecord::RAW get the text regardless of permissions
|
|
* @param User|null $user User object to check. Required if $audience is FOR_THIS_USER,
|
|
* ignored otherwise.
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function audienceCan( $field, $audience, User $user = null ) {
|
|
if ( $audience == self::FOR_PUBLIC && $this->isDeleted( $field ) ) {
|
|
return false;
|
|
} elseif ( $audience == self::FOR_THIS_USER ) {
|
|
if ( !$user ) {
|
|
throw new InvalidArgumentException(
|
|
'A User object must be given when checking FOR_THIS_USER audience.'
|
|
);
|
|
}
|
|
|
|
if ( !$this->userCan( $field, $user ) ) {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* Determine if the current user is allowed to view a particular
|
|
* field of this revision, if it's marked as deleted.
|
|
*
|
|
* MCR migration note: this corresponds to Revision::userCan
|
|
*
|
|
* @param int $field One of self::DELETED_TEXT,
|
|
* self::DELETED_COMMENT,
|
|
* self::DELETED_USER
|
|
* @param User $user User object to check
|
|
* @return bool
|
|
*/
|
|
protected function userCan( $field, User $user ) {
|
|
// TODO: use callback for permission checks, so we don't need to know a Title object!
|
|
return self::userCanBitfield( $this->getVisibility(), $field, $user, $this->mTitle );
|
|
}
|
|
|
|
/**
|
|
* Determine if the current user is allowed to view a particular
|
|
* field of this revision, if it's marked as deleted. This is used
|
|
* by various classes to avoid duplication.
|
|
*
|
|
* MCR migration note: this replaces Revision::userCanBitfield
|
|
*
|
|
* @param int $bitfield Current field
|
|
* @param int $field One of self::DELETED_TEXT = File::DELETED_FILE,
|
|
* self::DELETED_COMMENT = File::DELETED_COMMENT,
|
|
* self::DELETED_USER = File::DELETED_USER
|
|
* @param User $user User object to check
|
|
* @param Title|null $title A Title object to check for per-page restrictions on,
|
|
* instead of just plain userrights
|
|
* @return bool
|
|
*/
|
|
public static function userCanBitfield( $bitfield, $field, User $user, Title $title = null ) {
|
|
if ( $bitfield & $field ) { // aspect is deleted
|
|
if ( $bitfield & self::DELETED_RESTRICTED ) {
|
|
$permissions = [ 'suppressrevision', 'viewsuppressed' ];
|
|
} elseif ( $field & self::DELETED_TEXT ) {
|
|
$permissions = [ 'deletedtext' ];
|
|
} else {
|
|
$permissions = [ 'deletedhistory' ];
|
|
}
|
|
$permissionlist = implode( ', ', $permissions );
|
|
if ( $title === null ) {
|
|
wfDebug( "Checking for $permissionlist due to $field match on $bitfield\n" );
|
|
return $user->isAllowedAny( ...$permissions );
|
|
} else {
|
|
$text = $title->getPrefixedText();
|
|
wfDebug( "Checking for $permissionlist on $text due to $field match on $bitfield\n" );
|
|
foreach ( $permissions as $perm ) {
|
|
if ( $title->userCan( $perm, $user ) ) {
|
|
return true;
|
|
}
|
|
}
|
|
return false;
|
|
}
|
|
} else {
|
|
return true;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns whether this RevisionRecord is ready for insertion, that is, whether it contains all
|
|
* information needed to save it to the database. This should trivially be true for
|
|
* RevisionRecords loaded from the database.
|
|
*
|
|
* Note that this may return true even if getId() or getPage() return null or 0, since these
|
|
* are generally assigned while the revision is saved to the database, and may not be available
|
|
* before.
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isReadyForInsertion() {
|
|
// NOTE: don't check getSize() and getSha1(), since that may cause the full content to
|
|
// be loaded in order to calculate the values. Just assume these methods will not return
|
|
// null if mSlots is not empty.
|
|
|
|
// NOTE: getId() and getPageId() may return null before a revision is saved, so don't
|
|
//check them.
|
|
|
|
return $this->getTimestamp() !== null
|
|
&& $this->getComment( self::RAW ) !== null
|
|
&& $this->getUser( self::RAW ) !== null
|
|
&& $this->mSlots->getSlotRoles() !== [];
|
|
}
|
|
|
|
}
|
|
|
|
/**
|
|
* Retain the old class name for backwards compatibility.
|
|
* @deprecated since 1.32
|
|
*/
|
|
class_alias( RevisionRecord::class, 'MediaWiki\Storage\RevisionRecord' );
|