Debian Codegraph @

vendor/ipl/stdlib/src/Filter.php

raw
1 <?php
2
3 namespace ipl\Stdlib;
4
5 use ipl\Stdlib\Filter\All;
6 use ipl\Stdlib\Filter\Any;
7 use ipl\Stdlib\Filter\Chain;
8 use ipl\Stdlib\Filter\Condition;
9 use ipl\Stdlib\Filter\Equal;
10 use ipl\Stdlib\Filter\GreaterThan;
11 use ipl\Stdlib\Filter\GreaterThanOrEqual;
12 use ipl\Stdlib\Filter\LessThan;
13 use ipl\Stdlib\Filter\LessThanOrEqual;
14 use ipl\Stdlib\Filter\Like;
15 use ipl\Stdlib\Filter\None;
16 use ipl\Stdlib\Filter\Rule;
17 use ipl\Stdlib\Filter\Unequal;
18 use ipl\Stdlib\Filter\Unlike;
19
20 /**
21 * Build filter rules and evaluate them against rows
22 */
23 class Filter
24 {
25 /**
26 * Create a new Filter
27 *
28 * Intentionally protected; use the static factory methods instead.
29 */
30 protected function __construct()
31 {
32 }
33
34 /**
35 * Check whether the given rule matches the given item
36 *
37 * @param Rule $rule
38 * @param array|object $row
39 *
40 * @return bool
41 */
42 public static function match(Rule $rule, array|object $row): bool
43 {
44 if (! is_object($row)) {
45 $row = (object) $row;
46 }
47
48 return (new self())->performMatch($rule, $row);
49 }
50
51 /**
52 * Create a rule that matches if **all** of the given rules do
53 *
54 * If no rules are given, the resulting rule always matches.
55 *
56 * @param Rule ...$rules
57 *
58 * @return Chain
59 */
60 public static function all(Rule ...$rules): Chain
61 {
62 return new All(...$rules);
63 }
64
65 /**
66 * Return whether the given rules all match the given item
67 *
68 * @param All $rules
69 * @param object $row
70 *
71 * @return bool True if all rules match; always true if no rules are given
72 */
73 protected function matchAll(All $rules, object $row): bool
74 {
75 foreach ($rules as $rule) {
76 if (! $this->performMatch($rule, $row)) {
77 return false;
78 }
79 }
80
81 return true;
82 }
83
84 /**
85 * Create a rule that matches if **any** of the given rules do
86 *
87 * If no rules are given, the resulting rule never matches.
88 *
89 * @param Rule ...$rules
90 *
91 * @return Chain
92 */
93 public static function any(Rule ...$rules): Chain
94 {
95 return new Any(...$rules);
96 }
97
98 /**
99 * Return whether any of the given rules match the given item
100 *
101 * @param Any $rules
102 * @param object $row
103 *
104 * @return bool True if any rule matches; always false if no rules are given
105 */
106 protected function matchAny(Any $rules, object $row): bool
107 {
108 foreach ($rules as $rule) {
109 if ($this->performMatch($rule, $row)) {
110 return true;
111 }
112 }
113
114 return false;
115 }
116
117 /**
118 * Create a rule that matches if **none** of the given rules do
119 *
120 * If no rules are given, the resulting rule always matches.
121 *
122 * @param Rule ...$rules
123 *
124 * @return Chain
125 */
126 public static function none(Rule ...$rules): Chain
127 {
128 return new None(...$rules);
129 }
130
131 /**
132 * Return whether none of the given rules match the given item
133 *
134 * @param None $rules
135 * @param object $row
136 *
137 * @return bool True if no rules match; always true if no rules are given
138 */
139 protected function matchNone(None $rules, object $row): bool
140 {
141 foreach ($rules as $rule) {
142 if ($this->performMatch($rule, $row)) {
143 return false;
144 }
145 }
146
147 return true;
148 }
149
150 /**
151 * Create a rule that matches rows with a column that **equals** the given value
152 *
153 * @param string $column
154 * @param mixed $value
155 *
156 * @return Condition
157 */
158 public static function equal(string $column, mixed $value): Condition
159 {
160 return new Equal($column, $value);
161 }
162
163 /**
164 * Return whether the given rule's value equals the given item's value
165 *
166 * @param Equal|Unequal $rule
167 * @param object $row
168 *
169 * @return bool
170 */
171 protected function matchEqual(Equal|Unequal $rule, object $row): bool
172 {
173 $rowValue = $this->extractValue($rule->getColumn(), $row);
174 $value = $rule->getValue();
175 $this->normalizeTypes($rowValue, $value);
176
177 if (! is_array($rowValue)) {
178 $rowValue = [$rowValue];
179 }
180
181 foreach ($rowValue as $rowVal) {
182 if ($this->performEqualityMatch($value, $rowVal, $rule->ignoresCase())) {
183 return true;
184 }
185 }
186
187 return false;
188 }
189
190 /**
191 * Create a rule that matches rows with a column that is **similar** to the given value
192 *
193 * Performs a wildcard search if the value contains asterisks.
194 *
195 * @param string $column
196 * @param mixed $value
197 *
198 * @return Condition
199 */
200 public static function like(string $column, mixed $value): Condition
201 {
202 return new Like($column, $value);
203 }
204
205 /**
206 * Return whether the given rule's value is similar to the given item's value
207 *
208 * @param Like|Unlike $rule
209 * @param object $row
210 *
211 * @return bool
212 */
213 protected function matchSimilar(Like|Unlike $rule, object $row): bool
214 {
215 $rowValue = $this->extractValue($rule->getColumn(), $row);
216 $value = $rule->getValue();
217 $this->normalizeTypes($rowValue, $value);
218
219 if (! is_array($rowValue)) {
220 $rowValue = [$rowValue];
221 }
222
223 foreach ($rowValue as $rowVal) {
224 if ($this->performSimilarityMatch($value, $rowVal, $rule->ignoresCase())) {
225 return true;
226 }
227 }
228
229 return false;
230 }
231
232 /**
233 * Apply equality matching rules on the given row value
234 *
235 * @param mixed $value
236 * @param mixed $rowValue
237 * @param bool $ignoreCase
238 *
239 * @return bool
240 */
241 protected function performEqualityMatch(mixed $value, mixed $rowValue, bool $ignoreCase = false): bool
242 {
243 if ($ignoreCase && is_string($rowValue)) {
244 $rowValue = strtolower($rowValue);
245 /** @var string|string[] $value {@see self::normalizeTypes} ensures this is the case */
246 $value = is_array($value)
247 ? array_map('strtolower', $value)
248 : ($value === null ? null : strtolower($value)); // PHPStan incorrectly infers the type here.
249 }
250
251 if (is_array($value)) {
252 return in_array($rowValue, $value, true);
253 }
254
255 return $rowValue === $value;
256 }
257
258 /**
259 * Apply similarity matching rules on the given row value
260 *
261 * @param mixed $value
262 * @param mixed $rowValue
263 * @param bool $ignoreCase
264 *
265 * @return bool
266 */
267 protected function performSimilarityMatch(mixed $value, mixed $rowValue, bool $ignoreCase = false): bool
268 {
269 if ($ignoreCase && is_string($rowValue)) {
270 $rowValue = strtolower($rowValue);
271 /** @var string|string[] $value {@see self::normalizeTypes} ensures this is the case */
272 $value = is_array($value)
273 ? array_map('strtolower', $value)
274 : ($value === null ? null : strtolower($value)); // PHPStan incorrectly infers the type here.
275 }
276
277 if (is_array($value)) {
278 return in_array($rowValue, $value, true);
279 } elseif (! is_string($value) || ! is_string($rowValue)) {
280 return $this->performEqualityMatch($value, $rowValue);
281 }
282
283 $wildcardSubSegments = preg_split('~\*~', $value);
284 if (! $wildcardSubSegments) {
285 $wildcardSubSegments = [];
286 }
287
288 if (count($wildcardSubSegments) === 1) {
289 return $rowValue === $value;
290 }
291
292 $parts = [];
293 foreach ($wildcardSubSegments as $part) {
294 $parts[] = preg_quote($part, '~');
295 }
296
297 $pattern = '~^' . join('.*', $parts) . '$~';
298
299 return (bool) preg_match($pattern, $rowValue);
300 }
301
302 /**
303 * Create a rule that matches rows with a column that is **unequal** with the given value
304 *
305 * @param string $column
306 * @param mixed $value
307 *
308 * @return Condition
309 */
310 public static function unequal(string $column, mixed $value): Condition
311 {
312 return new Unequal($column, $value);
313 }
314
315 /**
316 * Return whether the given rule's value does not equal the given item's value
317 *
318 * @param Unequal $rule
319 * @param object $row
320 *
321 * @return bool
322 */
323 protected function matchUnequal(Unequal $rule, object $row): bool
324 {
325 return ! $this->matchEqual($rule, $row);
326 }
327
328 /**
329 * Create a rule that matches rows with a column that is **unlike** with the given value
330 *
331 * Performs a wildcard search if the value contains asterisks.
332 *
333 * @param string $column
334 * @param mixed $value
335 *
336 * @return Condition
337 */
338 public static function unlike(string $column, mixed $value): Condition
339 {
340 return new Unlike($column, $value);
341 }
342
343 /**
344 * Return whether the given rule's value is unlike the given item's value
345 *
346 * @param Unlike $rule
347 * @param object $row
348 *
349 * @return bool
350 */
351 protected function matchUnlike(Unlike $rule, object $row): bool
352 {
353 return ! $this->matchSimilar($rule, $row);
354 }
355
356 /**
357 * Create a rule that matches rows with a column that is **greater** than the given value
358 *
359 * @param string $column
360 * @param mixed $value
361 *
362 * @return Condition
363 */
364 public static function greaterThan(string $column, mixed $value): Condition
365 {
366 return new GreaterThan($column, $value);
367 }
368
369 /**
370 * Return whether the given rule's value is greater than the given item's value
371 *
372 * @param GreaterThan $rule
373 * @param object $row
374 *
375 * @return bool
376 */
377 protected function matchGreaterThan(GreaterThan $rule, object $row): bool
378 {
379 $rowValue = $this->extractValue($rule->getColumn(), $row);
380 $value = $rule->getValue();
381
382 return $rowValue !== null && $value !== null && $rowValue > $value;
383 }
384
385 /**
386 * Create a rule that matches rows with a column that is **less** than the given value
387 *
388 * @param string $column
389 * @param mixed $value
390 *
391 * @return Condition
392 */
393 public static function lessThan(string $column, mixed $value): Condition
394 {
395 return new LessThan($column, $value);
396 }
397
398 /**
399 * Return whether the given rule's value is less than the given item's value
400 *
401 * @param LessThan $rule
402 * @param object $row
403 *
404 * @return bool
405 */
406 protected function matchLessThan(LessThan $rule, object $row): bool
407 {
408 $rowValue = $this->extractValue($rule->getColumn(), $row);
409 $value = $rule->getValue();
410
411 return $rowValue !== null && $value !== null && $rowValue < $value;
412 }
413
414 /**
415 * Create a rule that matches rows with a column that is **greater** than or **equal** to the given value
416 *
417 * @param string $column
418 * @param mixed $value
419 *
420 * @return Condition
421 */
422 public static function greaterThanOrEqual(string $column, mixed $value): Condition
423 {
424 return new GreaterThanOrEqual($column, $value);
425 }
426
427 /**
428 * Return whether the given rule's value is greater than or equals the given item's value
429 *
430 * @param GreaterThanOrEqual $rule
431 * @param object $row
432 *
433 * @return bool
434 */
435 protected function matchGreaterThanOrEqual(GreaterThanOrEqual $rule, object $row): bool
436 {
437 $rowValue = $this->extractValue($rule->getColumn(), $row);
438 $value = $rule->getValue();
439
440 return $rowValue !== null && $value !== null && $rowValue >= $value;
441 }
442
443 /**
444 * Create a rule that matches rows with a column that is **less** than or **equal** to the given value
445 *
446 * @param string $column
447 * @param mixed $value
448 *
449 * @return Condition
450 */
451 public static function lessThanOrEqual(string $column, mixed $value): Condition
452 {
453 return new LessThanOrEqual($column, $value);
454 }
455
456 /**
457 * Return whether the given rule's value is less than or equals the given item's value
458 *
459 * @param LessThanOrEqual $rule
460 * @param object $row
461 *
462 * @return bool
463 */
464 protected function matchLessThanOrEqual(LessThanOrEqual $rule, object $row): bool
465 {
466 $rowValue = $this->extractValue($rule->getColumn(), $row);
467 $value = $rule->getValue();
468
469 return $rowValue !== null && $value !== null && $rowValue <= $value;
470 }
471
472 /**
473 * Perform the appropriate match for the given rule on the given item
474 *
475 * @param Rule $rule
476 * @param object $row
477 *
478 * @return bool
479 */
480 protected function performMatch(Rule $rule, object $row): bool
481 {
482 return match (true) {
483 $rule instanceof All => $this->matchAll($rule, $row),
484 $rule instanceof Any => $this->matchAny($rule, $row),
485 $rule instanceof Like => $this->matchSimilar($rule, $row),
486 $rule instanceof Equal => $this->matchEqual($rule, $row),
487 $rule instanceof GreaterThan => $this->matchGreaterThan($rule, $row),
488 $rule instanceof GreaterThanOrEqual => $this->matchGreaterThanOrEqual($rule, $row),
489 $rule instanceof LessThan => $this->matchLessThan($rule, $row),
490 $rule instanceof LessThanOrEqual => $this->matchLessThanOrEqual($rule, $row),
491 $rule instanceof None => $this->matchNone($rule, $row),
492 $rule instanceof Unequal => $this->matchUnequal($rule, $row),
493 $rule instanceof Unlike => $this->matchUnlike($rule, $row),
494 };
495 }
496
497 /**
498 * Return a value from the given row suitable to work with
499 *
500 * @param string $column
501 * @param object $row
502 *
503 * @return mixed
504 */
505 protected function extractValue(string $column, object $row): mixed
506 {
507 return $row->$column ?? null;
508 }
509
510 /**
511 * Normalize type of $value to the one of $rowValue
512 *
513 * For details on how this works please see the corresponding test
514 * {@see \ipl\Tests\Stdlib\FilterTest::testConditionsAreValueTypeAgnostic}.
515 *
516 * @param mixed $rowValue
517 * @param mixed $value
518 *
519 * @return void
520 */
521 protected function normalizeTypes(mixed $rowValue, mixed &$value): void
522 {
523 if ($rowValue === null || $value === null) {
524 return;
525 }
526
527 if (is_array($rowValue)) {
528 if (empty($rowValue)) {
529 return;
530 }
531
532 $rowValue = array_shift($rowValue);
533 }
534
535 if (is_array($value)) {
536 if (is_bool($rowValue) && ! empty($value) && is_string(array_values($value)[0])) {
537 return;
538 }
539
540 $rowValueType = gettype($rowValue);
541 foreach ($value as &$val) {
542 settype($val, $rowValueType);
543 }
544 } elseif (! is_bool($rowValue) || ! is_string($value)) {
545 settype($value, gettype($rowValue));
546 }
547 }
548 }