CommentStore handles storage of comments (edit summaries, log reasons, etc) in the database. More...

Collaboration diagram for CommentStore:

[legend]

Public Member Functions
	__construct (Language $lang, $migrationStage)

	createComment (IDatabase $dbw, $comment, array $data=null)
	Create a new CommentStoreComment, inserting it into the database if necessary.

	getComment ( $key, $row=null, $fallback=false)
	Extract the comment from a row.

	getCommentLegacy (IDatabase $db, $key, $row=null, $fallback=false)
	Extract the comment from a row, with legacy lookups.

	getFields ( $key=null)
	Get SELECT fields for the comment key.

	getJoin ( $key=null)
	Get SELECT fields and joins for the comment key.

	insert (IDatabase $dbw, $key, $comment=null, $data=null)
	Insert a comment in preparation for a row that references it.

	insertWithTempTable (IDatabase $dbw, $key, $comment=null, $data=null)
	Insert a comment in a temporary table in preparation for a row that references it.

Static Public Member Functions
static	getStore ()

static	hash ( $text, $data)
	Hashing function for comment storage.

static	newKey ( $key)
	Static constructor for easier chaining.

Public Attributes
const	COMMENT_CHARACTER_LIMIT = 500
	Maximum length of a comment in UTF-8 characters.

const	MAX_COMMENT_LENGTH = 65535
	Maximum length of a comment in bytes.

const	MAX_DATA_LENGTH = 65535
	Maximum length of serialized data in bytes.

Static Protected Member Functions
static	decodeMessage ( $data)
	Decode a message that was encoded by self::encodeMessage()

static	encodeMessage (Message $msg)
	Encode a Message as a PHP data structure.

Protected Attributes
array[]	$joinCache = []
	Cache for `self::getJoin()`

string null	$key = null

Language	$lang
	Language to use for comment truncation.

int	$stage
	One of the MIGRATION_* constants.

Static Protected Attributes
static array	$formerTempTables = []
	Fields that formerly used $tempTables Key is '$key', value is the MediaWiki version in which it was removed from $tempTables.

static array	$tempTables
	Define fields that use temporary tables for transitional purposes Keys are '$key', values are arrays with four fields:

Private Member Functions
	getCommentInternal (IDatabase $db=null, $key, $row, $fallback=false)
	Extract the comment from a row.

	getKey ( $methodKey=null)
	Compat method allowing use of self::newKey until removed.

	insertInternal (IDatabase $dbw, $key, $comment, $data)
	Implementation for `self::insert()` and `self::insertWithTempTable()`

Detailed Description

CommentStore handles storage of comments (edit summaries, log reasons, etc) in the database.

Since: 1.30

Definition at line 31 of file CommentStore.php.

Constructor & Destructor Documentation

◆ __construct()

CommentStore::__construct	(	Language	$lang,
			$migrationStage )

Parameters

Language	$lang	Language to use for comment truncation. Defaults to $wgContLang.
int	$migrationStage	One of the MIGRATION_* constants

Definition at line 104 of file CommentStore.php.

References $lang.

Member Function Documentation

◆ createComment()

CommentStore::createComment	(	IDatabase	$dbw,
			$comment,
		array	$data = null )

Create a new CommentStoreComment, inserting it into the database if necessary.

If a comment is going to be passed to self::insert() or the like multiple times, it will be more efficient to pass a CommentStoreComment once rather than making self::insert() do it every time through.

Note: When passing a CommentStoreComment, this may set $comment->id if it's not already set. If $comment->id is already set, it will not be verified that the specified comment actually exists or that it corresponds to the comment text, message, and/or data in the CommentStoreComment.

Parameters

IDatabase	$dbw	Database handle to insert on. Unused if `$comment` is a CommentStoreComment and `$comment->id` is set.
string \| Message \| CommentStoreComment	$comment	Comment text or Message object, or a CommentStoreComment.
array \| null	$data	Structured data to store. Keys beginning with '_' are reserved. Ignored if $comment is a CommentStoreComment.

