Revision.php

Go to the documentation of this file.

<?php
use MediaWiki\Revision\MutableRevisionRecord;
use MediaWiki\Revision\RevisionAccessException;
use MediaWiki\Revision\RevisionFactory;
use MediaWiki\Revision\RevisionLookup;
use MediaWiki\Revision\RevisionRecord;
use MediaWiki\Revision\RevisionStore;
use MediaWiki\Revision\RevisionStoreRecord;
use MediaWiki\Revision\SlotRecord;
use MediaWiki\Storage\SqlBlobStore;
use Wikimedia\Assert\Assert;
use Wikimedia\Rdbms\IDatabase;
use MediaWiki\Linker\LinkTarget;
use MediaWiki\MediaWikiServices;
use Wikimedia\Rdbms\ResultWrapper;
use Wikimedia\Rdbms\FakeResultWrapper;

class Revision implements IDBAccessObject {

    protected $mRecord;

    // Revision deletion constants
    const DELETED_TEXT = RevisionRecord::DELETED_TEXT;
    const DELETED_COMMENT = RevisionRecord::DELETED_COMMENT;
    const DELETED_USER = RevisionRecord::DELETED_USER;
    const DELETED_RESTRICTED = RevisionRecord::DELETED_RESTRICTED;
    const SUPPRESSED_USER = RevisionRecord::SUPPRESSED_USER;
    const SUPPRESSED_ALL = RevisionRecord::SUPPRESSED_ALL;

    // Audience options for accessors
    const FOR_PUBLIC = RevisionRecord::FOR_PUBLIC;
    const FOR_THIS_USER = RevisionRecord::FOR_THIS_USER;
    const RAW = RevisionRecord::RAW;

    const TEXT_CACHE_GROUP = SqlBlobStore::TEXT_CACHE_GROUP;

    protected static function getRevisionStore( $wiki = false ) {
        if ( $wiki ) {
            return MediaWikiServices::getInstance()->getRevisionStoreFactory()
                ->getRevisionStore( $wiki );
        } else {
            return MediaWikiServices::getInstance()->getRevisionStore();
        }
    }

    protected static function getRevisionLookup() {
        return MediaWikiServices::getInstance()->getRevisionLookup();
    }

    protected static function getRevisionFactory() {
        return MediaWikiServices::getInstance()->getRevisionFactory();
    }

    protected static function getBlobStore( $wiki = false ) {
        $store = MediaWikiServices::getInstance()
            ->getBlobStoreFactory()
            ->newSqlBlobStore( $wiki );

        if ( !$store instanceof SqlBlobStore ) {
            throw new RuntimeException(
                'The backwards compatibility code in Revision currently requires the BlobStore '
                . 'service to be an SqlBlobStore instance, but it is a ' . get_class( $store )
            );
        }

        return $store;
    }

    public static function newFromId( $id, $flags = 0 ) {
        $rec = self::getRevisionLookup()->getRevisionById( $id, $flags );
        return $rec === null ? null : new Revision( $rec, $flags );
    }

    public static function newFromTitle( LinkTarget $linkTarget, $id = 0, $flags = 0 ) {
        $rec = self::getRevisionLookup()->getRevisionByTitle( $linkTarget, $id, $flags );
        return $rec === null ? null : new Revision( $rec, $flags );
    }

    public static function newFromPageId( $pageId, $revId = 0, $flags = 0 ) {
        $rec = self::getRevisionLookup()->getRevisionByPageId( $pageId, $revId, $flags );
        return $rec === null ? null : new Revision( $rec, $flags );
    }

    public static function newFromArchiveRow( $row, $overrides = [] ) {
        if ( array_key_exists( 'page', $overrides ) ) {
            $overrides['page_id'] = $overrides['page'];
            unset( $overrides['page'] );
        }

        $title = null;
        if ( isset( $overrides['title'] ) ) {
            if ( !( $overrides['title'] instanceof Title ) ) {
                throw new MWException( 'title field override must contain a Title object.' );
            }

            $title = $overrides['title'];
        }
        if ( $title !== null ) {
            if ( isset( $row->ar_namespace ) && isset( $row->ar_title ) ) {
                $title = Title::makeTitle( $row->ar_namespace, $row->ar_title );
            } else {
                throw new InvalidArgumentException(
                    'A Title or ar_namespace and ar_title must be given'
                );
            }
        }

        $rec = self::getRevisionFactory()->newRevisionFromArchiveRow( $row, 0, $title, $overrides );
        return new Revision( $rec, self::READ_NORMAL, $title );
    }

