pfSense-pkg-RESTAPI

SystemTunablesEndpoint extends Endpoint
in package

RESTAPI

Defines an Endpoint for interacting with many SystemTunable Model objects at /api/v2/system/tunables.

Properties

$append : bool
$async : bool
$auth_methods : array<string|int, mixed>
$decode_content_handlers : array<string|int, mixed>
$delete_help_text : string
$delete_privileges : array<string|int, mixed>
$deprecated : bool
$encode_content_handlers : array<string|int, mixed>
$get_help_text : string
$get_privileges : array<string|int, mixed>
$ignore_acl : bool
$ignore_enabled : bool
$ignore_interfaces : bool
$ignore_read_only : bool
$limit : int
$many : bool
$model : Model
$model_name : string
$offset : int
$patch_help_text : string
$patch_privileges : array<string|int, mixed>
$post_help_text : string
$post_privileges : array<string|int, mixed>
$put_help_text : string
$put_privileges : array<string|int, mixed>
$remove : bool
$request_data : array<string|int, mixed>
$request_method : string
$request_method_options : array<string|int, mixed>
$requires_auth : bool
$resource_link_set : ResourceLinkSet|null
$response_types : array<string|int, mixed>
$restapi_settings : RESTAPISettings
$reverse : bool
$sort_by : string|array<string|int, mixed>|null
$sort_flags : string|null
$sort_order : string
$tag : string
$url : string
$client : Auth
$errors : array<string|int, mixed>

Methods

__construct() : mixed: Sets values whenever the Endpoint object is crated.
build_endpoint_url() : bool: Generate an endpoint for this view in the pfSense webroot.
check_construct() : void: Checks for conflicting attributes during object construction.
check_decode_content_handler_supported() : void: Checks if the requested decode ContentHandler is supported.
check_encode_content_handler_supported() : void: Checks if the requested encode ContentHandler is supported.
generate_pfsense_privs() : array<string|int, mixed>: Utilizes the $url and $request_method_options properties of this Endpoint to generate pfSense privileges specific to this Endpoint class. The resulting array is then supplied to the pfSense privilege system located at /etc/inc/priv/.
get_class_fqn() : string: Obtains the fully qualified name of the called class.
get_class_shortname() : string: Obtains the shortname of the called class.
get_classes_in_namespace() : array<string|int, mixed>: Obtains all classes associated with this class's current namespace.
get_endpoint_filepath() : string: Obtains the absolute filepath to the PHP file generated for this Endpoint.
get_pagination_resource_links() : void: Obtains the `prev` and `next` HATEOAS resource links for pagination use. These links supply the previous and next set of objects from the dataset.
log_error() : void: Logs an error to the syslog.
process_request() : string: Processes the API request and returns the serialized API response to send back to the client.
response_handler() : Response: Defines a middleware method that can be used to handle the call's Response object before it is sent back to the client. This can be used by child Endpoints to extend or override the default Response handling behavior.
delete() : Model|ModelSet: Deletes an existing object for the assigned Model using the data submitted in a DELETE request.
get() : Model|ModelSet: Obtains the object data for GET requests to this Endpoint.
options() : void: Populates associated headers whenever an OPTIONS request is received.
patch() : Model|ModelSet: Updates an existing object for the assigned Model using the data submitted in a PATCH request.
post() : Model|ModelSet: Creates a new object for the assigned Model using the data submitted in a POST request.
put() : Model|ModelSet: Replaces all existing objects for the assigned Model using the data submitted in a PUT request.

$append


        public
            bool
    $append
     = false

Sets the default value for the append field in the request data. This value is used to control how Model objects apply updates to array fields on existing objects. If set to true, any requested updates to array fields will be appended to the existing array instead of replacing it. This value can be overridden by the client in the request data.

$async


        public
            bool
    $async
     = true

Sets the default value for the async field in the request data. This value is used to determine if the API call should be processed asynchronously when available. This value can be overridden by the client in the request data.

$auth_methods


        public
            array<string|int, mixed>
    $auth_methods
     = []

Explicitly specify authentication methods this Endpoint uses. Leave blank to use the authentication methods allowed by the REST API settings. If any authentication methods are specified here, this Endpoint will always allow authentication using this method, even if the method is not enabled in the REST API settings.

