Create HookRunner class and the hook handler interfaces

Bug: T338435
Change-Id: I34726d15dad5045f5c1b00ec7796b7b5f1516d12

hooks.txt

@@ -1,24 +0,0 @@
-This document describes MediaWiki hooks added by the TemplateStyles extension.
-See MediaWiki core's docs/hooks.txt for details on how hooks work.
-
-==Events and parameters==
-
-'TemplateStylesPropertySanitizer': Allows for adjusting or replacing the
-StylePropertySanitizer used when sanitizing style rules. For example, you might
-add, remove, or redefine known properties.
-&$propertySanitizer: Wikimedia\CSS\Sanitizer\StylePropertySanitizer to be used
- for sanitization.
-$matcherFactory: Wikimedia\CSS\Grammar\MatcherFactory being used, for use in
- adding or redefining known properties or replacing the entire sanitizer.
-
-'TemplateStylesStylesheetSanitizer': Allows for adjusting or replacing the
-StylesheetSanitizer. For example, you might add, remove, or redefine at-rule
-sanitizers.
-&$sanitizer: Wikimedia\CSS\Sanitizer\StylesheetSanitizer to be used for
- sanitization. The array returned by `$sanitizer->getRuleSanitizers()` will use
- the at-rule names (including the '@') as keys. The style rule sanitizer has
- key 'styles'.
-$propertySanitizer: Wikimedia\CSS\Sanitizer\StylePropertySanitizer being used
- for sanitization, for use in adding or redefining rule sanitizers.
-$matcherFactory: Wikimedia\CSS\Grammar\MatcherFactory being used, for use in
- adding or redefining rule sanitizers.

includes/Hooks.php

@@ -13,6 +13,7 @@ use ExtensionRegistry;
 use Html;
 use InvalidArgumentException;
 use MapCacheLRU;
+use MediaWiki\Extension\TemplateStyles\Hooks\HookRunner;
 use MediaWiki\MediaWikiServices;
 use MediaWiki\Revision\SlotRecord;
 use Parser;
@@ -107,8 +108,8 @@ class Hooks {
 				$propertySanitizer->getKnownProperties(),
 				array_flip( $config->get( 'TemplateStylesDisallowedProperties' ) )
 			) );
