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

Builder of MediaWiki ApiResult objects with various convenience functions for adding Wikibase concepts and result parts to results in a uniform way. More...

Public Member Functions

 __construct (ApiResult $result, EntityTitleStoreLookup $entityTitleStoreLookup, SerializerFactory $serializerFactory, Serializer $entitySerializer, SiteLookup $siteLookup, PropertyDataTypeLookup $dataTypeLookup, EntityIdParser $entityIdParser, $addMetaData=null)
 
 markSuccess ( $success=true)
 Mark the ApiResult as successful. More...
 
 setList ( $path, $name, array $values, $tag)
 Adds a list of values for the given path and name. More...
 
 setValue ( $path, $name, $value)
 Set an atomic value (or record) for the given path and name. More...
 
 appendValue ( $path, $key, $value, $tag)
 Appends a value to the list at the given path. More...
 
 addEntityRevision ( $sourceEntityIdSerialization, EntityRevision $entityRevision, $props='all', array $filterSiteIds=null, array $filterLangCodes=[], array $termFallbackChains=[])
 Get serialized entity for the EntityRevision and add it to the result alongside other needed properties. More...
 
 getModifiedEntityArray (EntityDocument $entity, $props, ?array $filterSiteIds, array $filterLangCodes, array $termFallbackChains)
 Gets the standard serialization of an EntityDocument and modifies it in a standard way. More...
 
 addBasicEntityInformation (EntityId $entityId, $path)
 Get serialized information for the EntityId and add them to result. More...
 
 addLabels (TermList $labels, $path)
 Get serialized labels and add them to result. More...
 
 addRemovedLabel ( $language, $path)
 Adds fake serialization to show a label has been removed. More...
 
 addDescriptions (TermList $descriptions, $path)
 Get serialized descriptions and add them to result. More...
 
 addRemovedDescription ( $language, $path)
 Adds fake serialization to show a label has been removed. More...
 
 addAliasGroupList (AliasGroupList $aliasGroupList, $path)
 Get serialized AliasGroupList and add it to result. More...
 
 addSiteLinkList (SiteLinkList $siteLinkList, $path, $addUrl=false)
 Get serialized sitelinks and add them to result. More...
 
 addRemovedSiteLinks (SiteLinkList $siteLinkList, $path)
 Adds fake serialization to show a sitelink has been removed. More...
 
 addStatements (StatementList $statements, $path, $props='all')
 Get serialized claims and add them to result. More...
 
 addStatement (Statement $statement)
 Get serialized claim and add it to result. More...
 
 addReference (Reference $reference)
 Get serialized reference and add it to result. More...
 
 addMissingEntity ( $key, array $missingDetails)
 Add an entry for a missing entity... More...
 
 addNormalizedTitle ( $from, $to, $name='n')
 
 addRevisionIdFromStatusToResult (Status $status, $path, $oldRevId=null)
 Adds the ID of the new revision from the Status object to the API result structure. More...
 

Private Member Functions

 checkPathType ( $path)
 
 checkKeyType ( $key)
 
 checkValueIsNotList ( $value)
 
 addEntityInfoToRecord (array $record, EntityId $entityId)
 
 addPageInfoToRecord (array $record, EntityRevision $entityRevision)
 
 addEntityRedirectInfoToRecord (array $record, $sourceEntityIdSerialization, EntityId $entityId)
 
 filterEntitySerializationUsingProps (array $serialization, $props)
 
 injectEntitySerializationWithSiteLinkUrls (array $serialization)
 
 sortEntitySerializationSiteLinks (array $serialization)
 
 filterEntitySerializationUsingSiteIds (array $serialization, array $siteIds=null)
 
 addEntitySerializationFallbackInfo (array $serialization, array $termFallbackChains)
 
 getTermsSerializationWithFallbackInfo (array $serialization, array $termFallbackChains)
 
 filterEntitySerializationUsingLangCodes (array $serialization, array $langCodes)
 
 getEntitySerializationWithMetaData (array $serialization)
 
 addTermList (TermList $termList, $name, $tag, $path)
 Get serialized TermList and add it to the result. More...
 
 addRemovedTerm ( $language, $name, $tag, $path)
 Adds fake serialization to show a term has been removed. More...
 
 getSiteLinkListArrayWithUrls (array $array)
 
 getSiteLinkListArrayWithMetaData (array $array)
 
 getArrayWithAlteredClaims (array $array, $claimPath='')
 
 getClaimsArrayWithMetaData (array $array, $claimPath='')
 
 getReferenceArrayWithMetaData (array $array)
 