    public static function newFromRow( $row ) {
        if ( is_array( $row ) ) {
            $rec = self::getRevisionFactory()->newMutableRevisionFromArray( $row );
        } else {
            $rec = self::getRevisionFactory()->newRevisionFromRow( $row );
        }

        return new Revision( $rec );
    }

    public static function loadFromId( $db, $id ) {
        wfDeprecated( __METHOD__, '1.31' ); // no known callers
        $rec = self::getRevisionStore()->loadRevisionFromId( $db, $id );
        return $rec === null ? null : new Revision( $rec );
    }

    public static function loadFromPageId( $db, $pageid, $id = 0 ) {
        $rec = self::getRevisionStore()->loadRevisionFromPageId( $db, $pageid, $id );
        return $rec === null ? null : new Revision( $rec );
    }

    public static function loadFromTitle( $db, $title, $id = 0 ) {
        $rec = self::getRevisionStore()->loadRevisionFromTitle( $db, $title, $id );
        return $rec === null ? null : new Revision( $rec );
    }

    public static function loadFromTimestamp( $db, $title, $timestamp ) {
        $rec = self::getRevisionStore()->loadRevisionFromTimestamp( $db, $title, $timestamp );
        return $rec === null ? null : new Revision( $rec );
    }

    public static function fetchRevision( LinkTarget $title ) {
        wfDeprecated( __METHOD__, '1.31' );
        return new FakeResultWrapper( [] );
    }

    public static function userJoinCond() {
        global $wgActorTableSchemaMigrationStage;

        wfDeprecated( __METHOD__, '1.31' );
        if ( $wgActorTableSchemaMigrationStage & SCHEMA_COMPAT_READ_NEW ) {
            // If code is using this instead of self::getQueryInfo(), there's
            // no way the join it's trying to do can work once the old fields
            // aren't being used anymore.
            throw new BadMethodCallException(
                'Cannot use ' . __METHOD__
                    . ' when $wgActorTableSchemaMigrationStage has SCHEMA_COMPAT_READ_NEW'
            );
        }

        return [ 'LEFT JOIN', [ 'rev_user != 0', 'user_id = rev_user' ] ];
    }

    public static function pageJoinCond() {
        wfDeprecated( __METHOD__, '1.31' );
        return [ 'INNER JOIN', [ 'page_id = rev_page' ] ];
    }

    public static function selectFields() {
        global $wgContentHandlerUseDB, $wgActorTableSchemaMigrationStage;
        global $wgMultiContentRevisionSchemaMigrationStage;

        if ( $wgActorTableSchemaMigrationStage & SCHEMA_COMPAT_READ_NEW ) {
            // If code is using this instead of self::getQueryInfo(), there's a
            // decent chance it's going to try to directly access
            // $row->rev_user or $row->rev_user_text and we can't give it
            // useful values here once those aren't being used anymore.
            throw new BadMethodCallException(
                'Cannot use ' . __METHOD__
                    . ' when $wgActorTableSchemaMigrationStage has SCHEMA_COMPAT_READ_NEW'
            );
        }

        if ( !( $wgMultiContentRevisionSchemaMigrationStage & SCHEMA_COMPAT_WRITE_OLD ) ) {
            // If code is using this instead of self::getQueryInfo(), there's a
            // decent chance it's going to try to directly access
            // $row->rev_text_id or $row->rev_content_model and we can't give it
            // useful values here once those aren't being written anymore,
            // and may not exist at all.
            throw new BadMethodCallException(
                'Cannot use ' . __METHOD__ . ' when $wgMultiContentRevisionSchemaMigrationStage '
                . 'does not have SCHEMA_COMPAT_WRITE_OLD set.'
            );
        }

        wfDeprecated( __METHOD__, '1.31' );

        $fields = [
            'rev_id',
            'rev_page',
            'rev_text_id',
            'rev_timestamp',
            'rev_user_text',
            'rev_user',
            'rev_actor' => 'NULL',
            'rev_minor_edit',
            'rev_deleted',
            'rev_len',
            'rev_parent_id',
            'rev_sha1',
        ];

        $fields += CommentStore::getStore()->getFields( 'rev_comment' );

        if ( $wgContentHandlerUseDB ) {
            $fields[] = 'rev_content_format';
            $fields[] = 'rev_content_model';
        }

        return $fields;
    }

