EntityContent::getTextForSummary() - Code Metrics - wikimedia/mediawiki-extensions-Wikibase - Measure and Improve Code Quality continuously with Scrutinizer

EntityContent::getTextForSummary() A
last analyzed 2020-11-13 17:34 UTC

↳ Parent: EntityContent

Complexity

Conditions	5
Paths	5

Size

Total Lines

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
dl	0
loc	30
rs	9.1288
c	0
b	0
f	0
cc	5
nc	5
nop	1

<?php

namespace Wikibase\Repo\Content;

use AbstractContent;
use Article;
use Content;
use Diff\Differ\MapDiffer;
use Diff\DiffOp\Diff\Diff;
use Diff\Patcher\MapPatcher;
use Diff\Patcher\PatcherException;
use Hooks;
use Language;
use LogicException;
use MediaWiki\MediaWikiServices;
use MWException;
use ParserOptions;
use ParserOutput;
use RequestContext;
use RuntimeException;
use Serializers\Exceptions\SerializationException;
use Status;
use Title;
use User;
use ValueValidators\Result;
use Wikibase\DataModel\Entity\EntityDocument;
use Wikibase\DataModel\Entity\EntityId;
use Wikibase\DataModel\Entity\EntityRedirect;
use Wikibase\DataModel\Term\LabelsProvider;
use Wikibase\Lib\Store\EntityRevision;
use Wikibase\Repo\ArrayValueCollector;
use Wikibase\Repo\FingerprintSearchTextGenerator;
use Wikibase\Repo\Validators\EntityValidator;
use Wikibase\Repo\WikibaseRepo;
use WikiPage;

/**
 * Abstract content object for articles representing Wikibase entities.
 *
 * For more information on the relationship between entities and wiki pages, see
 * docs/entity-storage.wiki.
 *
 * @license GPL-2.0-or-later
 * @author Jeroen De Dauw < [email protected] >
 * @author Daniel Kinzler
 * @author Bene* < [email protected] >
 *
 * @method \Wikibase\Repo\Content\EntityHandler getContentHandler()
 */
abstract class EntityContent extends AbstractContent {

	/**
	 * Flag for use with prepareSave(), indicating that no pre-save validation should be applied.
	 * Can be passed in via EditEntity::attemptSave, EntityStore::saveEntity,
	 * as well as WikiPage::doEditContent()
	 *
	 * @note: must not collide with the EDIT_XXX flags defined by MediaWiki core in Defines.php.
	 */
	const EDIT_IGNORE_CONSTRAINTS = 1024;

	/**
	 * @see Content::isValid()
	 *
	 * @return bool True if this content object is valid for saving. False if there is no entity, or
	 *  the entity does not have an ID set.
	 */
	public function isValid() {
		if ( $this->isRedirect() ) {
			// Under some circumstances, the handler will not support redirects,
			// but it's still possible to construct Content objects that represent
			// redirects. In such a case, make sure such Content objects are considered
			// invalid and do not get saved.
			return $this->getContentHandler()->supportsRedirects();
		}

		$holder = $this->getEntityHolder();
		return $holder !== null && $holder->getEntityId() !== null;
	}

	/**
	 * @see EntityContent::isCountable
	 *
	 * @param bool|null $hasLinks
	 *
	 * @return bool True if this is not a redirect and the item is not empty.
	 */
	public function isCountable( $hasLinks = null ) {
		return !$this->isRedirect() && !$this->isEmpty();
	}

	/**
	 * Returns the EntityRedirect represented by this EntityContent, or null if this
	 * EntityContent is not a redirect.
	 *
	 * @note This default implementation will fail if isRedirect() is true.
	 * Subclasses that support redirects must override getEntityRedirect().
	 *
	 * @throws LogicException
	 * @return EntityRedirect|null
	 */
	public function getEntityRedirect() {
		if ( $this->isRedirect() ) {
			throw new LogicException( 'EntityContent subclasses that support redirects must override getEntityRedirect()' );
		}

		return null;
	}

	/**
	 * Returns the entity contained by this entity content.
	 * Deriving classes typically have a more specific get method as
	 * for greater clarity and type hinting.
	 *
	 * @throws MWException when it's a redirect (targets will never be resolved)
	 * @throws LogicException if the content object is empty and does not contain an entity.
	 * @return EntityDocument
	 */
	abstract public function getEntity();

	/**
	 * Returns a holder for the entity contained in this EntityContent object.
	 *
	 * @throws MWException when it's a redirect (targets will never be resolved)
	 * @return EntityHolder|null
	 */
	abstract protected function getEntityHolder();

	/**
	 * @throws RuntimeException if the content object is empty or no entity ID is set
	 * @return EntityId
	 */
	public function getEntityId(): EntityId {
		if ( $this->isRedirect() ) {
			return $this->getEntityRedirect()->getEntityId();
		}

		$holder = $this->getEntityHolder();
		if ( $holder !== null ) {
			$id = $holder->getEntityId();
			if ( $id !== null ) {
				return $id;
			}
		}

		throw new RuntimeException( 'EntityContent was constructed without an EntityId!' );
	}