Returns: CommentStoreComment

Definition at line 457 of file CommentStore.php.

References Wikimedia\Rdbms\IDatabase\insert(), Wikimedia\Rdbms\IDatabase\insertId(), MIGRATION_OLD, Wikimedia\Rdbms\IDatabase\selectField(), true, and wfMessage().

Referenced by insertInternal().

◆ decodeMessage()

static CommentStore::decodeMessage ( $data )

staticprotected

Decode a message that was encoded by self::encodeMessage()

Parameters

array $data

Returns: Message

Definition at line 668 of file CommentStore.php.

References $key, and array().

◆ encodeMessage()

static CommentStore::encodeMessage ( Message $msg )

staticprotected

Encode a Message as a PHP data structure.

Parameters

Message $msg

Returns: array

Definition at line 649 of file CommentStore.php.

References $key, and $params.

◆ getComment()

CommentStore::getComment	(	$key,
		$row = null,
		$fallback = false )

Extract the comment from a row.

Use self::getJoin() to ensure the row contains the needed data.

If you need to fake a comment in a row for some reason, set fields {$key}_text (string) and {$key}_data (JSON string or null).

Since: 1.30; 1.31 Method signature changed, $key parameter added (with deprecated back compat)

Parameters

string	$key	A key such as "rev_comment" identifying the comment field being fetched.
object \| array	$row	Result row.
bool	$fallback	If true, fall back as well as possible instead of throwing an exception.

Returns: CommentStoreComment

Definition at line 388 of file CommentStore.php.

References $fallback, $key, getCommentInternal(), getKey(), and key.

◆ getCommentInternal()

CommentStore::getCommentInternal	(	IDatabase	$db = null,
			$key,
			$row,
			$fallback = false )

private

Extract the comment from a row.

Shared implementation for getComment() and getCommentLegacy()

Parameters

IDatabase \| null	$db	Database handle for getCommentLegacy(), or null for getComment()
string	$key	A key such as "rev_comment" identifying the comment field being fetched.
object \| array	$row
bool	$fallback

Returns: CommentStoreComment

Definition at line 261 of file CommentStore.php.

References $fallback, $key, $t, array(), MIGRATION_NEW, MIGRATION_OLD, object, and wfLogWarning().

Referenced by getComment(), and getCommentLegacy().

◆ getCommentLegacy()

CommentStore::getCommentLegacy	(	IDatabase	$db,
			$key,
			$row = null,
			$fallback = false )

Extract the comment from a row, with legacy lookups.

If $row might have been generated using self::getFields() rather than self::getJoin(), use this. Prefer self::getComment() if you know callers used self::getJoin() for the row fetch.

If you need to fake a comment in a row for some reason, set fields {$key}_text (string) and {$key}_data (JSON string or null).

Since: 1.30; 1.31 Method signature changed, $key parameter added (with deprecated back compat)

Parameters

IDatabase	$db	Database handle to use for lookup
string	$key	A key such as "rev_comment" identifying the comment field being fetched.
object \| array	$row	Result row.
bool	$fallback	If true, fall back as well as possible instead of throwing an exception.

Returns: CommentStoreComment

Definition at line 422 of file CommentStore.php.

References $fallback, $key, getCommentInternal(), getKey(), and key.

◆ getFields()

CommentStore::getFields ( $key = null )

Get SELECT fields for the comment key.

Each resulting row should be passed to self::getCommentLegacy() to get the actual comment.

Note: Use of this method may require a subsequent database query to actually fetch the comment. If possible, use self::getJoin() instead.

Since: 1.30; 1.31 Method signature changed, $key parameter added (with deprecated back compat)

Parameters

string $key A key such as "rev_comment" identifying the comment field being fetched.

Returns: string[] to include in the $vars to IDatabase->select(). All fields are aliased, so + is safe to use.

Definition at line 166 of file CommentStore.php.

References $key, getKey(), MIGRATION_NEW, and MIGRATION_OLD.

◆ getJoin()

CommentStore::getJoin ( $key = null )