Private Attributes

 $result
 
 $entityTitleStoreLookup
 
 $serializerFactory
 
 $entitySerializer
 
 $siteLookup
 
 $dataTypeLookup
 
 $addMetaData
 
 $modifier
 
 $callbackFactory
 
 $missingEntityCounter = -1
 
 $dataTypeInjector
 
 $entityIdParser
 

Detailed Description

Builder of MediaWiki ApiResult objects with various convenience functions for adding Wikibase concepts and result parts to results in a uniform way.

This class was introduced when Wikibase was reduced from 2 sets of serializers (lib & data-model) to one. This class makes various modifications to the 1 standard serialization of Wikibase concepts for public exposure. The resulting format can be seen as the public serialization of Wikibase concepts.

Many concepts such as "tag name" relate to concepts explained within ApiResult.

Author
Addshore
Daniel Kinzler

Constructor & Destructor Documentation

◆ __construct()

Wikibase\Repo\Api\ResultBuilder::__construct ( ApiResult  $result,
EntityTitleStoreLookup  $entityTitleStoreLookup,
SerializerFactory  $serializerFactory,
Serializer  $entitySerializer,
SiteLookup  $siteLookup,
PropertyDataTypeLookup  $dataTypeLookup,
EntityIdParser  $entityIdParser,
  $addMetaData = null 
)
Parameters
ApiResult$result
EntityTitleStoreLookup$entityTitleStoreLookup
SerializerFactory$serializerFactory
Serializer$entitySerializer
SiteLookup$siteLookup
PropertyDataTypeLookup$dataTypeLookup
EntityIdParser$entityIdParser
bool | null$addMetaDatawhen special elements such as '_element' are needed

Member Function Documentation

◆ addAliasGroupList()

Wikibase\Repo\Api\ResultBuilder::addAliasGroupList ( AliasGroupList  $aliasGroupList,
  $path 
)

Get serialized AliasGroupList and add it to result.

Parameters
AliasGroupList$aliasGroupListthe AliasGroupList to set in the result
array | string$pathwhere the data is located

◆ addBasicEntityInformation()

Wikibase\Repo\Api\ResultBuilder::addBasicEntityInformation ( EntityId  $entityId,
  $path 
)

Get serialized information for the EntityId and add them to result.

Parameters
EntityId$entityId
string | array | null$path

◆ addDescriptions()

Wikibase\Repo\Api\ResultBuilder::addDescriptions ( TermList  $descriptions,
  $path 
)

Get serialized descriptions and add them to result.

Parameters
TermList$descriptionsthe descriptions to insert in the result
array | string$pathwhere the data is located

◆ addEntityInfoToRecord()

Wikibase\Repo\Api\ResultBuilder::addEntityInfoToRecord ( array  $record,
EntityId  $entityId 
)
private

◆ addEntityRedirectInfoToRecord()

Wikibase\Repo\Api\ResultBuilder::addEntityRedirectInfoToRecord ( array  $record,
  $sourceEntityIdSerialization,
EntityId  $entityId 
)
private

◆ addEntityRevision()

Wikibase\Repo\Api\ResultBuilder::addEntityRevision (   $sourceEntityIdSerialization,
EntityRevision  $entityRevision,
  $props = 'all',
array  $filterSiteIds = null,
array  $filterLangCodes = [],
array  $termFallbackChains = [] 
)

Get serialized entity for the EntityRevision and add it to the result alongside other needed properties.

