MediaWiki REL1_34
CommentStore Class Reference

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

Collaboration diagram for CommentStore:

Public Member Functions

 __construct (Language $lang, $stage)
 
 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, or an appropriate combination of SCHEMA_COMPAT_* constants.
 
array $tempTables
 Define fields that use temporary tables for transitional purposes Keys are '$key', values are arrays with these possible 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,
  $stage 
)
Parameters
Language$langLanguage to use for comment truncation. Defaults to content language.
int$stageOne of the MIGRATION_* constants, or an appropriate combination of SCHEMA_COMPAT_* constants. Always MIGRATION_NEW for MediaWiki core since 1.33.

Definition at line 106 of file CommentStore.php.

References $lang, SCHEMA_COMPAT_READ_BOTH, and SCHEMA_COMPAT_WRITE_BOTH.

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$dbwDatabase handle to insert on. Unused if $comment is a CommentStoreComment and $comment->id is set.
string | Message | CommentStoreComment$commentComment text or Message object, or a CommentStoreComment.
array | null$dataStructured data to store. Keys beginning with '_' are reserved. Ignored if $comment is a CommentStoreComment.
Returns
CommentStoreComment

Definition at line 486 of file CommentStore.php.

References Wikimedia\Rdbms\IDatabase\insert(), Wikimedia\Rdbms\IDatabase\insertId(), SCHEMA_COMPAT_WRITE_NEW, 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 693 of file CommentStore.php.

References $key.

◆ encodeMessage()

static CommentStore::encodeMessage ( Message  $msg)
staticprotected

Encode a Message as a PHP data structure.

Parameters
Message$msg
Returns
array

Definition at line 674 of file CommentStore.php.

References $key, Message\getKey(), Message\getKeysToTry(), and Message\getParams().

◆ 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$keyA key such as "rev_comment" identifying the comment field being fetched.
object | array | null$rowResult row.
bool$fallbackIf true, fall back as well as possible instead of throwing an exception.
Returns
CommentStoreComment

Definition at line 417 of file CommentStore.php.

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

◆ 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$dbDatabase handle for getCommentLegacy(), or null for getComment()
string$keyA key such as "rev_comment" identifying the comment field being fetched.
object | array$row
bool$fallback
Returns
CommentStoreComment

Definition at line 288 of file CommentStore.php.

References $fallback, $key, $t, MIGRATION_NEW, SCHEMA_COMPAT_READ_BOTH, SCHEMA_COMPAT_READ_NEW, SCHEMA_COMPAT_READ_OLD, 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$dbDatabase handle to use for lookup
string$keyA key such as "rev_comment" identifying the comment field being fetched.
object | array | null$rowResult row.
bool$fallbackIf true, fall back as well as possible instead of throwing an exception.
Returns
CommentStoreComment

Definition at line 451 of file CommentStore.php.

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

◆ 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$keyA 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 175 of file CommentStore.php.

References $key, getKey(), MIGRATION_NEW, SCHEMA_COMPAT_READ_BOTH, SCHEMA_COMPAT_READ_NEW, and SCHEMA_COMPAT_READ_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$keyA 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. -return array{tables:string[],fields:string[],joins:array}

Definition at line 216 of file CommentStore.php.

References $key, $t, getKey(), MIGRATION_NEW, SCHEMA_COMPAT_READ_BOTH, SCHEMA_COMPAT_READ_NEW, and SCHEMA_COMPAT_READ_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 149 of file CommentStore.php.

References $key.

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

◆ getStore()

static CommentStore::getStore ( )
static

◆ hash()

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

Hashing function for comment storage.

Parameters
string$textComment text
string | null$dataComment data
Returns
int 32-bit signed integer

Definition at line 712 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$dbwDatabase handle to insert on
string$keyA key such as "rev_comment" identifying the comment field being fetched.
string | Message | CommentStoreComment | null$commentAs for self::createComment()
array | null$dataAs for self::createComment()
Returns
array Fields for the insert or update

Definition at line 597 of file CommentStore.php.

References $key, insertInternal(), MIGRATION_NEW, and SCHEMA_COMPAT_WRITE_OLD.

◆ insertInternal()

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

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

Parameters
IDatabase$dbw
string$keyA 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 546 of file CommentStore.php.

References $key, $t, createComment(), Wikimedia\Rdbms\IDatabase\insert(), MIGRATION_NEW, SCHEMA_COMPAT_WRITE_NEW, and SCHEMA_COMPAT_WRITE_OLD.

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$dbwDatabase handle to insert on
string$keyA key such as "rev_comment" identifying the comment field being fetched.
string | Message | CommentStoreComment | null$commentAs for self::createComment()
array | null$dataAs 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 641 of file CommentStore.php.

References $key, getKey(), insertInternal(), 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$keyA key such as "rev_comment" identifying the comment field being fetched.
Returns
CommentStore

Definition at line 125 of file CommentStore.php.

References $key, MIGRATION_NEW, and wfDeprecated().

Member Data Documentation

◆ $joinCache

array [] CommentStore::$joinCache = []
protected

Cache for self::getJoin()

Definition at line 94 of file CommentStore.php.

◆ $key

string null CommentStore::$key = null
protected

◆ $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, or an appropriate combination of SCHEMA_COMPAT_* constants.

Todo:
Deprecate and remove once extensions seem unlikely to need to use it for migration anymore.

Definition at line 91 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',
],
]
const MIGRATION_NEW
Definition Defines.php:307
const MIGRATION_OLD
Definition Defines.php:304

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.

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