    public static function selectArchiveFields() {
        global $wgContentHandlerUseDB, $wgActorTableSchemaMigrationStage;
        global $wgMultiContentRevisionSchemaMigrationStage;

        if ( $wgActorTableSchemaMigrationStage & SCHEMA_COMPAT_READ_NEW ) {
            // If code is using this instead of self::getQueryInfo(), there's a
            // decent chance it's going to try to directly access
            // $row->ar_user or $row->ar_user_text and we can't give it
            // useful values here once those aren't being used anymore.
            throw new BadMethodCallException(
                'Cannot use ' . __METHOD__
                    . ' when $wgActorTableSchemaMigrationStage has SCHEMA_COMPAT_READ_NEW'
            );
        }

        if ( !( $wgMultiContentRevisionSchemaMigrationStage & SCHEMA_COMPAT_WRITE_OLD ) ) {
            // If code is using this instead of self::getQueryInfo(), there's a
            // decent chance it's going to try to directly access
            // $row->ar_text_id or $row->ar_content_model and we can't give it
            // useful values here once those aren't being written anymore,
            // and may not exist at all.
            throw new BadMethodCallException(
                'Cannot use ' . __METHOD__ . ' when $wgMultiContentRevisionSchemaMigrationStage '
                . 'does not have SCHEMA_COMPAT_WRITE_OLD set.'
            );
        }

        wfDeprecated( __METHOD__, '1.31' );

        $fields = [
            'ar_id',
            'ar_page_id',
            'ar_rev_id',
            'ar_text_id',
            'ar_timestamp',
            'ar_user_text',
            'ar_user',
            'ar_actor' => 'NULL',
            'ar_minor_edit',
            'ar_deleted',
            'ar_len',
            'ar_parent_id',
            'ar_sha1',
        ];

        $fields += CommentStore::getStore()->getFields( 'ar_comment' );

        if ( $wgContentHandlerUseDB ) {
            $fields[] = 'ar_content_format';
            $fields[] = 'ar_content_model';
        }
        return $fields;
    }

    public static function selectTextFields() {
        wfDeprecated( __METHOD__, '1.31' );
        return [
            'old_text',
            'old_flags'
        ];
    }

    public static function selectPageFields() {
        wfDeprecated( __METHOD__, '1.31' );
        return [
            'page_namespace',
            'page_title',
            'page_id',
            'page_latest',
            'page_is_redirect',
            'page_len',
        ];
    }

    public static function selectUserFields() {
        wfDeprecated( __METHOD__, '1.31' );
        return [ 'user_name' ];
    }

    public static function getQueryInfo( $options = [] ) {
        return self::getRevisionStore()->getQueryInfo( $options );
    }

    public static function getArchiveQueryInfo() {
        return self::getRevisionStore()->getArchiveQueryInfo();
    }

    public static function getParentLengths( $db, array $revIds ) {
        return self::getRevisionStore()->listRevisionSizes( $db, $revIds );
    }

    function __construct( $row, $queryFlags = 0, Title $title = null ) {
        global $wgUser;

        if ( $row instanceof RevisionRecord ) {
            $this->mRecord = $row;
        } elseif ( is_array( $row ) ) {
            // If no user is specified, fall back to using the global user object, to stay
            // compatible with pre-1.31 behavior.
            if ( !isset( $row['user'] ) && !isset( $row['user_text'] ) ) {
                $row['user'] = $wgUser;
            }

            $this->mRecord = self::getRevisionFactory()->newMutableRevisionFromArray(
                $row,
                $queryFlags,
                $this->ensureTitle( $row, $queryFlags, $title )
            );
        } elseif ( is_object( $row ) ) {
            $this->mRecord = self::getRevisionFactory()->newRevisionFromRow(
                $row,
                $queryFlags,
                $this->ensureTitle( $row, $queryFlags, $title )
            );
        } else {
            throw new InvalidArgumentException(
                '$row must be a row object, an associative array, or a RevisionRecord'
            );
        }

        Assert::postcondition( $this->mRecord !== null, 'Failed to construct a RevisionRecord' );
    }

