CommentStore.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
use Wikimedia\Rdbms\IDatabase;

class CommentStore {

    const COMMENT_CHARACTER_LIMIT = 500;

    const MAX_COMMENT_LENGTH = 65535;

    const MAX_DATA_LENGTH = 65535;

    protected $tempTables = [
        'rev_comment' => [
            'table' => 'revision_comment_temp',
            'pk' => 'revcomment_rev',
            'field' => 'revcomment_comment_id',
            'joinPK' => 'rev_id',
            'stage' => MIGRATION_OLD,
            'deprecatedIn' => null,
        ],
        'img_description' => [
            'stage' => MIGRATION_NEW,
            'deprecatedIn' => '1.32',
        ],
    ];

    protected $key = null;

    protected $stage;

    protected $joinCache = [];

    protected $lang;

    public function __construct( Language $lang, $stage ) {
        if ( ( $stage & SCHEMA_COMPAT_WRITE_BOTH ) === 0 ) {
            throw new InvalidArgumentException( '$stage must include a write mode' );
        }
        if ( ( $stage & SCHEMA_COMPAT_READ_BOTH ) === 0 ) {
            throw new InvalidArgumentException( '$stage must include a read mode' );
        }

        $this->stage = $stage;
        $this->lang = $lang;
    }

    public static function newKey( $key ) {
        wfDeprecated( __METHOD__, '1.31' );
        $store = new CommentStore(
            MediaWikiServices::getInstance()->getContentLanguage(), MIGRATION_NEW
        );
        $store->key = $key;
        return $store;
    }

    public static function getStore() {
        return MediaWikiServices::getInstance()->getCommentStore();
    }

    private function getKey( $methodKey = null ) {
        $key = $this->key ?? $methodKey;
        if ( $key === null ) {
            // @codeCoverageIgnoreStart
            throw new InvalidArgumentException( '$key should not be null' );
            // @codeCoverageIgnoreEnd
        }
        return $key;
    }

