feat: allow sorting by multiple fields

Author: jaredhendrickson13

README.md

@@ -23,7 +23,7 @@ API package and provide you with the information you need to configure and use t
 - [Installation and Configuration](https://pfrest.org/INSTALL_AND_CONFIG/)
 - [Authentication and Authorization](https://pfrest.org/AUTHENTICATION_AND_AUTHORIZATION/)
 - [Swagger and OpenAPI](https://pfrest.org/SWAGGER_AND_OPENAPI/)
-- [Queries and Filters](https://pfrest.org/QUERIES_AND_FILTERS/)
+- [Queries, Filters, and Sorting](https://pfrest.org/QUERIES_FILTERS_AND_SORTING/)
 
 ## Quickstart
 

docs/COMMON_CONTROL_PARAMETERS.md

@@ -84,5 +84,22 @@ parameters you can use:
   looking for an object near the end of the list. Additionally, it is helpful for time-sorted objects, such as logs,
   where you may want to view the most recent entries first.
 
-!!! Note
-    This parameter is only available for `GET` requests to [plural endpoints](ENDPOINT_TYPES.md#plural-many-endpoints).
+## sort_by
+
+- Type: String or Array
+- Default: _Defaults to the primary sort attribute for the endpoint, typically `null`._
+- Description: This parameters allows you to select the fields to use to sort the objects related to the endpoint. The
+  behavior of this parameter varies based on the request method and endpoint type. Refer to the 
+  [Sorting](QUERIES_FILTERS_AND_SORTING.md#sorting) section for more information.
+
+## sort_order
+
+- Type: String
+- Default: `SORT_ASC`
+- Choices:
+    - `SORT_ASC`
+    - `SORT_DESC`
+- Description: This parameter allows you to control the order in which the objects are sorted. The default value is
+  `SORT_ASC` which sorts the objects in ascending order. Setting this parameter to `SORT_DESC` will sort the objects in
+  descending order. The behavior of this parameter varies based on the request method and endpoint type. Refer to the
+  [Sorting](QUERIES_FILTERS_AND_SORTING.md#sorting) section for more information.

docs/ENDPOINT_TYPES.md

@@ -61,9 +61,9 @@ Some examples of plural endpoints are:
 ### GET Requests to Plural Endpoints
 
 A `GET` request to a plural endpoint will allow you to retrieve a list of all existing objects at once. GET requests to plural
-endpoints also support [querying and filtering](QUERIES_AND_FILTERS.md) to help you narrow down the list of objects
+endpoints also support [querying and filtering](QUERIES_FILTERS_AND_SORTING) to help you narrow down the list of objects
 returned by specifying criteria for the objects you want to retrieve. This includes support for 
-[pagination](QUERIES_AND_FILTERS.md#pagination) which will allow you to limit the amount of objects returned in a single request.
+[pagination](QUERIES_FILTERS_AND_SORTING#pagination) which will allow you to limit the amount of objects returned in a single request.
 
 ### PUT Requests to Plural Endpoints
 
@@ -87,7 +87,7 @@ one by one, and can instead replace the entire dataset as a whole in a single re
 
 ### DELETE Requests to Plural Endpoints
 
-A `DELETE` request to a plural endpoint will allow you to delete many objects at once using a [query](QUERIES_AND_FILTERS.md).
+A `DELETE` request to a plural endpoint will allow you to delete many objects at once using a [query](QUERIES_FILTERS_AND_SORTING).
 This is useful when you need to remove a large number of objects from the system, such as when decommissioning services,
 cleaning up old data, or removing objects that are no longer needed. This is primarily used as a method of deleting
 objects without requiring an ID.

docs/QUERIES_AND_FILTERS.md docs/QUERIES_FILTERS_AND_SORTING.mddocs/QUERIES_AND_FILTERS.md renamed to docs/QUERIES_FILTERS_AND_SORTING.md

@@ -1,4 +1,4 @@
-# Queries and Filters
+# Queries, Filters and Sorting
 
 ## Queries
 
@@ -114,11 +114,47 @@ Search for objects whose field value matches a given PCRE regular expression.
 - Name: `regex`
 - Example: `https://pfsense.example.com/api/v2/examples?fieldname__regex=^example`
 
-## Custom Query Filters
+### Custom Query Filters
 
 For advanced users, the REST API's framework allows for custom query filter classes to be added using PHP. Refer to
 [Building Custom Query Filters](./BUILDING_CUSTOM_QUERY_FILTER_CLASSES.md) for more information.
 
+## Sorting
+
+Sorting can be used to order the data that is returned from the API based on specific criteria, as well as sorting the
+objects written to the pfSense configuration. Sorting is controlled by two common control parameters: 
+[`sort_by`](./COMMON_CONTROL_PARAMETERS.md#sort_by) and [`sort_order`](./COMMON_CONTROL_PARAMETERS.md#sort_order).
+
+!!! Note
+    - Sorting is only available for model objects that allow many instances, meaning multiple objects of its type can
+      exist in the pfSense configuration (e.g. firewall rules, static routes, etc.).
+    - Sorting requires additional processing time and may impact performance. Use sorting only when
+      necessary.
+
+The behavior of sorting varies based on the request method and endpoint type:
+
+### GET requests to Plural (Many) Endpoints
+
+For `GET` requests to [plural endpoints](./ENDPOINT_TYPES.md#plural-many-endpoints), sorting allows to you sort the
+objects returned in the `data` section of the API response by a specific field and a specific ordering. This does not
+affect the order of the objects stored in the pfSense configuration.
+
+### POST and PATCH requests to Singular Endpoints
+
+For `POST` and `PATCH` requests to [singular endpoints](./ENDPOINT_TYPES.md#singular-endpoints), sorting allows you to
+sort the relevant objects in the pfSense configuration after creating or updating an object. This is useful when you 
+need to control the order of objects in the configuration, especially for objects where the order of objects directly
+affects the behavior (like ACLs). Some example use cases for sorting the configuration include:
+
+- Reordering firewall rules based on a custom description.
+- Reordering NAT rules based on interface.
+
+!!! Warning
+    - Use caution when setting the sort order of objects which may be sensitive to order such as firewall rules. Placing
+      the object in the wrong location may have unintended consequences such as blocking all traffic or allowing all traffic.
+    - Some endpoints may already have default sorting attributes. Setting the `sort_by` parameter will override these
+      defaults which may result in unexpected behavior.
+
 ## Pagination
 
 Pagination can be used to limit the number of items returned in a single request. Pagination is controlled by two query

docs/WORKING_WITH_HATEOAS.md

@@ -15,7 +15,7 @@ easily navigate the API and discover available actions and resources related to
 !!! Important
     Enabling HATEOAS can greatly increase the size of API responses as additional links are included in the response data;
     which may also impact performance on large datasets. It is strongly recommended to only enable HATEOAS when needed and
-    to use [pagination](./QUERIES_AND_FILTERS.md#pagination) to limit the amount of data returned in a single request.
+    to use [pagination](./QUERIES_FILTERS_AND_SORTING#pagination) to limit the amount of data returned in a single request.
 
 ### Link types
 
@@ -28,11 +28,11 @@ API response.
 
 #### next
 
-Provides a link to the next set of data when [pagination](./QUERIES_AND_FILTERS.md#pagination) is used.
+Provides a link to the next set of data when [pagination](./QUERIES_FILTERS_AND_SORTING#pagination) is used.
 
 #### prev
 
-Provides a link to the previous set of data when [pagination](./QUERIES_AND_FILTERS.md#pagination) is used.
+Provides a link to the previous set of data when [pagination](./QUERIES_FILTERS_AND_SORTING#pagination) is used.
 
 #### self
 

mkdocs.yml

@@ -7,7 +7,7 @@ nav:
       - Endpoint Types: ENDPOINT_TYPES.md
       - Authentication & Authorization: AUTHENTICATION_AND_AUTHORIZATION.md
       - Content & Accept Types: CONTENT_AND_ACCEPT_TYPES.md
-      - Queries & Filters: QUERIES_AND_FILTERS.md
+      - Queries & Filters: QUERIES_FILTERS_AND_SORTING.md
       - Working with Object IDs: WORKING_WITH_OBJECT_IDS.md
       - Working with HATEOAS: WORKING_WITH_HATEOAS.md
       - Common Control Parameters: COMMON_CONTROL_PARAMETERS.md

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

@@ -317,12 +317,12 @@ class Endpoint {
 
     /**
      * @var string|null $sort_by
-     * Sets the default value for the `sort_by` field in the request data. This value is used to control the sorting of
+     * 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
      * configuration file.
      */
-    public ?string $sort_by = null;
+    public string|array|null $sort_by = null;
 
     /**
      * @var string $sort_order
@@ -794,20 +794,28 @@ class Endpoint {
     {
         # Only validate this field if the client specifically requested it in the request data
         if (isset($this->request_data['sort_by'])) {
-            # Ensure value is a string
-            if (!is_string($this->request_data['sort_by'])) {
-                throw new ValidationError(
-                    message: 'Field `sort_by` must be of type `string`.',
-                    response_id: 'ENDPOINT_SORT_BY_FIELD_INVALID_TYPE',
-                );
-            }
+            # Ensure value is an array
+            $this->request_data['sort_by'] = is_array($this->request_data['sort_by'])
+                ? $this->request_data['sort_by']
+                : [$this->request_data['sort_by']];
+
+            # Check each field in the array
+            foreach ($this->request_data['sort_by'] as $sort_by) {
+                # Ensure value is a string
+                if (!is_string($sort_by)) {
+                    throw new ValidationError(
+                        message: 'Field `sort_by` must be of type `string`.',
+                        response_id: 'ENDPOINT_SORT_BY_FIELD_INVALID_TYPE',
+                    );
+                }
 
-            # Ensure the field is a valid field in the Model
-            if (!in_array($this->request_data['sort_by'], $this->model->get_fields())) {
-                throw new ValidationError(
-                    message: 'Field `sort_by` must be a valid field in the Model.',
-                    response_id: 'ENDPOINT_SORT_BY_FIELD_NON_EXISTENT_FIELD',
-                );
+                # Ensure the field is a valid field in the Model
+                if (!in_array($sort_by, $this->model->get_fields())) {
+                    throw new ValidationError(
+                        message: 'Field `sort_by` must be a valid field in the Model.',
+                        response_id: 'ENDPOINT_SORT_BY_FIELD_NON_EXISTENT_FIELD',
+                    );
+                }
             }
 
             # Update the sort_by property to use the client's requested value and remove it from the request data

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

@@ -1856,7 +1856,7 @@ class Model {
         int $limit = 0,
         int $offset = 0,
         bool $reverse = false,
-        ?string $sort_by = null,
+        ?array $sort_by = null,
         int $sort_order = SORT_ASC,
         ...$vl_query_params,
     ): ModelSet {
@@ -1872,7 +1872,7 @@ 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(field: $sort_by, order: $sort_order, retain_ids: true) : $modelset;
+        $modelset = ($sort_by) ? $modelset->sort(fields: $sort_by, order: $sort_order, retain_ids: true) : $modelset;
 
         # 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

@@ -81,23 +81,33 @@ class ModelSet {
 
     /**
      * Sorts the Model objects in this ModelSet by a specific field and order.
-     * @param string $field The field to sort the Model objects by.
+     * @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 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 $field, int $order = SORT_ASC, bool $retain_ids = false): ModelSet {
+    public function sort(string|array $fields, int $order = SORT_ASC, bool $retain_ids = false): ModelSet {
         # Variables
-        $sort_values = [];
         $model_objects = $this->model_objects;
+        $fields = is_array($fields) ? $fields : [$fields];
+        $sort_criteria = [];
 
-        # Loop through each model object and store the sort value
-        foreach ($model_objects as $model_object) {
-            $sort_values[] = $model_object->$field->value;
+        # Loop through each Model object and add the field values to the sort criteria
+        foreach ($this->model_objects as $model_object) {
+            # Loop variables
+            $sort_values = [];
+
+            # Loop through each field to sort by and extract it's value
+            foreach ($fields as $field) {
+                $sort_values[] = $field === 'id' ? $model_object->id : $model_object->$field->value;
+            }
+
+            # Add the sort values to the sort criteria
+            $sort_criteria[] = $sort_values;
         }
 
-        # Sort the sort values
-        array_multisort($sort_values, $order, $model_objects);
+        # Sort using array_multisort
+        array_multisort($sort_criteria, $order, $model_objects);
 
         # Re-assign the model object IDs if they should not be retained
         if (!$retain_ids) {

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

@@ -209,7 +209,7 @@ class NestedModelField extends Field {
 
             # Sort the nested Model objects by the specified field
             $this->modelset = $this->modelset->sort(
-                field: $this->model->sort_by_field,
+                fields: $this->model->sort_by_field,
                 order: $this->model->sort_option,
             );