feat(FilterAddressField): allow direct internal values

This commit allows FilterAddressField to return values directly instead
of returning them in the usual filter address array format. This
is primarily useful for fields who need the same valiadations as
a normal filter address field but don't store the value as an array.

Author: jaredhendrickson13

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Fields/FilterAddressField.inc

@@ -42,6 +42,9 @@ class FilterAddressField extends InterfaceField {
      * L2TP client.
      * @param bool $allow_pppoe Allow this field's value to be `pppoe`. This is used to indicate the address is any
      * PPPoE client.
+     * @param bool $internal_direct If `true`, this field's value will be written as a direct value instead of
+     * an array. This is useful for fields that need the same validation as this Field, but do not store their
+     * values as the usual filter address array.
      * @param bool $allow_empty If `true`, empty strings will be allowed by this field.
      * @param bool $allow_null If `true`, null values will be allowed by this field.
      * @param array $interface_query Assigns query parameters to limit which interfaces should be accepted by this
@@ -102,6 +105,7 @@ class FilterAddressField extends InterfaceField {
         public bool $allow_self = true,
         public bool $allow_l2tp = true,
         public bool $allow_pppoe = true,
+        public bool $internal_direct = false,
         bool $allow_empty = false,
         bool $allow_null = false,
         array $interface_query = [],
@@ -290,12 +294,12 @@ class FilterAddressField extends InterfaceField {
         $if_ip_modifier_set = false;
 
         # When `any` is set, additional parameters are irrelevant. Set the `any` internal value and return it.
-        if ($representation_value === 'any') {
+        if ($representation_value === 'any' and !$this->internal_direct) {
             return ['any' => true];
         }
 
         # Remove the prefixed invert character (!) and set its internal value if present
-        if (str_starts_with($representation_value, self::INVERT_PREFIX)) {
+        if (str_starts_with($representation_value, self::INVERT_PREFIX) and !$this->internal_direct) {
             $representation_value = substr($representation_value, 1);
             $internal_value['not'] = true;
         }
@@ -306,6 +310,11 @@ class FilterAddressField extends InterfaceField {
             $if_ip_modifier_set = true;
         }
 
+        # If this value has internal direct set, we can return it directly
+        if ($this->internal_direct) {
+            return $if_ip_modifier_set ? $representation_value . 'ip' : $representation_value;
+        }
+
         # Assign the `address` internal value for individual IP values, subnets, and aliases
         if ($this->has_label('is_ipaddr') or $this->has_label('is_subnet') or $this->has_label('is_alias')) {
             $internal_value[$this->internal_value_key] = $representation_value;
@@ -331,6 +340,15 @@ class FilterAddressField extends InterfaceField {
         # Assign a variable to use when piecing back together our representation value
         $representation_value = '';
 
+        # If this is a direct internal value, just check for the :ip modifier and return the value directly
+        if ($this->internal_direct) {
+            # If the value ends with `ip`, append the `:ip` modifier to the representation value
+            if (str_ends_with($internal_value, 'ip')) {
+                return substr($internal_value, 0, -2) . ':ip';
+            }
+            return $internal_value;
+        }
+
         # If the `any` flag is set, the representation value has to be `any`
         if (isset($internal_value['any'])) {
             return 'any';

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

@@ -434,4 +434,29 @@ class APIFieldsFilterAddressFieldTestCase extends TestCase {
         # Delete the firewall alias
         $alias->delete();
     }
+
+    /**
+     * Checks that the internal_direct option stores the field's value as a direct value instead of a normal filter
+     * address array.
+     */
+    public function test_internal_direct(): void {
+        $field = new FilterAddressField(
+            required: true,
+            allow_ipaddr: true,
+            allow_interface_ip: true,
+            internal_direct: true,
+        );
+
+        # Ensure the to_internal method returns the internal value directly
+        $field->value = '1.2.3.4';
+        $this->assert_equals($field->to_internal(), '1.2.3.4');
+        $field->value = 'wan:ip';
+        $this->assert_equals($field->to_internal(), 'wanip');
+
+        # Ensure the from_internal method populates the value correctly from a direct value
+        $field->from_internal('1.2.3.4');
+        $this->assert_equals($field->value, '1.2.3.4');
+        $field->from_internal('wanip');
+        $this->assert_equals($field->value, 'wan:ip');
+    }
 }