    private function ensureTitle( $row, $queryFlags, $title = null ) {
        if ( $title ) {
            return $title;
        }

        if ( is_array( $row ) ) {
            if ( isset( $row['title'] ) ) {
                if ( !( $row['title'] instanceof Title ) ) {
                    throw new MWException( 'title field must contain a Title object.' );
                }

                return $row['title'];
            }

            $pageId = $row['page'] ?? 0;
            $revId = $row['id'] ?? 0;
        } else {
            $pageId = $row->rev_page ?? 0;
            $revId = $row->rev_id ?? 0;
        }

        try {
            $title = self::getRevisionStore()->getTitle( $pageId, $revId, $queryFlags );
        } catch ( RevisionAccessException $ex ) {
            // construct a dummy title!
            wfLogWarning( __METHOD__ . ': ' . $ex->getMessage() );

            // NOTE: this Title will only be used inside RevisionRecord
            $title = Title::makeTitleSafe( NS_SPECIAL, "Badtitle/ID=$pageId" );
            $title->resetArticleID( $pageId );
        }

        return $title;
    }

    public function getRevisionRecord() {
        return $this->mRecord;
    }

    public function getId() {
        return $this->mRecord->getId();
    }

    public function setId( $id ) {
        if ( $this->mRecord instanceof MutableRevisionRecord ) {
            $this->mRecord->setId( intval( $id ) );
        } else {
            throw new MWException( __METHOD__ . ' is not supported on this instance' );
        }
    }

    public function setUserIdAndName( $id, $name ) {
        if ( $this->mRecord instanceof MutableRevisionRecord ) {
            $user = User::newFromAnyId( intval( $id ), $name, null );
            $this->mRecord->setUser( $user );
        } else {
            throw new MWException( __METHOD__ . ' is not supported on this instance' );
        }
    }

    private function getMainSlotRaw() {
        return $this->mRecord->getSlot( SlotRecord::MAIN, RevisionRecord::RAW );
    }

    public function getTextId() {
        $slot = $this->getMainSlotRaw();
        return $slot->hasAddress()
            ? self::getBlobStore()->getTextIdFromAddress( $slot->getAddress() )
            : null;
    }

    public function getParentId() {
        return $this->mRecord->getParentId();
    }

    public function getSize() {
        try {
            return $this->mRecord->getSize();
        } catch ( RevisionAccessException $ex ) {
            return null;
        }
    }

    public function getSha1() {
        try {
            return $this->mRecord->getSha1();
        } catch ( RevisionAccessException $ex ) {
            return null;
        }
    }

    public function getTitle() {
        $linkTarget = $this->mRecord->getPageAsLinkTarget();
        return Title::newFromLinkTarget( $linkTarget );
    }

    public function setTitle( $title ) {
        if ( !$title->equals( $this->getTitle() ) ) {
            throw new InvalidArgumentException(
                $title->getPrefixedText()
                    . ' is not the same as '
                    . $this->mRecord->getPageAsLinkTarget()->__toString()
            );
        }
    }

    public function getPage() {
        return $this->mRecord->getPageId();
    }

    public function getUser( $audience = self::FOR_PUBLIC, User $user = null ) {
        global $wgUser;

        if ( $audience === self::FOR_THIS_USER && !$user ) {
            $user = $wgUser;
        }

        $user = $this->mRecord->getUser( $audience, $user );
        return $user ? $user->getId() : 0;
    }

    public function getUserText( $audience = self::FOR_PUBLIC, User $user = null ) {
        global $wgUser;

        if ( $audience === self::FOR_THIS_USER && !$user ) {
            $user = $wgUser;
        }

        $user = $this->mRecord->getUser( $audience, $user );
        return $user ? $user->getName() : '';
    }