Parameters
string | null$sourceEntityIdSerializationEntityId used to retrieve $entityRevision Used as the key for the entity in the 'entities' structure and for adding redirect info Will default to the entity's serialized ID if null. If given this must be the entity id before any redirects were resolved.
EntityRevision$entityRevision
string[] | string$propsa list of fields to include, or "all"
string[] | null$filterSiteIdsA list of site IDs to filter by
string[]$filterLangCodesA list of language codes to filter by
TermLanguageFallbackChain[]$termFallbackChainswith keys of the origional language

◆ addEntitySerializationFallbackInfo()

Wikibase\Repo\Api\ResultBuilder::addEntitySerializationFallbackInfo ( array  $serialization,
array  $termFallbackChains 
)
private
Parameters
array$serialization
TermLanguageFallbackChain[]$termFallbackChains
Returns
array

◆ addLabels()

Wikibase\Repo\Api\ResultBuilder::addLabels ( TermList  $labels,
  $path 
)

Get serialized labels and add them to result.

Parameters
TermList$labelsthe labels to insert in the result
array | string$pathwhere the data is located

◆ addMissingEntity()

Wikibase\Repo\Api\ResultBuilder::addMissingEntity (   $key,
array  $missingDetails 
)

Add an entry for a missing entity...

Parameters
string | null$keyThe key under which to place the missing entity in the 'entities' structure. If null, defaults to the 'id' field in $missingDetails if that is set; otherwise, it defaults to using a unique negative number.
array$missingDetailsarray containing key value pair missing details

◆ addNormalizedTitle()

Wikibase\Repo\Api\ResultBuilder::addNormalizedTitle (   $from,
  $to,
  $name = 'n' 
)
Parameters
string$from
string$to
string$name

◆ addPageInfoToRecord()

Wikibase\Repo\Api\ResultBuilder::addPageInfoToRecord ( array  $record,
EntityRevision  $entityRevision 
)
private

◆ addReference()

Wikibase\Repo\Api\ResultBuilder::addReference ( Reference  $reference)

Get serialized reference and add it to result.

Parameters
Reference$reference

◆ addRemovedDescription()

Wikibase\Repo\Api\ResultBuilder::addRemovedDescription (   $language,
  $path 
)

Adds fake serialization to show a label has been removed.

Parameters
string$language
array | string$pathwhere the data is located

◆ addRemovedLabel()

Wikibase\Repo\Api\ResultBuilder::addRemovedLabel (   $language,
  $path 
)

Adds fake serialization to show a label has been removed.

Parameters
string$language
array | string$pathwhere the data is located

◆ addRemovedSiteLinks()

Wikibase\Repo\Api\ResultBuilder::addRemovedSiteLinks ( SiteLinkList  $siteLinkList,
  $path 
)

Adds fake serialization to show a sitelink has been removed.

Parameters
SiteLinkList$siteLinkList
array | string$pathwhere the data is located

◆ addRemovedTerm()

Wikibase\Repo\Api\ResultBuilder::addRemovedTerm (   $language,
  $name,
  $tag,
  $path 
)
private

Adds fake serialization to show a term has been removed.

Parameters
string$language
string$name
string$tag
array | string$pathwhere the data is located

◆ addRevisionIdFromStatusToResult()

Wikibase\Repo\Api\ResultBuilder::addRevisionIdFromStatusToResult ( Status  $status,
  $path,
  $oldRevId = null 
)

Adds the ID of the new revision from the Status object to the API result structure.

The status value is expected to be structured in the way that EditEntity::attemptSave() resp WikiPage::doUserEditContent() do it: as an array, with an EntityRevision object in the 'revision' field. If $oldRevId is set and the latest edit was null, a 'nochange' flag is also added.

If no revision is found in the Status object, this method does nothing.

See also
ApiResult::addValue()
Parameters
Status$statusThe status to get the revision ID from.
string | null | array$pathWhere in the result to put the revision id
int | null$oldRevIdThe id of the latest revision of the entity before the last (possibly null) edit

◆ addSiteLinkList()

Wikibase\Repo\Api\ResultBuilder::addSiteLinkList ( SiteLinkList  $siteLinkList,
  $path,
  $addUrl = false 
)

