feat(QueryFilter): add query filter for finding objects whose field values are within an array or string

Author: jaredhendrickson13

docs/QUERIES_FILTERS_AND_SORTING.md

@@ -52,6 +52,15 @@ value array contains a given value for array fields.
 - Name: `contains`
 - Example: `https://pfsense.example.com/api/v2/examples?fieldname__contains=example`
 
+### In (in)
+
+Search for objects whose field value is within a given array of values (when the filter value is an array), or search
+for objects whose field value is a substring of a given string (when the filter value is a string).
+- Name: `in`
+- Examples: 
+  - `https://pfsense.example.com/api/v2/examples?fieldname__in=example`
+  - `https://pfsense.example.com/api/v2/examples?fieldname__in[]=example1&fieldname__in[]=example2`
+
 ### Less Than (lt)
 
 Search for objects whose field value is less than a given integer.

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/QueryFilters/InQueryFilter.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace RESTAPI\QueryFilters;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\QueryFilter;
+
+/**
+ * Defines a query filter that checks if the given field value is within a set of values.
+ */
+class InQueryFilter extends QueryFilter {
+    public string $name = 'in';
+
+    /**
+     * Checks if the field's value is one of the values in the given filter value array. If the field value is an
+     * array, this filter will check if the field's value matches an item in the filter value array exactly. Otherwise,
+     * this filter will check if the field's value is a substring of the filter value string.
+     * @param mixed $field_value The value of the field being used to filter.
+     * @param mixed $filter_value The value of the filter criteria to evaluate against.
+     * @return bool true if the field_value contains the filter_value, false otherwise.
+     */
+    public function evaluate(mixed $field_value, mixed $filter_value): bool {
+        # When filter value is an array and field value is not, check if the field value is in the filter value array
+        if (is_array($filter_value) and !is_array($field_value)) {
+            return in_array($field_value, $filter_value);
+        }
+
+        return str_contains(strval($filter_value), strval($field_value));
+    }
+}

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Tests/APIQueryFiltersInQueryFilterTestCase.inc

@@ -0,0 +1,24 @@
+<?php
+
+namespace RESTAPI\Tests;
+
+use RESTAPI\Core\TestCase;
+use RESTAPI\QueryFilters\InQueryFilter;
+
+class APIQueryFiltersInQueryFilterTestCase extends TestCase {
+    /**
+     * Checks that the 'evaluate' method correctly returns true when the field value is found within the filter value,
+     * and false when it is not.
+     */
+    public function test_evaluate(): void {
+        $filter = new InQueryFilter();
+
+        # Check with string values
+        $this->assert_is_true($filter->evaluate('test', 'test'));
+        $this->assert_is_false($filter->evaluate('test', 'notfound'));
+
+        # Check with array filter value and non-array field value
+        $this->assert_is_true($filter->evaluate('apple', ['apple', 'banana']));
+        $this->assert_is_false($filter->evaluate('cherry', ['apple', 'banana']));
+    }
+}