feat: allow endpoints, models and clients to specify sort flags #646

Author: jaredhendrickson13

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Endpoint.inc

@@ -316,7 +316,7 @@ class Endpoint {
     public bool $reverse = false;
 
     /**
-     * @var string|null $sort_by
+     * @var string|array|null $sort_by
      * Sets the default value(s) for the `sort_by` field in the request data. This value is used to control the sorting of
      * the Model objects returned by this Endpoint. This value can be overridden by the client in the request data. Use
      * caution when assigning this value as it may force objects to be sorted in this order when they are written to the
@@ -333,6 +333,15 @@ class Endpoint {
      */
     public string $sort_order = 'SORT_ASC';
 
+    /**
+     * @var string $sort_flags
+     * Sets the default value for the `sort_flags` field in the request data. This value is used to control the sorting
+     * flags of the Model objects returned by this Endpoint. This value can be overridden by the client in the request
+     * data. This value only takes effect when the `sort_by` field is also set. This value must be the name of a valid
+     * PHP sort flags constant (e.g. 'SORT_REGULAR', 'SORT_NATURAL')
+     */
+    public string $sort_flags = 'SORT_REGULAR';
+
     /**
      * @var bool $append
      * Sets the default value for the `append` field in the request data. This value is used to control how Model objects
@@ -854,6 +863,43 @@ class Endpoint {
         }
     }
 
+    /**
+     * Validates the $sort_flags common control parameter for this request.
+     * @note If the `sort_flags` field was not provided in the request data, the request will default to the
+     * Endpoint's assigned $sort_flags property value.
+     * @throws ValidationError When the `sort_flags` field is not a string or is not a valid sort flags constant.
+     */
+    private function validate_sort_flags(): void
+    {
+        # Valid sort_flags options
+        $flag_opts = [
+            'SORT_REGULAR', 'SORT_NUMERIC', 'SORT_STRING', 'SORT_LOCALE_STRING', 'SORT_NATURAL', 'SORT_FLAG_CASE'
+        ];
+
+        # Only validate this field if the client specifically requested it in the request data
+        if (isset($this->request_data['sort_flags'])) {
+            # Ensure value is a string
+            if (!is_string($this->request_data['sort_flags'])) {
+                throw new ValidationError(
+                    message: 'Field `sort_flags` must be of type `string`.',
+                    response_id: 'ENDPOINT_SORT_FLAGS_FIELD_INVALID_TYPE',
+                );
+            }
+
+            # Ensure the field is a valid sort flags constant
+            if (!in_array($this->request_data['sort_flags'], $flag_opts)) {
+                throw new ValidationError(
+                    message: 'Field `sort_flags` must be one of: ' . json_encode($flag_opts),
+                    response_id: 'ENDPOINT_SORT_FLAGS_FIELD_UNKNOWN_SORT_FLAGS',
+                );
+            }
+
+            # Update the sort_flags property to use the client's requested value and remove it from the request data
+            $this->sort_flags = $this->request_data['sort_flags'];
+            unset($this->request_data['sort_flags']);
+        }
+    }
+
     /**
      * Validates the $append common control parameter for this request.
      * @note If the `append` field was not provided in the request data, the request will default to the Endpoint's assigned
@@ -964,6 +1010,7 @@ class Endpoint {
         $this->validate_reverse();
         $this->validate_sort_by();
         $this->validate_sort_order();
+        $this->validate_sort_flags();
         $this->validate_append();
         $this->validate_remove();
         $this->validate_limit();
@@ -1082,6 +1129,7 @@ class Endpoint {
                 reverse: $this->reverse,
                 sort_by: $this->sort_by,
                 sort_order: constant($this->sort_order),
+                sort_flags: constant($this->sort_flags),
             );
         }
         # For GET requests on many Endpoints, obtain all objects from the assigned Model.
@@ -1105,6 +1153,7 @@ class Endpoint {
         # Allow the endpoint/client to override the Model's sort_by and sort_order properties
         $this->model->sort_by = $this->sort_by ?? $this->model->sort_by;
         $this->model->sort_order = constant($this->sort_order) ?? $this->model->sort_order;
+        $this->model->sort_flags = constant($this->sort_flags) ?? $this->model->sort_flags;
 
         # Create the object and return it
         return $this->model->create(apply: $this->request_data['apply'] === true);
@@ -1128,6 +1177,7 @@ class Endpoint {
         # Allow the endpoint/client to override the Model's sort_by and sort_order properties
         $this->model->sort_by = $this->sort_by ?? $this->model->sort_by;
         $this->model->sort_order = constant($this->sort_order) ?? $this->model->sort_order;
+        $this->model->sort_flags = constant($this->sort_flags) ?? $this->model->sort_flags;
 
         # Update the object and return it
         return $this->model->update(

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Model.inc

@@ -222,6 +222,15 @@ class Model {
      */
     public int|null $sort_order = null;
 
+    /**
+     * @var int|null $sort_flags
+     * For $many enabled Models, this property can be used to set the PHP sort flags used when writing Model objects to
+     * config. This property is only applicable if the $sort_by_field property is also defined. This property only applies
+     * to Models with a $config_path defined. For valid value options for this property, refer to:
+     * https://www.php.net/manual/en/function.array-multisort.php
+     */
+    public int|null $sort_flags = null;
+
     /**
      * @var array|null $sort_by
      * Sets the field names this Model will use when sorting objects written to the pfSense configuration. These fields must
@@ -1703,7 +1712,12 @@ class Model {
         }
 
         # Obtain all Model objects for this Model and sort them by the requested criteria
-        $modelset = $this->query(parent_id: $this->parent_id, sort_by: $this->sort_by, sort_order: $this->sort_order);
+        $modelset = $this->query(
+            parent_id: $this->parent_id,
+            sort_by: $this->sort_by,
+            sort_order: $this->sort_order,
+            sort_flags: $this->sort_flags
+        );
 
         # Loop through the sorted object and assign it's internal value
         $internal_objects = [];
@@ -1915,6 +1929,7 @@ class Model {
         bool $reverse = false,
         ?array $sort_by = null,
         int $sort_order = SORT_ASC,
+        int $sort_flags = SORT_REGULAR,
         ...$vl_query_params,
     ): ModelSet {
         # Merge the $query_params and any provided variable-length arguments into a single variable
@@ -1929,7 +1944,11 @@ class Model {
         $modelset = self::read_all(parent_id: $parent_id)->query(query_params: $query_params, excluded: $excluded);
 
         # Sort the set if a sort field was provided
-        $modelset = $sort_by ? $modelset->sort(fields: $sort_by, order: $sort_order, retain_ids: true) : $modelset;
+        if ($sort_by) {
+            $modelset = $modelset->sort(
+                fields: $sort_by, order: $sort_order, flags: $sort_flags, retain_ids: true
+            );
+        }
 
         # Apply pagination to limit the number of objects returned and/or reverse the order if requested
         $modelset->model_objects = self::paginate($modelset->model_objects, $limit, $offset);

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/ModelSet.inc

@@ -83,10 +83,16 @@ class ModelSet {
      * Sorts the Model objects in this ModelSet by a specific field and order.
      * @param string|array $fields The field(s) to sort the Model objects by.
      * @param int $order The order to sort the Model objects by. This must be a PHP sort order constant.
+     * @param int $flags The flags to use when sorting the Model objects. This must be a PHP sort flags constant.
      * @param bool $retain_ids Retain the original Model object IDs when sorting.
      * @return ModelSet A new ModelSet object with the Model objects sorted by the specified field and order.
      */
-    public function sort(string|array $fields, int $order = SORT_ASC, bool $retain_ids = false): ModelSet {
+    public function sort(
+        string|array $fields,
+        int $order = SORT_ASC,
+        int $flags = SORT_REGULAR,
+        bool $retain_ids = false
+    ): ModelSet {
         # Variables
         $model_objects = $this->model_objects;
         $fields = is_array($fields) ? $fields : [$fields];
@@ -107,7 +113,7 @@ class ModelSet {
         }
 
         # Sort using array_multisort
-        array_multisort($sort_criteria, $order, $model_objects);
+        array_multisort($sort_criteria, $order, $flags, $model_objects);
 
         # Re-assign the model object IDs if they should not be retained
         if (!$retain_ids) {