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, EntityTitleLookup $entityTitleLookup, SerializerFactory $serializerFactory, Serializer $entitySerializer, SiteLookup $siteLookup, PropertyDataTypeLookup $dataTypeLookup, $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 $fallbackChains=[])
	Get serialized entity for the EntityRevision and add it to the result alongside other needed properties.

	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)

	addPageInfoToRecord (array $record, EntityRevision $entityRevision)

	addEntityRedirectInfoToRecord (array $record, $sourceEntityIdSerialization, EntityId $entityId)

	getModifiedEntityArray (EntityDocument $entity, $props, ?array $filterSiteIds, array $filterLangCodes, array $fallbackChains)
	Gets the standard serialization of an EntityDocument and modifies it in a standard way.

	filterEntitySerializationUsingProps (array $serialization, $props)

	injectEntitySerializationWithSiteLinkUrls (array $serialization)

	sortEntitySerializationSiteLinks (array $serialization)

	injectEntitySerializationWithDataTypes (array $serialization)

	filterEntitySerializationUsingSiteIds (array $serialization, array $siteIds=null)

	addEntitySerializationFallbackInfo (array $serialization, array $fallbackChains)

	getTermsSerializationWithFallbackInfo (array $serialization, array $fallbackChains)

	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='')

	getArrayWithDataTypesInGroupedSnakListAtPath (array $array, $path)

	getReferenceArrayWithMetaData (array $array)

Private Attributes
	$result

	$entityTitleLookup

	$serializerFactory

	$entitySerializer

	$siteLookup

	$dataTypeLookup

	$addMetaData

	$modifier

	$callbackFactory

	$missingEntityCounter = -1

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,
		EntityTitleLookup	$entityTitleLookup,
		SerializerFactory	$serializerFactory,
		Serializer	$entitySerializer,
		SiteLookup	$siteLookup,
		PropertyDataTypeLookup	$dataTypeLookup,
			$addMetaData = `null`
	)

Parameters

ApiResult	$result
EntityTitleLookup	$entityTitleLookup
SerializerFactory	$serializerFactory
Serializer	$entitySerializer
SiteLookup	$siteLookup
PropertyDataTypeLookup	$dataTypeLookup
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	$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	$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	$fallbackChains = `[]`
	)

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
LanguageFallbackChain[]	$fallbackChains	with keys of the origional language

◆ addEntitySerializationFallbackInfo()

Wikibase\Repo\Api\ResultBuilder::addEntitySerializationFallbackInfo	(	array	$serialization,
		array	$fallbackChains
	)

private

Parameters

array	$serialization
LanguageFallbackChain[]	$fallbackChains

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	$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

◆ 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	$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	$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	$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	$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::doEditContent() 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	$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	$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	$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

◆ getArrayWithDataTypesInGroupedSnakListAtPath()

Wikibase\Repo\Api\ResultBuilder::getArrayWithDataTypesInGroupedSnakListAtPath	(	array	$array,
			$path
	)

private

Parameters

array	$array
string	$path

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	$fallbackChains
	)

private

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
LanguageFallbackChain[]	$fallbackChains

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	$fallbackChains
	)

private

Parameters

array	$serialization
LanguageFallbackChain[]	$fallbackChains

Returns: array

◆ injectEntitySerializationWithDataTypes()

Wikibase\Repo\Api\ResultBuilder::injectEntitySerializationWithDataTypes ( array $serialization )

private

◆ 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

◆ $callbackFactory

Wikibase\Repo\Api\ResultBuilder::$callbackFactory

private

◆ $dataTypeLookup

Wikibase\Repo\Api\ResultBuilder::$dataTypeLookup

private

◆ $entitySerializer

Wikibase\Repo\Api\ResultBuilder::$entitySerializer

private

◆ $entityTitleLookup

Wikibase\Repo\Api\ResultBuilder::$entityTitleLookup

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

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addAliasGroupList()

◆ addBasicEntityInformation()

◆ addDescriptions()

◆ addEntityInfoToRecord()

◆ addEntityRedirectInfoToRecord()

◆ addEntityRevision()

◆ addEntitySerializationFallbackInfo()

◆ addLabels()

◆ addMissingEntity()

◆ addNormalizedTitle()

◆ addPageInfoToRecord()

◆ addReference()

◆ addRemovedDescription()

◆ addRemovedLabel()

◆ addRemovedSiteLinks()

◆ addRemovedTerm()

◆ addRevisionIdFromStatusToResult()

◆ addSiteLinkList()

◆ addStatement()

◆ addStatements()

◆ addTermList()

◆ appendValue()

◆ checkKeyType()

◆ checkPathType()

◆ checkValueIsNotList()

◆ filterEntitySerializationUsingLangCodes()

◆ filterEntitySerializationUsingProps()

◆ filterEntitySerializationUsingSiteIds()

◆ getArrayWithAlteredClaims()

◆ getArrayWithDataTypesInGroupedSnakListAtPath()

◆ getClaimsArrayWithMetaData()

◆ getEntitySerializationWithMetaData()

◆ getModifiedEntityArray()

◆ getReferenceArrayWithMetaData()

◆ getSiteLinkListArrayWithMetaData()

◆ getSiteLinkListArrayWithUrls()

◆ getTermsSerializationWithFallbackInfo()

◆ injectEntitySerializationWithDataTypes()

◆ injectEntitySerializationWithSiteLinkUrls()

◆ markSuccess()

◆ setList()

◆ setValue()

◆ sortEntitySerializationSiteLinks()

Member Data Documentation

◆ $addMetaData

◆ $callbackFactory

◆ $dataTypeLookup

◆ $entitySerializer

◆ $entityTitleLookup

◆ $missingEntityCounter

◆ $modifier

◆ $result

◆ $serializerFactory

◆ $siteLookup