$decode_content_handlers


        public
            array<string|int, mixed>
    $decode_content_handlers
     = []

Defines which ContentHandler class (as shortnames) can be used to decode the API request. If this array is empty, all ContentHandlers with decode capabilities can be used. This directly relates to which MIME-types this endpoint supports in the Content-Type header.

$delete_help_text


        public
            string
    $delete_help_text
     = ''

Sets the DELETE request's OpenAPI documentation for this Endpoint. This will be used when generating the OpenAPI documentation for this Endpoint. This is typically only necessary if the default description is not adequate.

$delete_privileges


        public
            array<string|int, mixed>
    $delete_privileges
     = []

Assigns pfSense privileges that should allow DELETE requests to this Endpoint. This property is dynamically populated.

$deprecated


        public
            bool
    $deprecated
     = false

Marks this Endpoint as deprecated in the OpenAPI documentation.

$encode_content_handlers


        public
            array<string|int, mixed>
    $encode_content_handlers
     = []

Defines which ContentHandler class (as shortnames) can be used to encode the API response. If this array is empty, all ContentHandlers with encode capabilities can be used. This directly relates to which MIME-types this endpoint supports in the Accept header.

$get_help_text


        public
            string
    $get_help_text
     = ''

Sets the GET request's OpenAPI documentation for this Endpoint. This will be used when generating the OpenAPI documentation for this Endpoint. This is typically only necessary if the default description is not adequate.

$get_privileges


        public
            array<string|int, mixed>
    $get_privileges
     = []

Assigns pfSense privileges that should allow GET requests to this Endpoint. This property is dynamically populated.

$ignore_acl


        public
            bool
    $ignore_acl
     = false

Allow this Endpoint to ignore the REST API Access List. By default, Endpoints will not accept API calls from clients that are not allowed by the REST API Access List. Setting this value to true will allow this Endpoint to respond to API calls from any client regardless of the REST API Access List.

$ignore_enabled


        public
            bool
    $ignore_enabled
     = false

Allow this Endpoint to ignore the enabled API setting. By default, Endpoints will not accept API calls when the API's enabled setting is disabled. Setting this value to true will allow this Endpoint to respond to API calls even if the API is disabled.

$ignore_interfaces


        public
            bool
    $ignore_interfaces
     = false

Allow this Endpoint to ignore the allowed_interfaces API setting. By default, if an Endpoint receives an API call on an interface not specified in the allowed_interfaces API setting, a ForbiddenError will be thrown. Setting this value to true will allow this Endpoint to respond to requests over any interface regardless of what is specified in allowed_interfaces.

$ignore_read_only


        public
            bool
    $ignore_read_only
     = false

Allow this Endpoint to ignore the current read_only API setting. By default, when the read_only API setting is enabled, Endpoints are only allowed to respond to GET requests. Setting this value to true will allow requests using any HTTP method even if read_only is enabled.

$limit


        public
            int
    $limit
     = 0

Sets the default limit for the number of Model objects to retrieve in a single call to this Endpoint. This value is used for pagination purposes and can be overridden by the client in the request data.

$many


        public
            bool
    $many
     = false

Indicates whether this Endpoint interacts with a single Model object (false) or many Model objects (true).

$model


        public
            Model
    $model

The actual Model object created for the assigned $model_name.

$model_name


        public
            string
    $model_name
     = ''

