SlotRecord.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Revision;
 
use Content;
use InvalidArgumentException;
use LogicException;
use OutOfBoundsException;
use Wikimedia\Assert\Assert;
use Wikimedia\NonSerializable\NonSerializableTrait;
 
class SlotRecord {
    use NonSerializableTrait;
 
    public const MAIN = 'main';
 
    private $row;
 
    private $content;
 
    private $derived;
 
    public static function newWithSuppressedContent( SlotRecord $slot ) {
        $row = $slot->row;
 
        return new SlotRecord(
            $row,
            static function () {
                throw new SuppressedDataException( 'Content suppressed!' );
            }
        );
    }
 
    public static function newDerived( string $role, Content $content ) {
        return self::newUnsaved( $role, $content, true );
    }
 
    private static function newFromSlotRecord( SlotRecord $slot, array $overrides = [] ) {
        $row = clone $slot->row;
        $row->slot_id = null; // never copy the row ID!
 
        foreach ( $overrides as $key => $value ) {
            $row->$key = $value;
        }
 
        return new SlotRecord( $row, $slot->content, $slot->isDerived() );
    }
 
    public static function newInherited( SlotRecord $slot ) {
        // We can't inherit from a Slot that's not attached to a revision.
        $slot->getRevision();
        $slot->getOrigin();
        $slot->getAddress();
 
        // NOTE: slot_origin and content_address are copied from $slot.
        return self::newFromSlotRecord( $slot, [
            'slot_revision_id' => null,
        ] );
    }
 
    public static function newUnsaved( string $role, Content $content, bool $derived = false ) {
        $row = [
            'slot_id' => null, // not yet known
            'slot_revision_id' => null, // not yet known
            'slot_origin' => null, // not yet known, will be set in newSaved()
            'content_size' => null, // compute later
            'content_sha1' => null, // compute later
            'slot_content_id' => null, // not yet known, will be set in newSaved()
            'content_address' => null, // not yet known, will be set in newSaved()
            'role_name' => $role,
            'model_name' => $content->getModel(),
        ];
 
        return new SlotRecord( (object)$row, $content, $derived );
    }
 
    public static function newSaved(
        int $revisionId,
        ?int $contentId,
        string $contentAddress,
        SlotRecord $protoSlot
    ) {
        if ( $protoSlot->hasRevision() && $protoSlot->getRevision() !== $revisionId ) {
            throw new LogicException(
                "Mismatching revision ID $revisionId: "
                . "The slot already belongs to revision {$protoSlot->getRevision()}. "
                . "Use SlotRecord::newInherited() to re-use content between revisions."
            );
        }
 
        if ( $protoSlot->hasAddress() && $protoSlot->getAddress() !== $contentAddress ) {
            throw new LogicException(
                "Mismatching blob address $contentAddress: "
                . "The slot already has content at {$protoSlot->getAddress()}."
            );
        }
 
        if ( $protoSlot->hasContentId() && $protoSlot->getContentId() !== $contentId ) {
            throw new LogicException(
                "Mismatching content ID $contentId: "
                . "The slot already has content row {$protoSlot->getContentId()} associated."
            );
        }
 
        if ( $protoSlot->isInherited() ) {
            if ( !$protoSlot->hasAddress() ) {
                throw new InvalidArgumentException(
                    "An inherited blob should have a content address!"
                );
            }
            if ( !$protoSlot->hasField( 'slot_origin' ) ) {
                throw new InvalidArgumentException(
                    "A saved inherited slot should have an origin set!"
                );
            }
            $origin = $protoSlot->getOrigin();
        } else {
            $origin = $revisionId;
        }
 
        return self::newFromSlotRecord( $protoSlot, [
            'slot_revision_id' => $revisionId,
            'slot_content_id' => $contentId,
            'slot_origin' => $origin,
            'content_address' => $contentAddress,
        ] );
    }
 
    public function __construct( \stdClass $row, $content, bool $derived = false ) {
        Assert::parameterType( [ 'Content', 'callable' ], $content, '$content' );
 
        Assert::parameter(
            property_exists( $row, 'slot_revision_id' ),
            '$row->slot_revision_id',
            'must exist'
        );
        Assert::parameter(
            property_exists( $row, 'slot_content_id' ),
            '$row->slot_content_id',
            'must exist'
        );
        Assert::parameter(
            property_exists( $row, 'content_address' ),
            '$row->content_address',
            'must exist'
        );
        Assert::parameter(
            property_exists( $row, 'model_name' ),
            '$row->model_name',
            'must exist'
        );
        Assert::parameter(
            property_exists( $row, 'slot_origin' ),
            '$row->slot_origin',
            'must exist'
        );
        Assert::parameter(
            !property_exists( $row, 'slot_inherited' ),
            '$row->slot_inherited',
            'must not exist'
        );
        Assert::parameter(
            !property_exists( $row, 'slot_revision' ),
            '$row->slot_revision',
            'must not exist'
        );
 
        $this->row = $row;
        $this->content = $content;
        $this->derived = $derived;
    }
 
