docs/pageupdater.md

   1 PageUpdater {#pageupdater}
   2 ===========
   3
   4 This document provides an overview of the usage of PageUpdater and DerivedPageDataUpdater.
   5
   6 ## PageUpdater
   7
   8 `PageUpdater` is the canonical way to create page revisions, that is, to perform edits.
   9
  10 `PageUpdater` is a stateful, handle-like object that allows new revisions to be created on a given wiki page using the `saveRevision()` method. `PageUpdater` provides setters for defining the new revision's content as well as meta-data such as change tags. `saveRevision()` stores the new revision's primary content and metadata, and triggers the necessary updates to derived secondary data and cached artifacts e.g. in the `ParserCache` and the CDN layer, using a `DerivedPageDataUpdater`.
  11
  12 `PageUpdater` instances follow the below life cycle, defined by a number of methods:
  13
  14                             +----------------------------+
  15                             |                            |
  16                             |             new            |
  17                             |                            |
  18                             +------|--------------|------+
  19                                    |              |
  20               grabParentRevision()-|              |
  21               or hasEditConflict()-|              |
  22                                    |              |
  23                           +--------v-------+      |
  24                           |                |      |
  25                           |  parent known  |      |
  26                           |                |      |
  27     Enables---------------+--------|-------+      |
  28       safe operations based on     |              |-saveRevision()
  29       the parent revision, e.g.    |              |
  30       section replacement or       |              |
  31       edit conflict resolution.    |              |
  32                                    |              |
  33                     saveRevision()-|              |
  34                                    |              |
  35                             +------v--------------v------+
  36                             |                            |
  37                             |      creation committed    |
  38                             |                            |
  39     Enables-----------------+----------------------------+
  40       wasSuccess()
  41       isUnchanged()
  42       isNew()
  43       getState()
  44       getNewRevision()
  45       etc.
  46
  47 The stateful nature of `PageUpdater` allows it to be used to safely perform transformations that depend on the new revision's parent revision, such as replacing sections or applying 3-way conflict resolution, while protecting against race conditions using a compare-and-swap (CAS) mechanism: after calling code used the `grabParentRevision()` method to access the edit's logical parent, `PageUpdater` remembers that revision, and ensure that that revision is still the page's current revision when performing the atomic database update for the revision's primary meta-data when `saveRevision()` is called. If another revision was created concurrently, `saveRevision()` will fail, indicating the problem with the "edit-conflict" code in the status object.
  48
  49 Typical usage for programmatic revision creation (with `$page` being a WikiPage as of 1.32, to be replaced by a repository service later):
  50
  51 ```php
  52 $updater = $page->newPageUpdater( $user );
  53 $updater->setContent( SlotRecord::MAIN, $content );
  54 $updater->setRcPatrolStatus( RecentChange::PRC_PATROLLED );
  55 $newRev = $updater->saveRevision( $comment );
  56 ```
  57
  58 Usage with content depending on the parent revision
  59
  60 ```php
  61 $updater = $page->newPageUpdater( $user );
  62 $parent = $updater->grabParentRevision();
  63 $content = $parent->getContent( SlotRecord::MAIN )->replaceSection( $section, $sectionContent );
  64 $updater->setContent( SlotRecord::MAIN, $content );
  65 $newRev = $updater->saveRevision( $comment, EDIT_UPDATE );
  66 ```
  67
  68 In both cases, all secondary updates will be triggered automatically.
  69
  70 ## DerivedPageDataUpdater
  71
  72 `DerivedPageDataUpdater` is a stateful, handle-like object that caches derived data representing a revision, and can trigger updates of cached copies of that data, e.g. in the links tables, `page_props`, the `ParserCache`, and the CDN layer.
  73
  74 `DerivedPageDataUpdater` is used by `PageUpdater` when creating new revisions, but can also be used independently when performing meta data updates during undeletion, import, or when puring a page. It's a stepping stone on the way to a more complete refactoring of WikiPage.
  75
  76 **NOTE**: Avoid direct usage of `DerivedPageDataUpdater`. In the future, we want to define interfaces for the different use cases of `DerivedPageDataUpdater`, particularly providing access to post-PST content and `ParserOutput` to callbacks during revision creation, which currently use `WikiPage::prepareContentForEdit`, and allowing updates to be triggered on purge, import, and undeletion, which currently use `WikiPage::doEditUpdates()` and `Content::getSecondaryDataUpdates()`.
  77
  78 The primary reason for `DerivedPageDataUpdater` to be stateful is internal caching of state that avoids the re-generation of `ParserOutput` and re-application of pre-save-transformations (PST).
  79
  80 `DerivedPageDataUpdater` instances follow the below life cycle, defined by a number of methods:
  81
  82                          +---------------------------------------------------------------------+
  83                          |                                                                     |
  84                          |                                 new                                 |
  85                          |                                                                     |
  86                          +---------------|------------------|------------------|---------------+
  87                                          |                  |                  |
  88                    grabCurrentRevision()-|                  |                  |
  89                                          |                  |                  |
  90                              +-----------v----------+       |                  |
  91                              |                      |       |-prepareContent() |
  92                              |    knows current     |       |                  |
  93                              |                      |       |                  |
  94     Enables------------------+-----|-----|----------+       |                  |
  95       pageExisted()                |     |                  |                  |
  96       wasRedirect()                |     |-prepareContent() |                  |-prepareUpdate()
  97                                    |     |                  |                  |
  98                                    |     |    +-------------v------------+     |
  99                                    |     |    |                          |     |
 100                                    |     +---->        has content       |     |
 101                                    |          |                          |     |
 102     Enables------------------------|----------+--------------------------+     |
 103       isChange()                   |                              |            |
 104       isCreation()                 |-prepareUpdate()              |            |
 105       getSlots()                   |              prepareUpdate()-|            |
 106       getTouchedSlotRoles()        |                              |            |
 107       getCanonicalParserOutput()   |                  +-----------v------------v-----------------+
 108                                    |                  |                                          |
 109                                    +------------------>                 has revision             |
 110                                                       |                                          |
 111     Enables-------------------------------------------+------------------------|-----------------+
 112       updateParserCache()                                                      |
 113       runSecondaryDataUpdates()                                                |-doUpdates()
 114                                                                                |
 115                                                                    +-----------v---------+
 116                                                                    |                     |
 117                                                                    |     updates done    |
 118                                                                    |                     |
 119                                                                    +---------------------+
 120
 121
 122 - `grabCurrentRevision()` returns the logical parent revision of the target revision. It is guaranteed to always return the same revision for a given `DerivedPageDataUpdater` instance. If called before `prepareUpdate()`, this fixates the logical parent to be the page's current revision. If called for the first time after `prepareUpdate()`, it returns the revision passed as the 'oldrevision' option to `prepareUpdate()`, or, if that wasn't given, the parent of $revision parameter passed to `prepareUpdate()`.
 123
 124 - `prepareContent()` is called before the new revision is created, to apply pre-save-transformation (PST) and allow subsequent access to the canonical `ParserOutput` of the revision. `getSlots()` and `getCanonicalParserOutput()` as well as `getSecondaryDataUpdates()` may be used after `prepareContent()` was called. Calling `prepareContent()` with the same parameters again has no effect. Calling it again with mismatching parameters, or calling it after `prepareUpdate()` was called, triggers a `LogicException`.
 125
 126 - `prepareUpdate()` is called after the new revision has been created. This may happen right after the revision was created, on the same instance on which `prepareContent()` was called, or later (possibly much later), on a fresh instance in a different process, due to deferred or asynchronous updates, or during import, undeletion, purging, etc. `prepareUpdate()` is required before a call to `doUpdates()`, and it also enables calls to `getSlots()` and `getCanonicalParserOutput()` as well as `getSecondaryDataUpdates()`. Calling `prepareUpdate()` with the same parameters again has no effect. Calling it again with mismatching parameters, or calling it with parameters mismatching the ones `prepareContent()` was called with, triggers a `LogicException`.
 127
 128 - `getSecondaryDataUpdates()` returns `DataUpdates` that represent derived data for the revision. These may be used to update such data, e.g. in `ApiPurge`, `RefreshLinksJob`, and the `refreshLinks` script.
 129
 130 - `doUpdates()` triggers the updates defined by `getSecondaryDataUpdates()`, and also causes updates to cached artifacts in the `ParserCache`, the CDN layer, etc. This is primarily used by PageUpdater, but also by `UndeletePage` during undeletion, and when importing revisions from XML. `doUpdates()` can only be called after `prepareUpdate()` was used to initialize the `DerivedPageDataUpdater` instance for a specific revision. Calling it before `prepareUpdate()` is called raises a `LogicException`.
 131
 132 A `DerivedPageDataUpdater` instance is intended to be re-used during different stages of complex update operations that often involve callbacks to extension code via
 133 MediaWiki's hook mechanism, or deferred or even asynchronous execution of Jobs and `DeferredUpdates`. Since these mechanisms typically do not provide a way to pass a
 134 `DerivedPageDataUpdater` directly, `WikiPage::getDerivedDataUpdater()` has to be used to obtain a `DerivedPageDataUpdater` for the update currently in progress - re-using the same `DerivedPageDataUpdater` if possible avoids re-generation of `ParserOutput` objects
 135 and other expensively derived artifacts.
 136
 137 This mechanism for re-using a `DerivedPageDataUpdater` instance without passing it directly requires a way to ensure that a given `DerivedPageDataUpdater` instance can actually be used in the calling code's context. For this purpose, `WikiPage::getDerivedDataUpdater()` calls the `isReusableFor()` method on `DerivedPageDataUpdater`, which ensures that the given instance is applicable to the given parameters. In other words, `isReusableFor()` predicts whether calling `prepareContent()` or `prepareUpdate()` with a given set of parameters will trigger a `LogicException`. In that case, `WikiPage::getDerivedDataUpdater()` creates a fresh `DerivedPageDataUpdater` instance.