    function getComment( $audience = self::FOR_PUBLIC, User $user = null ) {
        global $wgUser;

        if ( $audience === self::FOR_THIS_USER && !$user ) {
            $user = $wgUser;
        }

        $comment = $this->mRecord->getComment( $audience, $user );
        return $comment === null ? null : $comment->text;
    }

    public function isMinor() {
        return $this->mRecord->isMinor();
    }

    public function isUnpatrolled() {
        return self::getRevisionStore()->getRcIdIfUnpatrolled( $this->mRecord );
    }

    public function getRecentChange( $flags = 0 ) {
        return self::getRevisionStore()->getRecentChange( $this->mRecord, $flags );
    }

    public function isDeleted( $field ) {
        return $this->mRecord->isDeleted( $field );
    }

    public function getVisibility() {
        return $this->mRecord->getVisibility();
    }

    public function getContent( $audience = self::FOR_PUBLIC, User $user = null ) {
        global $wgUser;

        if ( $audience === self::FOR_THIS_USER && !$user ) {
            $user = $wgUser;
        }

        try {
            return $this->mRecord->getContent( SlotRecord::MAIN, $audience, $user );
        }
        catch ( RevisionAccessException $e ) {
            return null;
        }
    }

    public function getSerializedData() {
        $slot = $this->getMainSlotRaw();
        return $slot->getContent()->serialize();
    }

    public function getContentModel() {
        return $this->getMainSlotRaw()->getModel();
    }

    public function getContentFormat() {
        $format = $this->getMainSlotRaw()->getFormat();

        if ( $format === null ) {
            // if no format was stored along with the blob, fall back to default format
            $format = $this->getContentHandler()->getDefaultFormat();
        }

        return $format;
    }

    public function getContentHandler() {
        return ContentHandler::getForModelID( $this->getContentModel() );
    }

    public function getTimestamp() {
        return $this->mRecord->getTimestamp();
    }

    public function isCurrent() {
        return ( $this->mRecord instanceof RevisionStoreRecord ) && $this->mRecord->isCurrent();
    }

    public function getPrevious() {
        $title = $this->getTitle();
        $rec = self::getRevisionLookup()->getPreviousRevision( $this->mRecord, $title );
        return $rec === null ? null : new Revision( $rec, self::READ_NORMAL, $title );
    }

    public function getNext() {
        $title = $this->getTitle();
        $rec = self::getRevisionLookup()->getNextRevision( $this->mRecord, $title );
        return $rec === null ? null : new Revision( $rec, self::READ_NORMAL, $title );
    }

    public static function getRevisionText( $row, $prefix = 'old_', $wiki = false ) {
        global $wgMultiContentRevisionSchemaMigrationStage;

        if ( !$row ) {
            return false;
        }

        $textField = $prefix . 'text';
        $flagsField = $prefix . 'flags';

        if ( isset( $row->$textField ) ) {
            if ( !( $wgMultiContentRevisionSchemaMigrationStage & SCHEMA_COMPAT_WRITE_OLD ) ) {
                // The text field was read, but it's no longer being populated!
                // We could gloss over this by using the text when it's there and loading
                // if when it's not, but it seems preferable to complain loudly about a
                // query that is no longer guaranteed to work reliably.
                throw new LogicException(
                    'Cannot use ' . __METHOD__ . ' with the ' . $textField . ' field when'
                    . ' $wgMultiContentRevisionSchemaMigrationStage does not include'
                    . ' SCHEMA_COMPAT_WRITE_OLD. The field may not be populated for all revisions!'
                );
            }

            $text = $row->$textField;
        } else {
            // Missing text field, we are probably looking at the MCR-enabled DB schema.

            if ( !( $wgMultiContentRevisionSchemaMigrationStage & SCHEMA_COMPAT_WRITE_OLD ) ) {
                // This method should no longer be used with the new schema. Ideally, we
                // would already trigger a deprecation warning when SCHEMA_COMPAT_READ_NEW is set.
                wfDeprecated( __METHOD__ . ' (MCR without SCHEMA_COMPAT_WRITE_OLD)', '1.32' );
            }

            $store = self::getRevisionStore( $wiki );
            $rev = $prefix === 'ar_'
                ? $store->newRevisionFromArchiveRow( $row )
                : $store->newRevisionFromRow( $row );

            $content = $rev->getContent( SlotRecord::MAIN );
            return $content ? $content->serialize() : false;
        }

        if ( isset( $row->$flagsField ) ) {
            $flags = explode( ',', $row->$flagsField );
        } else {
            $flags = [];
        }

        $cacheKey = isset( $row->old_id )
            ? SqlBlobStore::makeAddressFromTextId( $row->old_id )
            : null;

        $revisionText = self::getBlobStore( $wiki )->expandBlob( $text, $flags, $cacheKey );

        if ( $revisionText === false ) {
            if ( isset( $row->old_id ) ) {
                wfLogWarning( __METHOD__ . ": Bad data in text row {$row->old_id}! " );
            } else {
                wfLogWarning( __METHOD__ . ": Bad data in text row! " );
            }
            return false;
        }

        return $revisionText;
    }

