Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | n/a |
0 / 0 |
n/a |
0 / 0 |
CRAP | n/a |
0 / 0 |
1 | <?php |
2 | |
3 | namespace CirrusSearch\Query; |
4 | |
5 | use CirrusSearch\CrossSearchStrategy; |
6 | use CirrusSearch\Parser\AST\KeywordFeatureNode; |
7 | use CirrusSearch\Search\SearchContext; |
8 | use CirrusSearch\SearchConfig; |
9 | use CirrusSearch\WarningCollector; |
10 | |
11 | /** |
12 | * Definition of a search keyword. |
13 | * |
14 | * This interface is being actively refactored, the initial behavior is to do all the |
15 | * work in the function apply( SearchContext $context, $term ). |
16 | * |
17 | * The aim is to clearly separate the parsing logic from the query building logic. |
18 | * |
19 | * - AST generation and parsing: must be idempotent and depend as little as possible on |
20 | * configuration variables. Output of the parsing will be KeywordFeatureNode. |
21 | * - CrossSearchStrategy evaluation |
22 | * - Expansion: for keyword needing to fetch external resources. |
23 | * - Query building |
24 | * |
25 | * The parsing behavior can be defined using the following methods: |
26 | * - getKeywordPrefixes() |
27 | * - allowEmptyValue() |
28 | * - hasValue() |
29 | * - greedy() |
30 | * - queryHeader() |
31 | * - getValueDelimiters() |
32 | * - parseValue() |
33 | * |
34 | * The keyword can define its CrossSearchStrategy to decide whether or not a query |
35 | * using this keyword can be applied to external wikis indices. |
36 | * |
37 | * For keywords that need to fetch data from external resource the method |
38 | * expand( KeywordFeatureNode $node, SearchConfig $config, WarningCollector $warningCollector ) |
39 | * can be used. Its return value will be made in a context available during query building. |
40 | * |
41 | * A keyword must not directly implement this interface but extends SimpleKeywordFeature. |
42 | * |
43 | * NOTE: since this interface is being refactored it's highly recommended to use and implement |
44 | * the dedicated method in the old all-in-one apply strategy (This "apply" strategy will be removed). |
45 | * |
46 | * @see SimpleKeywordFeature |
47 | * @see CrossSearchStrategy |
48 | * @see KeywordFeatureNode |
49 | */ |
50 | interface KeywordFeature { |
51 | /** |
52 | * List of keyword strings this implementation consumes |
53 | * @return string[] |
54 | */ |
55 | public function getKeywordPrefixes(); |
56 | |
57 | /** |
58 | * Whether this keyword allows empty value. |
59 | * @return bool true to allow the keyword to appear in an empty form |
60 | */ |
61 | public function allowEmptyValue(); |
62 | |
63 | /** |
64 | * Whether this keyword can have a value |
65 | * @return bool |
66 | */ |
67 | public function hasValue(); |
68 | |
69 | /** |
70 | * Whether this keyword is greedy consuming the rest of the string. |
71 | * NOTE: do not use, greedy keywords will eventually be removed in the future |
72 | * @return bool |
73 | */ |
74 | public function greedy(); |
75 | |
76 | /** |
77 | * Whether this keyword can appear only at the beginning of the query |
78 | * (excluding spaces) |
79 | * @return bool |
80 | */ |
81 | public function queryHeader(); |
82 | |
83 | /** |
84 | * Determine the name of the feature being set in SearchContext::addSyntaxUsed |
85 | * Defaults to $key |
86 | * |
87 | * @param string $key |
88 | * @param string $valueDelimiter the delimiter used to wrap the value |
89 | * @return string |
90 | * '"' when parsing keyword:"test" |
91 | * '' when parsing keyword:test |
92 | */ |
93 | public function getFeatureName( $key, $valueDelimiter ); |
94 | |
95 | /** |
96 | * List of value delimiters supported (must be an array of single byte char) |
97 | * @return string[][] list of delimiters options |
98 | */ |
99 | public function getValueDelimiters(); |
100 | |
101 | /** |
102 | * Parse the value of the keyword. |
103 | * NOTE: this function called prior to creating the node in the AST. |
104 | * It is not allowed to call external resources here (db, elastic, others). |
105 | * The data known by this method should only be the value contained in the user query string |
106 | * and maybe few config vars for sanity check purposes. |
107 | * |
108 | * @param string $key The keyword |
109 | * @param string $value The value attached to the keyword with quotes stripped and escaped |
110 | * quotes un-escaped. |
111 | * @param string $quotedValue The original value in the search string, including quotes if used |
112 | * @param string $valueDelimiter the delimiter char used to wrap the keyword value ('"' in intitle:"test") |
113 | * @param string $suffix the optional suffix used after the value ('i' in insource:/regex/i) |
114 | * @param WarningCollector $warningCollector |
115 | * @return array|null|false an array kept containing the information parsed, |
116 | * null when nothing is to be kept |
117 | * false when the value is refused (only allowed for keywords that allows empty value) |
118 | * @see self::allowEmptyValue |
119 | */ |
120 | public function parseValue( $key, $value, $quotedValue, $valueDelimiter, $suffix, WarningCollector $warningCollector ); |
121 | |
122 | /** |
123 | * Get support strategy for cross searching |
124 | * @param KeywordFeatureNode $node |
125 | * @return CrossSearchStrategy |
126 | */ |
127 | public function getCrossSearchStrategy( KeywordFeatureNode $node ); |
128 | |
129 | /** |
130 | * Expand the keyword potentially accessing external resources. |
131 | * Keywords that need to access the DB or any other external resources |
132 | * should implement this method. |
133 | * NOTE: this method will be called on every external wikis the search |
134 | * request will be made to. |
135 | * @param KeywordFeatureNode $node |
136 | * @param SearchConfig $config |
137 | * @param WarningCollector $warningCollector |
138 | * @return array a state containing the data the keyword fetched from an external resource |
139 | * The format of this array is only known by the keyword implementation and is stored in |
140 | * the query building context. |
141 | */ |
142 | public function expand( KeywordFeatureNode $node, SearchConfig $config, WarningCollector $warningCollector ); |
143 | |
144 | /** |
145 | * Checks $term for usage of the feature, and applies necessary filters, |
146 | * rescores, etc. to the provided $context. The returned $term will be |
147 | * passed on to other keyword features, and eventually to an elasticsearch |
148 | * QueryString query. |
149 | * |
150 | * @param SearchContext $context |
151 | * @param string $term The input search query |
152 | * @return string The remaining search query after processing |
153 | */ |
154 | public function apply( SearchContext $context, $term ); |
155 | } |