    public function getContent() {
        if ( $this->content instanceof Content ) {
            return $this->content;
        }
 
        $obj = call_user_func( $this->content, $this );
 
        Assert::postcondition(
            $obj instanceof Content,
            'Slot content callback should return a Content object'
        );
 
        $this->content = $obj;
 
        return $this->content;
    }
 
    private function getField( $name ) {
        if ( !isset( $this->row->$name ) ) {
            // distinguish between unknown and uninitialized fields
            if ( property_exists( $this->row, $name ) ) {
                throw new IncompleteRevisionException(
                    'Uninitialized field: {name}',
                    [ 'name' => $name ]
                );
            } else {
                throw new OutOfBoundsException( 'No such field: ' . $name );
            }
        }
 
        $value = $this->row->$name;
 
        // NOTE: allow callbacks, but don't trust plain string callables from the database!
        if ( !is_string( $value ) && is_callable( $value ) ) {
            $value = call_user_func( $value, $this );
            $this->setField( $name, $value );
        }
 
        return $value;
    }
 
    private function getStringField( $name ) {
        return strval( $this->getField( $name ) );
    }
 
    private function getIntField( $name ) {
        return intval( $this->getField( $name ) );
    }
 
    private function hasField( $name ) {
        if ( isset( $this->row->$name ) ) {
            // if the field is a callback, resolve first, then re-check
            if ( !is_string( $this->row->$name ) && is_callable( $this->row->$name ) ) {
                $this->getField( $name );
            }
        }
 
        return isset( $this->row->$name );
    }
 
    public function getRevision() {
        return $this->getIntField( 'slot_revision_id' );
    }
 
    public function getOrigin() {
        return $this->getIntField( 'slot_origin' );
    }
 
    public function isInherited() {
        if ( $this->hasRevision() ) {
            return $this->getRevision() !== $this->getOrigin();
        } else {
            return $this->hasAddress();
        }
    }
 
    public function hasAddress() {
        return $this->hasField( 'content_address' );
    }
 
    public function hasOrigin() {
        return $this->hasField( 'slot_origin' );
    }
 
    public function hasContentId() {
        return $this->hasField( 'slot_content_id' );
    }
 
    public function hasRevision() {
        return $this->hasField( 'slot_revision_id' );
    }
 
    public function getRole() {
        return $this->getStringField( 'role_name' );
    }
 
    public function getAddress() {
        return $this->getStringField( 'content_address' );
    }
 
    public function getContentId() {
        return $this->getIntField( 'slot_content_id' );
    }
 
    public function getSize() {
        try {
            $size = $this->getIntField( 'content_size' );
        } catch ( IncompleteRevisionException $ex ) {
            $size = $this->getContent()->getSize();
            $this->setField( 'content_size', $size );
        }
 
        return $size;
    }
 
    public function getSha1() {
        try {
            $sha1 = $this->getStringField( 'content_sha1' );
        } catch ( IncompleteRevisionException $ex ) {
            $sha1 = null;
        }
 
        // Compute if missing. Missing could mean null or empty.
        if ( $sha1 === null || $sha1 === '' ) {
            $format = $this->hasField( 'format_name' )
                ? $this->getStringField( 'format_name' )
                : null;
 
            $data = $this->getContent()->serialize( $format );
            $sha1 = self::base36Sha1( $data );
            $this->setField( 'content_sha1', $sha1 );
        }
 
        return $sha1;
    }
 
    public function getModel() {
        try {
            $model = $this->getStringField( 'model_name' );
        } catch ( IncompleteRevisionException $ex ) {
            $model = $this->getContent()->getModel();
            $this->setField( 'model_name', $model );
        }
 
        return $model;
    }
 
    public function getFormat() {
        // XXX: we currently do not plan to store the format for each slot!
 
        if ( $this->hasField( 'format_name' ) ) {
            return $this->getStringField( 'format_name' );
        }
 
        return null;
    }
 
    private function setField( $name, $value ) {
        $this->row->$name = $value;
    }
 
    public static function base36Sha1( $blob ) {
        return \Wikimedia\base_convert( sha1( $blob ), 16, 36, 31 );
    }
 
    public function hasSameContent( SlotRecord $other ) {
        if ( $other === $this ) {
            return true;
        }
 
        if ( $this->getModel() !== $other->getModel() ) {
            return false;
        }
 
        if ( $this->hasAddress()
            && $other->hasAddress()
            && $this->getAddress() == $other->getAddress()
        ) {
            return true;
        }
 
        if ( $this->getSize() !== $other->getSize() ) {
            return false;
        }
 
        if ( $this->getSha1() !== $other->getSha1() ) {
            return false;
        }
 
        return true;
    }
 
    public function isDerived(): bool {
        return $this->derived;
    }
 
}