The name of the Model class this Endpoint interacts with (excluding the Model class's namespace).

$offset


        public
            int
    $offset
     = 0

Sets the default offset for the starting point in the dataset requested for pagination. This value is used for pagination purposes and can be overridden by the client in the request data.

$patch_help_text


        public
            string
    $patch_help_text
     = ''

Sets the PATCH request's OpenAPI documentation for this Endpoint. This will be used when generating the OpenAPI documentation for this Endpoint. This is typically only necessary if the default description is not adequate.

$patch_privileges


        public
            array<string|int, mixed>
    $patch_privileges
     = []

Assigns pfSense privileges that should allow PATCH requests to this Endpoint. This property is dynamically populated.

$post_help_text


        public
            string
    $post_help_text
     = ''

Sets the POST request's OpenAPI documentation for this Endpoint. This will be used when generating the OpenAPI documentation for this Endpoint. This is typically only necessary if the default description is not adequate.

$post_privileges


        public
            array<string|int, mixed>
    $post_privileges
     = []

Assigns pfSense privileges that should allow POST requests to this Endpoint. This property is dynamically populated.

$put_help_text


        public
            string
    $put_help_text
     = ''

Sets the PUT request's OpenAPI documentation for this Endpoint. This will be used when generating the OpenAPI documentation for this Endpoint. This is typically only necessary if the default description is not adequate.

$put_privileges


        public
            array<string|int, mixed>
    $put_privileges
     = []

Assigns pfSense privileges that should allow PUT requests to this Endpoint. This property is dynamically populated.

$remove


        public
            bool
    $remove
     = false

Sets the default value for the remove field in the request data. This value is used to control how Model objects apply updates to array fields on existing objects. If set to true, any requested updates to array fields will remove the specified values from the existing array. This value can be overridden by the client in the request data.

$request_data


        public
            array<string|int, mixed>
    $request_data
     = []

The request body or parameters sent by the remote client.

$request_method


        public
            string
    $request_method

The HTTP request method sent by the remote client.

$request_method_options


        public
            array<string|int, mixed>
    $request_method_options
     = []

Sets the allowed HTTP request methods for this Endpoint. For $many=true, only GET, PUT and DELETE methods can be specified here. GET will use the Model's read_all() method, PUT will use the Model's replace_all() method and DELETE will use the Model's delete_many() method. For Endpoints with $many=false, GET, POST, PATCH, and DELETE methods can be specified here. GET will use the Model's read() method, POST will use the Model's create() method. PATCH will use the Model's update() method, and DELETE will use the Model's delete() method.

$requires_auth


        public
            bool
    $requires_auth
     = true

$resource_link_set


        public
            ResourceLinkSet|null
    $resource_link_set
     = null

A ResourceLinkSet containing ResourceLinks that should always be included in the root _links for this response.

$response_types


        public
            array<string|int, mixed>
    $response_types
     = []

An array of Response classes that can be returned by this Endpoint. This array should contain the class names of the Response objects that can be returned by this Endpoint.

$restapi_settings


        public
            RESTAPISettings
    $restapi_settings

Contains the current API configuration.

$reverse


        public
            bool
    $reverse
     = false

Sets the default value for the reverse field in the request data. This value is used to control the order of the Model objects returned by this Endpoint. This value can be overridden by the client in the request data. If set to true, the Model objects in the data section of the response will be reversed.

$sort_by


        public
            string|array<string|int, mixed>|null
    $sort_by
     = null

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.

$sort_flags


        public
            string|null
    $sort_flags
     = null

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')

$sort_order


        public
            string
    $sort_order
     = 'SORT_ASC'

Sets the default value for the sort_order field in the request data. This value is used to control the sorting order 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 order constant ('SORT_ASC' or 'SORT_DESC').

$tag


        public
            string
    $tag
     = ''

The OpenAPI tag applied to this Endpoint, nesting it under a specific name in the OpenAPI documentation. Defaults to the first value in the $url after /api/v2/.

$url


        public
            string
    $url
     = ''

The URL of this endpoint, used to generate a PHP file in the web path pointing back to this Endpoint class.

$client


        protected
            Auth
    $client

The \RESTAPI\Core\Auth object created by this Endpoint during API calls, contains client authentication information.

$errors


        protected
            array<string|int, mixed>
    $errors
     = []

An array to store errors encountered during API calls to this Endpoint.

__construct()

Sets values whenever the Endpoint object is crated.


    public
                    __construct() : mixed

build_endpoint_url()

Generate an endpoint for this view in the pfSense webroot.


    public
                    build_endpoint_url() : bool

Return values

bool

check_construct()

Checks for conflicting attributes during object construction.


    public
                    check_construct() : void

check_decode_content_handler_supported()

Checks if the requested decode ContentHandler is supported.


    public
                    check_decode_content_handler_supported(ContentHandler $content_handler) : void

Parameters

$content_handler : ContentHandler

check_encode_content_handler_supported()

Checks if the requested encode ContentHandler is supported.


    public
                    check_encode_content_handler_supported(ContentHandler $content_handler) : void

Parameters

$content_handler : ContentHandler

generate_pfsense_privs()

Utilizes the $url and $request_method_options properties of this Endpoint to generate pfSense privileges specific to this Endpoint class. The resulting array is then supplied to the pfSense privilege system located at /etc/inc/priv/.


    public
                    generate_pfsense_privs() : array<string|int, mixed>

Return values

array<string|int, mixed>

get_class_fqn()

Obtains the fully qualified name of the called class.


    public
                    get_class_fqn() : string

Return values

string —

The FQN for this object's class.

get_class_shortname()

Obtains the shortname of the called class.


    public
                    get_class_shortname() : string

Return values

string —

The shortname for this object's class.

get_classes_in_namespace()

Obtains all classes associated with this class's current namespace.


    public
                    get_classes_in_namespace([bool $shortnames = false ]) : array<string|int, mixed>

Parameters

$shortnames : bool = false

Return values

array<string|int, mixed> —

An array of classes currently in this object's namespace

get_endpoint_filepath()

Obtains the absolute filepath to the PHP file generated for this Endpoint.


    public
                    get_endpoint_filepath() : string

Return values

string —

The absolute filepath to this Endpoint's PHP file within the pfSense webroot.

get_pagination_resource_links()

Obtains the `prev` and `next` HATEOAS resource links for pagination use. These links supply the previous and next set of objects from the dataset.


    public
                    get_pagination_resource_links(int $limit, int $offset) : void

Parameters

$limit : int: The maximum number of Model objects to retrieve. This will be used to determine the prev and next link values.
$offset : int: The starting point in the dataset requested for pagination. This will be used to determine the prev and next link values.

log_error()

Logs an error to the syslog.


    public
            static        log_error(string $message) : void

Parameters

$message : string: The error message to write to the syslog

process_request()

Processes the API request and returns the serialized API response to send back to the client.


    public
                    process_request() : string

Return values

string —

The serialized API response to send back to the client.

response_handler()

Defines a middleware method that can be used to handle the call's Response object before it is sent back to the client. This can be used by child Endpoints to extend or override the default Response handling behavior.


    public
                    response_handler(Response $response) : Response

Parameters

$response : Response: The Response object handle before it is sent back to the client by process_request()

Return values

Response

delete()

Deletes an existing object for the assigned Model using the data submitted in a DELETE request.


    protected
                    delete() : Model|ModelSet

Return values

Model|ModelSet

get()

Obtains the object data for GET requests to this Endpoint.


    protected
                    get() : Model|ModelSet

Return values

Model|ModelSet

options()

Populates associated headers whenever an OPTIONS request is received.


    protected
        final            options() : void

patch()

Updates an existing object for the assigned Model using the data submitted in a PATCH request.


    protected
                    patch() : Model|ModelSet

Return values

Model|ModelSet

post()

Creates a new object for the assigned Model using the data submitted in a POST request.


    protected
                    post() : Model|ModelSet

Return values

Model|ModelSet

put()

Replaces all existing objects for the assigned Model using the data submitted in a PUT request.


    protected
                    put() : Model|ModelSet

Return values

Model|ModelSet

SystemTunablesEndpoint extends Endpoint in package RESTAPI

Table of Contents

Properties

Methods

Properties

$append

$async

$auth_methods

$decode_content_handlers

$delete_help_text

$delete_privileges

$deprecated

$encode_content_handlers

$get_help_text

$get_privileges

$ignore_acl

$ignore_enabled

$ignore_interfaces

$ignore_read_only

$limit

$many

$model

$model_name

$offset

$patch_help_text

$patch_privileges

$post_help_text

$post_privileges

$put_help_text

$put_privileges

$remove

$request_data

$request_method

$request_method_options

$requires_auth

$resource_link_set

$response_types

$restapi_settings

$reverse

$sort_by

$sort_flags

$sort_order

$tag

$url

$client

$errors

Methods

__construct()

build_endpoint_url()

Tags

Return values

check_construct()

check_decode_content_handler_supported()

Parameters

Tags

check_encode_content_handler_supported()

Parameters

Tags

generate_pfsense_privs()

Tags

Return values

get_class_fqn()

Return values

get_class_shortname()

Return values

get_classes_in_namespace()

Parameters

Return values

get_endpoint_filepath()

Return values

get_pagination_resource_links()

Parameters

log_error()

Parameters

process_request()

Return values

response_handler()

Parameters

Tags

Return values

SystemTunablesEndpoint extends Endpoint
in package

RESTAPI