Rename ParserOutput::setCategoryLinks() and ::getCategoryLinks()

Make ::setCategory() consistent with the corresponding singular method,
which is ::addCategory(), not ::addCategoryLink().  Also, don't return
a value.

This renaming is in preparation for factoring out a write-only base
class from ParserOutput suitable to be used by Parsoid.

Note that OutputPage does distinguish a 'category link' from a
'category list', and there are separate OutputPage::getCategories()
and OutputPage::getCategoryLinks() methods.  However, the category
map in ParserOutput isn't exactly the same as either of these:
it's actually a map (or list of pairs) of category name to sort key.

Rename ParserOutput::getCategoryLinks() to ::getCategoryNames()
in order to clarify that the concept involved is not the same as
the OutputPage "category links" methods.

Code search:
https://codesearch.wmcloud.org/deployed/?q=-%3E(get%7Cset)CategoryLinks%5C(&i=nope&files=&excludeFiles=&repos=

(Note that many of the code search matches are for the methods in
OutputPage, which we are trying to disambiguate here.)

Bug: T287216
Change-Id: Idb383d3d9ef7b76f8a0208a057a3cb8c639465c9

RELEASE-NOTES-1.38

@@ -221,8 +221,10 @@ because of Phabricator reports.
    - ::setProperty()   - use ::setPageProperty()
    - ::unsetProperty() - use ::unsetPageProperties()
    - ::getProperties() - use ::getPageProperties()
-* The following methods were soft-deprecated; use ::setPreventClickjacking(..)
-  instead:
+* The following methods from the ParserOutput class were deprecated:
+   - ::getCategoryLinks() - use ::getCategoryNames()
+   - ::setCategoryLinks() - use ::setCategories()
+* The following methods were deprecated; use ::setPreventClickjacking() instead:
    - OutputPage::preventClickjacking()
    - OutputPage::allowClickjacking()
    - ImageHistoryList::preventClickjacking()

includes/parser/LinkHolderArray.php

@@ -407,7 +407,7 @@ class LinkHolderArray {
 		// process categories, check if a category exists in some variant
 		$categoryMap = []; // maps $category_variant => $category (dbkeys)
 		$varCategories = []; // category replacements oldDBkey => newDBkey
-		foreach ( $output->getCategoryLinks() as $category ) {
+		foreach ( $output->getCategoryNames() as $category ) {
 			$categoryTitle = Title::makeTitleSafe( NS_CATEGORY, $category );
 			$linkBatch->addObj( $categoryTitle );
 			$variants = $this->languageConverter->autoConvertToAllVariants( $category );
@@ -488,7 +488,7 @@ class LinkHolderArray {
 					// make the replacement
 					$newCats[$varCategories[$cat] ?? $cat] = $sortkey;
 				}
-				$output->setCategoryLinks( $newCats );
+				$output->setCategories( $newCats );
 			}
 		}
 	}

includes/parser/ParserOutput.php

