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	}