MediaWiki master
MediaWiki\Storage\DerivedPageDataUpdater Class Reference

A handle for managing updates for derived page data on edit, import, purge, etc. More...

Inherits LoggerAwareInterface, and MediaWiki\Storage\PreparedUpdate.

Collaboration diagram for MediaWiki\Storage\DerivedPageDataUpdater:

Public Member Functions

 __construct (ServiceOptions $options, WikiPage $wikiPage, RevisionStore $revisionStore, RevisionRenderer $revisionRenderer, SlotRoleRegistry $slotRoleRegistry, ParserCache $parserCache, JobQueueGroup $jobQueueGroup, MessageCache $messageCache, Language $contLang, ILBFactory $loadbalancerFactory, IContentHandlerFactory $contentHandlerFactory, HookContainer $hookContainer, EditResultCache $editResultCache, UserNameUtils $userNameUtils, ContentTransformer $contentTransformer, PageEditStash $pageEditStash, TalkPageNotificationManager $talkPageNotificationManager, WANObjectCache $mainWANObjectCache, PermissionManager $permissionManager)
 
 doParserCacheUpdate ()
 Causes parser cache entries to be updated.
 
 doSecondaryDataUpdates (array $options=[])
 Do secondary data updates (e.g.
 
 doUpdates ()
 Do standard updates after page edit, purge, or import.
 
 getCanonicalParserOptions ()
 
 getCanonicalParserOutput ()
 Returns the canonical parser output.Code that does not need access to the rendered HTML should use getParserOutputForMetaData() instead.
Returns
ParserOutput

 
 getModifiedSlotRoles ()
 Returns the role names of the slots modified by the new revision, not including removed roles.
 
 getPage ()
 Returns the page being updated.
 
 getParserOutputForMetaData ()
 
 getPreparedEdit ()
 
 getRawContent (string $role)
 Returns the content of the given slot, with no audience checks.
 
 getRawSlot ( $role)
 Returns the slot, modified or inherited, after PST, with no audience checks applied.
 
 getRemovedSlotRoles ()
 Returns the role names of the slots removed by the new revision.
 
 getRenderedRevision ()
 
 getRevision ()
 Returns the update's target revision - that is, the revision that will be the current revision after the update.
 
 getSecondaryDataUpdates ( $recursive=false)
 
 getSlotParserOutput ( $role, $generateHtml=true)
 
 getSlots ()
 Returns the slots of the target revision, after PST.
 
 getTouchedSlotRoles ()
 Returns the role names of the slots touched by the new revision, including removed roles.
 
 grabCurrentRevision ()
 Returns the revision that was the page's current revision when grabCurrentRevision() was first called.
 
 isChange ()
 Whether the content of the current revision after the edit is different from the content of the current revision before the edit.
 
 isContentDeleted ()
 Whether the content is deleted and thus not visible to the public.
 
 isContentPrepared ()
 Whether prepareUpdate() or prepareContent() have been called on this instance.
 
 isCountable ()
 
 isCreation ()
 Whether the edit creates the page.
 
 isRedirect ()
 
 isReusableFor (UserIdentity $user=null, RevisionRecord $revision=null, RevisionSlotsUpdate $slotsUpdate=null, $parentId=null)
 Checks whether this DerivedPageDataUpdater can be re-used for running updates targeting the given revision.
 
 isUpdatePrepared ()
 Whether prepareUpdate() has been called on this instance.
 
 pageExisted ()
 Determines whether the page being edited already existed.
 
 prepareContent (UserIdentity $user, RevisionSlotsUpdate $slotsUpdate, $useStash=true)
 Prepare updates based on an update which has not yet been saved.
 
 prepareUpdate (RevisionRecord $revision, array $options=[])
 Prepare derived data updates targeting the given RevisionRecord.
 
 setArticleCountMethod ( $articleCountMethod)
 
 setCause (?string $causeAction, ?string $causeAgent)
 Set the cause action and cause agent, for logging and debugging.
 
 setForceEmptyRevision (bool $forceEmptyRevision)
 Set whether null-edits should create a revision.
 
 setLogger (LoggerInterface $logger)
 
 setRcWatchCategoryMembership ( $rcWatchCategoryMembership)
 
 wasRedirect ()
 Whether the page was a redirect before the edit.
 

Detailed Description

A handle for managing updates for derived page data on edit, import, purge, etc.

Note
Avoid direct usage of DerivedPageDataUpdater.
Todo
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().

DerivedPageDataUpdater instances are designed to be cached inside a WikiPage instance, and re-used by callback code over the course of an update operation. It's a stepping stone on the way to a more complete refactoring of WikiPage.

When using a DerivedPageDataUpdater, the following life cycle must be observed: grabCurrentRevision (optional), prepareContent (optional), prepareUpdate (required for doUpdates). getCanonicalParserOutput, getSlots, and getSecondaryDataUpdates require prepareContent or prepareUpdate to have been called first, to initialize the DerivedPageDataUpdater.

MCR migration note: this replaces the relevant methods in WikiPage, and covers the use cases of PreparedEdit.

See also
docs/pageupdater.md for more information.
Access: internal
Since
1.32

Definition at line 107 of file DerivedPageDataUpdater.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Storage\DerivedPageDataUpdater::__construct ( ServiceOptions $options,
WikiPage $wikiPage,
RevisionStore $revisionStore,
RevisionRenderer $revisionRenderer,
SlotRoleRegistry $slotRoleRegistry,
ParserCache $parserCache,
JobQueueGroup $jobQueueGroup,
MessageCache $messageCache,
Language $contLang,
ILBFactory $loadbalancerFactory,
IContentHandlerFactory $contentHandlerFactory,
HookContainer $hookContainer,
EditResultCache $editResultCache,
UserNameUtils $userNameUtils,
ContentTransformer $contentTransformer,
PageEditStash $pageEditStash,
TalkPageNotificationManager $talkPageNotificationManager,
WANObjectCache $mainWANObjectCache,
PermissionManager $permissionManager )
Parameters
ServiceOptions$options
WikiPage$wikiPage
RevisionStore$revisionStore
RevisionRenderer$revisionRenderer
SlotRoleRegistry$slotRoleRegistry
ParserCache$parserCache
JobQueueGroup$jobQueueGroup
MessageCache$messageCache
Language$contLang
ILBFactory$loadbalancerFactory
IContentHandlerFactory$contentHandlerFactory
HookContainer$hookContainer
EditResultCache$editResultCache
UserNameUtils$userNameUtils
ContentTransformer$contentTransformer
PageEditStash$pageEditStash
TalkPageNotificationManager$talkPageNotificationManager
WANObjectCache$mainWANObjectCache
PermissionManager$permissionManager

Definition at line 341 of file DerivedPageDataUpdater.php.

References MediaWiki\Config\ServiceOptions\get(), and MediaWiki\MainConfigNames\ParsoidCacheConfig.

Member Function Documentation

◆ doParserCacheUpdate()

MediaWiki\Storage\DerivedPageDataUpdater::doParserCacheUpdate ( )

Causes parser cache entries to be updated.

Note
This does not update links tables. Use doSecondaryDataUpdates() for that.
Application logic should use Wikipage::updateParserCache instead.

Definition at line 1841 of file DerivedPageDataUpdater.php.

References WikiPage\getId(), and WikiPage\toPageRecord().

◆ doSecondaryDataUpdates()

MediaWiki\Storage\DerivedPageDataUpdater::doSecondaryDataUpdates ( array $options = [])

Do secondary data updates (e.g.

updating link tables) or schedule them as deferred updates

Note
This does not update the parser cache. Use doParserCacheUpdate() for that.
Application logic should use Wikipage::doSecondaryDataUpdates instead.
Parameters
array$options
  • recursive: make the update recursive, i.e. also update pages which transclude the current page or otherwise depend on it (default: false)
  • defer: one of the DeferredUpdates constants, or false to run immediately after waiting for replication of the changes from the SecondaryDataUpdates hooks (default: false)
  • freshness: used with 'defer'; forces an update if the last update was before the given timestamp, even if the page and its dependencies didn't change since then (TS_MW; default: false)
Since
1.32

Definition at line 1799 of file DerivedPageDataUpdater.php.

◆ doUpdates()

MediaWiki\Storage\DerivedPageDataUpdater::doUpdates ( )

Do standard updates after page edit, purge, or import.

Update links tables, site stats, search index, title cache, message cache, etc. Purges pages that depend on this page when appropriate. With a 10% chance, triggers pruning the recent changes table.

Note
prepareUpdate() must be called before calling this method!

MCR migration note: this replaces WikiPage::doEditUpdates.

Definition at line 1578 of file DerivedPageDataUpdater.php.

References getTitle(), NS_MEDIAWIKI, NS_USER_TALK, and wfDebug().

◆ getCanonicalParserOptions()

MediaWiki\Storage\DerivedPageDataUpdater::getCanonicalParserOptions ( )
Returns
ParserOptions

Definition at line 1459 of file DerivedPageDataUpdater.php.

◆ getCanonicalParserOutput()

MediaWiki\Storage\DerivedPageDataUpdater::getCanonicalParserOutput ( )

Returns the canonical parser output.Code that does not need access to the rendered HTML should use getParserOutputForMetaData() instead.

Returns
ParserOutput

Returns
ParserOutput

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 1452 of file DerivedPageDataUpdater.php.

◆ getModifiedSlotRoles()

MediaWiki\Storage\DerivedPageDataUpdater::getModifiedSlotRoles ( )

Returns the role names of the slots modified by the new revision, not including removed roles.

Returns
string[]

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 1168 of file DerivedPageDataUpdater.php.

◆ getPage()

MediaWiki\Storage\DerivedPageDataUpdater::getPage ( )

Returns the page being updated.

Since
1.37
Returns
PageIdentity

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 583 of file DerivedPageDataUpdater.php.

◆ getParserOutputForMetaData()

MediaWiki\Storage\DerivedPageDataUpdater::getParserOutputForMetaData ( )
Since
1.37
Returns
ParserOutput

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 1444 of file DerivedPageDataUpdater.php.

◆ getPreparedEdit()

MediaWiki\Storage\DerivedPageDataUpdater::getPreparedEdit ( )
Deprecated
This only exists for B/C, use the getters on DerivedPageDataUpdater directly!
Returns
PreparedEdit

Definition at line 1408 of file DerivedPageDataUpdater.php.

◆ getRawContent()

MediaWiki\Storage\DerivedPageDataUpdater::getRawContent ( string $role)

Returns the content of the given slot, with no audience checks.

Exceptions
PageUpdateExceptionIf the slot is neither set for update nor inherited from the parent revision.
Parameters
string$roleslot role name
Returns
Content

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 741 of file DerivedPageDataUpdater.php.

◆ getRawSlot()

MediaWiki\Storage\DerivedPageDataUpdater::getRawSlot ( $role)

Returns the slot, modified or inherited, after PST, with no audience checks applied.

Parameters
string$roleslot role name
Exceptions
PageUpdateExceptionIf the slot is neither set for update nor inherited from the parent revision.
Returns
SlotRecord

Definition at line 729 of file DerivedPageDataUpdater.php.

◆ getRemovedSlotRoles()

MediaWiki\Storage\DerivedPageDataUpdater::getRemovedSlotRoles ( )

Returns the role names of the slots removed by the new revision.

Returns
string[]

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 1177 of file DerivedPageDataUpdater.php.

◆ getRenderedRevision()

MediaWiki\Storage\DerivedPageDataUpdater::getRenderedRevision ( )
Returns
RenderedRevision

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 1042 of file DerivedPageDataUpdater.php.

◆ getRevision()

MediaWiki\Storage\DerivedPageDataUpdater::getRevision ( )

Returns the update's target revision - that is, the revision that will be the current revision after the update.

Note
Callers must treat the returned RevisionRecord's content as immutable, even if it is a MutableRevisionRecord instance. Other aspects of a MutableRevisionRecord returned from here, such as the user or the comment, may be changed, but may not be reflected in ParserOutput until after prepareUpdate() has been called.
Todo
This is currently used by PageUpdater::makeNewRevision() to construct an unsaved MutableRevisionRecord instance. Introduce something like an UnsavedRevisionFactory service for that purpose instead!
Returns
RevisionRecord

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 1034 of file DerivedPageDataUpdater.php.

◆ getSecondaryDataUpdates()

MediaWiki\Storage\DerivedPageDataUpdater::getSecondaryDataUpdates ( $recursive = false)
Parameters
bool$recursive
Returns
DeferrableUpdate[]

Definition at line 1468 of file DerivedPageDataUpdater.php.

References WikiPage\exists(), WikiPage\getTitle(), and WikiPage\loadPageData().

◆ getSlotParserOutput()

MediaWiki\Storage\DerivedPageDataUpdater::getSlotParserOutput ( $role,
$generateHtml = true )
Parameters
string$role
bool$generateHtml
Returns
ParserOutput

Definition at line 1433 of file DerivedPageDataUpdater.php.

◆ getSlots()

MediaWiki\Storage\DerivedPageDataUpdater::getSlots ( )

Returns the slots of the target revision, after PST.

Note
Callers must treat the returned RevisionSlots instance as immutable, even if it is a MutableRevisionSlots instance.
Returns
RevisionSlots

Definition at line 1129 of file DerivedPageDataUpdater.php.

◆ getTouchedSlotRoles()

MediaWiki\Storage\DerivedPageDataUpdater::getTouchedSlotRoles ( )

Returns the role names of the slots touched by the new revision, including removed roles.

Returns
string[]

Definition at line 1158 of file DerivedPageDataUpdater.php.

◆ grabCurrentRevision()

MediaWiki\Storage\DerivedPageDataUpdater::grabCurrentRevision ( )

Returns the revision that was the page's current revision when grabCurrentRevision() was first called.

During an edit, that revision will act as the logical parent of the new revision.

Some updates are performed based on the difference between the database state at the moment this method is first called, and the state after the edit.

See also
docs/pageupdater.md for more information on when thie method can and should be called.
Note
After prepareUpdate() was called, grabCurrentRevision() will throw an exception to avoid confusion, since the page's current revision is then the new revision after the edit, which was presumably passed to prepareUpdate() as the $revision parameter. Use getParentRevision() instead to access the revision that is the parent of the new revision.
Returns
RevisionRecord|null the page's current revision, or null if the page does not yet exist.

Definition at line 651 of file DerivedPageDataUpdater.php.

References WikiPage\getRevisionRecord(), WikiPage\isCountable(), WikiPage\isRedirect(), and WikiPage\loadPageData().

◆ isChange()

MediaWiki\Storage\DerivedPageDataUpdater::isChange ( )

Whether the content of the current revision after the edit is different from the content of the current revision before the edit.

This will return false for a null-edit (no revision created), as well as for a dummy revision (a "null-revision" that has the same content as its parent).

Warning
at present, dummy revision would return false after prepareContent(), but true after prepareUpdate()!
Todo
This should probably be fixed.
Returns
bool

Definition at line 1095 of file DerivedPageDataUpdater.php.

◆ isContentDeleted()

MediaWiki\Storage\DerivedPageDataUpdater::isContentDeleted ( )

Whether the content is deleted and thus not visible to the public.

Returns
bool

Definition at line 711 of file DerivedPageDataUpdater.php.

◆ isContentPrepared()

MediaWiki\Storage\DerivedPageDataUpdater::isContentPrepared ( )

Whether prepareUpdate() or prepareContent() have been called on this instance.

Returns
bool

Definition at line 683 of file DerivedPageDataUpdater.php.

◆ isCountable()

MediaWiki\Storage\DerivedPageDataUpdater::isCountable ( )
Returns
bool

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 763 of file DerivedPageDataUpdater.php.

◆ isCreation()

MediaWiki\Storage\DerivedPageDataUpdater::isCreation ( )

Whether the edit creates the page.

Returns
bool

Definition at line 1078 of file DerivedPageDataUpdater.php.

◆ isRedirect()

MediaWiki\Storage\DerivedPageDataUpdater::isRedirect ( )
Returns
bool

Implements MediaWiki\Storage\PreparedUpdate.

Definition at line 808 of file DerivedPageDataUpdater.php.

◆ isReusableFor()

MediaWiki\Storage\DerivedPageDataUpdater::isReusableFor ( UserIdentity $user = null,
RevisionRecord $revision = null,
RevisionSlotsUpdate $slotsUpdate = null,
$parentId = null )

Checks whether this DerivedPageDataUpdater can be re-used for running updates targeting the given revision.

Parameters
UserIdentity | null$userThe user creating the revision in question
RevisionRecord | null$revisionNew revision (after save, if already saved)
RevisionSlotsUpdate | null$slotsUpdateNew content (before PST)
null | int$parentIdParent revision of the edit (use 0 for page creation)
Returns
bool

Definition at line 468 of file DerivedPageDataUpdater.php.

◆ isUpdatePrepared()

MediaWiki\Storage\DerivedPageDataUpdater::isUpdatePrepared ( )

Whether prepareUpdate() has been called on this instance.

Note
will also return null in case of a null-edit!
Returns
bool

Definition at line 694 of file DerivedPageDataUpdater.php.

◆ pageExisted()

MediaWiki\Storage\DerivedPageDataUpdater::pageExisted ( )

Determines whether the page being edited already existed.

Only defined after calling grabCurrentRevision() or prepareContent() or prepareUpdate()!

Returns
bool
Exceptions
LogicExceptionif called before grabCurrentRevision

Definition at line 594 of file DerivedPageDataUpdater.php.

◆ prepareContent()

MediaWiki\Storage\DerivedPageDataUpdater::prepareContent ( UserIdentity $user,
RevisionSlotsUpdate $slotsUpdate,
$useStash = true )

Prepare updates based on an update which has not yet been saved.

This may be used to create derived data that is needed when creating a new revision; particularly, this makes available the slots of the new revision via the getSlots() method, after applying PST and slot inheritance.

The derived data prepared for revision creation may then later be re-used by doUpdates(), without the need to re-calculate.

See also
docs/pageupdater.md for more information on when thie method can and should be called.
Note
Calling this method more than once with the same $slotsUpdate has no effect. Calling this method multiple times with different content will cause an exception.
Calling this method after prepareUpdate() has been called will cause an exception.
Parameters
UserIdentity$userThe user to act as context for pre-save transformation (PST).
RevisionSlotsUpdate$slotsUpdateThe new content of the slots to be updated by this edit, before PST.
bool$useStashWhether to use stashed ParserOutput

Definition at line 851 of file DerivedPageDataUpdater.php.

References MediaWiki\Title\Title\equals(), MediaWiki\Storage\RevisionSlotsUpdate\getModifiedRoles(), MediaWiki\Storage\RevisionSlotsUpdate\getModifiedSlot(), MediaWiki\User\UserIdentity\getName(), MediaWiki\Storage\RevisionSlotsUpdate\getRemovedRoles(), getTitle(), and MediaWiki\Storage\RevisionSlotsUpdate\isModifiedSlot().

◆ prepareUpdate()

MediaWiki\Storage\DerivedPageDataUpdater::prepareUpdate ( RevisionRecord $revision,
array $options = [] )

Prepare derived data updates targeting the given RevisionRecord.

Calling this method requires the given revision to be present in the database. This may be right after a new revision has been created, or when re-generating derived data e.g. in ApiPurge, RefreshLinksJob, and the refreshLinks script.

See also
docs/pageupdater.md for more information on when thie method can and should be called.
Note
Calling this method more than once with the same revision has no effect. $options are only used for the first call. Calling this method multiple times with different revisions will cause an exception.
If grabCurrentRevision() (or prepareContent()) has been called before calling this method, $revision->getParentRevision() has to refer to the revision that was the current revision at the time grabCurrentRevision() was called.
Parameters
RevisionRecord$revision
array$optionsArray of options, following indexes are used:
  • changed: bool, whether the revision changed the content (default true)
  • created: bool, whether the revision created the page (default false)
  • moved: bool, whether the page was moved (default false)
  • oldtitle: PageIdentity, if the page was moved this is the source title (default null)
  • restored: bool, whether the page was undeleted (default false)
  • oldrevision: RevisionRecord object for the pre-update revision (default null)
  • triggeringUser: The user triggering the update (UserIdentity, defaults to the user who created the revision)
  • oldredirect: bool, null, or string 'no-change' (default null):
    • bool: whether the page was counted as a redirect before that revision, only used in changed is true and created is false
    • null or 'no-change': don't update the redirect status.
  • oldcountable: bool, null, or string 'no-change' (default null):
    • bool: whether the page was counted as an article before that revision, only used in changed is true and created is false
    • null: if created is false, don't update the article count; if created is true, do update the article count
    • 'no-change': don't update the article count, ever When set to null, pageState['oldCountable'] will be used instead if available.
  • causeAction: an arbitrary string identifying the reason for the update. See DataUpdate::getCauseAction(). (default 'unknown')
  • causeAgent: name of the user who caused the update. See DataUpdate::getCauseAgent(). (string, default 'unknown')
  • known-revision-output: a combined canonical ParserOutput for the revision, perhaps from some cache. The caller is responsible for ensuring that the ParserOutput indeed matched the $rev and $options. This mechanism is intended as a temporary stop-gap, for the time until caches have been changed to store RenderedRevision states instead of ParserOutput objects. (default: null) (since 1.33)
  • editResult: EditResult object created during the update. Required to perform reverted tag update using RevertedTagUpdateJob. (default: null) (since 1.36)
  • approved: whether the edit is somehow "approved" and the RevertedTagUpdateJob should be scheduled right away. Required only if EditResult::isRevert() is true. (boolean, default: false) (since 1.36)

Definition at line 1235 of file DerivedPageDataUpdater.php.

References MediaWiki\Revision\RevisionRecord\getId(), MediaWiki\Revision\RevisionRecord\getParentId(), MediaWiki\Revision\RevisionRecord\getSlots(), and MediaWiki\Revision\RevisionRecord\getUser().

◆ setArticleCountMethod()

MediaWiki\Storage\DerivedPageDataUpdater::setArticleCountMethod ( $articleCountMethod)
Parameters
string$articleCountMethod"any" or "link".
See also
$wgArticleCountMethod

Definition at line 550 of file DerivedPageDataUpdater.php.

◆ setCause()

MediaWiki\Storage\DerivedPageDataUpdater::setCause ( ?string $causeAction,
?string $causeAgent )

Set the cause action and cause agent, for logging and debugging.

If $causeAction or $causeAgent is null, any previously set value is preserved.

Parameters
?string$causeAction
?string$causeAgent
Returns
void

Definition at line 402 of file DerivedPageDataUpdater.php.

◆ setForceEmptyRevision()

MediaWiki\Storage\DerivedPageDataUpdater::setForceEmptyRevision ( bool $forceEmptyRevision)

Set whether null-edits should create a revision.

Enabling this allows the creation of dummy revisions ("null revisions") to mark events such as renaming in the page history.

Must not be called once prepareContent() or prepareUpdate() have been called.

Since
1.38
See also
PageUpdater setForceEmptyRevision
Parameters
bool$forceEmptyRevision

Definition at line 538 of file DerivedPageDataUpdater.php.

◆ setLogger()

MediaWiki\Storage\DerivedPageDataUpdater::setLogger ( LoggerInterface $logger)

Definition at line 389 of file DerivedPageDataUpdater.php.

◆ setRcWatchCategoryMembership()

MediaWiki\Storage\DerivedPageDataUpdater::setRcWatchCategoryMembership ( $rcWatchCategoryMembership)
Parameters
bool$rcWatchCategoryMembership
See also
$wgRCWatchCategoryMembership

Definition at line 558 of file DerivedPageDataUpdater.php.

◆ wasRedirect()

MediaWiki\Storage\DerivedPageDataUpdater::wasRedirect ( )

Whether the page was a redirect before the edit.

Returns
bool

Definition at line 1105 of file DerivedPageDataUpdater.php.


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