Daniel Kinzler has uploaded a new change for review. (
https://gerrit.wikimedia.org/r/404173 )
Change subject: Document the interpretation of revision row fields.
......................................................................
Document the interpretation of revision row fields.
This adds explicit documentation for all the fields used by
RevisionStore in various methods that take a database row object
or an associative array to describe a revision.
Change-Id: Ic85ee9e82c221c0c215759a7a99801f1a9d53245
---
M includes/Revision.php
M includes/Storage/RevisionStore.php
2 files changed, 86 insertions(+), 7 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/73/404173/1
diff --git a/includes/Revision.php b/includes/Revision.php
index 510c1ee..6078a32 100644
--- a/includes/Revision.php
+++ b/includes/Revision.php
@@ -474,7 +474,8 @@
}
/**
- * @param object|array|RevisionRecord $row Either a database row or an
array
+ * @param object|array|RevisionRecord $row Either a database row or an
array.
+ * See class level documentation of RevisionStore for supported
fields and their meaning.
* @param int $queryFlags
* @param Title|null $title
*
diff --git a/includes/Storage/RevisionStore.php
b/includes/Storage/RevisionStore.php
index f8481fe..4e125d4 100644
--- a/includes/Storage/RevisionStore.php
+++ b/includes/Storage/RevisionStore.php
@@ -54,7 +54,80 @@
use Wikimedia\Rdbms\LoadBalancer;
/**
- * Service for looking up page revisions.
+ * Service for looking up and storing page revisions.
+ *
+ * Several methods in this class allow the creation of a RevisionRecord from a
database row object,
+ * or a programmatically constructed array. The following rules apply when
constructing a
+ * RevisionRecord from a row object: it is expected to be a database row
object containing fields
+ * from the revision table, the text table, the page table, and possibly other
auxiliary tables.
+ * Note that if rev_id is not present but ar_user is, the archive table is
assumed to be used
+ * instead of the revision table, so the ar_* fields are used instead of the
rev_* fields.
+ *
+ * The following fields are used when constructing a RevisionStoreRecord resp.
a
+ * RevisionArchiveRecord from a database row:
+ * - rev_id (or ar_rev_id): the revision ID (required).
+ * May also be used to load a Title if none is passed explicitly.
+ * - rev_page (or ar_page_id): the ID of the page the revision belongs to.
+ * May be used to load a Title if none is passed explicitly.
+ * - ar_title and ar_namespace: used to construct a Title object of none is
provided.
+ * Note that page_title and page_namespace are not used in this way.
+ * - rev_comment (or ar_comment): handled by CommentStore::getCommentLegacy
+ * - rev_comment_* (or ar_comment_*): handled by CommentStore::getCommentLegacy
+ * - comment_*: handled by CommentStore
+ * - rev_user (or ar_user): the name of the user who created the revision.
+ * (FUTURE: handled by ActorStore::getActorLegacy)
+ * - rev_user_text (or ar_user_text): the name the user who created the
revision.
+ * (FUTURE: handled by ActorStore::getActorLegacy)
+ * - rev_actor: (FUTURE) the actor ID of the user who created the revision,
andled by ActorStore.
+ * - rev_parent_id (or ar_parent_id): The ID of the parent revision.
+ * - rev_minor (or ar_minor): 1 if the edit was marked as minor by the user.
+ * - rev_deleted (or ar_deleted): bitfield indicating what aspect of the
revision is suppressed.
+ *
+ * The following fields are used when constructing the main slot content from
a MW 1.29 style
+ * database row:
+ * - rev_id (or ar_id): the revision ID (required)
+ * - rev_text_id (or ar_text_id): a reference to a row in the text table;
needed unless
+ * old_text (or ar_text) is present.
+ * - rev_len (or ar_len): the nominal size of the main slot's content.
+ * Calculated if missing or null.
+ * - rev_sha1 (or ar_sha1): the Base36 encoded SHA1 hash of the slot's content.
+ * Calculated if missing or null.
+ * - rev_content_model (or ar_content_model): the main slot's content model.
+ * Derived from the title of not given.
+ * - rev_content_format (or ar_content_format): the main slot's serialization
format.
+ * Derived from the model of not given.
+ * - old_text (or ar_text): the main slots content, with any
encoding/compression/indirection
+ * indicated by old_flags.
+ * - old_flags (or ar_flags): flags indicating any
encoding/compression/indirection to be
+ * undone when loading the main slot's content. Required if old_text/ar_text
is present!
+ * Note that the content will be converted according to any legacy encoding
configured in
+ * BlobStore unless the "utf-8" flag is present here!
+ *
+ * Code that constructs a revision programmatically has traditionally done so
by passing an
+ * associative array to the constructor of Revision. New code is encouraged to
directly use a
+ * MutableRevisionRecord instead. Construction from an associative array is
still supported
+ * for easier migration.
+ *
+ * The following fields are used when constructing the main slot content from
a MW 1.29 style
+ * associative array:
+ * - 'id': the revision ID
+ * - 'text_id': a reference to a row in the text table; needed unless 'text'
+ * or 'content' are present.
+ * - 'len': the nominal size of the main slot's content.
+ * Calculated if missing or null.
+ * - 'sha1': the Base36 encoded SHA1 hash of the slot's content.
+ * Calculated if missing or null.
+ * - 'content_model': the main slot's content model.
+ * Derived from the title of not given.
+ * - 'content_format': the main slot's serialization format.
+ * Derived from the model of not given.
+ * - 'text': the main slots content. Assumed to be the serialized content,
+ * unless some encoding/compression/indirection specified by the 'flags'
field.
+ * - 'flags': flags indicating the encoding/compression/indirection to be
+ * undone before deserializing the value of the 'text' field. If this field
is null or absent,
+ * 'text' is assumed to contain the raw serialized content, and no
conversion is applied.
+ * Note that, if the field is present and not null, the content will be
converted according to
+ * any legacy encoding configured in BlobStore, unless the "utf-8" flag is
present here!
*
* @since 1.31
*
@@ -676,7 +749,8 @@
/**
* Constructs a RevisionRecord for the revisions main slot, based on
the MW1.29 schema.
*
- * @param object|array $row Either a database row or an array
+ * @param object|array $row Either a database row or an associative
array.
+ * See class level documentation for supported fields and their
meaning.
* @param int $queryFlags for callbacks
* @param Title $title
*
@@ -989,7 +1063,8 @@
*
* MCR migration note: this replaces Revision::newFromArchiveRow
*
- * @param object $row
+ * @param object $row Database row object.
+ * See class level documentation for supported fields and their
meaning.
* @param int $queryFlags
* @param Title|null $title
* @param array $overrides associative array with fields of $row to
override. This may be
@@ -1079,7 +1154,8 @@
*
* MCR migration note: this replaces Revision::newFromRow
*
- * @param object $row
+ * @param object $row Database row object.
+ * See class level documentation for supported fields and their
meaning.
* @param int $queryFlags
* @param Title|null $title
*
@@ -1121,7 +1197,8 @@
*
* MCR migration note: this replaces Revision::newFromRow
*
- * @param object $row
+ * @param object $row Database row object.
+ * See class level documentation for supported fields and their
meaning.
* @param int $queryFlags
* @param Title|null $title
*
@@ -1137,7 +1214,8 @@
*
* MCR migration note: this replaces Revision::newFromRow
*
- * @param array $fields
+ * @param array $fields An associative array.
+ * See class level documentation for supported fields and their
meaning.
* @param int $queryFlags
* @param Title|null $title
*
--
To view, visit https://gerrit.wikimedia.org/r/404173
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ic85ee9e82c221c0c215759a7a99801f1a9d53245
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Daniel Kinzler <daniel.kinz...@wikimedia.de>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
