Debian Codegraph @

vendor/ipl/web/src/FormElement/SearchSuggestions.php

raw
1 <?php
2
3 namespace ipl\Web\FormElement;
4
5 use ArrayIterator;
6 use Exception;
7 use ipl\Html\Attributes;
8 use ipl\Html\BaseHtmlElement;
9 use ipl\Html\HtmlElement;
10 use ipl\Html\Text;
11 use ipl\Html\ValidHtml;
12 use ipl\I18n\Translation;
13 use Psr\Http\Message\ServerRequestInterface;
14
15 use function ipl\Stdlib\yield_groups;
16
17 class SearchSuggestions extends BaseHtmlElement
18 {
19 use Translation;
20
21 protected $tag = 'ul';
22
23 /** @var iterable */
24 protected iterable $provider;
25
26 /** @var ?string */
27 protected ?string $failureMessage = null;
28
29 /** @var ?callable */
30 protected $groupingCallback;
31
32 /** @var ?string */
33 protected $searchTerm;
34
35 /** @var ?string */
36 protected $searchPattern;
37
38 /** @var ?string */
39 protected $originalValue;
40
41 /** @var string[] */
42 protected $excludeTerms = [];
43
44 /**
45 * Create new SearchSuggestions
46 *
47 * The provider must deliver terms in form of arrays with the following keys:
48 * * (required) search: The search value
49 * * label: A human-readable label
50 * * details: {@see ValidHtml} to render inside a button element instead of an input
51 * * class: A CSS class
52 * * title: A message shown upon hover on the term
53 *
54 * Any excess key is also transferred to the client, but currently unused.
55 *
56 * @param iterable $provider
57 */
58 public function __construct(iterable $provider = [])
59 {
60 $this->provider = $provider;
61 }
62
63 /**
64 * Show a failure message
65 *
66 * @param ?string $message
67 *
68 * @return $this
69 */
70 public function showFailureMessage(?string $message)
71 {
72 $this->failureMessage = $message;
73
74 return $this;
75 }
76
77 /**
78 * Set a callback to identify groups for terms delivered by the provider
79 *
80 * The callback must return a string which is used as label for the group.
81 * Its interface is: `function (array $data): string`
82 *
83 * @param callable $callback
84 *
85 * @return $this
86 */
87 public function setGroupingCallback(callable $callback): self
88 {
89 $this->groupingCallback = $callback;
90
91 return $this;
92 }
93
94 /**
95 * Get the callback used to identify groups for terms delivered by the provider
96 *
97 * @return ?callable
98 */
99 public function getGroupingCallback(): ?callable
100 {
101 return $this->groupingCallback;
102 }
103
104 /**
105 * Set the search term (can contain `*` wildcards)
106 *
107 * @param string $term
108 *
109 * @return $this
110 */
111 public function setSearchTerm(string $term): self
112 {
113 $this->searchTerm = $term;
114 $this->setSearchPattern(
115 '/' . str_replace(
116 '\\000',
117 '.*',
118 preg_quote(
119 str_replace(
120 '*',
121 "\0",
122 $term
123 ),
124 '/'
125 )
126 ) . '/i'
127 );
128
129 return $this;
130 }
131
132 /**
133 * Get the search term
134 *
135 * @return ?string
136 */
137 public function getSearchTerm(): ?string
138 {
139 return $this->searchTerm;
140 }
141
142 /**
143 * Set the search pattern used by {@see matchSearch}
144 *
145 * @param string $pattern
146 *
147 * @return $this
148 */
149 protected function setSearchPattern(string $pattern): self
150 {
151 $this->searchPattern = $pattern;
152
153 return $this;
154 }
155
156 /**
157 * Set the original search value
158 *
159 * The one without automatically added wildcards.
160 *
161 * @param string $term
162 *
163 * @return $this
164 */
165 public function setOriginalSearchValue(string $term): self
166 {
167 $this->originalValue = $term;
168
169 return $this;
170 }
171
172 /**
173 * Get the original search value
174 *
175 * @return ?string
176 */
177 public function getOriginalSearchValue(): ?string
178 {
179 return $this->originalValue;
180 }
181
182 /**
183 * Set the terms to exclude in the suggestion list
184 *
185 * @param string[] $terms
186 *
187 * @return $this
188 */
189 public function setExcludeTerms(array $terms): self
190 {
191 $this->excludeTerms = $terms;
192
193 return $this;
194 }
195
196 /**
197 * Get the terms to exclude in the suggestion list
198 *
199 * @return string[]
200 */
201 public function getExcludeTerms(): array
202 {
203 return $this->excludeTerms;
204 }
205
206 /**
207 * Match the given search term against the users search
208 *
209 * @param string $term
210 *
211 * @return bool Whether the search matches or not
212 */
213 public function matchSearch(string $term): bool
214 {
215 if (! $this->searchPattern || $this->searchPattern === '.*') {
216 return true;
217 }
218
219 return (bool) preg_match($this->searchPattern, $term);
220 }
221
222 /**
223 * Load suggestions as requested by the client
224 *
225 * @param ServerRequestInterface $request
226 *
227 * @return $this
228 */
229 public function forRequest(ServerRequestInterface $request): self
230 {
231 $requestData = static::parseRequest($request);
232 if ($requestData === null) {
233 return $this;
234 }
235
236 $this->setSearchTerm($requestData['term']['label']);
237 $this->setOriginalSearchValue($requestData['term']['search']);
238 $this->setExcludeTerms($requestData['exclude'] ?? []);
239
240 return $this;
241 }
242
243 protected function assembleSuggestions(): void
244 {
245 $groupingCallback = $this->getGroupingCallback();
246 if ($groupingCallback) {
247 $iterator = $this->provider;
248 if (is_array($iterator)) {
249 $iterator = new ArrayIterator($iterator);
250 }
251
252 $provider = yield_groups($iterator, $groupingCallback);
253 } else {
254 $provider = ['' => $this->provider];
255 }
256
257 /** @var iterable<?string, array<array<string, string|ValidHtml>>> $provider */
258 foreach ($provider as $group => $suggestions) {
259 if ($group) {
260 $this->addHtml(
261 new HtmlElement(
262 'li',
263 Attributes::create(['class' => 'suggestion-title']),
264 Text::create($group)
265 )
266 );
267 }
268
269 foreach ($suggestions as $data) {
270 $attributes = [
271 'type' => 'button',
272 'value' => $data['label'] ?? $data['search']
273 ];
274 $details = $data['details'] ?? null;
275 unset($data['details']);
276 foreach ($data as $name => $value) {
277 $attributes["data-$name"] = $value;
278 }
279
280 if ($details instanceof ValidHtml) {
281 $attributes['class'] = 'has-details';
282 $content = new HtmlElement(
283 'button',
284 Attributes::create($attributes),
285 $details
286 );
287 } else {
288 $content = new HtmlElement(
289 'input',
290 Attributes::create($attributes)
291 );
292 }
293
294 $this->addHtml(
295 new HtmlElement(
296 'li',
297 null,
298 $content
299 )
300 );
301 }
302 }
303 }
304
305 protected function assemble(): void
306 {
307 if ($this->failureMessage === null) {
308 try {
309 $this->assembleSuggestions();
310 } catch (Exception $e) {
311 $this->failureMessage = $e->getMessage();
312 $this->setContent(null);
313 }
314 }
315
316 if ($this->failureMessage !== null) {
317 $this->addHtml(new HtmlElement(
318 'li',
319 Attributes::create(['class' => 'failure-message']),
320 new HtmlElement('em', null, Text::create($this->translate('Can\'t search:'))),
321 Text::create($this->failureMessage)
322 ));
323 return;
324 }
325
326 if ($this->isEmpty()) {
327 $this->addHtml(new HtmlElement(
328 'li',
329 Attributes::create(['class' => 'nothing-to-suggest']),
330 new HtmlElement('em', null, Text::create($this->translate('Nothing to suggest')))
331 ));
332 }
333 }
334
335 /**
336 * Get the JSON-decoded body of a suggestion request
337 *
338 * Returns `null` for non-POST requests or an empty body
339 *
340 * @param ServerRequestInterface $request
341 *
342 * @return ?array<string, mixed>
343 */
344 public static function parseRequest(ServerRequestInterface $request): ?array
345 {
346 if ($request->getMethod() !== 'POST') {
347 return null;
348 }
349
350 /** @var array<string, array<int|string, string>> $requestData */
351 $requestData = json_decode($request->getBody()->read(8192), true);
352 if (empty($requestData)) {
353 return null;
354 }
355
356 return $requestData;
357 }
358 }