3 * Mutable RevisionRecord implementation, for building new revision entries programmatically.
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\Revision
;
25 use CommentStoreComment
;
27 use InvalidArgumentException
;
28 use MediaWiki\Storage\RevisionSlotsUpdate
;
29 use MediaWiki\User\UserIdentity
;
32 use Wikimedia\Assert\Assert
;
35 * Mutable RevisionRecord implementation, for building new revision entries programmatically.
36 * Provides setters for all fields.
39 * @since 1.32 Renamed from MediaWiki\Storage\MutableRevisionRecord
41 class MutableRevisionRecord
extends RevisionRecord
{
44 * Returns an incomplete MutableRevisionRecord which uses $parent as its
45 * parent revision, and inherits all slots form it. If saved unchanged,
46 * the new revision will act as a null-revision.
48 * @param RevisionRecord $parent
50 * @return MutableRevisionRecord
52 public static function newFromParentRevision( RevisionRecord
$parent ) {
53 // TODO: ideally, we wouldn't need a Title here
54 $title = Title
::newFromLinkTarget( $parent->getPageAsLinkTarget() );
55 $rev = new MutableRevisionRecord( $title, $parent->getWikiId() );
57 foreach ( $parent->getSlotRoles() as $role ) {
58 $slot = $parent->getSlot( $role, self
::RAW
);
59 $rev->inheritSlot( $slot );
62 $rev->setPageId( $parent->getPageId() );
63 $rev->setParentId( $parent->getId() );
69 * @note Avoid calling this constructor directly. Use the appropriate methods
70 * in RevisionStore instead.
72 * @param Title $title The title of the page this Revision is associated with.
73 * @param bool|string $wikiId the wiki ID of the site this Revision belongs to,
74 * or false for the local site.
78 function __construct( Title
$title, $wikiId = false ) {
79 $slots = new MutableRevisionSlots();
81 parent
::__construct( $title, $slots, $wikiId );
83 $this->mSlots
= $slots; // redundant, but nice for static analysis
87 * @param int $parentId
89 public function setParentId( $parentId ) {
90 Assert
::parameterType( 'integer', $parentId, '$parentId' );
92 $this->mParentId
= $parentId;
96 * Sets the given slot. If a slot with the same role is already present in the revision,
99 * @note This can only be used with a fresh "unattached" SlotRecord. Calling code that has a
100 * SlotRecord from another revision should use inheritSlot(). Calling code that has access to
101 * a Content object can use setContent().
103 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
105 * @note Calling this method will cause the revision size and hash to be re-calculated upon
106 * the next call to getSize() and getSha1(), respectively.
108 * @param SlotRecord $slot
110 public function setSlot( SlotRecord
$slot ) {
111 if ( $slot->hasRevision() && $slot->getRevision() !== $this->getId() ) {
112 throw new InvalidArgumentException(
113 'The given slot must be an unsaved, unattached one. '
114 . 'This slot is already attached to revision ' . $slot->getRevision() . '. '
115 . 'Use inheritSlot() instead to preserve a slot from a previous revision.'
119 $this->mSlots
->setSlot( $slot );
120 $this->resetAggregateValues();
124 * "Inherits" the given slot's content.
126 * If a slot with the same role is already present in the revision, it is replaced.
128 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
130 * @param SlotRecord $parentSlot
132 public function inheritSlot( SlotRecord
$parentSlot ) {
133 $this->mSlots
->inheritSlot( $parentSlot );
134 $this->resetAggregateValues();
138 * Sets the content for the slot with the given role.
140 * If a slot with the same role is already present in the revision, it is replaced.
141 * Calling code that has access to a SlotRecord can use inheritSlot() instead.
143 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
145 * @note Calling this method will cause the revision size and hash to be re-calculated upon
146 * the next call to getSize() and getSha1(), respectively.
148 * @param string $role
149 * @param Content $content
151 public function setContent( $role, Content
$content ) {
152 $this->mSlots
->setContent( $role, $content );
153 $this->resetAggregateValues();
157 * Removes the slot with the given role from this revision.
158 * This effectively ends the "stream" with that role on the revision's page.
159 * Future revisions will no longer inherit this slot, unless it is added back explicitly.
161 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
163 * @note Calling this method will cause the revision size and hash to be re-calculated upon
164 * the next call to getSize() and getSha1(), respectively.
166 * @param string $role
168 public function removeSlot( $role ) {
169 $this->mSlots
->removeSlot( $role );
170 $this->resetAggregateValues();
174 * Applies the given update to the slots of this revision.
176 * @param RevisionSlotsUpdate $update
178 public function applyUpdate( RevisionSlotsUpdate
$update ) {
179 $update->apply( $this->mSlots
);
183 * @param CommentStoreComment $comment
185 public function setComment( CommentStoreComment
$comment ) {
186 $this->mComment
= $comment;
190 * Set revision hash, for optimization. Prevents getSha1() from re-calculating the hash.
192 * @note This should only be used if the calling code is sure that the given hash is correct
193 * for the revision's content, and there is no chance of the content being manipulated
194 * later. When in doubt, this method should not be called.
196 * @param string $sha1 SHA1 hash as a base36 string.
198 public function setSha1( $sha1 ) {
199 Assert
::parameterType( 'string', $sha1, '$sha1' );
201 $this->mSha1
= $sha1;
205 * Set nominal revision size, for optimization. Prevents getSize() from re-calculating the size.
207 * @note This should only be used if the calling code is sure that the given size is correct
208 * for the revision's content, and there is no chance of the content being manipulated
209 * later. When in doubt, this method should not be called.
211 * @param int $size nominal size in bogo-bytes
213 public function setSize( $size ) {
214 Assert
::parameterType( 'integer', $size, '$size' );
216 $this->mSize
= $size;
220 * @param int $visibility
222 public function setVisibility( $visibility ) {
223 Assert
::parameterType( 'integer', $visibility, '$visibility' );
225 $this->mDeleted
= $visibility;
229 * @param string $timestamp A timestamp understood by wfTimestamp
231 public function setTimestamp( $timestamp ) {
232 Assert
::parameterType( 'string', $timestamp, '$timestamp' );
234 $this->mTimestamp
= wfTimestamp( TS_MW
, $timestamp );
238 * @param bool $minorEdit
240 public function setMinorEdit( $minorEdit ) {
241 Assert
::parameterType( 'boolean', $minorEdit, '$minorEdit' );
243 $this->mMinorEdit
= $minorEdit;
247 * Set the revision ID.
249 * MCR migration note: this replaces Revision::setId()
251 * @warning Use this with care, especially when preparing a revision for insertion
252 * into the database! The revision ID should only be fixed in special cases
253 * like preserving the original ID when restoring a revision.
257 public function setId( $id ) {
258 Assert
::parameterType( 'integer', $id, '$id' );
264 * Sets the user identity associated with the revision
266 * @param UserIdentity $user
268 public function setUser( UserIdentity
$user ) {
269 $this->mUser
= $user;
275 public function setPageId( $pageId ) {
276 Assert
::parameterType( 'integer', $pageId, '$pageId' );
278 if ( $this->mTitle
->exists() && $pageId !== $this->mTitle
->getArticleID() ) {
279 throw new InvalidArgumentException(
280 'The given Title does not belong to page ID ' . $this->mPageId
284 $this->mPageId
= $pageId;
288 * Returns the nominal size of this revision.
290 * MCR migration note: this replaces Revision::getSize
292 * @return int The nominal size, may be computed on the fly if not yet known.
294 public function getSize() {
295 // If not known, re-calculate and remember. Will be reset when slots change.
296 if ( $this->mSize
=== null ) {
297 $this->mSize
= $this->mSlots
->computeSize();
304 * Returns the base36 sha1 of this revision.
306 * MCR migration note: this replaces Revision::getSha1
308 * @return string The revision hash, may be computed on the fly if not yet known.
310 public function getSha1() {
311 // If not known, re-calculate and remember. Will be reset when slots change.
312 if ( $this->mSha1
=== null ) {
313 $this->mSha1
= $this->mSlots
->computeSha1();
320 * Returns the slots defined for this revision as a MutableRevisionSlots instance,
321 * which can be modified to defined the slots for this revision.
323 * @return MutableRevisionSlots
325 public function getSlots() {
326 // Overwritten just guarantee the more narrow return type.
327 return parent
::getSlots();
331 * Invalidate cached aggregate values such as hash and size.
333 private function resetAggregateValues() {
341 * Retain the old class name for backwards compatibility.
342 * @deprecated since 1.32
344 class_alias( MutableRevisionRecord
::class, 'MediaWiki\Storage\MutableRevisionRecord' );