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
= 12; // convenience
52 const SUPPRESSED_ALL
= 15; // convenience
54 // Audience options for accessors
56 const FOR_THIS_USER
= 2;
59 /** @var string Wiki ID; false means the current wiki */
60 protected $mWiki = false;
65 /** @var UserIdentity|null */
68 protected $mMinorEdit = false;
69 /** @var string|null */
70 protected $mTimestamp;
71 /** @var int using the DELETED_XXX and SUPPRESSED_XXX flags */
72 protected $mDeleted = 0;
75 /** @var string|null */
79 /** @var CommentStoreComment|null */
83 protected $mTitle; // TODO: we only need the title for permission checks!
85 /** @var RevisionSlots */
89 * @note Avoid calling this constructor directly. Use the appropriate methods
90 * in RevisionStore instead.
92 * @param Title $title The title of the page this Revision is associated with.
93 * @param RevisionSlots $slots The slots of this revision.
94 * @param bool|string $wikiId the wiki ID of the site this Revision belongs to,
95 * or false for the local site.
99 function __construct( Title
$title, RevisionSlots
$slots, $wikiId = false ) {
100 Assert
::parameterType( 'string|boolean', $wikiId, '$wikiId' );
102 $this->mTitle
= $title;
103 $this->mSlots
= $slots;
104 $this->mWiki
= $wikiId;
106 // XXX: this is a sensible default, but we may not have a Title object here in the future.
107 $this->mPageId
= $title->getArticleID();
111 * Implemented to defy serialization.
113 * @throws LogicException always
115 public function __sleep() {
116 throw new LogicException( __CLASS__
. ' is not serializable.' );
120 * @param RevisionRecord $rec
122 * @return bool True if this RevisionRecord is known to have same content as $rec.
123 * False if the content is different (or not known to be the same).
125 public function hasSameContent( RevisionRecord
$rec ) {
126 if ( $rec === $this ) {
130 if ( $this->getId() !== null && $this->getId() === $rec->getId() ) {
134 // check size before hash, since size is quicker to compute
135 if ( $this->getSize() !== $rec->getSize() ) {
139 // instead of checking the hash, we could also check the content addresses of all slots.
141 if ( $this->getSha1() === $rec->getSha1() ) {
149 * Returns the Content of the given slot of this revision.
150 * Call getSlotNames() to get a list of available slots.
152 * Note that for mutable Content objects, each call to this method will return a
155 * MCR migration note: this replaces Revision::getContent
157 * @param string $role The role name of the desired slot
158 * @param int $audience
159 * @param User|null $user
161 * @throws RevisionAccessException if the slot does not exist or slot data
162 * could not be lazy-loaded.
163 * @return Content|null The content of the given slot, or null if access is forbidden.
165 public function getContent( $role, $audience = self
::FOR_PUBLIC
, User
$user = null ) {
166 // XXX: throwing an exception would be nicer, but would a further
167 // departure from the signature of Revision::getContent(), and thus
168 // more complex and error prone refactoring.
169 if ( !$this->audienceCan( self
::DELETED_TEXT
, $audience, $user ) ) {
173 $content = $this->getSlot( $role, $audience, $user )->getContent();
174 return $content->copy();
178 * Returns meta-data for the given slot.
180 * @param string $role The role name of the desired slot
181 * @param int $audience
182 * @param User|null $user
184 * @throws RevisionAccessException if the slot does not exist or slot data
185 * could not be lazy-loaded.
186 * @return SlotRecord The slot meta-data. If access to the slot content is forbidden,
187 * calling getContent() on the SlotRecord will throw an exception.
189 public function getSlot( $role, $audience = self
::FOR_PUBLIC
, User
$user = null ) {
190 $slot = $this->mSlots
->getSlot( $role );
192 if ( !$this->audienceCan( self
::DELETED_TEXT
, $audience, $user ) ) {
193 return SlotRecord
::newWithSuppressedContent( $slot );
200 * Returns the slot names (roles) of all slots present in this revision.
201 * getContent() will succeed only for the names returned by this method.
205 public function getSlotRoles() {
206 return $this->mSlots
->getSlotRoles();
210 * Get revision ID. Depending on the concrete subclass, this may return null if
211 * the revision ID is not known (e.g. because the revision does not yet exist
214 * MCR migration note: this replaces Revision::getId
218 public function getId() {
223 * Get parent revision ID (the original previous page revision).
224 * If there is no parent revision, this returns 0.
225 * If the parent revision is undefined or unknown, this returns null.
227 * @note As of MW 1.31, the database schema allows the parent ID to be
228 * NULL to indicate that it is unknown.
230 * MCR migration note: this replaces Revision::getParentId
234 public function getParentId() {
235 return $this->mParentId
;
239 * Returns the nominal size of this revision, in bogo-bytes.
240 * May be calculated on the fly if not known, which may in the worst
241 * case may involve loading all content.
243 * MCR migration note: this replaces Revision::getSize
247 abstract public function getSize();
250 * Returns the base36 sha1 of this revision. This hash is derived from the
251 * hashes of all slots associated with the revision.
252 * May be calculated on the fly if not known, which may in the worst
253 * case may involve loading all content.
255 * MCR migration note: this replaces Revision::getSha1
259 abstract public function getSha1();
262 * Get the page ID. If the page does not yet exist, the page ID is 0.
264 * MCR migration note: this replaces Revision::getPage
268 public function getPageId() {
269 return $this->mPageId
;
273 * Get the ID of the wiki this revision belongs to.
275 * @return string|false The wiki's logical name, of false to indicate the local wiki.
277 public function getWikiId() {
282 * Returns the title of the page this revision is associated with as a LinkTarget object.
284 * MCR migration note: this replaces Revision::getTitle
288 public function getPageAsLinkTarget() {
289 return $this->mTitle
;
293 * Fetch revision's author's user identity, if it's available to the specified audience.
294 * If the specified audience does not have access to it, null will be
295 * returned. Depending on the concrete subclass, null may also be returned if the user is
298 * MCR migration note: this replaces Revision::getUser
300 * @param int $audience One of:
301 * RevisionRecord::FOR_PUBLIC to be displayed to all users
302 * RevisionRecord::FOR_THIS_USER to be displayed to the given user
303 * RevisionRecord::RAW get the ID regardless of permissions
304 * @param User|null $user User object to check for, only if FOR_THIS_USER is passed
305 * to the $audience parameter
306 * @return UserIdentity|null
308 public function getUser( $audience = self
::FOR_PUBLIC
, User
$user = null ) {
309 if ( !$this->audienceCan( self
::DELETED_USER
, $audience, $user ) ) {
317 * Fetch revision comment, if it's available to the specified audience.
318 * If the specified audience does not have access to the comment,
319 * this will return null. Depending on the concrete subclass, null may also be returned
320 * if the comment is not yet specified.
322 * MCR migration note: this replaces Revision::getComment
324 * @param int $audience One of:
325 * RevisionRecord::FOR_PUBLIC to be displayed to all users
326 * RevisionRecord::FOR_THIS_USER to be displayed to the given user
327 * RevisionRecord::RAW get the text regardless of permissions
328 * @param User|null $user User object to check for, only if FOR_THIS_USER is passed
329 * to the $audience parameter
331 * @return CommentStoreComment|null
333 public function getComment( $audience = self
::FOR_PUBLIC
, User
$user = null ) {
334 if ( !$this->audienceCan( self
::DELETED_COMMENT
, $audience, $user ) ) {
337 return $this->mComment
;
342 * MCR migration note: this replaces Revision::isMinor
346 public function isMinor() {
347 return (bool)$this->mMinorEdit
;
351 * MCR migration note: this replaces Revision::isDeleted
353 * @param int $field One of DELETED_* bitfield constants
357 public function isDeleted( $field ) {
358 return ( $this->getVisibility() & $field ) == $field;
362 * Get the deletion bitfield of the revision
364 * MCR migration note: this replaces Revision::getVisibility
368 public function getVisibility() {
369 return (int)$this->mDeleted
;
373 * MCR migration note: this replaces Revision::getTimestamp.
375 * May return null if the timestamp was not specified.
377 * @return string|null
379 public function getTimestamp() {
380 return $this->mTimestamp
;
384 * Check that the given audience has access to the given field.
386 * MCR migration note: this corresponds to Revision::userCan
388 * @param int $field One of self::DELETED_TEXT,
389 * self::DELETED_COMMENT,
391 * @param int $audience One of:
392 * RevisionRecord::FOR_PUBLIC to be displayed to all users
393 * RevisionRecord::FOR_THIS_USER to be displayed to the given user
394 * RevisionRecord::RAW get the text regardless of permissions
395 * @param User|null $user User object to check. Required if $audience is FOR_THIS_USER,
400 protected function audienceCan( $field, $audience, User
$user = null ) {
401 if ( $audience == self
::FOR_PUBLIC
&& $this->isDeleted( $field ) ) {
403 } elseif ( $audience == self
::FOR_THIS_USER
) {
405 throw new InvalidArgumentException(
406 'A User object must be given when checking FOR_THIS_USER audience.'
410 if ( !$this->userCan( $field, $user ) ) {
419 * Determine if the current user is allowed to view a particular
420 * field of this revision, if it's marked as deleted.
422 * MCR migration note: this corresponds to Revision::userCan
424 * @param int $field One of self::DELETED_TEXT,
425 * self::DELETED_COMMENT,
427 * @param User $user User object to check
430 protected function userCan( $field, User
$user ) {
431 // TODO: use callback for permission checks, so we don't need to know a Title object!
432 return self
::userCanBitfield( $this->getVisibility(), $field, $user, $this->mTitle
);
436 * Determine if the current user is allowed to view a particular
437 * field of this revision, if it's marked as deleted. This is used
438 * by various classes to avoid duplication.
440 * MCR migration note: this replaces Revision::userCanBitfield
442 * @param int $bitfield Current field
443 * @param int $field One of self::DELETED_TEXT = File::DELETED_FILE,
444 * self::DELETED_COMMENT = File::DELETED_COMMENT,
445 * self::DELETED_USER = File::DELETED_USER
446 * @param User $user User object to check
447 * @param Title|null $title A Title object to check for per-page restrictions on,
448 * instead of just plain userrights
451 public static function userCanBitfield( $bitfield, $field, User
$user, Title
$title = null ) {
452 if ( $bitfield & $field ) { // aspect is deleted
453 if ( $bitfield & self
::DELETED_RESTRICTED
) {
454 $permissions = [ 'suppressrevision', 'viewsuppressed' ];
455 } elseif ( $field & self
::DELETED_TEXT
) {
456 $permissions = [ 'deletedtext' ];
458 $permissions = [ 'deletedhistory' ];
460 $permissionlist = implode( ', ', $permissions );
461 if ( $title === null ) {
462 wfDebug( "Checking for $permissionlist due to $field match on $bitfield\n" );
463 return call_user_func_array( [ $user, 'isAllowedAny' ], $permissions );
465 $text = $title->getPrefixedText();
466 wfDebug( "Checking for $permissionlist on $text due to $field match on $bitfield\n" );
467 foreach ( $permissions as $perm ) {
468 if ( $title->userCan( $perm, $user ) ) {