Get serialized sitelinks and add them to result.

Todo:
use a SiteLinkListSerializer when created in DataModelSerialization here
Parameters
SiteLinkList$siteLinkListthe site links to insert in the result
array | string$pathwhere the data is located
bool$addUrl

◆ addStatement()

Wikibase\Repo\Api\ResultBuilder::addStatement ( Statement  $statement)

Get serialized claim and add it to result.

Parameters
Statement$statement

◆ addStatements()

Wikibase\Repo\Api\ResultBuilder::addStatements ( StatementList  $statements,
  $path,
  $props = 'all' 
)

Get serialized claims and add them to result.

Parameters
StatementList$statementsthe labels to set in the result
array | string$pathwhere the data is located
array | string$propsa list of fields to include, or "all"

◆ addTermList()

Wikibase\Repo\Api\ResultBuilder::addTermList ( TermList  $termList,
  $name,
  $tag,
  $path 
)
private

Get serialized TermList and add it to the result.

Parameters
TermList$termList
string$name
string$tag
array | string$pathwhere the data is located

◆ appendValue()

Wikibase\Repo\Api\ResultBuilder::appendValue (   $path,
  $key,
  $value,
  $tag 
)

Appends a value to the list at the given path.

This automatically sets the indexed tag name, if appropriate.

If the value is an array, it should be associative, not a list. For adding lists, use setList().

See also
ResultBuilder::setList()
ResultBuilder::setValue()
ApiResult::addValue
ApiResult::setIndexedTagName_internal
Parameters
array | string | null$path
int | string | null$keythe key to use when appending, or null for automatic. May be ignored even if given, based on $this->addMetaData.
mixed$value
string$tagtag name to use for $value in indexed mode

◆ checkKeyType()

Wikibase\Repo\Api\ResultBuilder::checkKeyType (   $key)
private
Parameters
int | string | null$keythe key to use when appending, or null for automatic.

◆ checkPathType()

Wikibase\Repo\Api\ResultBuilder::checkPathType (   $path)
private
Parameters
array | string | null$path

◆ checkValueIsNotList()

Wikibase\Repo\Api\ResultBuilder::checkValueIsNotList (   $value)
private
Parameters
mixed$value

◆ filterEntitySerializationUsingLangCodes()

Wikibase\Repo\Api\ResultBuilder::filterEntitySerializationUsingLangCodes ( array  $serialization,
array  $langCodes 
)
private
Parameters
array$serialization
string[]$langCodes
Returns
array

◆ filterEntitySerializationUsingProps()

Wikibase\Repo\Api\ResultBuilder::filterEntitySerializationUsingProps ( array  $serialization,
  $props 
)
private
Parameters
array$serialization
string | array$props
Returns
array

◆ filterEntitySerializationUsingSiteIds()

Wikibase\Repo\Api\ResultBuilder::filterEntitySerializationUsingSiteIds ( array  $serialization,
array  $siteIds = null 
)
private

◆ getArrayWithAlteredClaims()

Wikibase\Repo\Api\ResultBuilder::getArrayWithAlteredClaims ( array  $array,
  $claimPath = '' 
)
private
Parameters
array$array
string$claimPathto the claim array/arrays with trailing /
Returns
array

◆ getClaimsArrayWithMetaData()

Wikibase\Repo\Api\ResultBuilder::getClaimsArrayWithMetaData ( array  $array,
  $claimPath = '' 
)
private
Parameters
array$array
string$claimPathto the claim array/arrays with trailing /
Returns
array

◆ getEntitySerializationWithMetaData()

Wikibase\Repo\Api\ResultBuilder::getEntitySerializationWithMetaData ( array  $serialization)
private

◆ getModifiedEntityArray()

Wikibase\Repo\Api\ResultBuilder::getModifiedEntityArray ( EntityDocument  $entity,
  $props,
?array  $filterSiteIds,
array  $filterLangCodes,
array  $termFallbackChains 
)

Gets the standard serialization of an EntityDocument and modifies it in a standard way.