@@ -61,7 +61,7 @@ class ParserOutput extends CacheTime {
 	private $mLanguageLinks;
 
 	/**
-	 * @var array Map of category names to sort keys
+	 * @var array<string,string> Map of category names to sort keys
 	 */
 	private $mCategories;
 
@@ -596,7 +596,23 @@ class ParserOutput extends CacheTime {
 		return $this->mInterwikiLinks;
 	}
 
+	/**
+	 * Return the names of the categories on this page.
+	 * @return array<string>
+	 * @deprecated since 1.38, use ::getCategoryNames() instead.
+	 */
 	public function getCategoryLinks() {
+		return $this->getCategoryNames();
+	}
+
+	/**
+	 * Return the names of the categories on this page.
+	 * Unlike ::getCategories(), sort keys are *not* included in the
+	 * return value.
+	 * @return array<string> The names of the categories
+	 * @since 1.38
+	 */
+	public function getCategoryNames(): array {
 		return array_keys( $this->mCategories );
 	}
 
@@ -750,6 +766,9 @@ class ParserOutput extends CacheTime {
 		return wfSetVar( $this->mLanguageLinks, $ll );
 	}
 
+	/**
+	 * @deprecated since 1.38, use ::setCategories() instead.
+	 */
 	public function setCategoryLinks( $cl ) {
 		return wfSetVar( $this->mCategories, $cl );
 	}
@@ -774,10 +793,24 @@ class ParserOutput extends CacheTime {
 		return wfSetVar( $this->mTimestamp, $timestamp );
 	}
 
-	public function addCategory( $c, $sort ) {
+	/**
+	 * Add a category.
+	 * @param string $c The category name
+	 * @param string $sort The sort key
+	 */
+	public function addCategory( $c, $sort ): void {
 		$this->mCategories[$c] = $sort;
 	}
 
+	/**
+	 * Overwrite the category map.
+	 * @param array<string,string> $c Map of category names to sort keys
+	 * @since 1.38
+	 */
+	public function setCategories( array $c ): void {
+		$this->mCategories = $c;
+	}
+
 	/**
 	 * @param string $id
 	 * @param string $content

includes/search/ParserOutputSearchDataExtractor.php

@@ -37,7 +37,7 @@ class ParserOutputSearchDataExtractor {
 	public function getCategories( ParserOutput $parserOutput ) {
 		$categories = [];
 
-		foreach ( $parserOutput->getCategoryLinks() as $key ) {
+		foreach ( $parserOutput->getCategoryNames() as $key ) {
 			$name = Category::newFromName( $key )->getName();
 			$categories[] = str_replace( '_', ' ', $name );
 		}

tests/phpunit/includes/ExtraParserTest.php

@@ -234,7 +234,7 @@ class ExtraParserTest extends MediaWikiIntegrationTestCase {
 		$cat = Title::makeTitleSafe( NS_CATEGORY, $catName );
 		$expected = [ $cat->getDBkey() ];
 		$parserOutput = $this->parser->parse( "[[file:nonexistent]]", $title, $this->options );
-		$result = $parserOutput->getCategoryLinks();
+		$result = $parserOutput->getCategoryNames();
 		$this->assertEquals( $expected, $result );
 	}
 
@@ -245,7 +245,7 @@ class ExtraParserTest extends MediaWikiIntegrationTestCase {
 		// Special pages shouldn't have tracking cats.
 		$title = SpecialPage::getTitleFor( 'Contributions' );
 		$parserOutput = $this->parser->parse( "[[file:nonexistent]]", $title, $this->options );
-		$result = $parserOutput->getCategoryLinks();
+		$result = $parserOutput->getCategoryNames();
 		$this->assertSame( [], $result );
 	}
 

tests/phpunit/includes/parser/ParserCacheSerializationTestCases.php

@@ -231,7 +231,7 @@ abstract class ParserCacheSerializationTestCases {
 					$testCase->assertNull( $object->getRevisionUsedSha1Base36() );
 					$testCase->assertArrayEquals( [], $object->getLanguageLinks() );
 					$testCase->assertArrayEquals( [], $object->getInterwikiLinks() );
-					$testCase->assertArrayEquals( [], $object->getCategoryLinks() );
+					$testCase->assertArrayEquals( [], $object->getCategoryNames() );
 					$testCase->assertArrayEquals( [], $object->getCategories() );
 					$testCase->assertArrayEquals( [], $object->getIndicators() );
 					$testCase->assertSame( '', $object->getTitleText() );
@@ -335,7 +335,7 @@ abstract class ParserCacheSerializationTestCases {
 						'interwiki1' => 1,
 						'interwiki2' => 1
 					] ], $object->getInterwikiLinks() );
-					$testCase->assertArrayEquals( [ 'category1', 'category2' ], $object->getCategoryLinks() );
+					$testCase->assertArrayEquals( [ 'category1', 'category2' ], $object->getCategoryNames() );
 					$testCase->assertArrayEquals( [
 						'category1' => 2,
 						'vategory2' => 1