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.
	setList ( $path, $name, array $values, $tag)
	Adds a list of values for the given path and name.
	setValue ( $path, $name, $value)
	Set an atomic value (or record) for the given path and name.
	appendValue ( $path, $key, $value, $tag)
	Appends a value to the list at the given path.
	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.
	getModifiedEntityArray (EntityDocument $entity, $props, ?array $filterSiteIds, array $filterLangCodes, array $termFallbackChains)
	Gets the standard serialization of an EntityDocument and modifies it in a standard way.
	addBasicEntityInformation (EntityId $entityId, $path)
	Get serialized information for the EntityId and add them to result.
	addLabels (TermList $labels, $path)
	Get serialized labels and add them to result.
	addRemovedLabel ( $language, $path)
	Adds fake serialization to show a label has been removed.
	addDescriptions (TermList $descriptions, $path)
	Get serialized descriptions and add them to result.
	addRemovedDescription ( $language, $path)
	Adds fake serialization to show a label has been removed.
	addAliasGroupList (AliasGroupList $aliasGroupList, $path)
	Get serialized AliasGroupList and add it to result.
	addSiteLinkList (SiteLinkList $siteLinkList, $path, $addUrl=false)
	Get serialized sitelinks and add them to result.
	addRemovedSiteLinks (SiteLinkList $siteLinkList, $path)
	Adds fake serialization to show a sitelink has been removed.
	addStatements (StatementList $statements, $path, $props='all')
	Get serialized claims and add them to result.
	addStatement (Statement $statement)
	Get serialized claim and add it to result.
	addReference (Reference $reference)
	Get serialized reference and add it to result.
	addMissingEntity ( $key, array $missingDetails)
	Add an entry for a missing entity...
	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.

Private Member Functions
	checkPathType ( $path)
	checkKeyType ( $key)
	checkValueIsNotList ( $value)
	addEntityInfoToRecord (array $record, EntityId $entityId)
	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.
	addRemovedTerm ( $language, $name, $tag, $path)
	Adds fake serialization to show a term has been removed.
	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
	$addPageInfo

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.

Copyright

GPL-2.0-or-later

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	$addMetaData	when 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	$aliasGroupList	the AliasGroupList to set in the result
array | string | null	$path	where 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	$descriptions	the descriptions to insert in the result
array | string | null	$path	where 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	$sourceEntityIdSerialization	EntityId 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	$props	a list of fields to include, or "all"
string[] | null	$filterSiteIds	A list of site IDs to filter by
string[]	$filterLangCodes	A list of language codes to filter by
TermLanguageFallbackChain[]	$termFallbackChains	with 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	$labels	the labels to insert in the result
array | string | null	$path	where the data is located

addMissingEntity()

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

Add an entry for a missing entity...

Parameters

string | null	$key	The 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	$missingDetails	array containing key value pair missing details

addNormalizedTitle()

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

Parameters

string	$from
string	$to
string	$name

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 | null	$path	where 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 | null	$path	where 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 | null	$path	where 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 | null	$path	where 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	$status	The status to get the revision ID from.
string | null | array	$path	Where in the result to put the revision id
int | null	$oldRevId	The 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	$siteLinkList	the site links to insert in the result
array | string | null	$path	where 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	$statements	the labels to set in the result
array | string | null	$path	where the data is located
array | string	$props	a 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 | null	$path	where 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	$key	the key to use when appending, or null for automatic. May be ignored even if given, based on $this->addMetaData.
mixed	$value
string	$tag	tag name to use for $value in indexed mode

checkKeyType()

Wikibase\Repo\Api\ResultBuilder::checkKeyType ( $key )

private

Parameters

int | string | null

$key

the 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	$claimPath	to the claim array/arrays with trailing /

Returns

array

getClaimsArrayWithMetaData()

Wikibase\Repo\Api\ResultBuilder::getClaimsArrayWithMetaData ( array $array, $claimPath = '' )

private

Parameters

array	$array
string	$claimPath	to 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	$tag	tag 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

$addPageInfo

Wikibase\Repo\Api\ResultBuilder::$addPageInfo

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:

• repo/includes/Api/ResultBuilder.php