Get SELECT fields and joins for the comment key.

Each resulting row should be passed to self::getComment() to get the actual comment.

Since: 1.30; 1.31 Method signature changed, $key parameter added (with deprecated back compat)

Parameters

string $key A key such as "rev_comment" identifying the comment field being fetched.

Returns

array With three keys:

tables: (string[]) to include in the $table to IDatabase->select()
fields: (string[]) to include in the $vars to IDatabase->select()
joins: (array) to include in the $join_conds to IDatabase->select() All tables, fields, and joins are aliased, so + is safe to use.

Definition at line 202 of file CommentStore.php.

References $key, $t, $tables, getKey(), MIGRATION_NEW, and MIGRATION_OLD.

◆ getKey()

CommentStore::getKey ( $methodKey = null )

private

Compat method allowing use of self::newKey until removed.

Parameters

string | null $methodKey

Exceptions

InvalidArgumentException

Returns: string

Definition at line 140 of file CommentStore.php.

References $key, and key.

Referenced by getComment(), getCommentLegacy(), getFields(), getJoin(), and insertWithTempTable().

◆ getStore()

static CommentStore::getStore ( )

static

Since: 1.31

Deprecated: in 1.31 Use DI to inject a CommentStore instance into your class.

Returns: CommentStore

Definition at line 130 of file CommentStore.php.

◆ hash()

static CommentStore::hash	(		$text,
			$data )

static

Hashing function for comment storage.

Parameters

string	$text	Comment text
string \| null	$data	Comment data

Returns: int 32-bit signed integer

Definition at line 687 of file CommentStore.php.

◆ insert()

CommentStore::insert	(	IDatabase	$dbw,
			$key,
			$comment = null,
			$data = null )

Insert a comment in preparation for a row that references it.

Note: It's recommended to include both the call to this method and the row insert in the same transaction.

Since: 1.30; 1.31 Method signature changed, $key parameter added (with deprecated back compat)

Parameters

IDatabase	$dbw	Database handle to insert on
string	$key	A key such as "rev_comment" identifying the comment field being fetched.
string \| Message \| CommentStoreComment	$comment	As for `self::createComment()`
array \| null	$data	As for `self::createComment()`

Returns: array Fields for the insert or update

Definition at line 574 of file CommentStore.php.

References $key, insertInternal(), key, and list.

◆ insertInternal()

CommentStore::insertInternal	(	IDatabase	$dbw,
			$key,
			$comment,
			$data )

private

Implementation for self::insert() and self::insertWithTempTable()

Parameters

IDatabase	$dbw
string	$key	A key such as "rev_comment" identifying the comment field being fetched.
string \| Message \| CommentStoreComment	$comment
array \| null	$data

Returns: array [ array $fields, callable $callback ]

Definition at line 526 of file CommentStore.php.

References $key, $t, createComment(), Wikimedia\Rdbms\IDatabase\insert(), and MIGRATION_WRITE_BOTH.

Referenced by insert(), and insertWithTempTable().

◆ insertWithTempTable()

CommentStore::insertWithTempTable	(	IDatabase	$dbw,
			$key,
			$comment = null,
			$data = null )

Insert a comment in a temporary table in preparation for a row that references it.

This is currently needed for "rev_comment" and "img_description". In the future that requirement will be removed.

Note: It's recommended to include both the call to this method and the row insert in the same transaction.

Since: 1.30; 1.31 Method signature changed, $key parameter added (with deprecated back compat)

Parameters

IDatabase	$dbw	Database handle to insert on
string	$key	A key such as "rev_comment" identifying the comment field being fetched.
string \| Message \| CommentStoreComment	$comment	As for `self::createComment()`
array \| null	$data	As for `self::createComment()`

Returns

array Two values:

array Fields for the insert or update
callable Function to call when the primary key of the row being inserted/updated is known. Pass it that primary key.

Definition at line 616 of file CommentStore.php.

References $key, getKey(), insertInternal(), key, list, and wfDeprecated().

◆ newKey()

