Handle database storage of comments such as edit summaries and log reasons. More...

Public Member Functions
	__construct (Language $lang)

	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 (IReadableDatabase $db, $key, $row=null, $fallback=false)
	Extract the comment from a row, with legacy lookups. More...

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

	getJoin ( $key)
	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...

Static Public Member Functions
static	hash ( $text, $data)
	Hashing function for comment storage. More...

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

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

Detailed Description

Handle database storage of comments such as edit summaries and log reasons.

Since: 1.30

Definition at line 51 of file CommentStore.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\CommentStore\CommentStore::__construct ( Language $lang )

Parameters

Language $lang Language to use for comment truncation. Defaults to content language.

Definition at line 76 of file CommentStore.php.

Member Function Documentation

◆ createComment()

MediaWiki\CommentStore\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 300 of file CommentStore.php.

References FormatJson\ALL_OK, FormatJson\encode(), MediaWiki\CommentStore\CommentStore\hash(), Wikimedia\Rdbms\IDatabase\insertId(), MediaWiki\CommentStore\CommentStore\MAX_DATA_LENGTH, Wikimedia\Rdbms\IDatabase\newInsertQueryBuilder(), Wikimedia\Rdbms\IReadableDatabase\newSelectQueryBuilder(), MediaWiki\CommentStore\CommentStoreComment\newUnsavedComment(), and true.

Referenced by MediaWiki\CommentStore\CommentStore\insert().

◆ getComment()

MediaWiki\CommentStore\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 (required since 1.35)

Parameters

string	$key	A key such as "rev_comment" identifying the comment field being fetched.
stdClass \| 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 243 of file CommentStore.php.

References $fallback.

◆ getCommentLegacy()

MediaWiki\CommentStore\CommentStore::getCommentLegacy	(	IReadableDatabase	$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 (required since 1.35)

Parameters

IReadableDatabase	$db	Database handle to use for lookup
string	$key	A key such as "rev_comment" identifying the comment field being fetched.
stdClass \| 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 271 of file CommentStore.php.

References $fallback.

◆ getFields()

MediaWiki\CommentStore\CommentStore::getFields ( $key )

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 (required since 1.35)

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

◆ getJoin()

MediaWiki\CommentStore\CommentStore::getJoin ( $key )

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 (required since 1.35)

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() or SelectQueryBuilder::tables
fields: (string[]) to include in the $vars to IDatabase->select() or SelectQueryBuilder::fields
joins: (array) to include in the $join_conds to IDatabase->select() or SelectQueryBuilder::joinConds All tables, fields, and joins are aliased, so + is safe to use.

-taint none

Definition at line 118 of file CommentStore.php.

◆ hash()

static MediaWiki\CommentStore\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 414 of file CommentStore.php.

Referenced by MediaWiki\CommentStore\CommentStore\createComment().

◆ insert()

MediaWiki\CommentStore\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 (required since 1.35)

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; -taint none

Definition at line 360 of file CommentStore.php.

References MediaWiki\CommentStore\CommentStore\createComment().

Member Data Documentation

◆ COMMENT_CHARACTER_LIMIT

const MediaWiki\CommentStore\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_DATA_LENGTH / 4 ).

Definition at line 57 of file CommentStore.php.

Referenced by MediaWiki\Specials\SpecialBlock\getFormFields(), MediaWiki\Specials\SpecialChangeContentModel\getFormFields(), MediaWiki\Specials\SpecialUserRights\showEditUserGroupsForm(), MediaWiki\Specials\SpecialMovePage\showForm(), MediaWiki\Specials\SpecialEditTags\showForm(), MediaWiki\Specials\SpecialRevisionDelete\showForm(), and MediaWiki\Specials\SpecialUndelete\showHistory().

◆ MAX_DATA_LENGTH

const MediaWiki\CommentStore\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 64 of file CommentStore.php.

Referenced by MediaWiki\CommentStore\CommentStore\createComment().

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

includes/CommentStore/CommentStore.php

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ createComment()

◆ getComment()

◆ getCommentLegacy()

◆ getFields()

◆ getJoin()

◆ hash()

◆ insert()

Member Data Documentation

◆ COMMENT_CHARACTER_LIMIT

◆ MAX_DATA_LENGTH