HTMLFileCache: replace Title in method signatures

Bug: T278459
Change-Id: I77fb37c1aec17d3e51056f85fdff59821f326cc3

includes/cache/CacheKeyHelper.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup Cache
+ */
+
+namespace MediaWiki\Cache;
+
+use LogicException;
+use MediaWiki\Linker\LinkTarget;
+use MediaWiki\Page\PageReference;
+
+/**
+ * Helper class for mapping value objects representing basic entities to cache keys.
+ *
+ * Rationale:
+ * The logic for deriving the cache key should not be in the value object themselves for two reasons:
+ * Firstly, the value object should not contain knowledge about caching or keys in general.
+ * Secondly, all implementations of a given interface must have the exact same logic for deriving
+ * the cache key. Otherwise, caches will break when different implementations are used when
+ * interacting with a cache.
+ *
+ * Furthermore, the logic for deriving cache keys should not be in a service instance: there can
+ * only ever be one implementation, it must not depend on configuration, and it should never change.
+ *
+ * @ingroup Cache
+ */
+abstract class CacheKeyHelper {
+
+	/** Private constructor to defy instantiation. */
+	private function __construct() {
+		// we should never even get here...
+		throw new LogicException( 'Should not instantiate ' . __CLASS__ );
+	}
+
+	/**
+	 * @param LinkTarget|PageReference $page
+	 *
+	 * @return string
+	 */
+	public static function getKeyForPage( $page ): string {
+		return 'ns' . $page->getNamespace() . ':' . $page->getDBkey();
+	}
+}

includes/cache/HTMLFileCache.php

@@ -21,7 +21,9 @@
  * @ingroup Cache
  */
 
+use MediaWiki\Cache\CacheKeyHelper;
 use MediaWiki\MediaWikiServices;
+use MediaWiki\Page\PageIdentity;
 
 /**
  * Page view caching in the file system.
@@ -36,20 +38,19 @@ class HTMLFileCache extends FileCacheBase {
 	public const MODE_REBUILD = 2; // background cache rebuild mode
 
 	/**
-	 * @param Title|string $title Title object or prefixed DB key string
+	 * @param PageIdentity|string $page PageIdentity object or prefixed DB key string
 	 * @param string $action
+	 *
 	 * @throws InvalidArgumentException
 	 */
-	public function __construct( $title, $action ) {
+	public function __construct( $page, $action ) {
 		parent::__construct();
 
 		if ( !in_array( $action, self::cacheablePageActions() ) ) {
 			throw new InvalidArgumentException( 'Invalid file cache type given.' );
 		}
 
-		$this->mKey = ( $title instanceof Title )
-			? $title->getPrefixedDBkey()
-			: (string)$title;
+		$this->mKey = CacheKeyHelper::getKeyForPage( $page );
 		$this->mType = (string)$action;
 		$this->mExt = 'html';
 	}
@@ -220,17 +221,17 @@ class HTMLFileCache extends FileCacheBase {
 	/**
 	 * Clear the file caches for a page for all actions
 	 *
-	 * @param Title|string $title Title or prefixed DB key
+	 * @param PageIdentity|string $page PageIdentity object or prefixed DB key string
 	 * @return bool Whether $wgUseFileCache is enabled
 	 */
-	public static function clearFileCache( $title ) {
+	public static function clearFileCache( $page ) {
 		$config = MediaWikiServices::getInstance()->getMainConfig();
 		if ( !$config->get( 'UseFileCache' ) ) {
 			return false;
 		}
 
 		foreach ( self::cacheablePageActions() as $type ) {
-			$fc = new self( $title, $type );
+			$fc = new self( $page, $type );
 			$fc->clearCache();
 		}
 

tests/phpunit/unit/includes/cache/CacheKeyHelperTest.php

@@ -0,0 +1,30 @@
+<?php
+
+use MediaWiki\Cache\CacheKeyHelper;
+use MediaWiki\Page\PageIdentityValue;
+use MediaWiki\Page\PageReference;
+use MediaWiki\Page\PageReferenceValue;
+
+/**
+ * @group Cache
+ */
+class CacheKeyHelperTest extends MediaWikiUnitTestCase {
+
+	public function provideKeyForPage() {
+		// NOTE: code changes that break these test cases
+		//       will result in incompatible cache keys when deployed!
+
+		yield [ new PageReferenceValue( NS_USER, 'Yulduz', PageReference::LOCAL ), 'ns2:Yulduz' ];
+		yield [ new PageIdentityValue( 7, NS_USER, 'Yulduz', PageReference::LOCAL ), 'ns2:Yulduz' ];
+		yield [ Title::makeTitle( NS_USER, 'Yulduz' ), 'ns2:Yulduz' ];
+		yield [ new TitleValue( NS_USER, 'Yulduz' ), 'ns2:Yulduz' ];
+	}
+
+	/**
+	 * @dataProvider provideKeyForPage
+	 * @covers MediaWiki\Cache\CacheKeyHelper::getKeyForPage
+	 */
+	public function testKeyForPage( $page, $key ) {
+		$this->assertSame( $key, CacheKeyHelper::getKeyForPage( $page ) );
+	}
+}