1	<?php
2
3	namespace CirrusSearch;
4
5	use CirrusSearch\Extra\MultiList\MultiListBuilder;
6	use MediaWiki\Page\ProperPageIdentity;
7
8	/**
9	* Interface for changing weighted tags.
10	*
11	* @license GPL-2.0-or-later
12	*/
13	interface WeightedTagsUpdater {
14
15	public const SERVICE = self::class;
16
17	/**
18	* Request the setting of the {@link WeightedTagsHooks::FIELD_NAME} field for the given tag(s) and weight(s).
19	* Will set a `$tagPrefix/$tagName|$tagWeight` tag for each element of `$tagNames`, and will unset
20	* all other tags with the same prefix (in other words, this will replace the existing
21	* tag set for a given prefix).
22	*
23	* @param ProperPageIdentity $page
24	* @param string $tagPrefix A prefix shared by all `$tagNames`
25	* @param null|null[]|int[] $tagWeights Optional tag weights. A map of optional weights, keyed by tag name.
26	* *   Omit for tags which are fully defined by their prefix.
27	* *   A single weight ranges between 1-1000.
28	* @param 'revision'|null $trigger Optional indicator what triggered this update,
29	*     this hint is currently only processed by {@link EventBusWeightedTagsUpdater}
30	*
31	* @throws WeightedTagsException if sending the event fails
32	*
33	* @see MultiListBuilder for parameter details
34	*/
35	public function updateWeightedTags(
36	ProperPageIdentity $page,
37	string $tagPrefix,
38	?array $tagWeights = null,
39	?string $trigger = null
40	): void;
41
42	/**
43	* Request the reset of the {@link WeightedTagsHooks::FIELD_NAME} field for all tags prefixed with any of the
44	* `$tagPrefixes`.
45	*
46	* @param ProperPageIdentity $page
47	* @param string[] $tagPrefixes
48	* @param 'revision'|null $trigger optionally indicate what triggered this update,
49	*                                 this hint is currently only processed by {@link EventBusWeightedTagsUpdater}
50	*
51	* @throws WeightedTagsException if sending the event fails
52	*
53	* @see WeightedTagsBuilder for parameter details
54	*/
55	public function resetWeightedTags(
56	ProperPageIdentity $page,
57	array $tagPrefixes,
58	?string $trigger = null
59	): void;
60	}