	/**
	 * Returns a ParserOutput object containing the HTML.
	 *
	 * @note this calls ParserOutput::recordOption( 'userlang' ) to split the cache
	 * by user language, and ParserOutput::recordOption( 'wb' ) to split the cache on
	 * EntityHandler::PARSER_VERSION.
	 *
	 * @see Content::getParserOutput
	 *
	 * @param Title $title
	 * @param int|null $revisionId
	 * @param ParserOptions|null $options
	 * @param bool $generateHtml
	 *
	 * @return ParserOutput
	 */
	public function getParserOutput(
		Title $title,
		$revisionId = null,
		ParserOptions $options = null,
		$generateHtml = true
	) {
		if ( $this->isRedirect() ) {
			return $this->getParserOutputForRedirect( $generateHtml );
		} else {
			if ( $options === null ) {
				$options = ParserOptions::newFromContext( RequestContext::getMain() );
			}

			$out = $this->getParserOutputFromEntityView( $revisionId, $options, $generateHtml );

			if ( !$options->getUserLangObj()->equals( RequestContext::getMain()->getLanguage() ) ) {
				// HACK: Don't save to parser cache if this is not in the user's lang: T199983.
				$out->updateCacheExpiry( 0 );
			}

			return $out;
		}
	}

	/**
	 * @note Will fail if this EntityContent does not represent a redirect.
	 *
	 * @param bool $generateHtml
	 *
	 * @return ParserOutput
	 */
	protected function getParserOutputForRedirect( $generateHtml ) {
		$output = new ParserOutput();
		$target = $this->getRedirectTarget();

		// Make sure to include the redirect link in pagelinks
		$output->addLink( $target );

		// Since the output depends on the user language, we must make sure
		// ParserCache::getKey() includes it in the cache key.
		$output->recordOption( 'userlang' );
		// And we need to include EntityHandler::PARSER_VERSION in the cache key too
		$output->recordOption( 'wb' );
		if ( $generateHtml ) {
			$chain = $this->getRedirectChain();
			$language = $this->getContentHandler()->getPageViewLanguage( $target );
			$html = Article::getRedirectHeaderHtml( $language, $chain, false );
			$output->setText( $html );
		}

		return $output;
	}

	/**
	 * @note Will fail if this EntityContent represents a redirect.
	 *
	 * @param int|null $revisionId
	 * @param ParserOptions $options
	 * @param bool $generateHtml
	 *
	 * @return ParserOutput
	 */
	protected function getParserOutputFromEntityView(
		$revisionId,
		ParserOptions $options,
		$generateHtml = true
	) {
		// @todo: move this to the ContentHandler
		$outputGenerator = WikibaseRepo::getDefaultInstance()->getEntityParserOutputGenerator(
			$this->getValidUserLanguage( $options->getUserLangObj() )
		);

		$entityRevision = $this->getEntityRevision( $revisionId );

		$output = $outputGenerator->getParserOutput( $entityRevision, $generateHtml );

		// Since the output depends on the user language, we must make sure
		// ParserCache::getKey() includes it in the cache key.
		$output->recordOption( 'userlang' );
		// And we need to include EntityHandler::PARSER_VERSION in the cache key too
		$output->recordOption( 'wb' );

		$this->applyEntityPageProperties( $output );

		return $output;
	}

	private function getValidUserLanguage( Language $language ) {
		if ( !Language::isValidBuiltInCode( $language->getCode() ) ) {
			return Language::factory( 'und' ); // T204791
		}

		return $language;
	}

	/**
	 * @param int|null $revisionId
	 *
	 * @return EntityRevision
	 */
	private function getEntityRevision( $revisionId = null ) {
		$entity = $this->getEntity();

		if ( $revisionId !== null ) {
			return new EntityRevision( $entity, $revisionId );
		}

		// Revision defaults to 0 (latest), which is desired and suitable in cases where
		// getParserOutput specifies no revision. (e.g. is called during save process
		// when revision id is unknown or not assigned yet)
		return new EntityRevision( $entity );
	}

	/**
	 * @return string A string representing the content in a way useful for building a full text
	 *         search index.
	 */
	public function getTextForSearchIndex() {
		if ( $this->isRedirect() ) {
			return '';
		}

		$searchTextGenerator = new FingerprintSearchTextGenerator();
		$text = $searchTextGenerator->generate( $this->getEntity() );

		if ( !Hooks::run( 'WikibaseTextForSearchIndex', [ $this, &$text ] ) ) {
			return '';
		}

		return $text;
	}

	/**
	 * @return string Returns the string representation of the redirect
	 * represented by this EntityContent (if any).
	 *
	 * @note Will fail if this EntityContent is not a redirect.
	 */
	protected function getRedirectText() {
		$target = $this->getRedirectTarget();
		return '#REDIRECT [[' . $target->getFullText() . ']]';
	}

	/**
	 * Get the keys within this Contents Entity JSON that should be removed for
	 * text passed to edit filters.
	 *
	 * @return string[] Keys to ignore
	 */
	abstract protected function getIgnoreKeysForFilters();

	/**
	 * @return string A string representing the content in a way useful for content filtering as
	 *         performed by extensions like AbuseFilter.
	 */
	public function getTextForFilters() {
		if ( $this->isRedirect() ) {
			return $this->getRedirectText();
		}

		// @todo this text for filters stuff should be it's own class with test coverage!
		$codec = WikibaseRepo::getDefaultInstance()->getEntityContentDataCodec();
		$json = $codec->encodeEntity( $this->getEntity(), CONTENT_FORMAT_JSON );
		$data = json_decode( $json, true );

		$values = ArrayValueCollector::collectValues( $data, $this->getIgnoreKeysForFilters() );

		return implode( "\n", $values );
	}

	/**
	 * @return string The wikitext to include when another page includes this  content, or false if
	 *         the content is not includable in a wikitext page.
	 */
	public function getWikitextForTransclusion() {
		return false;
	}

