Wikibase
MediaWiki Wikibase extension
Wikibase\Repo\Api\EntitySavingHelper Class Reference

Helper class for api modules to save entities. More...

+ Inheritance diagram for Wikibase\Repo\Api\EntitySavingHelper:
+ Collaboration diagram for Wikibase\Repo\Api\EntitySavingHelper:

Public Member Functions

 __construct (bool $isWriteMode, $needsToken, RevisionLookup $revisionLookup, TitleFactory $titleFactory, EntityIdParser $idParser, EntityRevisionLookup $entityRevisionLookup, EntityTitleStoreLookup $entityTitleStoreLookup, ApiErrorReporter $errorReporter, SummaryFormatter $summaryFormatter, MediawikiEditEntityFactory $editEntityFactory, PermissionManager $permissionManager)
 
 getBaseRevisionId ()
 
 getSaveFlags ()
 
 getEntityFactory ()
 
 setEntityFactory (EntityFactory $entityFactory)
 
 getEntityStore ()
 
 setEntityStore (EntityStore $entityStore)
 
 loadEntity (array $requestParams, ?EntityId $entityId=null, $assignFreshId=self::ASSIGN_FRESH_ID)
 
 attemptSaveEntity (EntityDocument $entity, $summary, array $requestParams, IContextSource $context, int $flags=0)
 Attempts to save the new entity content, while first checking for permissions, edit conflicts, etc. More...
 
- Public Member Functions inherited from Wikibase\Repo\Api\EntityLoadingHelper
 __construct (RevisionLookup $revisionLookup, TitleFactory $titleFactory, EntityIdParser $idParser, EntityRevisionLookup $entityRevisionLookup, EntityTitleStoreLookup $entityTitleStoreLookup, ApiErrorReporter $errorReporter)
 
 getEntityIdParam ()
 Returns the name of the request parameter expected to contain the ID of the entity to load. More...
 
 setEntityIdParam ( $entityIdParam)
 Sets the name of the request parameter expected to contain the ID of the entity to load. More...
 
 setEntityByLinkedTitleLookup (EntityByLinkedTitleLookup $lookup)
 
 getDefaultRetrievalMode ()
 
 setDefaultRetrievalMode ( $defaultRetrievalMode)
 
 loadEntity (array $requestParams, EntityId $entityId=null)
 
 getEntityIdFromParams (array $params)
 

Public Attributes

const ASSIGN_FRESH_ID = 'assignFreshId'
 
const NO_FRESH_ID = 'noFreshId'
 

Private Member Functions

 isEntityCreationSupported ()
 
 createEntity ( $entityType, EntityId $customId=null, $assignFreshId=self::ASSIGN_FRESH_ID)
 Create an empty entity. More...
 
 evaluateTokenParam (array $params)
 
 handleSaveStatus (Status $status)
 Signal errors and warnings from a save operation to the API call's output. More...
 
 isArrayLike ( $value)
 Checks whether accessing array keys is safe, with e.g. More...
 
 handleStatus (Status $status, $errorCode)
 Include messages from a Status object in the API call's output. More...
 

Private Attributes

 $summaryFormatter
 
 $editEntityFactory
 
 $permissionManager
 
 $entitySavingFlags = 0
 
 $entityId = null
 
 $baseRevisionId = 0
 
 $entityFactory = null
 
 $entityStore = null
 
 $isApiModuleWriteMode = false
 
 $apiModuleNeedsToken = false
 

Additional Inherited Members

- Protected Member Functions inherited from Wikibase\Repo\Api\EntityLoadingHelper
 loadEntityRevision (EntityId $entityId, $revId=0, $mode=null)
 Load the entity content of the given revision. More...
 
- Protected Attributes inherited from Wikibase\Repo\Api\EntityLoadingHelper
 $revisionLookup
 
 $titleFactory
 
 $entityRevisionLookup
 
 $entityTitleStoreLookup
 
 $errorReporter
 
 $defaultRetrievalMode = LookupConstants::LATEST_FROM_REPLICA
 

Detailed Description

Helper class for api modules to save entities.

Author
Addshore
Daniel Kinzler

Constructor & Destructor Documentation

◆ __construct()

Wikibase\Repo\Api\EntitySavingHelper::__construct ( bool  $isWriteMode,
  $needsToken,
RevisionLookup  $revisionLookup,
TitleFactory  $titleFactory,
EntityIdParser  $idParser,
EntityRevisionLookup  $entityRevisionLookup,
EntityTitleStoreLookup  $entityTitleStoreLookup,
ApiErrorReporter  $errorReporter,
SummaryFormatter  $summaryFormatter,
MediawikiEditEntityFactory  $editEntityFactory,
PermissionManager  $permissionManager 
)

Member Function Documentation

◆ attemptSaveEntity()

Wikibase\Repo\Api\EntitySavingHelper::attemptSaveEntity ( EntityDocument  $entity,
  $summary,
array  $requestParams,
IContextSource  $context,
int  $flags = 0 
)

Attempts to save the new entity content, while first checking for permissions, edit conflicts, etc.

Saving is done via EditEntityHandler::attemptSave().

This method automatically takes into account several parameters:

  • 'bot' for setting the bot flag
  • 'baserevid' for determining the edit's base revision for conflict resolution
  • 'token' for the edit token
  • 'tags' for change tags, assuming they were already permission checked by ApiBase (i.e. PARAM_TYPE => 'tags')

If an error occurs, it is automatically reported and execution of the API module is terminated using the ApiErrorReporter (via handleStatus()). If there were any warnings, they will automatically be included in the API call's output (again, via handleStatus()).

