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\Storage
;
27 use OutOfBoundsException
;
28 use Wikimedia\Assert\Assert
;
31 * Value object representing a content slot associated with a page revision.
32 * SlotRecord provides direct access to a Content object.
33 * That access may be implemented through a callback.
40 * @var object database result row, as a raw object
45 * @var Content|callable
50 * Returns a new SlotRecord just like the given $slot, except that calling getContent()
51 * will fail with an exception.
53 * @param SlotRecord $slot
57 public static function newWithSuppressedContent( SlotRecord
$slot ) {
60 return new SlotRecord( $row, function () {
61 throw new SuppressedDataException( 'Content suppressed!' );
66 * Constructs a new SlotRecord from an existing SlotRecord, overriding some fields.
67 * The slot's content cannot be overwritten.
69 * @param SlotRecord $slot
70 * @param array $overrides
74 private static function newDerived( SlotRecord
$slot, array $overrides = [] ) {
77 foreach ( $overrides as $key => $value ) {
81 return new SlotRecord( $row, $slot->content
);
85 * Constructs a new SlotRecord for a new revision, inheriting the content of the given SlotRecord
86 * of a previous revision.
88 * @param SlotRecord $slot
92 public static function newInherited( SlotRecord
$slot ) {
93 return self
::newDerived( $slot, [
94 'slot_inherited' => true,
95 'slot_revision' => null,
100 * Constructs a new Slot from a Content object for a new revision.
101 * This is the preferred way to construct a slot for storing Content that
102 * resulted from a user edit.
104 * @param string $role
105 * @param Content $content
106 * @param bool $inherited
110 public static function newUnsaved( $role, Content
$content, $inherited = false ) {
111 Assert
::parameterType( 'boolean', $inherited, '$inherited' );
112 Assert
::parameterType( 'string', $role, '$role' );
115 'slot_id' => null, // not yet known
116 'slot_address' => null, // not yet known. need setter?
117 'slot_revision' => null, // not yet known
118 'slot_inherited' => $inherited,
119 'cont_size' => null, // compute later
120 'cont_sha1' => null, // compute later
121 'role_name' => $role,
122 'model_name' => $content->getModel(),
125 return new SlotRecord( (object)$row, $content );
129 * Constructs a SlotRecord for a newly saved revision, based on the proto-slot that was
130 * supplied to the code that performed the save operation. This adds information that
131 * has only become available during saving, particularly the revision ID and blob address.
133 * @param int $revisionId
134 * @param string $blobAddress
135 * @param SlotRecord $protoSlot The proto-slot that was provided to the code that then
139 public static function newSaved( $revisionId, $blobAddress, SlotRecord
$protoSlot ) {
140 Assert
::parameterType( 'integer', $revisionId, '$revisionId' );
141 Assert
::parameterType( 'string', $blobAddress, '$blobAddress' );
143 return self
::newDerived( $protoSlot, [
144 'slot_revision' => $revisionId,
145 'cont_address' => $blobAddress,
150 * SlotRecord constructor.
152 * The following fields are supported by the $row parameter:
157 * @param object $row A database row composed of fields of the slot and content tables,
158 * as a raw object. Any field value can be a callback that produces the field value
159 * given this SlotRecord as a parameter. However, plain strings cannot be used as
160 * callbacks here, for security reasons.
161 * @param Content|callable $content The content object associated with the slot, or a
162 * callback that will return that Content object, given this SlotRecord as a parameter.
164 public function __construct( $row, $content ) {
165 Assert
::parameterType( 'object', $row, '$row' );
166 Assert
::parameterType( 'Content|callable', $content, '$content' );
169 $this->content
= $content;
173 * Implemented to defy serialization.
175 * @throws LogicException always
177 public function __sleep() {
178 throw new LogicException( __CLASS__
. ' is not serializable.' );
182 * Returns the Content of the given slot.
184 * @note This is free to load Content from whatever subsystem is necessary,
185 * performing potentially expensive operations and triggering I/O-related
188 * @note This method does not apply audience filtering.
190 * @throws SuppressedDataException if access to the content is not allowed according
191 * to the audience check performed by RevisionRecord::getSlot().
193 * @return Content The slot's content. This is a direct reference to the internal instance,
194 * copy before exposing to application logic!
196 public function getContent() {
197 if ( $this->content
instanceof Content
) {
198 return $this->content
;
201 $obj = call_user_func( $this->content
, $this );
203 Assert
::postcondition(
204 $obj instanceof Content
,
205 'Slot content callback should return a Content object'
208 $this->content
= $obj;
210 return $this->content
;
214 * Returns the string value of a data field from the database row supplied to the constructor.
215 * If the field was set to a callback, that callback is invoked and the result returned.
217 * @param string $name
219 * @throws OutOfBoundsException
220 * @return mixed Returns the field's value, or null if the field is NULL in the DB row.
222 private function getField( $name ) {
223 if ( !isset( $this->row
->$name ) ) {
224 // distinguish between unknown and uninitialized fields
225 if ( property_exists( $this->row
, $name ) ) {
226 throw new IncompleteRevisionException( 'Uninitialized field: ' . $name );
228 throw new OutOfBoundsException( 'No such field: ' . $name );
232 $value = $this->row
->$name;
234 // NOTE: allow callbacks, but don't trust plain string callables from the database!
235 if ( !is_string( $value ) && is_callable( $value ) ) {
236 $value = call_user_func( $value, $this );
237 $this->setField( $name, $value );
244 * Returns the string value of a data field from the database row supplied to the constructor.
246 * @param string $name
248 * @throws OutOfBoundsException
249 * @throws IncompleteRevisionException
250 * @return string Returns the string value
252 private function getStringField( $name ) {
253 return strval( $this->getField( $name ) );
257 * Returns the int value of a data field from the database row supplied to the constructor.
259 * @param string $name
261 * @throws OutOfBoundsException
262 * @throws IncompleteRevisionException
263 * @return int Returns the int value
265 private function getIntField( $name ) {
266 return intval( $this->getField( $name ) );
270 * @param string $name
271 * @return bool whether this record contains the given field
273 private function hasField( $name ) {
274 return isset( $this->row
->$name );
278 * Returns the ID of the revision this slot is associated with.
282 public function getRevision() {
283 return $this->getIntField( 'slot_revision' );
287 * Whether this slot was inherited from an older revision.
291 public function isInherited() {
292 return $this->getIntField( 'slot_inherited' ) !== 0;
296 * Whether this slot has an address. Slots will have an address if their
297 * content has been stored. While building a new revision,
298 * SlotRecords will not have an address associated.
302 public function hasAddress() {
303 return $this->hasField( 'cont_address' );
307 * Whether this slot has revision ID associated. Slots will have a revision ID associated
308 * only if they were loaded as part of an existing revision. While building a new revision,
309 * Slotrecords will not have a revision ID associated.
313 public function hasRevision() {
314 return $this->hasField( 'slot_revision' );
318 * Returns the role of the slot.
322 public function getRole() {
323 return $this->getStringField( 'role_name' );
327 * Returns the address of this slot's content.
328 * This address can be used with BlobStore to load the Content object.
332 public function getAddress() {
333 return $this->getStringField( 'cont_address' );
337 * Returns the content size
339 * @return int size of the content, in bogo-bytes, as reported by Content::getSize.
341 public function getSize() {
343 $size = $this->getIntField( 'cont_size' );
344 } catch ( IncompleteRevisionException
$ex ) {
345 $size = $this->getContent()->getSize();
346 $this->setField( 'cont_size', $size );
353 * Returns the content size
355 * @return string hash of the content.
357 public function getSha1() {
359 $sha1 = $this->getStringField( 'cont_sha1' );
360 } catch ( IncompleteRevisionException
$ex ) {
361 $format = $this->hasField( 'format_name' )
362 ?
$this->getStringField( 'format_name' )
365 $data = $this->getContent()->serialize( $format );
366 $sha1 = self
::base36Sha1( $data );
367 $this->setField( 'cont_sha1', $sha1 );
374 * Returns the content model. This is the model name that decides
375 * which ContentHandler is appropriate for interpreting the
376 * data of the blob referenced by the address returned by getAddress().
378 * @return string the content model of the content
380 public function getModel() {
382 $model = $this->getStringField( 'model_name' );
383 } catch ( IncompleteRevisionException
$ex ) {
384 $model = $this->getContent()->getModel();
385 $this->setField( 'model_name', $model );
392 * Returns the blob serialization format as a MIME type.
394 * @note When this method returns null, the caller is expected
395 * to auto-detect the serialization format, or to rely on
396 * the default format associated with the content model.
398 * @return string|null
400 public function getFormat() {
401 // XXX: we currently do not plan to store the format for each slot!
403 if ( $this->hasField( 'format_name' ) ) {
404 return $this->getStringField( 'format_name' );
411 * @param string $name
412 * @param string|int|null $value
414 private function setField( $name, $value ) {
415 $this->row
->$name = $value;
419 * Get the base 36 SHA-1 value for a string of text
421 * MCR migration note: this replaces Revision::base36Sha1
423 * @param string $blob
426 public static function base36Sha1( $blob ) {
427 return \Wikimedia\base_convert
( sha1( $blob ), 16, 36, 31 );