-			$hookContainer = MediaWikiServices::getInstance()->getHookContainer();
+			$hookRunner = new HookRunner( MediaWikiServices::getInstance()->getHookContainer() );
-			$hookContainer->run( 'TemplateStylesPropertySanitizer', [ &$propertySanitizer, $matcherFactory ] );
+			$hookRunner->onTemplateStylesPropertySanitizer( $propertySanitizer, $matcherFactory );
 
 			$htmlOrBodySimpleSelectorSeqMatcher = new CheckedMatcher(
 				$matcherFactory->cssSimpleSelectorSeq(),
@@ -175,8 +176,8 @@ class Hooks {
 			];
 			$allRuleSanitizers = array_diff_key( $allRuleSanitizers, $disallowedAtRules );
 			$sanitizer = new StylesheetSanitizer( $allRuleSanitizers );
-			$hookContainer->run( 'TemplateStylesStylesheetSanitizer',
+			$hookRunner->onTemplateStylesStylesheetSanitizer(
-				[ &$sanitizer, $propertySanitizer, $matcherFactory ]
+				$sanitizer, $propertySanitizer, $matcherFactory
 			);
 			self::$sanitizers[$key] = $sanitizer;
 		}

includes/Hooks/HookRunner.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace MediaWiki\Extension\TemplateStyles\Hooks;
+
+use MediaWiki\HookContainer\HookContainer;
+use Wikimedia\CSS\Grammar\MatcherFactory;
+use Wikimedia\CSS\Sanitizer\StylePropertySanitizer;
+use Wikimedia\CSS\Sanitizer\StylesheetSanitizer;
+
+/**
+ * This is a hook runner class, see docs/Hooks.md in core.
+ * @internal
+ */
+class HookRunner implements
+	TemplateStylesPropertySanitizerHook,
+	TemplateStylesStylesheetSanitizerHook
+{
+	private HookContainer $hookContainer;
+
+	public function __construct( HookContainer $hookContainer ) {
+		$this->hookContainer = $hookContainer;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onTemplateStylesPropertySanitizer(
+		StylePropertySanitizer &$propertySanitizer,
+		MatcherFactory $matcherFactory
+	) {
+		return $this->hookContainer->run(
+			'TemplateStylesPropertySanitizer',
+			[ &$propertySanitizer, $matcherFactory ]
+		);
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onTemplateStylesStylesheetSanitizer(
+		StylesheetSanitizer &$sanitizer,
+		StylePropertySanitizer $propertySanitizer,
+		MatcherFactory $matcherFactory
+	) {
+		return $this->hookContainer->run(
+			'TemplateStylesStylesheetSanitizer',
+			[ &$sanitizer, $propertySanitizer, $matcherFactory ]
+		);
+	}
+}

includes/Hooks/TemplateStylesPropertySanitizerHook.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace MediaWiki\Extension\TemplateStyles\Hooks;
+
+use Wikimedia\CSS\Grammar\MatcherFactory;
+use Wikimedia\CSS\Sanitizer\StylePropertySanitizer;
+
+/**
+ * This is a hook handler interface, see docs/Hooks.md in core.
+ * Use the hook name "TemplateStylesPropertySanitizer" to register handlers implementing this interface.
+ *
+ * @stable to implement
+ * @ingroup Hooks
+ */
+interface TemplateStylesPropertySanitizerHook {
+	/**
+	 * Allows for adjusting or replacing the StylePropertySanitizer used when sanitizing style rules.
+	 * For example, you might add, remove, or redefine known properties
+	 *
+	 * @param StylePropertySanitizer &$propertySanitizer StylePropertySanitizer to be used  for sanitization
+	 * @param MatcherFactory $matcherFactory MatcherFactory being used, for use in adding or redefining known
+	 *  properties or replacing the entire sanitizer
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onTemplateStylesPropertySanitizer(
+		StylePropertySanitizer &$propertySanitizer,
+		MatcherFactory $matcherFactory
+	);
+}

includes/Hooks/TemplateStylesStylesheetSanitizerHook.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace MediaWiki\Extension\TemplateStyles\Hooks;
+
+use Wikimedia\CSS\Grammar\MatcherFactory;
+use Wikimedia\CSS\Sanitizer\StylePropertySanitizer;
+use Wikimedia\CSS\Sanitizer\StylesheetSanitizer;
+
+/**
+ * This is a hook handler interface, see docs/Hooks.md in core.
+ * Use the hook name "TemplateStylesStylesheetSanitizer" to register handlers implementing this interface.
+ *
+ * @stable to implement
+ * @ingroup Hooks
+ */
+interface TemplateStylesStylesheetSanitizerHook {
+	/**
+	 * Allows for adjusting or replacing the StylesheetSanitizer.
+	 * For example, you might add, remove, or redefine at-rule sanitizers
+	 *
+	 * @param StylesheetSanitizer &$sanitizer StylesheetSanitizer to be used for sanitization.
+	 *  The array returned by `$sanitizer->getRuleSanitizers()` will use the at-rule names (including the '@') as keys.
+	 *  The style rule sanitizer has key 'styles'
+	 * @param StylePropertySanitizer $propertySanitizer StylePropertySanitizer being used for sanitization,
+	 *  for use in adding or redefining rule sanitizers
+	 * @param MatcherFactory $matcherFactory MatcherFactory being used, for use in adding or redefining rule sanitizers
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onTemplateStylesStylesheetSanitizer(
+		StylesheetSanitizer &$sanitizer,
+		StylePropertySanitizer $propertySanitizer,
+		MatcherFactory $matcherFactory
+	);
+}

tests/phpunit/unit/HookRunnerTest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace MediaWiki\Extension\TemplateStyles\Tests\Unit;
+
+use MediaWiki\Extension\TemplateStyles\Hooks\HookRunner;
+use MediaWiki\Tests\HookContainer\HookRunnerTestBase;
+
+/**
+ * @covers \MediaWiki\Extension\TemplateStyles\Hooks\HookRunner
+ */
+class HookRunnerTest extends HookRunnerTestBase {
+
+	public static function provideHookRunners() {
+		yield HookRunner::class => [ HookRunner::class ];
+	}
+}