	/**
	 * Returns a textual representation of the content suitable for use in edit summaries and log messages.
	 *
	 * @param int $maxLength maximum length of the summary text
	 * @return string
	 * @throws MWException
	 */
	public function getTextForSummary( $maxLength = 250 ) {
		if ( $this->isRedirect() ) {
			return $this->getRedirectText();
		}

		$entity = $this->getEntity();

		// TODO: This assumes all entities not implementing their own getTextForSummary are LabelsProvider. Fix it.
		if ( !( $entity instanceof LabelsProvider ) ) {
			throw new LogicException(
				"Entity type {$entity->getType()} must implement its own getTextForSummary method."
			);
		}

		$labels = $entity->getLabels();
		if ( $labels->isEmpty() ) {
			return '';
		}

		$language = MediaWikiServices::getInstance()->getContentLanguage();

		if ( $labels->hasTermForLanguage( $language->getCode() ) ) {
			$label = $labels->getByLanguage( $language->getCode() )->getText();
			return $language->truncateForDatabase( $label, $maxLength );
		}

		// Return first term it can find
		$term = $labels->getIterator()->current();
		return $language->truncateForDatabase( $term->getText(), $maxLength );
	}

	/**
	 * Returns an array structure for the redirect represented by this EntityContent, if any.
	 *
	 * @note This may or may not be consistent with what EntityContentCodec does.
	 *       It it intended to be used primarily for diffing.
	 */
	private function getRedirectData() {
		// NOTE: keep in sync with getPatchedRedirect
		$data = [];

		if ( $this->isValid() ) {
			$data['entity'] = $this->getEntityId()->getSerialization();
		}

		if ( $this->isRedirect() ) {
			$data['redirect'] = $this->getEntityRedirect()->getTargetId()->getSerialization();
		}

		return $data;
	}

	/**
	 * @see Content::getNativeData
	 *
	 * @note Avoid relying on this method! It bypasses EntityContentCodec, and does
	 *       not make any guarantees about the structure of the array returned.
	 *
	 * @return array|EntityDocument An undefined data structure representing the content. This is
	 *  not guaranteed to conform to any serialization structure used in the database or externally.
	 */
	public function getNativeData() {
		if ( $this->isRedirect() ) {
			return $this->getRedirectData();
		}

		// NOTE: this may or may not be consistent with what EntityContentCodec does!
		$serializer = WikibaseRepo::getDefaultInstance()->getAllTypesEntitySerializer();
		try {
			return $serializer->serialize( $this->getEntity() );
		} catch ( SerializationException $ex ) {
			return $this->getEntity();
		}
	}

	/**
	 * returns the content's nominal size in bogo-bytes.
	 *
	 * @return int
	 */
	public function getSize() {
		return strlen( serialize( $this->getNativeData() ) );
	}

	/**
	 * Both contents will be considered equal if they have the same ID and equal Entity data. If
	 * one of the contents is considered "new", then matching IDs is not a criteria for them to be
	 * considered equal.
	 *
	 * @see Content::equals
	 *
	 * @param Content|null $that
	 *
	 * @return bool
	 */
	public function equals( Content $that = null ) {
		if ( $that === $this ) {
			return true;
		}

		if ( !( $that instanceof self ) || $that->getModel() !== $this->getModel() ) {
			return false;
		}

		$thisRedirect = $this->getRedirectTarget();
		$thatRedirect = $that->getRedirectTarget();

		if ( $thisRedirect !== null ) {
			if ( $thatRedirect === null ) {
				return false;
			} else {
				return $thisRedirect->equals( $thatRedirect )
					&& $this->getEntityRedirect()->equals( $that->getEntityRedirect() );
			}
		} elseif ( $thatRedirect !== null ) {
			return false;
		}

		$thisHolder = $this->getEntityHolder();
		$thatHolder = $that->getEntityHolder();
		if ( !$thisHolder && !$thatHolder ) {
			return true;
		} elseif ( !$thisHolder || !$thatHolder ) {
			return false;
		}

		$thisId = $thisHolder->getEntityId();
		$thatId = $thatHolder->getEntityId();
		if ( $thisId && $thatId && !$thisId->equals( $thatId ) ) {
			return false;
		}

		return $thisHolder->getEntity()->equals( $thatHolder->getEntity() );
	}

	/**
	 * @return EntityDocument
	 */
	private function makeEmptyEntity() {
		$handler = $this->getContentHandler();
		return $handler->makeEmptyEntity();
	}

	/**
	 * Returns a diff between this EntityContent and the given EntityContent.
	 *
	 * @param self $toContent
	 *
	 * @return EntityContentDiff
	 */
	public function getDiff( EntityContent $toContent ) {
		$fromContent = $this;

		$differ = new MapDiffer();
		$redirectDiffOps = $differ->doDiff(
			$fromContent->getRedirectData(),
			$toContent->getRedirectData()
		);

		$redirectDiff = new Diff( $redirectDiffOps, true );

		$fromEntity = ( $fromContent->isRedirect() || $fromContent->getEntityHolder() === null ) ?
			$this->makeEmptyEntity() : $fromContent->getEntity();
		$toEntity = ( $toContent->isRedirect() || $toContent->getEntityHolder() === null ) ?
			$this->makeEmptyEntity() : $toContent->getEntity();

		$entityDiffer = WikibaseRepo::getDefaultInstance()->getEntityDiffer();
		$entityDiff = $entityDiffer->diffEntities( $fromEntity, $toEntity );

		return new EntityContentDiff( $entityDiff, $redirectDiff, $fromEntity->getType() );
	}

