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\Storage
;
25 use CommentStoreComment
;
27 use InvalidArgumentException
;
28 use MediaWiki\User\UserIdentity
;
31 use Wikimedia\Assert\Assert
;
34 * Mutable RevisionRecord implementation, for building new revision entries programmatically.
35 * Provides setters for all fields.
39 class MutableRevisionRecord
extends RevisionRecord
{
42 * Returns an incomplete MutableRevisionRecord which uses $parent as its
43 * parent revision, and inherits all slots form it. If saved unchanged,
44 * the new revision will act as a null-revision.
46 * @param RevisionRecord $parent
48 * @return MutableRevisionRecord
50 public static function newFromParentRevision( RevisionRecord
$parent ) {
51 // TODO: ideally, we wouldn't need a Title here
52 $title = Title
::newFromLinkTarget( $parent->getPageAsLinkTarget() );
53 $rev = new MutableRevisionRecord( $title, $parent->getWikiId() );
55 foreach ( $parent->getSlotRoles() as $role ) {
56 $slot = $parent->getSlot( $role, self
::RAW
);
57 $rev->inheritSlot( $slot );
60 $rev->setPageId( $parent->getPageId() );
61 $rev->setParentId( $parent->getId() );
67 * @note Avoid calling this constructor directly. Use the appropriate methods
68 * in RevisionStore instead.
70 * @param Title $title The title of the page this Revision is associated with.
71 * @param bool|string $wikiId the wiki ID of the site this Revision belongs to,
72 * or false for the local site.
76 function __construct( Title
$title, $wikiId = false ) {
77 $slots = new MutableRevisionSlots();
79 parent
::__construct( $title, $slots, $wikiId );
81 $this->mSlots
= $slots; // redundant, but nice for static analysis
85 * @param int $parentId
87 public function setParentId( $parentId ) {
88 Assert
::parameterType( 'integer', $parentId, '$parentId' );
90 $this->mParentId
= $parentId;
94 * Sets the given slot. If a slot with the same role is already present in the revision,
97 * @note This can only be used with a fresh "unattached" SlotRecord. Calling code that has a
98 * SlotRecord from another revision should use inheritSlot(). Calling code that has access to
99 * a Content object can use setContent().
101 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
103 * @note Calling this method will cause the revision size and hash to be re-calculated upon
104 * the next call to getSize() and getSha1(), respectively.
106 * @param SlotRecord $slot
108 public function setSlot( SlotRecord
$slot ) {
109 if ( $slot->hasRevision() && $slot->getRevision() !== $this->getId() ) {
110 throw new InvalidArgumentException(
111 'The given slot must be an unsaved, unattached one. '
112 . 'This slot is already attached to revision ' . $slot->getRevision() . '. '
113 . 'Use inheritSlot() instead to preserve a slot from a previous revision.'
117 $this->mSlots
->setSlot( $slot );
118 $this->resetAggregateValues();
122 * "Inherits" the given slot's content.
124 * If a slot with the same role is already present in the revision, it is replaced.
126 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
128 * @param SlotRecord $parentSlot
130 public function inheritSlot( SlotRecord
$parentSlot ) {
131 $this->mSlots
->inheritSlot( $parentSlot );
132 $this->resetAggregateValues();
136 * Sets the content for the slot with the given role.
138 * If a slot with the same role is already present in the revision, it is replaced.
139 * Calling code that has access to a SlotRecord can use inheritSlot() instead.
141 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
143 * @note Calling this method will cause the revision size and hash to be re-calculated upon
144 * the next call to getSize() and getSha1(), respectively.
146 * @param string $role
147 * @param Content $content
149 public function setContent( $role, Content
$content ) {
150 $this->mSlots
->setContent( $role, $content );
151 $this->resetAggregateValues();
155 * Removes the slot with the given role from this revision.
156 * This effectively ends the "stream" with that role on the revision's page.
157 * Future revisions will no longer inherit this slot, unless it is added back explicitly.
159 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
161 * @note Calling this method will cause the revision size and hash to be re-calculated upon
162 * the next call to getSize() and getSha1(), respectively.
164 * @param string $role
166 public function removeSlot( $role ) {
167 $this->mSlots
->removeSlot( $role );
168 $this->resetAggregateValues();
172 * Applies the given update to the slots of this revision.
174 * @param RevisionSlotsUpdate $update
176 public function applyUpdate( RevisionSlotsUpdate
$update ) {
177 $update->apply( $this->mSlots
);
181 * @param CommentStoreComment $comment
183 public function setComment( CommentStoreComment
$comment ) {
184 $this->mComment
= $comment;
188 * Set revision hash, for optimization. Prevents getSha1() from re-calculating the hash.
190 * @note This should only be used if the calling code is sure that the given hash is correct
191 * for the revision's content, and there is no chance of the content being manipulated
192 * later. When in doubt, this method should not be called.
194 * @param string $sha1 SHA1 hash as a base36 string.
196 public function setSha1( $sha1 ) {
197 Assert
::parameterType( 'string', $sha1, '$sha1' );
199 $this->mSha1
= $sha1;
203 * Set nominal revision size, for optimization. Prevents getSize() from re-calculating the size.
205 * @note This should only be used if the calling code is sure that the given size is correct
206 * for the revision's content, and there is no chance of the content being manipulated
207 * later. When in doubt, this method should not be called.
209 * @param int $size nominal size in bogo-bytes
211 public function setSize( $size ) {
212 Assert
::parameterType( 'integer', $size, '$size' );
214 $this->mSize
= $size;
218 * @param int $visibility
220 public function setVisibility( $visibility ) {
221 Assert
::parameterType( 'integer', $visibility, '$visibility' );
223 $this->mDeleted
= $visibility;
227 * @param string $timestamp A timestamp understood by wfTimestamp
229 public function setTimestamp( $timestamp ) {
230 Assert
::parameterType( 'string', $timestamp, '$timestamp' );
232 $this->mTimestamp
= wfTimestamp( TS_MW
, $timestamp );
236 * @param bool $minorEdit
238 public function setMinorEdit( $minorEdit ) {
239 Assert
::parameterType( 'boolean', $minorEdit, '$minorEdit' );
241 $this->mMinorEdit
= $minorEdit;
245 * Set the revision ID.
247 * MCR migration note: this replaces Revision::setId()
249 * @warning Use this with care, especially when preparing a revision for insertion
250 * into the database! The revision ID should only be fixed in special cases
251 * like preserving the original ID when restoring a revision.
255 public function setId( $id ) {
256 Assert
::parameterType( 'integer', $id, '$id' );
262 * Sets the user identity associated with the revision
264 * @param UserIdentity $user
266 public function setUser( UserIdentity
$user ) {
267 $this->mUser
= $user;
273 public function setPageId( $pageId ) {
274 Assert
::parameterType( 'integer', $pageId, '$pageId' );
276 if ( $this->mTitle
->exists() && $pageId !== $this->mTitle
->getArticleID() ) {
277 throw new InvalidArgumentException(
278 'The given Title does not belong to page ID ' . $this->mPageId
282 $this->mPageId
= $pageId;
286 * Returns the nominal size of this revision.
288 * MCR migration note: this replaces Revision::getSize
290 * @return int The nominal size, may be computed on the fly if not yet known.
292 public function getSize() {
293 // If not known, re-calculate and remember. Will be reset when slots change.
294 if ( $this->mSize
=== null ) {
295 $this->mSize
= $this->mSlots
->computeSize();
302 * Returns the base36 sha1 of this revision.
304 * MCR migration note: this replaces Revision::getSha1
306 * @return string The revision hash, may be computed on the fly if not yet known.
308 public function getSha1() {
309 // If not known, re-calculate and remember. Will be reset when slots change.
310 if ( $this->mSha1
=== null ) {
311 $this->mSha1
= $this->mSlots
->computeSha1();
318 * Returns the slots defined for this revision as a MutableRevisionSlots instance,
319 * which can be modified to defined the slots for this revision.
321 * @return MutableRevisionSlots
323 public function getSlots() {
324 // Overwritten just guarantee the more narrow return type.
325 return parent
::getSlots();
329 * Invalidate cached aggregate values such as hash and size.
331 private function resetAggregateValues() {