This code was created for Items and Properties and since new entity types have been introduced it may not work in the desired way.

See also
https://phabricator.wikimedia.org/T249206
ResultBuilder::addEntityRevision
Parameters
EntityDocument$entity
array | string$props
string[] | null$filterSiteIds
string[]$filterLangCodes
TermLanguageFallbackChain[]$termFallbackChains
Returns
array

◆ getReferenceArrayWithMetaData()

Wikibase\Repo\Api\ResultBuilder::getReferenceArrayWithMetaData ( array  $array)
private

◆ getSiteLinkListArrayWithMetaData()

Wikibase\Repo\Api\ResultBuilder::getSiteLinkListArrayWithMetaData ( array  $array)
private

◆ getSiteLinkListArrayWithUrls()

Wikibase\Repo\Api\ResultBuilder::getSiteLinkListArrayWithUrls ( array  $array)
private

◆ getTermsSerializationWithFallbackInfo()

Wikibase\Repo\Api\ResultBuilder::getTermsSerializationWithFallbackInfo ( array  $serialization,
array  $termFallbackChains 
)
private
Parameters
array$serialization
TermLanguageFallbackChain[]$termFallbackChains
Returns
array

◆ injectEntitySerializationWithSiteLinkUrls()

Wikibase\Repo\Api\ResultBuilder::injectEntitySerializationWithSiteLinkUrls ( array  $serialization)
private

◆ markSuccess()

Wikibase\Repo\Api\ResultBuilder::markSuccess (   $success = true)

Mark the ApiResult as successful.

{ "success": 1 }

Parameters
bool | int | null$success

◆ setList()

Wikibase\Repo\Api\ResultBuilder::setList (   $path,
  $name,
array  $values,
  $tag 
)

Adds a list of values for the given path and name.

This automatically sets the indexed tag name, if appropriate.

To set atomic values or records, use setValue() or appendValue().

See also
ApiResult::addValue
ApiResult::setIndexedTagName
ResultBuilder::setValue()
ResultBuilder::appendValue()
Parameters
array | string | null$path
string$name
array$values
string$tagtag name to use for elements of $values if not already present

◆ setValue()

Wikibase\Repo\Api\ResultBuilder::setValue (   $path,
  $name,
  $value 
)

Set an atomic value (or record) for the given path and name.

If the value is an array, it should be a record (associative), not a list. For adding lists, use setList().

See also
ResultBuilder::setList()
ResultBuilder::appendValue()
ApiResult::addValue
Parameters
array | string | null$path
string$name
mixed$value

◆ sortEntitySerializationSiteLinks()

Wikibase\Repo\Api\ResultBuilder::sortEntitySerializationSiteLinks ( array  $serialization)
private

Member Data Documentation

◆ $addMetaData

Wikibase\Repo\Api\ResultBuilder::$addMetaData
private

◆ $callbackFactory

Wikibase\Repo\Api\ResultBuilder::$callbackFactory
private

◆ $dataTypeInjector

Wikibase\Repo\Api\ResultBuilder::$dataTypeInjector
private

◆ $dataTypeLookup

Wikibase\Repo\Api\ResultBuilder::$dataTypeLookup
private

◆ $entityIdParser

Wikibase\Repo\Api\ResultBuilder::$entityIdParser
private

◆ $entitySerializer

Wikibase\Repo\Api\ResultBuilder::$entitySerializer
private

◆ $entityTitleStoreLookup

Wikibase\Repo\Api\ResultBuilder::$entityTitleStoreLookup
private

◆ $missingEntityCounter

Wikibase\Repo\Api\ResultBuilder::$missingEntityCounter = -1
private

◆ $modifier

Wikibase\Repo\Api\ResultBuilder::$modifier
private

◆ $result

Wikibase\Repo\Api\ResultBuilder::$result
private

◆ $serializerFactory

Wikibase\Repo\Api\ResultBuilder::$serializerFactory
private

◆ $siteLookup

Wikibase\Repo\Api\ResultBuilder::$siteLookup
private

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