	/**
	 * Returns a patched copy of this Content object.
	 *
	 * @param EntityContentDiff $patch
	 *
	 * @throws PatcherException
	 * @return self
	 */
	public function getPatchedCopy( EntityContentDiff $patch ) {
		$handler = $this->getContentHandler();

		if ( $this->isRedirect() ) {
			$entityAfterPatch = $this->makeEmptyEntity();
			$entityAfterPatch->setId( $this->getEntityId() );
		} else {
			$entityAfterPatch = $this->getEntity()->copy();
		}

		$patcher = WikibaseRepo::getDefaultInstance()->getEntityPatcher();
		$patcher->patchEntity( $entityAfterPatch, $patch->getEntityDiff() );

		$redirAfterPatch = $this->getPatchedRedirect( $patch->getRedirectDiff() );

		if ( $redirAfterPatch !== null && !$entityAfterPatch->isEmpty() ) {
			throw new PatcherException( 'EntityContent must not contain Entity data as well as'
				. ' a redirect after applying the patch!' );
		} elseif ( $redirAfterPatch ) {
			$patched = $handler->makeEntityRedirectContent( $redirAfterPatch );

			if ( !$patched ) {
				throw new PatcherException( 'Cannot create a redirect using content model '
					. $this->getModel() . '!' );
			}
		} else {
			$patched = $handler->makeEntityContent( new EntityInstanceHolder( $entityAfterPatch ) );
		}

		return $patched;
	}

	/**
	 * @param Diff $redirectPatch
	 *
	 * @return EntityRedirect|null
	 */
	private function getPatchedRedirect( Diff $redirectPatch ) {
		// See getRedirectData() for the structure of the data array.
		$redirData = $this->getRedirectData();

		if ( !$redirectPatch->isEmpty() ) {
			$patcher = new MapPatcher();
			$redirData = $patcher->patch( $redirData, $redirectPatch );
		}

		if ( isset( $redirData['redirect'] ) ) {
			$handler = $this->getContentHandler();

			$entityId = $this->getEntityId();
			$targetId = $handler->makeEntityId( $redirData['redirect'] );

			return new EntityRedirect( $entityId, $targetId );
		} else {
			return null;
		}
	}

	/**
	 * @return bool True if this is not a redirect and the page is empty.
	 */
	public function isEmpty() {
		if ( $this->isRedirect() ) {
			return false;
		}

		$holder = $this->getEntityHolder();
		return $holder === null || $holder->getEntity()->isEmpty();
	}

	/**
	 * @see Content::copy
	 *
	 * @return self
	 */
	public function copy() {
		$handler = $this->getContentHandler();

		if ( $this->isRedirect() ) {
			return $handler->makeEntityRedirectContent( $this->getEntityRedirect() );
		}

		$holder = $this->getEntityHolder();
		if ( $holder !== null ) {
			return $handler->makeEntityContent( new DeferredCopyEntityHolder( $holder ) );
		}

		// There is nothing mutable on an entirely empty content object.
		return $this;
	}

	/**
	 * @see Content::prepareSave
	 *
	 * @param WikiPage $page
	 * @param int $flags
	 * @param int $baseRevId
	 * @param User $user
	 *
	 * @return Status
	 */
	public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user ) {
		// Chain to parent
		$status = parent::prepareSave( $page, $flags, $baseRevId, $user );

		if ( $status->isOK() ) {
			if ( !$this->isRedirect() && !( $flags & self::EDIT_IGNORE_CONSTRAINTS ) ) {
				$handler = $this->getContentHandler();
				$validators = $handler->getOnSaveValidators(
					( $flags & EDIT_NEW ) !== 0,
					$this->getEntity()->getId()
				);
				$status = $this->applyValidators( $validators );
			}
		}

		return $status;
	}

	/**
	 * Apply the given validators.
	 *
	 * @param EntityValidator[] $validators
	 *
	 * @return Status
	 */
	private function applyValidators( array $validators ) {
		$result = Result::newSuccess();

		foreach ( $validators as $validator ) {
			$result = $validator->validateEntity( $this->getEntity() );

			if ( !$result->isValid() ) {
				break;
			}
		}

		$handler = $this->getContentHandler();
		$status = $handler->getValidationErrorLocalizer()->getResultStatus( $result );
		return $status;
	}

	/**
	 * Registers any properties returned by getEntityPageProperties()
	 * in $output.
	 *
	 * @param ParserOutput $output
	 */
	private function applyEntityPageProperties( ParserOutput $output ) {
		if ( $this->isRedirect() ) {
			return;
		}

		$properties = $this->getEntityPageProperties();
		foreach ( $properties as $name => $value ) {
			$output->setProperty( $name, $value );
		}
	}

	/**
	 * Returns a map of properties about the entity, to be recorded in
	 * MediaWiki's page_props table. The idea is to allow efficient lookups
	 * of entities based on such properties.
	 *
	 * @return array A map from property names to property values.
	 */
	public function getEntityPageProperties() {
		return [];
	}

}


