1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\search\backend;
15
16	interface search_backend_interface
17	{
18	/**
19	* Returns the name of this search backend to be displayed to administrators
20	*
21	* @return string Name
22	*/
23	public function get_name(): string;
24
25	/**
26	* Returns if the search engine is available
27	*
28	* @return bool
29	*/
30	public function is_available(): bool;
31
32	/**
33	* Method executed when a search backend is set from acp.
34	*
35	* Checks permissions and paths, if everything is correct it generates the config file
36	*
37	* @return string|false False if everything was ok or string with error message
38	*/
39	public function init();
40
41	/**
42	* Returns the search_query
43	*
44	* @return string search query
45	*/
46	public function get_search_query(): string;
47
48	/**
49	* Returns the common_words array
50	*
51	* @return array common words that are ignored by search backend
52	*/
53	public function get_common_words(): array;
54
55	/**
56	* Returns the word_length array
57	*
58	* @return array|false min and max word length for searching
59	*/
60	public function get_word_length();
61
62	/**
63	* Splits keywords entered by a user into an array of words stored in $this->split_words
64	* This function fills $this->search_query with the cleaned user search query
65	*
66	* If $terms is 'any' then the words will be extracted from the search query
67	* and combined with | inside brackets. They will afterwards be treated like
68	* an standard search query.
69	*
70	* Then it analyses the query and fills the internal arrays $must_not_contain_ids,
71	* $must_contain_ids and $must_exclude_one_ids which are later used by keyword_search()
72	*
73	* @param    string    $keywords    contains the search query string as entered by the user
74	* @param    string    $terms        is either 'all' (use search query as entered, default words to 'must be contained in post')
75	*     or 'any' (find all posts containing at least one of the given words)
76	* @return    boolean                false if no valid keywords were found and otherwise true
77	*/
78	public function split_keywords(string &$keywords, string $terms): bool;
79
80	/**
81	* Performs a search on keywords depending on display specific params. You have to run split_keywords() first
82	*
83	* @param string $type contains either posts or topics depending on what should be searched for
84	* @param string $fields contains either titleonly (topic titles should be searched), msgonly (only message bodies should be searched), firstpost (only subject and body of the first post should be searched) or all (all post bodies and subjects should be searched)
85	* @param string $terms is either 'all' (use query as entered, words without prefix should default to "have to be in field") or 'any' (ignore search query parts and just return all posts that contain any of the specified words)
86	* @param array $sort_by_sql contains SQL code for the ORDER BY part of a query
87	* @param string $sort_key is the key of $sort_by_sql for the selected sorting
88	* @param string $sort_dir is either a or d representing ASC and DESC
89	* @param string $sort_days specifies the maximum amount of days a post may be old
90	* @param array $ex_fid_ary specifies an array of forum ids which should not be searched
91	* @param string $post_visibility specifies which types of posts the user can view in which forums
92	* @param int $topic_id is set to 0 or a topic id, if it is not 0 then only posts in this topic should be searched
93	* @param array $author_ary an array of author ids if the author should be ignored during the search the array is empty
94	* @param string $author_name specifies the author match, when ANONYMOUS is also a search-match
95	* @param array        &$id_ary passed by reference, to be filled with ids for the page specified by $start and $per_page, should be ordered
96	* @param int $start indicates the first index of the page
97	* @param int $per_page number of ids each page is supposed to contain
98	* @return    boolean|int                        total number of results
99	*/
100	public function keyword_search(string $type, string $fields, string $terms, array $sort_by_sql, string $sort_key, string $sort_dir, string $sort_days, array $ex_fid_ary, string $post_visibility, int $topic_id, array $author_ary, string $author_name, array &$id_ary, int &$start, int $per_page);
101
102	/**
103	* Performs a search on an author's posts without caring about message contents. Depends on display specific params
104	*
105	* @param string $type contains either posts or topics depending on what should be searched for
106	* @param boolean $firstpost_only if true, only topic starting posts will be considered
107	* @param array $sort_by_sql contains SQL code for the ORDER BY part of a query
108	* @param string $sort_key is the key of $sort_by_sql for the selected sorting
109	* @param string $sort_dir is either a or d representing ASC and DESC
110	* @param string $sort_days specifies the maximum amount of days a post may be old
111	* @param array $ex_fid_ary specifies an array of forum ids which should not be searched
112	* @param string $post_visibility specifies which types of posts the user can view in which forums
113	* @param int $topic_id is set to 0 or a topic id, if it is not 0 then only posts in this topic should be searched
114	* @param array $author_ary an array of author ids
115	* @param string $author_name specifies the author match, when ANONYMOUS is also a search-match
116	* @param array        &$id_ary passed by reference, to be filled with ids for the page specified by $start and $per_page, should be ordered
117	* @param int $start indicates the first index of the page
118	* @param int $per_page number of ids each page is supposed to contain
119	* @return    boolean|int                        total number of results
120	*/
121	public function author_search(string $type, bool $firstpost_only, array $sort_by_sql, string $sort_key, string $sort_dir, string $sort_days, array $ex_fid_ary, string $post_visibility, int $topic_id, array $author_ary, string $author_name, array &$id_ary, int &$start, int $per_page);
122
123	/**
124	* Returns if phrase search is supported or not
125	*
126	* @return bool
127	*/
128	public function supports_phrase_search(): bool;
129
130	/**
131	* Updates wordlist and wordmatch tables when a message is posted or changed
132	* Destroys cached search results, that contained one of the new words in a post so the results won't be outdated
133	*
134	* @param string $mode contains the post mode: edit, post, reply, quote ...
135	* @param int $post_id contains the post id of the post to index
136	* @param string $message contains the post text of the post
137	* @param string $subject contains the subject of the post to index
138	* @param int $poster_id contains the user id of the poster
139	* @param int $forum_id contains the forum id of parent forum of the post
140	*/
141	public function index(string $mode, int $post_id, string &$message, string &$subject, int $poster_id, int $forum_id);
142
143	/**
144	* Destroy cached results, that might be outdated after deleting a post
145	* @param array $post_ids
146	* @param array $author_ids
147	* @param array $forum_ids
148	*
149	* @return void
150	*/
151	public function index_remove(array $post_ids, array $author_ids, array $forum_ids): void;
152
153	/**
154	* Destroy old cache entries
155	*
156	* @return void
157	*/
158	public function tidy(): void;
159
160	/**
161	* Create fulltext index
162	*
163	* @param int $post_counter
164	* @return array|null array with current status or null if finished
165	*/
166	public function create_index(int &$post_counter = 0): ?array;
167
168	/**
169	* Drop fulltext index
170	*
171	* @param int $post_counter
172	* @return array|null array with current status or null if finished
173	*/
174	public function delete_index(int &$post_counter = 0): ?array;
175
176	/**
177	* Returns true if both FULLTEXT indexes exist
178	*
179	* @return bool
180	*/
181	public function index_created(): bool;
182
183	/**
184	* Returns an associative array containing information about the indexes
185	*
186	* @return array|false Language string of error false otherwise
187	*/
188	public function index_stats();
189
190	/**
191	* Display various options that can be configured for the backend from the acp
192	*
193	* @return array array containing template and config variables
194	*/
195	public function get_acp_options(): array;
196
197	/**
198	* Gets backend class
199	*
200	* @return string
201	*/
202	public function get_type(): string;
203	}