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. More...

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

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

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

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

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

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

Static Public Member Functions
static	getStore ()

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

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

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

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

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

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

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

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

string null	$key = null

Language	$lang
	Language to use for comment truncation. More...

int	$stage
	One of the MIGRATION_* constants. More...

array	$tempTables
	Define fields that use temporary tables for transitional purposes Keys are '$key', values are arrays with these possible fields: More...

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

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

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

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 content language.
int	$migrationStage	One of the MIGRATION_* constants

Definition at line 99 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 466 of file CommentStore.php.

References FormatJson\ALL_OK, FormatJson\encode(), encodeMessage(), hash(), Wikimedia\Rdbms\IDatabase\insert(), Wikimedia\Rdbms\IDatabase\insertId(), MAX_DATA_LENGTH, MIGRATION_OLD, CommentStoreComment\newUnsavedComment(), Wikimedia\Rdbms\IDatabase\selectField(), and true.

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 673 of file CommentStore.php.

References $key, array(), as, and captcha-old\count.

Referenced by getCommentInternal().

◆ encodeMessage()

static CommentStore::encodeMessage ( Message $msg )

staticprotected

Encode a Message as a PHP data structure.

Parameters

Message $msg

Returns: array

Definition at line 654 of file CommentStore.php.

References $key, $params, as, and captcha-old\count.

Referenced by createComment().

◆ 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 \| null	$row	Result row.
bool	$fallback	If true, fall back as well as possible instead of throwing an exception.

Returns: CommentStoreComment

Definition at line 397 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 273 of file CommentStore.php.

References $fallback, $key, $t, array(), as, FormatJson\decode(), decodeMessage(), 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 \| null	$row	Result row.
bool	$fallback	If true, fall back as well as possible instead of throwing an exception.

Returns: CommentStoreComment

Definition at line 431 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 | null $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 161 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 | null $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 201 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 135 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 125 of file CommentStore.php.

Referenced by WikiPage\archiveRevisions(), Orphans\checkOrphans(), RenameUserCleanup\checkRenameLog(), RevDelLogList\doQuery(), WikiPage\doUpdateRestrictions(), WikiExporter\dumpLogs(), ApiQueryBlocks\execute(), ApiQueryDeletedrevs\execute(), ApiQueryFilearchive\execute(), ApiQueryAllUsers\execute(), ApiQueryUserContribs\execute(), ApiQueryLogEvents\execute(), ApiQueryUsers\execute(), FeedUtils\formatDiff(), DeletedContribsPager\formatRevisionRow(), BlockListPager\formatValue(), ProtectedPagesPager\formatValue(), ImageListPager\formatValue(), RevDelLogItem\getApiData(), RecentChange\getAttribute(), Block\getAutoblockUpdateArray(), DatabaseLogEntry\getComment(), RCDatabaseLogEntry\getComment(), Block\getDatabaseArray(), RevDelLogItem\getHTML(), EditPage\getLastDelete(), IRCColourfulRCFeedFormatter\getLine(), DeletedContribsPager\getQueryInfo(), BlockListPager\getQueryInfo(), Block\getQueryInfo(), ProtectedPagesPager\getQueryInfo(), RecentChange\getQueryInfo(), ImageListPager\getQueryInfoReal(), DatabaseLogEntry\getSelectQueryData(), Title\getTitleProtectionInternal(), WikiRevision\importLogItem(), Block\initFromRow(), ManualLogEntry\insert(), RecentChange\loadFromRow(), RebuildRecentchanges\rebuildRecentChangesTablePass1(), RebuildRecentchanges\rebuildRecentChangesTablePass3(), SpecialNewpages\revisionFromRcResult(), ApiQueryProtectedTitles\run(), ApiQueryWatchlist\run(), ApiQueryRecentChanges\run(), RecentChange\save(), LogPage\saveContent(), Revision\selectArchiveFields(), Block\selectFields(), RecentChange\selectFields(), Revision\selectFields(), EditPage\showEditForm(), ApiQueryBase\showHiddenUsersAddBlockInfo(), CommentStoreTest\testGetStore(), XmlDumpWriter\writeLogItem(), and XmlDumpWriter\writeRevision().

◆ 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 692 of file CommentStore.php.

Referenced by createComment(), and MigrateComments\loadCommentIDs().

◆ 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 \| null	$comment	As for `self::createComment()`
array \| null	$data	As for `self::createComment()`

Returns: array Fields for the insert or update

Definition at line 577 of file CommentStore.php.

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

◆ 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(), MIGRATION_NEW, MIGRATION_WRITE_BOTH, and use.

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 \| null	$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 621 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 111 of file CommentStore.php.

References $key, $wgCommentTableSchemaMigrationStage, and wfDeprecated().

Referenced by CommentStoreTest\makeStoreWithKey(), and CommentStoreTest\testNewKey().

Member Data Documentation

◆ $joinCache

array [] CommentStore::$joinCache = []

protected

Cache for self::getJoin()

Definition at line 89 of file CommentStore.php.

◆ $key

string null CommentStore::$key = null

protected

Since: 1.30

Deprecated:: in 1.31

Definition at line 83 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 92 of file CommentStore.php.

Referenced by __construct().

◆ $stage

int CommentStore::$stage

protected

One of the MIGRATION_* constants.

Definition at line 86 of file CommentStore.php.

◆ $tempTables

array CommentStore::$tempTables

protected

Initial value:

= [
        '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',
        ],
    ]

Define fields that use temporary tables for transitional purposes Keys are '$key', values are arrays with these possible 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
stage: Migration stage
deprecatedIn: Version when using insertWithTempTable() was deprecated

Definition at line 63 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.

Referenced by ProtectionForm\buildForm(), Article\confirmDelete(), ResourceLoaderStartUpModule\getConfigSettings(), SpecialBlock\getFormFields(), McrUndoAction\getFormFields(), EditPage\getSummaryInputAttributes(), UserrightsPage\showEditUserGroupsForm(), MovePageForm\showForm(), SpecialEditTags\showForm(), FileDeleteForm\showForm(), SpecialRevisionDelete\showForm(), SpecialUndelete\showHistory(), and CommentStoreTest\testInsertTruncation().

◆ 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.

Referenced by createComment().

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

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

◆ $joinCache

◆ $key

◆ $lang

◆ $stage

◆ $tempTables

◆ COMMENT_CHARACTER_LIMIT

◆ MAX_COMMENT_LENGTH

◆ MAX_DATA_LENGTH