1			<?php
2
3			namespace Wikibase\Repo\Content;
4
5			use AbstractContent;
6			use Article;
7			use Content;
8			use Diff\Differ\MapDiffer;
9			use Diff\DiffOp\Diff\Diff;
10			use Diff\Patcher\MapPatcher;
11			use Diff\Patcher\PatcherException;
12			use Hooks;
13			use Language;
14			use LogicException;
15			use MediaWiki\MediaWikiServices;
16			use MWException;
17			use ParserOptions;
18			use ParserOutput;
19			use RequestContext;
20			use RuntimeException;
21			use Serializers\Exceptions\SerializationException;
22			use Status;
23			use Title;
24			use User;
25			use ValueValidators\Result;
26			use Wikibase\DataModel\Entity\EntityDocument;
27			use Wikibase\DataModel\Entity\EntityId;
28			use Wikibase\DataModel\Entity\EntityRedirect;
29			use Wikibase\DataModel\Term\LabelsProvider;
30			use Wikibase\Lib\Store\EntityRevision;
31			use Wikibase\Repo\ArrayValueCollector;
32			use Wikibase\Repo\FingerprintSearchTextGenerator;
33			use Wikibase\Repo\Validators\EntityValidator;
34			use Wikibase\Repo\WikibaseRepo;
35			use WikiPage;
36
37			/**
38			* Abstract content object for articles representing Wikibase entities.
39			*
40			* For more information on the relationship between entities and wiki pages, see
41			* docs/entity-storage.wiki.
42			*
43			* @license GPL-2.0-or-later
44			* @author Jeroen De Dauw < [email protected] >
45			* @author Daniel Kinzler
46			* @author Bene* < [email protected] >
47			*
48			* @method \Wikibase\Repo\Content\EntityHandler getContentHandler()
49			*/
50			abstract class EntityContent extends AbstractContent {
51
52			/**
53			* Flag for use with prepareSave(), indicating that no pre-save validation should be applied.
54			* Can be passed in via EditEntity::attemptSave, EntityStore::saveEntity,
55			* as well as WikiPage::doEditContent()
56			*
57			* @note: must not collide with the EDIT_XXX flags defined by MediaWiki core in Defines.php.
58			*/
59			const EDIT_IGNORE_CONSTRAINTS = 1024;
60
61			/**
62			* @see Content::isValid()
63			*
64			* @return bool True if this content object is valid for saving. False if there is no entity, or
65			* the entity does not have an ID set.
66			*/
67			public function isValid() {
68			if ( $this->isRedirect() ) {
69			// Under some circumstances, the handler will not support redirects,
70			// but it's still possible to construct Content objects that represent
71			// redirects. In such a case, make sure such Content objects are considered
72			// invalid and do not get saved.
73			return $this->getContentHandler()->supportsRedirects();
74			}
75
76			$holder = $this->getEntityHolder();
77			return $holder !== null && $holder->getEntityId() !== null;
78			}
79
80			/**
81			* @see EntityContent::isCountable
82			*
83			* @param bool\|null $hasLinks
84			*
85			* @return bool True if this is not a redirect and the item is not empty.
86			*/
87			public function isCountable( $hasLinks = null ) {
88			return !$this->isRedirect() && !$this->isEmpty();
89			}
90
91			/**
92			* Returns the EntityRedirect represented by this EntityContent, or null if this
93			* EntityContent is not a redirect.
94			*
95			* @note This default implementation will fail if isRedirect() is true.
96			* Subclasses that support redirects must override getEntityRedirect().
97			*
98			* @throws LogicException
99			* @return EntityRedirect\|null
100			*/
101			public function getEntityRedirect() {
102			if ( $this->isRedirect() ) {
103			throw new LogicException( 'EntityContent subclasses that support redirects must override getEntityRedirect()' );
104			}
105
106			return null;
107			}
108
109			/**
110			* Returns the entity contained by this entity content.
111			* Deriving classes typically have a more specific get method as
112			* for greater clarity and type hinting.
113			*
114			* @throws MWException when it's a redirect (targets will never be resolved)
115			* @throws LogicException if the content object is empty and does not contain an entity.
116			* @return EntityDocument
117			*/
118			abstract public function getEntity();
119
120			/**
121			* Returns a holder for the entity contained in this EntityContent object.
122			*
123			* @throws MWException when it's a redirect (targets will never be resolved)
124			* @return EntityHolder\|null
125			*/
126			abstract protected function getEntityHolder();
127
128			/**
129			* @throws RuntimeException if the content object is empty or no entity ID is set
130			* @return EntityId
131			*/
132			public function getEntityId(): EntityId {
133			if ( $this->isRedirect() ) {
134			return $this->getEntityRedirect()->getEntityId();
135			}
136
137			$holder = $this->getEntityHolder();
138			if ( $holder !== null ) {
139			$id = $holder->getEntityId();
140			if ( $id !== null ) {
141			return $id;
142			}
143			}
144
145			throw new RuntimeException( 'EntityContent was constructed without an EntityId!' );
146			}
147
148			/**
149			* Returns a ParserOutput object containing the HTML.
150			*
151			* @note this calls ParserOutput::recordOption( 'userlang' ) to split the cache
152			* by user language, and ParserOutput::recordOption( 'wb' ) to split the cache on
153			* EntityHandler::PARSER_VERSION.
154			*
155			* @see Content::getParserOutput
156			*
157			* @param Title $title
158			* @param int\|null $revisionId
159			* @param ParserOptions\|null $options
160			* @param bool $generateHtml
161			*
162			* @return ParserOutput
163			*/
164			public function getParserOutput(
165			Title $title,
166			$revisionId = null,
167			ParserOptions $options = null,
168			$generateHtml = true
169			) {
170			if ( $this->isRedirect() ) {
171			return $this->getParserOutputForRedirect( $generateHtml );
172			} else {
173			if ( $options === null ) {
174			$options = ParserOptions::newFromContext( RequestContext::getMain() );
175			}
176
177			$out = $this->getParserOutputFromEntityView( $revisionId, $options, $generateHtml );
178
179			if ( !$options->getUserLangObj()->equals( RequestContext::getMain()->getLanguage() ) ) {
180			// HACK: Don't save to parser cache if this is not in the user's lang: T199983.
181			$out->updateCacheExpiry( 0 );
182			}
183
184			return $out;
185			}
186			}
187
188			/**
189			* @note Will fail if this EntityContent does not represent a redirect.
190			*
191			* @param bool $generateHtml
192			*
193			* @return ParserOutput
194			*/
195			protected function getParserOutputForRedirect( $generateHtml ) {
196			$output = new ParserOutput();
197			$target = $this->getRedirectTarget();
198
199			// Make sure to include the redirect link in pagelinks
200			$output->addLink( $target );
201
202			// Since the output depends on the user language, we must make sure
203			// ParserCache::getKey() includes it in the cache key.
204			$output->recordOption( 'userlang' );
205			// And we need to include EntityHandler::PARSER_VERSION in the cache key too
206			$output->recordOption( 'wb' );
207			if ( $generateHtml ) {
208			$chain = $this->getRedirectChain();
209			$language = $this->getContentHandler()->getPageViewLanguage( $target );
210			$html = Article::getRedirectHeaderHtml( $language, $chain, false );
211			$output->setText( $html );
212			}
213
214			return $output;
215			}
216
217			/**
218			* @note Will fail if this EntityContent represents a redirect.
219			*
220			* @param int\|null $revisionId
221			* @param ParserOptions $options
222			* @param bool $generateHtml
223			*
224			* @return ParserOutput
225			*/
226			protected function getParserOutputFromEntityView(
227			$revisionId,
228			ParserOptions $options,
229			$generateHtml = true
230			) {
231			// @todo: move this to the ContentHandler
232			$outputGenerator = WikibaseRepo::getDefaultInstance()->getEntityParserOutputGenerator(
233			$this->getValidUserLanguage( $options->getUserLangObj() )
234			);
235
236			$entityRevision = $this->getEntityRevision( $revisionId );
237
238			$output = $outputGenerator->getParserOutput( $entityRevision, $generateHtml );
239
240			// Since the output depends on the user language, we must make sure
241			// ParserCache::getKey() includes it in the cache key.
242			$output->recordOption( 'userlang' );
243			// And we need to include EntityHandler::PARSER_VERSION in the cache key too
244			$output->recordOption( 'wb' );
245
246			$this->applyEntityPageProperties( $output );
247
248			return $output;
249			}
250
251			private function getValidUserLanguage( Language $language ) {
252			if ( !Language::isValidBuiltInCode( $language->getCode() ) ) {
253			return Language::factory( 'und' ); // T204791
254			}
255
256			return $language;
257			}
258
259			/**
260			* @param int\|null $revisionId
261			*
262			* @return EntityRevision
263			*/
264			private function getEntityRevision( $revisionId = null ) {
265			$entity = $this->getEntity();
266
267			if ( $revisionId !== null ) {
268			return new EntityRevision( $entity, $revisionId );
269			}
270
271			// Revision defaults to 0 (latest), which is desired and suitable in cases where
272			// getParserOutput specifies no revision. (e.g. is called during save process
273			// when revision id is unknown or not assigned yet)
274			return new EntityRevision( $entity );
275			}
276
277			/**
278			* @return string A string representing the content in a way useful for building a full text
279			* search index.
280			*/
281			public function getTextForSearchIndex() {
282			if ( $this->isRedirect() ) {
283			return '';
284			}
285
286			$searchTextGenerator = new FingerprintSearchTextGenerator();
287			$text = $searchTextGenerator->generate( $this->getEntity() );
288
289			if ( !Hooks::run( 'WikibaseTextForSearchIndex', [ $this, &$text ] ) ) {
290			return '';
291			}
292
293			return $text;
294			}
295
296			/**
297			* @return string Returns the string representation of the redirect
298			* represented by this EntityContent (if any).
299			*
300			* @note Will fail if this EntityContent is not a redirect.
301			*/
302			protected function getRedirectText() {
303			$target = $this->getRedirectTarget();
304			return '#REDIRECT [[' . $target->getFullText() . ']]';
305			}
306
307			/**
308			* Get the keys within this Contents Entity JSON that should be removed for
309			* text passed to edit filters.
310			*
311			* @return string[] Keys to ignore
312			*/
313			abstract protected function getIgnoreKeysForFilters();
314
315			/**
316			* @return string A string representing the content in a way useful for content filtering as
317			* performed by extensions like AbuseFilter.
318			*/
319			public function getTextForFilters() {
320			if ( $this->isRedirect() ) {
321			return $this->getRedirectText();
322			}
323
324			// @todo this text for filters stuff should be it's own class with test coverage!
325			$codec = WikibaseRepo::getDefaultInstance()->getEntityContentDataCodec();
326			$json = $codec->encodeEntity( $this->getEntity(), CONTENT_FORMAT_JSON );
327			$data = json_decode( $json, true );
328
329			$values = ArrayValueCollector::collectValues( $data, $this->getIgnoreKeysForFilters() );
330
331			return implode( "\n", $values );
332			}
333
334			/**
335			* @return string The wikitext to include when another page includes this content, or false if
336			* the content is not includable in a wikitext page.
337			*/
338			public function getWikitextForTransclusion() {
339			return false;
340			}
341
342			/**
343			* Returns a textual representation of the content suitable for use in edit summaries and log messages.
344			*
345			* @param int $maxLength maximum length of the summary text
346			* @return string
347			* @throws MWException
348			*/
349			public function getTextForSummary( $maxLength = 250 ) {
350			if ( $this->isRedirect() ) {
351			return $this->getRedirectText();
352			}
353
354			$entity = $this->getEntity();
355
356			// TODO: This assumes all entities not implementing their own getTextForSummary are LabelsProvider. Fix it.
357			if ( !( $entity instanceof LabelsProvider ) ) {
358			throw new LogicException(
359			"Entity type {$entity->getType()} must implement its own getTextForSummary method."
360			);
361			}
362
363			$labels = $entity->getLabels();
364			if ( $labels->isEmpty() ) {
365			return '';
366			}
367
368			$language = MediaWikiServices::getInstance()->getContentLanguage();
369
370			if ( $labels->hasTermForLanguage( $language->getCode() ) ) {
371			$label = $labels->getByLanguage( $language->getCode() )->getText();
372			return $language->truncateForDatabase( $label, $maxLength );
373			}
374
375			// Return first term it can find
376			$term = $labels->getIterator()->current();
377			return $language->truncateForDatabase( $term->getText(), $maxLength );
378			}
379
380			/**
381			* Returns an array structure for the redirect represented by this EntityContent, if any.
382			*
383			* @note This may or may not be consistent with what EntityContentCodec does.
384			* It it intended to be used primarily for diffing.
385			*/
386			private function getRedirectData() {
387			// NOTE: keep in sync with getPatchedRedirect
388			$data = [];
389
390			if ( $this->isValid() ) {
391			$data['entity'] = $this->getEntityId()->getSerialization();
392			}
393
394			if ( $this->isRedirect() ) {
395			$data['redirect'] = $this->getEntityRedirect()->getTargetId()->getSerialization();
396			}
397
398			return $data;
399			}
400
401			/**
402			* @see Content::getNativeData
403			*
404			* @note Avoid relying on this method! It bypasses EntityContentCodec, and does
405			* not make any guarantees about the structure of the array returned.
406			*
407			* @return array\|EntityDocument An undefined data structure representing the content. This is
408			* not guaranteed to conform to any serialization structure used in the database or externally.
409			*/
410			public function getNativeData() {
411			if ( $this->isRedirect() ) {
412			return $this->getRedirectData();
413			}
414
415			// NOTE: this may or may not be consistent with what EntityContentCodec does!
416			$serializer = WikibaseRepo::getDefaultInstance()->getAllTypesEntitySerializer();
417			try {
418			return $serializer->serialize( $this->getEntity() );
419			} catch ( SerializationException $ex ) {
420			return $this->getEntity();
421			}
422			}
423
424			/**
425			* returns the content's nominal size in bogo-bytes.
426			*
427			* @return int
428			*/
429			public function getSize() {
430			return strlen( serialize( $this->getNativeData() ) );
431			}
432
433			/**
434			* Both contents will be considered equal if they have the same ID and equal Entity data. If
435			* one of the contents is considered "new", then matching IDs is not a criteria for them to be
436			* considered equal.
437			*
438			* @see Content::equals
439			*
440			* @param Content\|null $that
441			*
442			* @return bool
443			*/
444			public function equals( Content $that = null ) {
445			if ( $that === $this ) {
446			return true;
447			}
448
449			if ( !( $that instanceof self ) \|\| $that->getModel() !== $this->getModel() ) {
450			return false;
451			}
452
453			$thisRedirect = $this->getRedirectTarget();
454			$thatRedirect = $that->getRedirectTarget();
455
456			if ( $thisRedirect !== null ) {
457			if ( $thatRedirect === null ) {
458			return false;
459			} else {
460			return $thisRedirect->equals( $thatRedirect )
461			&& $this->getEntityRedirect()->equals( $that->getEntityRedirect() );
462			}
463			} elseif ( $thatRedirect !== null ) {
464			return false;
465			}
466
467			$thisHolder = $this->getEntityHolder();
468			$thatHolder = $that->getEntityHolder();
469			if ( !$thisHolder && !$thatHolder ) {
470			return true;
471			} elseif ( !$thisHolder \|\| !$thatHolder ) {
472			return false;
473			}
474
475			$thisId = $thisHolder->getEntityId();
476			$thatId = $thatHolder->getEntityId();
477			if ( $thisId && $thatId && !$thisId->equals( $thatId ) ) {
478			return false;
479			}
480
481			return $thisHolder->getEntity()->equals( $thatHolder->getEntity() );
482			}
483
484			/**
485			* @return EntityDocument
486			*/
487			private function makeEmptyEntity() {
488			$handler = $this->getContentHandler();
489			return $handler->makeEmptyEntity();
490			}
491
492			/**
493			* Returns a diff between this EntityContent and the given EntityContent.
494			*
495			* @param self $toContent
496			*
497			* @return EntityContentDiff
498			*/
499			public function getDiff( EntityContent $toContent ) {
500			$fromContent = $this;
501
502			$differ = new MapDiffer();
503			$redirectDiffOps = $differ->doDiff(
504			$fromContent->getRedirectData(),
505			$toContent->getRedirectData()
506			);
507
508			$redirectDiff = new Diff( $redirectDiffOps, true );
509
510			$fromEntity = ( $fromContent->isRedirect() \|\| $fromContent->getEntityHolder() === null ) ?
511			$this->makeEmptyEntity() : $fromContent->getEntity();
512			$toEntity = ( $toContent->isRedirect() \|\| $toContent->getEntityHolder() === null ) ?
513			$this->makeEmptyEntity() : $toContent->getEntity();
514
515			$entityDiffer = WikibaseRepo::getDefaultInstance()->getEntityDiffer();
516			$entityDiff = $entityDiffer->diffEntities( $fromEntity, $toEntity );
517
518			return new EntityContentDiff( $entityDiff, $redirectDiff, $fromEntity->getType() );
519			}
520
521			/**
522			* Returns a patched copy of this Content object.
523			*
524			* @param EntityContentDiff $patch
525			*
526			* @throws PatcherException
527			* @return self
528			*/
529			public function getPatchedCopy( EntityContentDiff $patch ) {
530			$handler = $this->getContentHandler();
531
532			if ( $this->isRedirect() ) {
533			$entityAfterPatch = $this->makeEmptyEntity();
534			$entityAfterPatch->setId( $this->getEntityId() );
535			} else {
536			$entityAfterPatch = $this->getEntity()->copy();
537			}
538
539			$patcher = WikibaseRepo::getDefaultInstance()->getEntityPatcher();
540			$patcher->patchEntity( $entityAfterPatch, $patch->getEntityDiff() );
541
542			$redirAfterPatch = $this->getPatchedRedirect( $patch->getRedirectDiff() );
543
544			if ( $redirAfterPatch !== null && !$entityAfterPatch->isEmpty() ) {
545			throw new PatcherException( 'EntityContent must not contain Entity data as well as'
546			. ' a redirect after applying the patch!' );
547			} elseif ( $redirAfterPatch ) {
548			$patched = $handler->makeEntityRedirectContent( $redirAfterPatch );
549
550			if ( !$patched ) {
551			throw new PatcherException( 'Cannot create a redirect using content model '
552			. $this->getModel() . '!' );
553			}
554			} else {
555			$patched = $handler->makeEntityContent( new EntityInstanceHolder( $entityAfterPatch ) );
556			}
557
558			return $patched;
559			}
560
561			/**
562			* @param Diff $redirectPatch
563			*
564			* @return EntityRedirect\|null
565			*/
566			private function getPatchedRedirect( Diff $redirectPatch ) {
567			// See getRedirectData() for the structure of the data array.
568			$redirData = $this->getRedirectData();
569
570			if ( !$redirectPatch->isEmpty() ) {
571			$patcher = new MapPatcher();
572			$redirData = $patcher->patch( $redirData, $redirectPatch );
573			}
574
575			if ( isset( $redirData['redirect'] ) ) {
576			$handler = $this->getContentHandler();
577
578			$entityId = $this->getEntityId();
579			$targetId = $handler->makeEntityId( $redirData['redirect'] );
580
581			return new EntityRedirect( $entityId, $targetId );
582			} else {
583			return null;
584			}
585			}
586
587			/**
588			* @return bool True if this is not a redirect and the page is empty.
589			*/
590			public function isEmpty() {
591			if ( $this->isRedirect() ) {
592			return false;
593			}
594
595			$holder = $this->getEntityHolder();
596			return $holder === null \|\| $holder->getEntity()->isEmpty();
597			}
598
599			/**
600			* @see Content::copy
601			*
602			* @return self
603			*/
604			public function copy() {
605			$handler = $this->getContentHandler();
606
607			if ( $this->isRedirect() ) {
608			return $handler->makeEntityRedirectContent( $this->getEntityRedirect() );
609			}
610
611			$holder = $this->getEntityHolder();
612			if ( $holder !== null ) {
613			return $handler->makeEntityContent( new DeferredCopyEntityHolder( $holder ) );
614			}
615
616			// There is nothing mutable on an entirely empty content object.
617			return $this;
618			}
619
620			/**
621			* @see Content::prepareSave
622			*
623			* @param WikiPage $page
624			* @param int $flags
625			* @param int $baseRevId
626			* @param User $user
627			*
628			* @return Status
629			*/
630			public function prepareSave( WikiPage $page, $flags, $baseRevId, User $user ) {
631			// Chain to parent
632			$status = parent::prepareSave( $page, $flags, $baseRevId, $user );
633
634			if ( $status->isOK() ) {
635			if ( !$this->isRedirect() && !( $flags & self::EDIT_IGNORE_CONSTRAINTS ) ) {
636			$handler = $this->getContentHandler();
637			$validators = $handler->getOnSaveValidators(
638			( $flags & EDIT_NEW ) !== 0,
639			$this->getEntity()->getId()
640			);
641			$status = $this->applyValidators( $validators );
642			}
643			}
644
645			return $status;
646			}
647
648			/**
649			* Apply the given validators.
650			*
651			* @param EntityValidator[] $validators
652			*
653			* @return Status
654			*/
655			private function applyValidators( array $validators ) {
656			$result = Result::newSuccess();
657
658			foreach ( $validators as $validator ) {
659			$result = $validator->validateEntity( $this->getEntity() );
660
661			if ( !$result->isValid() ) {
662			break;
663			}
664			}
665
666			$handler = $this->getContentHandler();
667			$status = $handler->getValidationErrorLocalizer()->getResultStatus( $result );
668			return $status;
669			}
670
671			/**
672			* Registers any properties returned by getEntityPageProperties()
673			* in $output.
674			*
675			* @param ParserOutput $output
676			*/
677			private function applyEntityPageProperties( ParserOutput $output ) {
678			if ( $this->isRedirect() ) {
679			return;
680			}
681
682			$properties = $this->getEntityPageProperties();
683			foreach ( $properties as $name => $value ) {
684			$output->setProperty( $name, $value );
685			}
686			}
687
688			/**
689			* Returns a map of properties about the entity, to be recorded in
690			* MediaWiki's page_props table. The idea is to allow efficient lookups
691			* of entities based on such properties.
692			*
693			* @return array A map from property names to property values.
694			*/
695			public function getEntityPageProperties() {
696			return [];
697			}
698
699			}
700

wikimedia / mediawiki-extensions-Wikibase

EntityContent::getTextForSummary() A last analyzed 2020-11-13 17:34 UTC

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like

EntityContent::getTextForSummary() A
last analyzed 2020-11-13 17:34 UTC