Parameters
EntityDocument$entityThe entity to save
string | FormatableSummary$summaryThe edit summary
int$flagsThe edit flags (see WikiPage::doEditContent)
Exceptions
LogicExceptionif not in write mode
Returns
Status the status of the save operation, as returned by EditEntityHandler::attemptSave()
See also
EditEntityHandler::attemptSave()

◆ createEntity()

Wikibase\Repo\Api\EntitySavingHelper::createEntity (   $entityType,
EntityId  $customId = null,
  $assignFreshId = self::ASSIGN_FRESH_ID 
)
private

Create an empty entity.

Parameters
string | null$entityTypeThe type of entity to create. Optional if an ID is given.
EntityId | null$customIdOptionally assigns a specific ID instead of generating a new one.
string$assignFreshIdEither of the ASSIGN_FRESH_ID/NO_FRESH_ID constants NOTE: We usually need to assign an ID early, for things like the ClaimIdGenerator.
Exceptions
InvalidArgumentExceptionwhen entity type and ID are given but do not match.
ApiUsageException
LogicException
Returns
EntityDocument

◆ evaluateTokenParam()

Wikibase\Repo\Api\EntitySavingHelper::evaluateTokenParam ( array  $params)
private
Parameters
array$params
Returns
string|bool|null Token string, or false if not needed, or null if not set.

◆ getBaseRevisionId()

Wikibase\Repo\Api\EntitySavingHelper::getBaseRevisionId ( )

◆ getEntityFactory()

Wikibase\Repo\Api\EntitySavingHelper::getEntityFactory ( )

◆ getEntityStore()

Wikibase\Repo\Api\EntitySavingHelper::getEntityStore ( )

◆ getSaveFlags()

Wikibase\Repo\Api\EntitySavingHelper::getSaveFlags ( )

◆ handleSaveStatus()

Wikibase\Repo\Api\EntitySavingHelper::handleSaveStatus ( Status  $status)
private

Signal errors and warnings from a save operation to the API call's output.

This is much like handleStatus(), but specialized for Status objects returned by EditEntityHandler::attemptSave(). In particular, the 'errorFlags' and 'errorCode' fields from the status value are used to determine the error code to return to the caller.

Note
this function may or may not return normally, depending on whether the status is fatal or not.
See also
handleStatus().
Parameters
Status$statusThe status to report

◆ handleStatus()

Wikibase\Repo\Api\EntitySavingHelper::handleStatus ( Status  $status,
  $errorCode 
)
private

Include messages from a Status object in the API call's output.

An ApiErrorHandler is used to report the status, if necessary. If $status->isOK() is false, this method will terminate with an ApiUsageException.

Parameters
Status$statusThe status to report
string$errorCodeThe API error code to use in case $status->isOK() returns false
Exceptions
ApiUsageExceptionIf $status->isOK() returns false.

◆ isArrayLike()

Wikibase\Repo\Api\EntitySavingHelper::isArrayLike (   $value)
private

Checks whether accessing array keys is safe, with e.g.

See also
DeprecatablePropertyArray

◆ isEntityCreationSupported()

Wikibase\Repo\Api\EntitySavingHelper::isEntityCreationSupported ( )
private

◆ loadEntity()

Wikibase\Repo\Api\EntitySavingHelper::loadEntity ( array  $requestParams,
?EntityId  $entityId = null,
  $assignFreshId = self::ASSIGN_FRESH_ID 
)
Parameters
EntityId | null$entityIdID of the entity to load. If not given, the ID is taken from the request parameters. If $entityId is given, the 'baserevid' parameter must belong to it.
string$assignFreshIdWhether to allow assigning entity ids to new entities. Either of the ASSIGN_FRESH_ID/NO_FRESH_ID constants. NOTE: We usually need to assign an ID early, for things like the ClaimIdGenerator.
Exceptions
ApiUsageException
Returns
EntityDocument

◆ setEntityFactory()

Wikibase\Repo\Api\EntitySavingHelper::setEntityFactory ( EntityFactory  $entityFactory)

◆ setEntityStore()

Wikibase\Repo\Api\EntitySavingHelper::setEntityStore ( EntityStore  $entityStore)

Member Data Documentation

◆ $apiModuleNeedsToken

Wikibase\Repo\Api\EntitySavingHelper::$apiModuleNeedsToken = false
private

◆ $baseRevisionId

Wikibase\Repo\Api\EntitySavingHelper::$baseRevisionId = 0
private

◆ $editEntityFactory

Wikibase\Repo\Api\EntitySavingHelper::$editEntityFactory
private

◆ $entityFactory

Wikibase\Repo\Api\EntitySavingHelper::$entityFactory = null
private

◆ $entityId

Wikibase\Repo\Api\EntitySavingHelper::$entityId = null
private

◆ $entitySavingFlags

Wikibase\Repo\Api\EntitySavingHelper::$entitySavingFlags = 0
private

◆ $entityStore

Wikibase\Repo\Api\EntitySavingHelper::$entityStore = null
private

◆ $isApiModuleWriteMode

Wikibase\Repo\Api\EntitySavingHelper::$isApiModuleWriteMode = false
private

◆ $permissionManager

Wikibase\Repo\Api\EntitySavingHelper::$permissionManager
private

◆ $summaryFormatter

Wikibase\Repo\Api\EntitySavingHelper::$summaryFormatter
private

◆ ASSIGN_FRESH_ID

const Wikibase\Repo\Api\EntitySavingHelper::ASSIGN_FRESH_ID = 'assignFreshId'

◆ NO_FRESH_ID

const Wikibase\Repo\Api\EntitySavingHelper::NO_FRESH_ID = 'noFreshId'

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