3 * Value object representing a content slot associated with a page revision.
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
;
26 use InvalidArgumentException
;
28 use OutOfBoundsException
;
29 use Wikimedia\Assert\Assert
;
32 * Value object representing a content slot associated with a page revision.
33 * SlotRecord provides direct access to a Content object.
34 * That access may be implemented through a callback.
37 * @since 1.32 Renamed from MediaWiki\Storage\SlotRecord
44 * @var object database result row, as a raw object. Callbacks are supported for field values,
45 * to enable on-demand emulation of these values. This is primarily intended for use
46 * during schema migration.
51 * @var Content|callable
56 * Returns a new SlotRecord just like the given $slot, except that calling getContent()
57 * will fail with an exception.
59 * @param SlotRecord $slot
63 public static function newWithSuppressedContent( SlotRecord
$slot ) {
66 return new SlotRecord( $row, function () {
67 throw new SuppressedDataException( 'Content suppressed!' );
72 * Constructs a new SlotRecord from an existing SlotRecord, overriding some fields.
73 * The slot's content cannot be overwritten.
75 * @param SlotRecord $slot
76 * @param array $overrides
80 private static function newDerived( SlotRecord
$slot, array $overrides = [] ) {
81 $row = clone $slot->row
;
82 $row->slot_id
= null; // never copy the row ID!
84 foreach ( $overrides as $key => $value ) {
88 return new SlotRecord( $row, $slot->content
);
92 * Constructs a new SlotRecord for a new revision, inheriting the content of the given SlotRecord
93 * of a previous revision.
95 * Note that a SlotRecord constructed this way are intended as prototypes,
96 * to be used wit newSaved(). They are incomplete, so some getters such as
97 * getRevision() will fail.
99 * @param SlotRecord $slot
103 public static function newInherited( SlotRecord
$slot ) {
104 // Sanity check - we can't inherit from a Slot that's not attached to a revision.
105 $slot->getRevision();
109 // NOTE: slot_origin and content_address are copied from $slot.
110 return self
::newDerived( $slot, [
111 'slot_revision_id' => null,
116 * Constructs a new Slot from a Content object for a new revision.
117 * This is the preferred way to construct a slot for storing Content that
118 * resulted from a user edit. The slot is assumed to be not inherited.
120 * Note that a SlotRecord constructed this way are intended as prototypes,
121 * to be used wit newSaved(). They are incomplete, so some getters such as
122 * getAddress() will fail.
124 * @param string $role
125 * @param Content $content
127 * @return SlotRecord An incomplete proto-slot object, to be used with newSaved() later.
129 public static function newUnsaved( $role, Content
$content ) {
130 Assert
::parameterType( 'string', $role, '$role' );
133 'slot_id' => null, // not yet known
134 'slot_revision_id' => null, // not yet known
135 'slot_origin' => null, // not yet known, will be set in newSaved()
136 'content_size' => null, // compute later
137 'content_sha1' => null, // compute later
138 'slot_content_id' => null, // not yet known, will be set in newSaved()
139 'content_address' => null, // not yet known, will be set in newSaved()
140 'role_name' => $role,
141 'model_name' => $content->getModel(),
144 return new SlotRecord( (object)$row, $content );
148 * Constructs a complete SlotRecord for a newly saved revision, based on the incomplete
149 * proto-slot. This adds information that has only become available during saving,
150 * particularly the revision ID, content ID and content address.
152 * @param int $revisionId the revision the slot is to be associated with (field slot_revision_id).
153 * If $protoSlot already has a revision, it must be the same.
154 * @param int|null $contentId the ID of the row in the content table describing the content
155 * referenced by $contentAddress (field slot_content_id).
156 * If $protoSlot already has a content ID, it must be the same.
157 * @param string $contentAddress the slot's content address (field content_address).
158 * If $protoSlot already has an address, it must be the same.
159 * @param SlotRecord $protoSlot The proto-slot that was provided as input for creating a new
160 * revision. $protoSlot must have a content address if inherited.
162 * @return SlotRecord If the state of $protoSlot is inappropriate for saving a new revision.
164 public static function newSaved(
168 SlotRecord
$protoSlot
170 Assert
::parameterType( 'integer', $revisionId, '$revisionId' );
171 // TODO once migration is over $contentId must be an integer
172 Assert
::parameterType( 'integer|null', $contentId, '$contentId' );
173 Assert
::parameterType( 'string', $contentAddress, '$contentAddress' );
175 if ( $protoSlot->hasRevision() && $protoSlot->getRevision() !== $revisionId ) {
176 throw new LogicException(
177 "Mismatching revision ID $revisionId: "
178 . "The slot already belongs to revision {$protoSlot->getRevision()}. "
179 . "Use SlotRecord::newInherited() to re-use content between revisions."
183 if ( $protoSlot->hasAddress() && $protoSlot->getAddress() !== $contentAddress ) {
184 throw new LogicException(
185 "Mismatching blob address $contentAddress: "
186 . "The slot already has content at {$protoSlot->getAddress()}."
190 if ( $protoSlot->hasContentId() && $protoSlot->getContentId() !== $contentId ) {
191 throw new LogicException(
192 "Mismatching content ID $contentId: "
193 . "The slot already has content row {$protoSlot->getContentId()} associated."
197 if ( $protoSlot->isInherited() ) {
198 if ( !$protoSlot->hasAddress() ) {
199 throw new InvalidArgumentException(
200 "An inherited blob should have a content address!"
203 if ( !$protoSlot->hasField( 'slot_origin' ) ) {
204 throw new InvalidArgumentException(
205 "A saved inherited slot should have an origin set!"
208 $origin = $protoSlot->getOrigin();
210 $origin = $revisionId;
213 return self
::newDerived( $protoSlot, [
214 'slot_revision_id' => $revisionId,
215 'slot_content_id' => $contentId,
216 'slot_origin' => $origin,
217 'content_address' => $contentAddress,
222 * SlotRecord constructor.
224 * The following fields are supported by the $row parameter:
229 * @param object $row A database row composed of fields of the slot and content tables,
230 * as a raw object. Any field value can be a callback that produces the field value
231 * given this SlotRecord as a parameter. However, plain strings cannot be used as
232 * callbacks here, for security reasons.
233 * @param Content|callable $content The content object associated with the slot, or a
234 * callback that will return that Content object, given this SlotRecord as a parameter.
236 public function __construct( $row, $content ) {
237 Assert
::parameterType( 'object', $row, '$row' );
238 Assert
::parameterType( 'Content|callable', $content, '$content' );
241 property_exists( $row, 'slot_revision_id' ),
242 '$row->slot_revision_id',
246 property_exists( $row, 'slot_content_id' ),
247 '$row->slot_content_id',
251 property_exists( $row, 'content_address' ),
252 '$row->content_address',
256 property_exists( $row, 'model_name' ),
261 property_exists( $row, 'slot_origin' ),
266 !property_exists( $row, 'slot_inherited' ),
267 '$row->slot_inherited',
271 !property_exists( $row, 'slot_revision' ),
272 '$row->slot_revision',
277 $this->content
= $content;
281 * Implemented to defy serialization.
283 * @throws LogicException always
285 public function __sleep() {
286 throw new LogicException( __CLASS__
. ' is not serializable.' );
290 * Returns the Content of the given slot.
292 * @note This is free to load Content from whatever subsystem is necessary,
293 * performing potentially expensive operations and triggering I/O-related
296 * @note This method does not apply audience filtering.
298 * @throws SuppressedDataException if access to the content is not allowed according
299 * to the audience check performed by RevisionRecord::getSlot().
301 * @return Content The slot's content. This is a direct reference to the internal instance,
302 * copy before exposing to application logic!
304 public function getContent() {
305 if ( $this->content
instanceof Content
) {
306 return $this->content
;
309 $obj = call_user_func( $this->content
, $this );
311 Assert
::postcondition(
312 $obj instanceof Content
,
313 'Slot content callback should return a Content object'
316 $this->content
= $obj;
318 return $this->content
;
322 * Returns the string value of a data field from the database row supplied to the constructor.
323 * If the field was set to a callback, that callback is invoked and the result returned.
325 * @param string $name
327 * @throws OutOfBoundsException
328 * @throws IncompleteRevisionException
329 * @return mixed Returns the field's value, never null.
331 private function getField( $name ) {
332 if ( !isset( $this->row
->$name ) ) {
333 // distinguish between unknown and uninitialized fields
334 if ( property_exists( $this->row
, $name ) ) {
335 throw new IncompleteRevisionException( 'Uninitialized field: ' . $name );
337 throw new OutOfBoundsException( 'No such field: ' . $name );
341 $value = $this->row
->$name;
343 // NOTE: allow callbacks, but don't trust plain string callables from the database!
344 if ( !is_string( $value ) && is_callable( $value ) ) {
345 $value = call_user_func( $value, $this );
346 $this->setField( $name, $value );
353 * Returns the string value of a data field from the database row supplied to the constructor.
355 * @param string $name
357 * @throws OutOfBoundsException
358 * @throws IncompleteRevisionException
359 * @return string Returns the string value
361 private function getStringField( $name ) {
362 return strval( $this->getField( $name ) );
366 * Returns the int value of a data field from the database row supplied to the constructor.
368 * @param string $name
370 * @throws OutOfBoundsException
371 * @throws IncompleteRevisionException
372 * @return int Returns the int value
374 private function getIntField( $name ) {
375 return intval( $this->getField( $name ) );
379 * @param string $name
380 * @return bool whether this record contains the given field
382 private function hasField( $name ) {
383 if ( isset( $this->row
->$name ) ) {
384 // if the field is a callback, resolve first, then re-check
385 if ( !is_string( $this->row
->$name ) && is_callable( $this->row
->$name ) ) {
386 $this->getField( $name );
390 return isset( $this->row
->$name );
394 * Returns the ID of the revision this slot is associated with.
398 public function getRevision() {
399 return $this->getIntField( 'slot_revision_id' );
403 * Returns the revision ID of the revision that originated the slot's content.
407 public function getOrigin() {
408 return $this->getIntField( 'slot_origin' );
412 * Whether this slot was inherited from an older revision.
414 * If this SlotRecord is already attached to a revision, this returns true
415 * if the slot's revision of origin is the same as the revision it belongs to.
417 * If this SlotRecord is not yet attached to a revision, this returns true
418 * if the slot already has an address.
422 public function isInherited() {
423 if ( $this->hasRevision() ) {
424 return $this->getRevision() !== $this->getOrigin();
426 return $this->hasAddress();
431 * Whether this slot has an address. Slots will have an address if their
432 * content has been stored. While building a new revision,
433 * SlotRecords will not have an address associated.
437 public function hasAddress() {
438 return $this->hasField( 'content_address' );
442 * Whether this slot has an origin (revision ID that originated the slot's content.
448 public function hasOrigin() {
449 return $this->hasField( 'slot_origin' );
453 * Whether this slot has a content ID. Slots will have a content ID if their
454 * content has been stored in the content table. While building a new revision,
455 * SlotRecords will not have an ID associated.
457 * Also, during schema migration, hasContentId() may return false when encountering an
458 * un-migrated database entry in SCHEMA_COMPAT_WRITE_BOTH mode.
459 * It will however always return true for saved revisions on SCHEMA_COMPAT_READ_NEW mode,
460 * or without SCHEMA_COMPAT_WRITE_NEW mode. In the latter case, an emulated content ID
461 * is used, derived from the revision's text ID.
463 * Note that hasContentId() returning false while hasRevision() returns true always
464 * indicates an unmigrated row in SCHEMA_COMPAT_WRITE_BOTH mode, as described above.
465 * For an unsaved slot, both these methods would return false.
471 public function hasContentId() {
472 return $this->hasField( 'slot_content_id' );
476 * Whether this slot has revision ID associated. Slots will have a revision ID associated
477 * only if they were loaded as part of an existing revision. While building a new revision,
478 * Slotrecords will not have a revision ID associated.
482 public function hasRevision() {
483 return $this->hasField( 'slot_revision_id' );
487 * Returns the role of the slot.
491 public function getRole() {
492 return $this->getStringField( 'role_name' );
496 * Returns the address of this slot's content.
497 * This address can be used with BlobStore to load the Content object.
501 public function getAddress() {
502 return $this->getStringField( 'content_address' );
506 * Returns the ID of the content meta data row associated with the slot.
507 * This information should be irrelevant to application logic, it is here to allow
508 * the construction of a full row for the revision table.
510 * Note that this method may return an emulated value during schema migration in
511 * SCHEMA_COMPAT_WRITE_OLD mode. See RevisionStore::emulateContentId for more information.
515 public function getContentId() {
516 return $this->getIntField( 'slot_content_id' );
520 * Returns the content size
522 * @return int size of the content, in bogo-bytes, as reported by Content::getSize.
524 public function getSize() {
526 $size = $this->getIntField( 'content_size' );
527 } catch ( IncompleteRevisionException
$ex ) {
528 $size = $this->getContent()->getSize();
529 $this->setField( 'content_size', $size );
536 * Returns the content size
538 * @return string hash of the content.
540 public function getSha1() {
542 $sha1 = $this->getStringField( 'content_sha1' );
543 } catch ( IncompleteRevisionException
$ex ) {
544 $format = $this->hasField( 'format_name' )
545 ?
$this->getStringField( 'format_name' )
548 $data = $this->getContent()->serialize( $format );
549 $sha1 = self
::base36Sha1( $data );
550 $this->setField( 'content_sha1', $sha1 );
557 * Returns the content model. This is the model name that decides
558 * which ContentHandler is appropriate for interpreting the
559 * data of the blob referenced by the address returned by getAddress().
561 * @return string the content model of the content
563 public function getModel() {
565 $model = $this->getStringField( 'model_name' );
566 } catch ( IncompleteRevisionException
$ex ) {
567 $model = $this->getContent()->getModel();
568 $this->setField( 'model_name', $model );
575 * Returns the blob serialization format as a MIME type.
577 * @note When this method returns null, the caller is expected
578 * to auto-detect the serialization format, or to rely on
579 * the default format associated with the content model.
581 * @return string|null
583 public function getFormat() {
584 // XXX: we currently do not plan to store the format for each slot!
586 if ( $this->hasField( 'format_name' ) ) {
587 return $this->getStringField( 'format_name' );
594 * @param string $name
595 * @param string|int|null $value
597 private function setField( $name, $value ) {
598 $this->row
->$name = $value;
602 * Get the base 36 SHA-1 value for a string of text
604 * MCR migration note: this replaces Revision::base36Sha1
606 * @param string $blob
609 public static function base36Sha1( $blob ) {
610 return \Wikimedia\base_convert
( sha1( $blob ), 16, 36, 31 );
614 * Returns true if $other has the same content as this slot.
615 * The check is performed based on the model, address size, and hash.
616 * Two slots can have the same content if they use different content addresses,
617 * but if they have the same address and the same model, they have the same content.
618 * Two slots can have the same content if they belong to different
619 * revisions or pages.
621 * Note that hasSameContent() may return false even if Content::equals returns true for
622 * the content of two slots. This may happen if the two slots have different serializations
623 * representing equivalent Content. Such false negatives are considered acceptable. Code
624 * that has to be absolutely sure the Content is really not the same if hasSameContent()
625 * returns false should call getContent() and compare the Content objects directly.
629 * @param SlotRecord $other
632 public function hasSameContent( SlotRecord
$other ) {
633 if ( $other === $this ) {
637 if ( $this->getModel() !== $other->getModel() ) {
641 if ( $this->hasAddress()
642 && $other->hasAddress()
643 && $this->getAddress() == $other->getAddress()
648 if ( $this->getSize() !== $other->getSize() ) {
652 if ( $this->getSha1() !== $other->getSha1() ) {
662 * Retain the old class name for backwards compatibility.
663 * @deprecated since 1.32
665 class_alias( SlotRecord
::class, 'MediaWiki\Storage\SlotRecord' );