1	<?php
2
3	namespace CirrusSearch\Fallbacks;
4
5	use CirrusSearch\InterwikiResolver;
6	use CirrusSearch\Search\SearchQuery;
7
8	/**
9	* A fallback method is a way to interact (correct/fix/suggest a better query) with the search
10	* results.
11	*
12	* Multiple methods can be chained together the order in which they are applied is determined
13	* by the successApproximation method.
14	*
15	* The actual work is then done in the rewrite method where the method can actually change/augment
16	* the current resultset.
17	*
18	* @package CirrusSearch\Fallbacks
19	*/
20	interface FallbackMethod {
21
22	/**
23	* @param SearchQuery $query
24	* @param array $params
25	* @param InterwikiResolver $interwikiResolver
26	* @return FallbackMethod|null the method instance or null if unavailable
27	*/
28	public static function build( SearchQuery $query, array $params, InterwikiResolver $interwikiResolver );
29
30	/**
31	* Approximation of the success of this fallback method
32	* this evaluation must be fast and not access remote resources.
33	*
34	* The score is interpreted as :
35	* - 1.0: the engine can blindly execute this one and discard any others
36	*      (saving respective calls to successApproximation of other methods)
37	* - 0.5: e.g. when no approximation is possible
38	* - 0.0: should not be tried (safe to skip costly work)
39	*
40	* The order of application (call to the rewrite method) is the order of these scores.
41	* If the score of multiple methods is equals the initialization order is kept.
42	*
43	* @param FallbackRunnerContext $context
44	* @return float
45	*/
46	public function successApproximation( FallbackRunnerContext $context );
47
48	/**
49	* Rewrite the results.
50	*
51	* A costly call is allowed here. Result sets must not be changed directly,
52	* rather a FallbackStatus that applies the desired change must be returned.
53	*
54	* @param FallbackRunnerContext $context
55	* @return FallbackStatus
56	*/
57	public function rewrite( FallbackRunnerContext $context ): FallbackStatus;
58	}