3 * Page revision base class.
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.
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.
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
23 namespace MediaWiki\Storage
;
25 use CommentStoreComment
;
27 use InvalidArgumentException
;
29 use MediaWiki\Linker\LinkTarget
;
30 use MediaWiki\User\UserIdentity
;
34 use Wikimedia\Assert\Assert
;
37 * Page revision base class.
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.
44 abstract class RevisionRecord
{
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
55 // Audience options for accessors
57 const FOR_THIS_USER
= 2;
60 /** @var string Wiki ID; false means the current wiki */
61 protected $mWiki = false;
66 /** @var UserIdentity|null */
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;
76 /** @var string|null */
80 /** @var CommentStoreComment|null */
84 protected $mTitle; // TODO: we only need the title for permission checks!
86 /** @var RevisionSlots */
90 * @note Avoid calling this constructor directly. Use the appropriate methods
91 * in RevisionStore instead.
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.
100 function __construct( Title
$title, RevisionSlots
$slots, $wikiId = false ) {
101 Assert
::parameterType( 'string|boolean', $wikiId, '$wikiId' );
103 $this->mTitle
= $title;
104 $this->mSlots
= $slots;
105 $this->mWiki
= $wikiId;
107 // XXX: this is a sensible default, but we may not have a Title object here in the future.
108 $this->mPageId
= $title->getArticleID();
112 * Implemented to defy serialization.
114 * @throws LogicException always
116 public function __sleep() {
117 throw new LogicException( __CLASS__
. ' is not serializable.' );
121 * @param RevisionRecord $rec
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).
126 public function hasSameContent( RevisionRecord
$rec ) {
127 if ( $rec === $this ) {
131 if ( $this->getId() !== null && $this->getId() === $rec->getId() ) {
135 // check size before hash, since size is quicker to compute
136 if ( $this->getSize() !== $rec->getSize() ) {
140 // instead of checking the hash, we could also check the content addresses of all slots.
142 if ( $this->getSha1() === $rec->getSha1() ) {
150 * Returns the Content of the given slot of this revision.
151 * Call getSlotNames() to get a list of available slots.
153 * Note that for mutable Content objects, each call to this method will return a
156 * MCR migration note: this replaces Revision::getContent
158 * @param string $role The role name of the desired slot
159 * @param int $audience
160 * @param User|null $user
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.
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 ) ) {
174 $content = $this->getSlot( $role, $audience, $user )->getContent();
175 return $content->copy();
179 * Returns meta-data for the given slot.
181 * @param string $role The role name of the desired slot
182 * @param int $audience
183 * @param User|null $user
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.
190 public function getSlot( $role, $audience = self
::FOR_PUBLIC
, User
$user = null ) {
191 $slot = $this->mSlots
->getSlot( $role );
193 if ( !$this->audienceCan( self
::DELETED_TEXT
, $audience, $user ) ) {
194 return SlotRecord
::newWithSuppressedContent( $slot );
201 * Returns whether the given slot is defined in this revision.
203 * @param string $role The role name of the desired slot
207 public function hasSlot( $role ) {
208 return $this->mSlots
->hasSlot( $role );
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.
217 public function getSlotRoles() {
218 return $this->mSlots
->getSlotRoles();
222 * Returns the slots defined for this revision.
224 * @return RevisionSlots
226 public function getSlots() {
227 return $this->mSlots
;
231 * Returns the slots that originate in this revision.
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.
239 * To find all slots modified by this revision against its immediate parent
240 * revision, use RevisionSlotsUpdate::newFromRevisionSlots().
242 * @return RevisionSlots
244 public function getOriginalSlots() {
245 return new RevisionSlots( $this->mSlots
->getOriginalSlots() );
249 * Returns slots inherited from some previous revision.
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.
257 * @return RevisionSlots
259 public function getInheritedSlots() {
260 return new RevisionSlots( $this->mSlots
->getInheritedSlots() );
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
268 * MCR migration note: this replaces Revision::getId
272 public function getId() {
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.
281 * @note As of MW 1.31, the database schema allows the parent ID to be
282 * NULL to indicate that it is unknown.
284 * MCR migration note: this replaces Revision::getParentId
288 public function getParentId() {
289 return $this->mParentId
;
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.
297 * MCR migration note: this replaces Revision::getSize
299 * @throws RevisionAccessException if the size was unknown and could not be calculated.
302 abstract public function getSize();
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.
310 * MCR migration note: this replaces Revision::getSha1
312 * @throws RevisionAccessException if the hash was unknown and could not be calculated.
315 abstract public function getSha1();
318 * Get the page ID. If the page does not yet exist, the page ID is 0.
320 * MCR migration note: this replaces Revision::getPage
324 public function getPageId() {
325 return $this->mPageId
;
329 * Get the ID of the wiki this revision belongs to.
331 * @return string|false The wiki's logical name, of false to indicate the local wiki.
333 public function getWikiId() {
338 * Returns the title of the page this revision is associated with as a LinkTarget object.
340 * MCR migration note: this replaces Revision::getTitle
344 public function getPageAsLinkTarget() {
345 return $this->mTitle
;
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
354 * MCR migration note: this replaces Revision::getUser
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
364 public function getUser( $audience = self
::FOR_PUBLIC
, User
$user = null ) {
365 if ( !$this->audienceCan( self
::DELETED_USER
, $audience, $user ) ) {
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.
378 * MCR migration note: this replaces Revision::getComment
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
387 * @return CommentStoreComment|null
389 public function getComment( $audience = self
::FOR_PUBLIC
, User
$user = null ) {
390 if ( !$this->audienceCan( self
::DELETED_COMMENT
, $audience, $user ) ) {
393 return $this->mComment
;
398 * MCR migration note: this replaces Revision::isMinor
402 public function isMinor() {
403 return (bool)$this->mMinorEdit
;
407 * MCR migration note: this replaces Revision::isDeleted
409 * @param int $field One of DELETED_* bitfield constants
413 public function isDeleted( $field ) {
414 return ( $this->getVisibility() & $field ) == $field;
418 * Get the deletion bitfield of the revision
420 * MCR migration note: this replaces Revision::getVisibility
424 public function getVisibility() {
425 return (int)$this->mDeleted
;
429 * MCR migration note: this replaces Revision::getTimestamp.
431 * May return null if the timestamp was not specified.
433 * @return string|null
435 public function getTimestamp() {
436 return $this->mTimestamp
;
440 * Check that the given audience has access to the given field.
442 * MCR migration note: this corresponds to Revision::userCan
444 * @param int $field One of self::DELETED_TEXT,
445 * self::DELETED_COMMENT,
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,
456 public function audienceCan( $field, $audience, User
$user = null ) {
457 if ( $audience == self
::FOR_PUBLIC
&& $this->isDeleted( $field ) ) {
459 } elseif ( $audience == self
::FOR_THIS_USER
) {
461 throw new InvalidArgumentException(
462 'A User object must be given when checking FOR_THIS_USER audience.'
466 if ( !$this->userCan( $field, $user ) ) {
475 * Determine if the current user is allowed to view a particular
476 * field of this revision, if it's marked as deleted.
478 * MCR migration note: this corresponds to Revision::userCan
480 * @param int $field One of self::DELETED_TEXT,
481 * self::DELETED_COMMENT,
483 * @param User $user User object to check
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
);
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.
496 * MCR migration note: this replaces Revision::userCanBitfield
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
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' ];
514 $permissions = [ 'deletedhistory' ];
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 );
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 ) ) {