    public static function compressRevisionText( &$text ) {
        return self::getBlobStore()->compressData( $text );
    }

    public static function decompressRevisionText( $text, $flags ) {
        if ( $text === false ) {
            // Text failed to be fetched; nothing to do
            return false;
        }

        return self::getBlobStore()->decompressData( $text, $flags );
    }

    public function insertOn( $dbw ) {
        global $wgUser;

        // Note that $this->mRecord->getId() will typically return null here, but not always,
        // e.g. not when restoring a revision.

        if ( $this->mRecord->getUser( RevisionRecord::RAW ) === null ) {
            if ( $this->mRecord instanceof MutableRevisionRecord ) {
                $this->mRecord->setUser( $wgUser );
            } else {
                throw new MWException( 'Cannot insert revision with no associated user.' );
            }
        }

        $rec = self::getRevisionStore()->insertRevisionOn( $this->mRecord, $dbw );

        $this->mRecord = $rec;
        Assert::postcondition( $this->mRecord !== null, 'Failed to acquire a RevisionRecord' );

        return $rec->getId();
    }

    public static function base36Sha1( $text ) {
        return SlotRecord::base36Sha1( $text );
    }

    public static function newNullRevision( $dbw, $pageId, $summary, $minor, $user = null ) {
        global $wgUser;
        if ( !$user ) {
            $user = $wgUser;
        }

        $comment = CommentStoreComment::newUnsavedComment( $summary, null );

        $title = Title::newFromID( $pageId, Title::GAID_FOR_UPDATE );
        if ( $title === null ) {
            return null;
        }

        $rec = self::getRevisionStore()->newNullRevision( $dbw, $title, $comment, $minor, $user );

        return $rec ? new Revision( $rec ) : null;
    }

    public function userCan( $field, User $user = null ) {
        return self::userCanBitfield( $this->getVisibility(), $field, $user );
    }

    public static function userCanBitfield( $bitfield, $field, User $user = null,
        Title $title = null
    ) {
        global $wgUser;

        if ( !$user ) {
            $user = $wgUser;
        }

        return RevisionRecord::userCanBitfield( $bitfield, $field, $user, $title );
    }

    static function getTimestampFromId( $title, $id, $flags = 0 ) {
        return self::getRevisionStore()->getTimestampFromId( $title, $id, $flags );
    }

    static function countByPageId( $db, $id ) {
        return self::getRevisionStore()->countRevisionsByPageId( $db, $id );
    }

    static function countByTitle( $db, $title ) {
        return self::getRevisionStore()->countRevisionsByTitle( $db, $title );
    }

    public static function userWasLastToEdit( $db, $pageId, $userId, $since ) {
        if ( is_int( $db ) ) {
            $db = wfGetDB( $db );
        }

        return self::getRevisionStore()->userWasLastToEdit( $db, $pageId, $userId, $since );
    }

    public static function newKnownCurrent( IDatabase $db, $pageIdOrTitle, $revId = 0 ) {
        $title = $pageIdOrTitle instanceof Title
            ? $pageIdOrTitle
            : Title::newFromID( $pageIdOrTitle );

        if ( !$title ) {
            return false;
        }

        $record = self::getRevisionLookup()->getKnownCurrentRevision( $title, $revId );
        return $record ? new Revision( $record ) : false;
    }
}