static CommentStore::newKey ( $key )

static

Static constructor for easier chaining.

Deprecated: in 1.31 Should not be constructed with a $key, use CommentStore::getStore

Parameters

string $key A key such as "rev_comment" identifying the comment field being fetched.

Returns: CommentStore

Definition at line 116 of file CommentStore.php.

References $key, $wgCommentTableSchemaMigrationStage, and $wgContLang.

Member Data Documentation

◆ $formerTempTables

array CommentStore::$formerTempTables = []

staticprotected

Fields that formerly used $tempTables Key is '$key', value is the MediaWiki version in which it was removed from $tempTables.

Definition at line 81 of file CommentStore.php.

◆ $joinCache

array [] CommentStore::$joinCache = []

protected

Cache for self::getJoin()

Definition at line 94 of file CommentStore.php.

◆ $key

string null CommentStore::$key = null

protected

Since: 1.30

Deprecated: in 1.31

Definition at line 88 of file CommentStore.php.

Referenced by decodeMessage(), encodeMessage(), getComment(), getCommentInternal(), getCommentLegacy(), getFields(), getJoin(), getKey(), insert(), insertInternal(), insertWithTempTable(), and newKey().

◆ $lang

Language CommentStore::$lang

protected

Language to use for comment truncation.

Definition at line 97 of file CommentStore.php.

◆ $stage

int CommentStore::$stage

protected

One of the MIGRATION_* constants.

Definition at line 91 of file CommentStore.php.

◆ $tempTables

array CommentStore::$tempTables

staticprotected

Initial value:

= [
        'rev_comment' => [
            'table' => 'revision_comment_temp',
            'pk' => 'revcomment_rev',
            'field' => 'revcomment_comment_id',
            'joinPK' => 'rev_id',
        ],
        'img_description' => [
            'table' => 'image_comment_temp',
            'pk' => 'imgcomment_name',
            'field' => 'imgcomment_description_id',
            'joinPK' => 'img_name',
        ],
    ]

Define fields that use temporary tables for transitional purposes Keys are '$key', values are arrays with four fields:

table: Temporary table name
pk: Temporary table column referring to the main table's primary key
field: Temporary table column referring comment.comment_id
joinPK: Main table's primary key

Definition at line 61 of file CommentStore.php.

◆ COMMENT_CHARACTER_LIMIT

const CommentStore::COMMENT_CHARACTER_LIMIT = 500

Maximum length of a comment in UTF-8 characters.

Longer comments will be truncated.

Note: This must be at least 255 and not greater than floor( MAX_COMMENT_LENGTH / 4 ).

Definition at line 37 of file CommentStore.php.

◆ MAX_COMMENT_LENGTH

const CommentStore::MAX_COMMENT_LENGTH = 65535

Maximum length of a comment in bytes.

Longer comments will be truncated.

Note: This value is determined by the size of the underlying database field, currently BLOB in MySQL/MariaDB.

Definition at line 44 of file CommentStore.php.

◆ MAX_DATA_LENGTH

const CommentStore::MAX_DATA_LENGTH = 65535

Maximum length of serialized data in bytes.

Longer data will result in an exception.

Note: This value is determined by the size of the underlying database field, currently BLOB in MySQL/MariaDB.

Definition at line 51 of file CommentStore.php.

The documentation for this class was generated from the following file:

includes/CommentStore.php

Public Member Functions

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ createComment()

◆ decodeMessage()

◆ encodeMessage()

◆ getComment()

◆ getCommentInternal()

◆ getCommentLegacy()

◆ getFields()

◆ getJoin()

◆ getKey()

◆ getStore()

◆ hash()

◆ insert()

◆ insertInternal()

◆ insertWithTempTable()

◆ newKey()

Member Data Documentation

◆ $formerTempTables

◆ $joinCache

◆ $key

◆ $lang

◆ $stage

◆ $tempTables

◆ COMMENT_CHARACTER_LIMIT

◆ MAX_COMMENT_LENGTH

◆ MAX_DATA_LENGTH