    public function getFields( $key = null ) {
        $key = $this->getKey( $key );
        $fields = [];
        if ( ( $this->stage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_OLD ) {
            $fields["{$key}_text"] = $key;
            $fields["{$key}_data"] = 'NULL';
            $fields["{$key}_cid"] = 'NULL';
        } else { // READ_BOTH or READ_NEW
            if ( $this->stage & SCHEMA_COMPAT_READ_OLD ) {
                $fields["{$key}_old"] = $key;
            }

            $tempTableStage = isset( $this->tempTables[$key] )
                ? $this->tempTables[$key]['stage'] : MIGRATION_NEW;
            if ( $tempTableStage & SCHEMA_COMPAT_READ_OLD ) {
                $fields["{$key}_pk"] = $this->tempTables[$key]['joinPK'];
            }
            if ( $tempTableStage & SCHEMA_COMPAT_READ_NEW ) {
                $fields["{$key}_id"] = "{$key}_id";
            }
        }
        return $fields;
    }

    public function getJoin( $key = null ) {
        $key = $this->getKey( $key );
        if ( !array_key_exists( $key, $this->joinCache ) ) {
            $tables = [];
            $fields = [];
            $joins = [];

            if ( ( $this->stage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_OLD ) {
                $fields["{$key}_text"] = $key;
                $fields["{$key}_data"] = 'NULL';
                $fields["{$key}_cid"] = 'NULL';
            } else { // READ_BOTH or READ_NEW
                $join = ( $this->stage & SCHEMA_COMPAT_READ_OLD ) ? 'LEFT JOIN' : 'JOIN';

                $tempTableStage = isset( $this->tempTables[$key] )
                    ? $this->tempTables[$key]['stage'] : MIGRATION_NEW;
                if ( $tempTableStage & SCHEMA_COMPAT_READ_OLD ) {
                    $t = $this->tempTables[$key];
                    $alias = "temp_$key";
                    $tables[$alias] = $t['table'];
                    $joins[$alias] = [ $join, "{$alias}.{$t['pk']} = {$t['joinPK']}" ];
                    if ( ( $tempTableStage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_OLD ) {
                        $joinField = "{$alias}.{$t['field']}";
                    } else {
                        // Nothing hits this code path for now, but will in the future when we set
                        // $this->tempTables['rev_comment']['stage'] to MIGRATION_WRITE_NEW while
                        // merging revision_comment_temp into revision.
                        // @codeCoverageIgnoreStart
                        $joins[$alias][0] = 'LEFT JOIN';
                        $joinField = "(CASE WHEN {$key}_id != 0 THEN {$key}_id ELSE {$alias}.{$t['field']} END)";
                        throw new LogicException( 'Nothing should reach this code path at this time' );
                        // @codeCoverageIgnoreEnd
                    }
                } else {
                    $joinField = "{$key}_id";
                }

                $alias = "comment_$key";
                $tables[$alias] = 'comment';
                $joins[$alias] = [ $join, "{$alias}.comment_id = {$joinField}" ];

                if ( ( $this->stage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_NEW ) {
                    $fields["{$key}_text"] = "{$alias}.comment_text";
                } else {
                    $fields["{$key}_text"] = "COALESCE( {$alias}.comment_text, $key )";
                }
                $fields["{$key}_data"] = "{$alias}.comment_data";
                $fields["{$key}_cid"] = "{$alias}.comment_id";
            }

            $this->joinCache[$key] = [
                'tables' => $tables,
                'fields' => $fields,
                'joins' => $joins,
            ];
        }

        return $this->joinCache[$key];
    }

    private function getCommentInternal( ?IDatabase $db, $key, $row, $fallback = false ) {
        $row = (array)$row;
        if ( array_key_exists( "{$key}_text", $row ) && array_key_exists( "{$key}_data", $row ) ) {
            $cid = $row["{$key}_cid"] ?? null;
            $text = $row["{$key}_text"];
            $data = $row["{$key}_data"];
        } elseif ( ( $this->stage & SCHEMA_COMPAT_READ_BOTH ) === SCHEMA_COMPAT_READ_OLD ) {
            $cid = null;
            if ( $fallback && isset( $row[$key] ) ) {
                wfLogWarning( "Using deprecated fallback handling for comment $key" );
                $text = $row[$key];
            } else {
                wfLogWarning(
                    "Missing {$key}_text and {$key}_data fields in row with MIGRATION_OLD / READ_OLD"
                );
                $text = '';
            }
            $data = null;
        } else {
            $tempTableStage = isset( $this->tempTables[$key] )
                ? $this->tempTables[$key]['stage'] : MIGRATION_NEW;
            $row2 = null;
            if ( ( $tempTableStage & SCHEMA_COMPAT_READ_NEW ) && array_key_exists( "{$key}_id", $row ) ) {
                if ( !$db ) {
                    throw new InvalidArgumentException(
                        "\$row does not contain fields needed for comment $key and getComment(), but "
                        . "does have fields for getCommentLegacy()"
                    );
                }
                $id = $row["{$key}_id"];
                $row2 = $db->selectRow(
                    'comment',
                    [ 'comment_id', 'comment_text', 'comment_data' ],
                    [ 'comment_id' => $id ],
                    __METHOD__
                );
            }
            if ( !$row2 && ( $tempTableStage & SCHEMA_COMPAT_READ_OLD ) &&
                array_key_exists( "{$key}_pk", $row )
            ) {
                if ( !$db ) {
                    throw new InvalidArgumentException(
                        "\$row does not contain fields needed for comment $key and getComment(), but "
                        . "does have fields for getCommentLegacy()"
                    );
                }
                $t = $this->tempTables[$key];
                $id = $row["{$key}_pk"];
                $row2 = $db->selectRow(
                    [ $t['table'], 'comment' ],
                    [ 'comment_id', 'comment_text', 'comment_data' ],
                    [ $t['pk'] => $id ],
                    __METHOD__,
                    [],
                    [ 'comment' => [ 'JOIN', [ "comment_id = {$t['field']}" ] ] ]
                );
            }
            if ( $row2 === null && $fallback && isset( $row[$key] ) ) {
                wfLogWarning( "Using deprecated fallback handling for comment $key" );
                $row2 = (object)[ 'comment_text' => $row[$key], 'comment_data' => null ];
            }
            if ( $row2 === null ) {
                throw new InvalidArgumentException( "\$row does not contain fields needed for comment $key" );
            }

            if ( $row2 ) {
                $cid = $row2->comment_id;
                $text = $row2->comment_text;
                $data = $row2->comment_data;
            } elseif ( ( $this->stage & SCHEMA_COMPAT_READ_OLD ) &&
                array_key_exists( "{$key}_old", $row )
            ) {
                $cid = null;
                $text = $row["{$key}_old"];
                $data = null;
            } else {
                // @codeCoverageIgnoreStart
                wfLogWarning( "Missing comment row for $key, id=$id" );
                $cid = null;
                $text = '';
                $data = null;
                // @codeCoverageIgnoreEnd
            }
        }

        $msg = null;
        if ( $data !== null ) {
            $data = FormatJson::decode( $data, true );
            if ( !is_array( $data ) ) {
                // @codeCoverageIgnoreStart
                wfLogWarning( "Invalid JSON object in comment: $data" );
                $data = null;
                // @codeCoverageIgnoreEnd
            } else {
                if ( isset( $data['_message'] ) ) {
                    $msg = self::decodeMessage( $data['_message'] )
                        ->setInterfaceMessageFlag( true );
                }
                if ( !empty( $data['_null'] ) ) {
                    $data = null;
                } else {
                    foreach ( $data as $k => $v ) {
                        if ( substr( $k, 0, 1 ) === '_' ) {
                            unset( $data[$k] );
                        }
                    }
                }
            }
        }

        return new CommentStoreComment( $cid, $text, $msg, $data );
    }

    public function getComment( $key, $row = null, $fallback = false ) {
        // Compat for method sig change in 1.31 (introduction of $key)
        if ( $this->key !== null ) {
            $fallback = $row;
            $row = $key;
            $key = $this->getKey();
        }
        if ( $row === null ) {
            // @codeCoverageIgnoreStart
            throw new InvalidArgumentException( '$row must not be null' );
            // @codeCoverageIgnoreEnd
        }
        return $this->getCommentInternal( null, $key, $row, $fallback );
    }

    public function getCommentLegacy( IDatabase $db, $key, $row = null, $fallback = false ) {
        // Compat for method sig change in 1.31 (introduction of $key)
        if ( $this->key !== null ) {
            $fallback = $row;
            $row = $key;
            $key = $this->getKey();
        }
        if ( $row === null ) {
            // @codeCoverageIgnoreStart
            throw new InvalidArgumentException( '$row must not be null' );
            // @codeCoverageIgnoreEnd
        }
        return $this->getCommentInternal( $db, $key, $row, $fallback );
    }

    public function createComment( IDatabase $dbw, $comment, array $data = null ) {
        $comment = CommentStoreComment::newUnsavedComment( $comment, $data );

        # Truncate comment in a Unicode-sensitive manner
        $comment->text = $this->lang->truncateForVisual( $comment->text, self::COMMENT_CHARACTER_LIMIT );

        if ( ( $this->stage & SCHEMA_COMPAT_WRITE_NEW ) && !$comment->id ) {
            $dbData = $comment->data;
            if ( !$comment->message instanceof RawMessage ) {
                if ( $dbData === null ) {
                    $dbData = [ '_null' => true ];
                }
                $dbData['_message'] = self::encodeMessage( $comment->message );
            }
            if ( $dbData !== null ) {
                $dbData = FormatJson::encode( (object)$dbData, false, FormatJson::ALL_OK );
                $len = strlen( $dbData );
                if ( $len > self::MAX_DATA_LENGTH ) {
                    $max = self::MAX_DATA_LENGTH;
                    throw new OverflowException( "Comment data is too long ($len bytes, maximum is $max)" );
                }
            }

            $hash = self::hash( $comment->text, $dbData );
            $comment->id = $dbw->selectField(
                'comment',
                'comment_id',
                [
                    'comment_hash' => $hash,
                    'comment_text' => $comment->text,
                    'comment_data' => $dbData,
                ],
                __METHOD__
            );
            if ( !$comment->id ) {
                $dbw->insert(
                    'comment',
                    [
                        'comment_hash' => $hash,
                        'comment_text' => $comment->text,
                        'comment_data' => $dbData,
                    ],
                    __METHOD__
                );
                $comment->id = $dbw->insertId();
            }
        }

        return $comment;
    }

    private function insertInternal( IDatabase $dbw, $key, $comment, $data ) {
        $fields = [];
        $callback = null;

        $comment = $this->createComment( $dbw, $comment, $data );

        if ( $this->stage & SCHEMA_COMPAT_WRITE_OLD ) {
            $fields[$key] = $this->lang->truncateForDatabase( $comment->text, 255 );
        }

        if ( $this->stage & SCHEMA_COMPAT_WRITE_NEW ) {
            $tempTableStage = isset( $this->tempTables[$key] )
                ? $this->tempTables[$key]['stage'] : MIGRATION_NEW;
            if ( $tempTableStage & SCHEMA_COMPAT_WRITE_OLD ) {
                $t = $this->tempTables[$key];
                $func = __METHOD__;
                $commentId = $comment->id;
                $callback = function ( $id ) use ( $dbw, $commentId, $t, $func ) {
                    $dbw->insert(
                        $t['table'],
                        [
                            $t['pk'] => $id,
                            $t['field'] => $commentId,
                        ],
                        $func
                    );
                };
            }
            if ( $tempTableStage & SCHEMA_COMPAT_WRITE_NEW ) {
                $fields["{$key}_id"] = $comment->id;
            }
        }

        return [ $fields, $callback ];
    }

    public function insert( IDatabase $dbw, $key, $comment = null, $data = null ) {
        // Compat for method sig change in 1.31 (introduction of $key)
        if ( $this->key !== null ) {
            $data = $comment;
            $comment = $key;
            $key = $this->key;
        }
        if ( $comment === null ) {
            // @codeCoverageIgnoreStart
            throw new InvalidArgumentException( '$comment can not be null' );
            // @codeCoverageIgnoreEnd
        }

        $tempTableStage = isset( $this->tempTables[$key] )
            ? $this->tempTables[$key]['stage'] : MIGRATION_NEW;
        if ( $tempTableStage & SCHEMA_COMPAT_WRITE_OLD ) {
            throw new InvalidArgumentException( "Must use insertWithTempTable() for $key" );
        }

        list( $fields ) = $this->insertInternal( $dbw, $key, $comment, $data );
        return $fields;
    }

    public function insertWithTempTable( IDatabase $dbw, $key, $comment = null, $data = null ) {
        // Compat for method sig change in 1.31 (introduction of $key)
        if ( $this->key !== null ) {
            $data = $comment;
            $comment = $key;
            $key = $this->getKey();
        }
        if ( $comment === null ) {
            // @codeCoverageIgnoreStart
            throw new InvalidArgumentException( '$comment can not be null' );
            // @codeCoverageIgnoreEnd
        }

        if ( !isset( $this->tempTables[$key] ) ) {
            throw new InvalidArgumentException( "Must use insert() for $key" );
        } elseif ( isset( $this->tempTables[$key]['deprecatedIn'] ) ) {
            wfDeprecated( __METHOD__ . " for $key", $this->tempTables[$key]['deprecatedIn'] );
        }

        list( $fields, $callback ) = $this->insertInternal( $dbw, $key, $comment, $data );
        if ( !$callback ) {
            $callback = function () {
                // Do nothing.
            };
        }
        return [ $fields, $callback ];
    }

    protected static function encodeMessage( Message $msg ) {
        $key = count( $msg->getKeysToTry() ) > 1 ? $msg->getKeysToTry() : $msg->getKey();
        $params = $msg->getParams();
        foreach ( $params as &$param ) {
            if ( $param instanceof Message ) {
                $param = [
                    'message' => self::encodeMessage( $param )
                ];
            }
        }
        array_unshift( $params, $key );
        return $params;
    }

    protected static function decodeMessage( $data ) {
        $key = array_shift( $data );
        foreach ( $data as &$param ) {
            if ( is_object( $param ) ) {
                $param = (array)$param;
            }
            if ( is_array( $param ) && count( $param ) === 1 && isset( $param['message'] ) ) {
                $param = self::decodeMessage( $param['message'] );
            }
        }
        return new Message( $key, $data );
    }

    public static function hash( $text, $data ) {
        $hash = crc32( $text ) ^ crc32( (string)$data );

        // 64-bit PHP returns an unsigned CRC, change it to signed for
        // insertion into the database.
        if ( $hash >= 0x80000000 ) {
            $hash |= -1 << 32;
        }

        return $hash;
    }

}