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
47 * @param CommentStoreComment $comment
48 * @param UserIdentity $user
49 * @param string $timestamp
51 * @return MutableRevisionRecord
53 public static function newFromParentRevision(
54 RevisionRecord
$parent,
55 CommentStoreComment
$comment,
59 // TODO: ideally, we wouldn't need a Title here
60 $title = Title
::newFromLinkTarget( $parent->getPageAsLinkTarget() );
61 $rev = new MutableRevisionRecord( $title, $parent->getWikiId() );
63 $rev->setComment( $comment );
64 $rev->setUser( $user );
65 $rev->setTimestamp( $timestamp );
67 foreach ( $parent->getSlotRoles() as $role ) {
68 $slot = $parent->getSlot( $role, self
::RAW
);
69 $rev->inheritSlot( $slot );
72 $rev->setPageId( $parent->getPageId() );
73 $rev->setParentId( $parent->getId() );
79 * @note Avoid calling this constructor directly. Use the appropriate methods
80 * in RevisionStore instead.
82 * @param Title $title The title of the page this Revision is associated with.
83 * @param bool|string $wikiId the wiki ID of the site this Revision belongs to,
84 * or false for the local site.
88 function __construct( Title
$title, $wikiId = false ) {
89 $slots = new MutableRevisionSlots();
91 parent
::__construct( $title, $slots, $wikiId );
93 $this->mSlots
= $slots; // redundant, but nice for static analysis
97 * @param int $parentId
99 public function setParentId( $parentId ) {
100 Assert
::parameterType( 'integer', $parentId, '$parentId' );
102 $this->mParentId
= $parentId;
106 * Sets the given slot. If a slot with the same role is already present in the revision,
109 * @note This can only be used with a fresh "unattached" SlotRecord. Calling code that has a
110 * SlotRecord from another revision should use inheritSlot(). Calling code that has access to
111 * a Content object can use setContent().
113 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
115 * @note Calling this method will cause the revision size and hash to be re-calculated upon
116 * the next call to getSize() and getSha1(), respectively.
118 * @param SlotRecord $slot
120 public function setSlot( SlotRecord
$slot ) {
121 if ( $slot->hasRevision() && $slot->getRevision() !== $this->getId() ) {
122 throw new InvalidArgumentException(
123 'The given slot must be an unsaved, unattached one. '
124 . 'This slot is already attached to revision ' . $slot->getRevision() . '. '
125 . 'Use inheritSlot() instead to preserve a slot from a previous revision.'
129 $this->mSlots
->setSlot( $slot );
130 $this->resetAggregateValues();
134 * "Inherits" the given slot's content.
136 * If a slot with the same role is already present in the revision, it is replaced.
138 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
140 * @param SlotRecord $parentSlot
142 public function inheritSlot( SlotRecord
$parentSlot ) {
143 $slot = SlotRecord
::newInherited( $parentSlot );
144 $this->setSlot( $slot );
148 * Sets the content for the slot with the given role.
150 * If a slot with the same role is already present in the revision, it is replaced.
151 * Calling code that has access to a SlotRecord can use inheritSlot() instead.
153 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
155 * @note Calling this method will cause the revision size and hash to be re-calculated upon
156 * the next call to getSize() and getSha1(), respectively.
158 * @param string $role
159 * @param Content $content
161 public function setContent( $role, Content
$content ) {
162 $this->mSlots
->setContent( $role, $content );
163 $this->resetAggregateValues();
167 * Removes the slot with the given role from this revision.
168 * This effectively ends the "stream" with that role on the revision's page.
169 * Future revisions will no longer inherit this slot, unless it is added back explicitly.
171 * @note This may cause the slot meta-data for the revision to be lazy-loaded.
173 * @note Calling this method will cause the revision size and hash to be re-calculated upon
174 * the next call to getSize() and getSha1(), respectively.
176 * @param string $role
178 public function removeSlot( $role ) {
179 $this->mSlots
->removeSlot( $role );
180 $this->resetAggregateValues();
184 * @param CommentStoreComment $comment
186 public function setComment( CommentStoreComment
$comment ) {
187 $this->mComment
= $comment;
191 * Set revision hash, for optimization. Prevents getSha1() from re-calculating the hash.
193 * @note This should only be used if the calling code is sure that the given hash is correct
194 * for the revision's content, and there is no chance of the content being manipulated
195 * later. When in doubt, this method should not be called.
197 * @param string $sha1 SHA1 hash as a base36 string.
199 public function setSha1( $sha1 ) {
200 Assert
::parameterType( 'string', $sha1, '$sha1' );
202 $this->mSha1
= $sha1;
206 * Set nominal revision size, for optimization. Prevents getSize() from re-calculating the size.
208 * @note This should only be used if the calling code is sure that the given size is correct
209 * for the revision's content, and there is no chance of the content being manipulated
210 * later. When in doubt, this method should not be called.
212 * @param int $size nominal size in bogo-bytes
214 public function setSize( $size ) {
215 Assert
::parameterType( 'integer', $size, '$size' );
217 $this->mSize
= $size;
221 * @param int $visibility
223 public function setVisibility( $visibility ) {
224 Assert
::parameterType( 'integer', $visibility, '$visibility' );
226 $this->mDeleted
= $visibility;
230 * @param string $timestamp A timestamp understood by wfTimestamp
232 public function setTimestamp( $timestamp ) {
233 Assert
::parameterType( 'string', $timestamp, '$timestamp' );
235 $this->mTimestamp
= wfTimestamp( TS_MW
, $timestamp );
239 * @param bool $minorEdit
241 public function setMinorEdit( $minorEdit ) {
242 Assert
::parameterType( 'boolean', $minorEdit, '$minorEdit' );
244 $this->mMinorEdit
= $minorEdit;
248 * Set the revision ID.
250 * MCR migration note: this replaces Revision::setId()
252 * @warning Use this with care, especially when preparing a revision for insertion
253 * into the database! The revision ID should only be fixed in special cases
254 * like preserving the original ID when restoring a revision.
258 public function setId( $id ) {
259 Assert
::parameterType( 'integer', $id, '$id' );
265 * Sets the user identity associated with the revision
267 * @param UserIdentity $user
269 public function setUser( UserIdentity
$user ) {
270 $this->mUser
= $user;
276 public function setPageId( $pageId ) {
277 Assert
::parameterType( 'integer', $pageId, '$pageId' );
279 if ( $this->mTitle
->exists() && $pageId !== $this->mTitle
->getArticleID() ) {
280 throw new InvalidArgumentException(
281 'The given Title does not belong to page ID ' . $this->mPageId
285 $this->mPageId
= $pageId;
289 * Returns the nominal size of this revision.
291 * MCR migration note: this replaces Revision::getSize
293 * @return int The nominal size, may be computed on the fly if not yet known.
295 public function getSize() {
296 // If not known, re-calculate and remember. Will be reset when slots change.
297 if ( $this->mSize
=== null ) {
298 $this->mSize
= $this->mSlots
->computeSize();
305 * Returns the base36 sha1 of this revision.
307 * MCR migration note: this replaces Revision::getSha1
309 * @return string The revision hash, may be computed on the fly if not yet known.
311 public function getSha1() {
312 // If not known, re-calculate and remember. Will be reset when slots change.
313 if ( $this->mSha1
=== null ) {
314 $this->mSha1
= $this->mSlots
->computeSha1();
321 * Invalidate cached aggregate values such as hash and size.
323 private function resetAggregateValues() {