pfSense-pkg-RESTAPI

Model
in package

RESTAPI

uses BaseTraits

Defines a Model object that relates to a pfSense configuration or service. This model defines the necessary steps to validate incoming configuration and create, read, update, and/or delete data from the pfSense configuration this object relates to.

Constants

WRITE_LOCK_FILE = '/tmp/.RESTAPI.write_config.lock'

Properties

$always_apply : bool
$async : bool
$cache : Cache|null
$cache_class : string
$client : Auth
$config_path : string|null
$id : mixed
$id_type : string
$initial_object : Model|null
$internal_callable : string
$many : bool
$many_maximum : int
$many_minimum : int
$package_includes : array<string|int, mixed>
$packages : array<string|int, mixed>
$parent_id : mixed
$parent_id_type : string
$parent_model : Model|null
$parent_model_class : string
$placement : int|null
$protected_model_query : array<string|int, mixed>
$related_objects : ModelSet
$skip_init : bool
$sort_by : array<string|int, mixed>|null
$sort_order : int|null
$subsystem : string
$unique_together_fields : array<string|int, mixed>
$update_strategy : string
$verbose_name : string
$verbose_name_plural : string

Methods

__construct() : mixed: Values to assign when a Model object is first constructed.
apply() : mixed: Initializes the default 'apply' method. This method is intended to be overridden by a child model class and is responsible for reloading/restarting services after changes occur.
check_many_maximum() : void: Checks if the creation of a new object would put the number of objects for this Model over the $many_maximum value.
check_many_minimum() : void: Checks if the deletion of this object would put the number of objects for this Model below the $many_minimum value.
create() : Model: Perform validation, create this object internally and restart any associated services.
del_config() : mixed: Delete a key from the configuration
delete() : Model: Perform validation, delete this object internally and restart any associated services.
delete_all() : ModelSet|Model: Deletes all Model objects for this Model. This method is only available for $many Models without a $parent_model_class.
delete_many() : ModelSet: Uses a query to delete many Model objects at once. This method is only available for $many Models.
does_apply_immediately() : bool|null: Determines if this Model applies changes immediately or if they must applied manually after changes are made.
from_internal() : mixed: Obtain this Model object from the internal pfSense configuration by object ID. If the specified ID exists in config, this Model object will be overwritten with the contents of that object.
from_internal_object() : void: Converts an internal object to this Model object's representation. This method is used to convert the internal object obtained from the pfSense configuration to the representation values used by this Model object.
from_representation() : mixed: Loads the Model object using an array representation of the object.
get_all_model_classes() : array<string|int, mixed>: Obtains an array of all Model classes.
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_config() : mixed: Read the value of specific configuration section by path.
get_config_path() : string|null: Retrieves the full config path including any assigned parent Model paths.
get_fields() : array<string|int, mixed>: Populates an array of field names for this model.
get_internal_objects() : array<string|int, mixed>: Obtains all internal objects for this Model. When a `config_path` is specified, this method will obtain the internal objects directly from config. When an `internal_callable` is assigned, this method will return the output of the assigned callable.
get_model_references() : ModelSet: Obtains external Models that reference this Model. This method checks Field objects assigned to this Model object for the `referenced_by` property. Any Model objects found that reference this Model object will be returned in a ModelSet object.
get_next_id() : string|int: Default method for obtaining the next ID from the pfSense configuration. This searches for the next index ID for the model in the pfSense configuration and requires the model's `config_path` and `many` properties to be set.
get_parent_model() : Model|null: Obtains the parent of this Model object if a parent Model is assigned.
get_related_endpoint() : Endpoint|null: Obtains the Endpoint this Model class is assigned to.
get_related_link() : ResourceLink: Obtains a HAL resource link to a specific Model object.
get_related_links() : ResourceLinkSet: Obtains REST API links to resources related to this Model object.
is_config_enabled() : bool: Checks if a specific config value is set. Toggle values are often set when enabled, or missing when they are not. This check is better suited for pfSense configurations than isset().
is_parent_model_many() : bool|null: Checks if the parent Model class assigned to this Model class is a $many enabled Model.
log_error() : void: Logs an error to the syslog.
merge_config() : mixed: Merges changed Model field values into the config. This is similar to `set_config()` but instead of replacing the entire config path with a set value, it only sets Field's known to this Model. Any Fields in the stored object that are not defined in a Field assigned to this Model will be left unchanged.
paginate() : array<string|int, mixed>: Paginates a given array but obtaining a smaller subset of the array based on the provided limit and offset values.
query() : ModelSet: Performs a query on all Model objects for this Model. This is essentially a shorthand way of calling `query()`. This method is only applicable to `many` Models.
read() : Model: Initializes the default 'read' method. By default, this method loads the Model object from its internal object using the current $this->id value and returns the ($this) Model object. Running this method will overwrite $this object.
read_all() : ModelSet|Model: Fetches Model objects for all objects stored in the internal pfSense values. If `config_path` is set, this will load Model objects for each object stored at the config path. If `internal_callable` is set, this will create Model objects for each object returned by the specified callable.
reload_config() : void: Reloads the configuration to include any changes that may have occurred since the last config reload
replace_all() : ModelSet: Perform validation and replace all existing objects for this Model with a specified set of Model representations.
set_config() : mixed: Set a value by path in the config.
to_internal() : array<string|int, mixed>|string: Converts this Model object into it's internal pfSense configuration form.
to_openapi_schema() : array<string|int, mixed>: Converts this Model object to a PHP array representation of its OpenAPI schema. This is used when auto-generating API documentation. This method can be extended to add additional options to the OpenAPI schema when necessary
to_representation() : array<string|int, mixed>: Creates a serializable array representation of this object. This array is suitable for content serialization such as JSON, YAML, etc.
update() : Model: Perform validation, update this object internally and restart any associated services.
validate() : bool: Performs a full validation on the API model. This includes checking that required packages are installed and validating all assigned Fields. Note: Fields are validated in the order they are defined in the class.
validate_extra() : void: Allows child classes to define extra validation for their Models. This can be used to build complex validations that check conditions between multiple Model fields.
write_config() : void: Write configuration changes to the config file
_create() : mixed: Initializes the default '_create' method. For Models with a `config_path` and `many` set, this method will automatically obtain the next model ID for the object and write this object to the pfSense config. Other Models will require this method to be overridden to support creations for this object.
_delete() : mixed: Initializes the default '_delete' method. For Models with a `config_path` and `many`, this method will automatically remove the existing object from configuration. Other Models must override this method with context-specific deletions.
_update() : mixed: Initializes the default '_update' method. For Models with a `config_path`, this method will automatically write changes to the existing object in configuration. Other Models must override this method with context specific updates.
apply_create() : mixed: Performs steps and processes required to apply changes after the `create()` method runs. This can be overridden to add custom steps applying for just create actions. Defaults to simply calling `apply()`.
apply_delete() : mixed: Performs steps and processes required to apply changes after the `delete()` method runs. This can be overridden to add custom steps to apply after delete actions only. Defaults to simply calling `apply()`.
apply_replace_all() : mixed: Performs steps and processes required to apply changes after the `replace_all()` method runs. This can be overridden to add custom steps to apply after replace all actions only. Defaults to simply calling `apply()`.
apply_update() : mixed: Performs steps and processes required to apply changes after the `update()` method runs. This can be overridden to add custom steps to apply after update actions only. Defaults to simply calling `apply()`.
init_config() : mixed: Initialize the configuration array of a specific config path
pre_apply() : mixed: Initializes the default 'pre_apply' method. This method is intended to be overidden by a child model class and is called immediately before the 'apply' method. This method runs regardless of whether an apply was requested.
pre_apply_create() : mixed: Initializes the default 'pre_apply_create' method. This method is intended to be overridden by a child model class and is called immediately before the 'apply' method for create actions only. This method runs regardless of whether an apply was requested. By default, this method simply calls the global 'pre_apply' method.
pre_apply_delete() : mixed: Initializes the default 'pre_apply_delete' method. This method is intended to be overridden by a child model class and is called immediately before the 'apply' method for delete actions only. This method runs regardless of whether an apply was requested. By default, this method simply calls the global 'pre_apply' method.
pre_apply_update() : mixed: Initializes the default 'pre_apply_update' method. This method is intended to be overridden by a child model class and is called immediately before the 'apply' method for update actions only. This method runs regardless of whether an apply was requested. By default, this method simply calls the global 'pre_apply' method.
set_placement() : void: For $many enabled models, this method will place this object in a specific location in the list of stored objects. This is primarily used to
sort() : void: Sorts `many` Model entries internally before writing the changes to config. This is useful for Model's whose internal objects must be written in a specific order.
append_array_changes() : void: Appends changes between the current object and the initial object for `many` enabled fields. This allows for changes to array field values to be appended to the existing array during updates instead of replaced.
check_packages() : mixed: Checks if the required pfSense packages for this model are installed.
check_unique_together() : void: Checks that any Fields which must be unique together are unique from all other existing objects for this Model.
construct_from_internal() : void: Attempts to construct this Model object by fetching an existing object from config/internally.
generate_verbose_name() : string: Auto-generates a verbose name for this Model class using its class name.
generate_verbose_name_plural() : string: Auto-generates the plural version of this Model's $verbose_name for $many enabled Models
get_cache() : Cache|null: Obtains the Cache object of the class assigned in the $cache_class property.
get_default_client() : Auth: Obtains a default $client Auth object for this Model object to use.
is_field_hidden() : bool: Determines if a given Model field should be hidden in responses.
is_fields_internal_name_unique() : void: Checks to ensure each of this Model's Field object has an internal name that is unique to it's namespace.
remove_array_changes() : void: Removes changes between the current object and the initial object for `many` enabled fields. This allows for changes to array field values to be removed from the existing array during updates instead of being replaced.
set_construct_options() : array<string|int, mixed>: Checks for options passed in during object construction and maps known options to Model properties. Any options that are not known options to the core Model will be returned so they can be merged into the Model data during construction.
setup_fields() : void: Provides this Model's Field object properties relevant information like its field name and provides this Model object as this Field's $context Model object.

WRITE_LOCK_FILE


    public
        mixed
    WRITE_LOCK_FILE
    = '/tmp/.RESTAPI.write_config.lock'

$always_apply


    public
        bool
    $always_apply
     = false

Force this Model to always run the apply() method after create(), update(), delete(), and replace_all().

$async


    public
        bool
    $async

If set to true, this Model will attempt to apply objects in the background. If set to false, this Model will wait for the apply*() methods to complete before providing a response. In many cases, the apply*() methods can take significant time to complete and, in extreme cases, can cause timeouts. Using $async enables these processes to run in the background, allowing the client to proceed without waiting. Polling Models should be made available for Models relying on $async, enabling clients to check the status of the process. Note: Not all Model classes will support or respect this value. Only Models utilizing Dispatcher objects support $async.

$cache


    public
        Cache|null
    $cache
     = null

The Cache object of the class specified in the $cache_class property. This is only applicable if a $cache_class was assigned.

$cache_class


    public
        string
    $cache_class
     = ''

The class name of a Cache object this Model utilizes. This is only relevant to Model who pull data from a local cache file using a Cache object and typically is only used for Models with an internal_callable assigned. The value assigned here must be an existing class shortname in the \RESTAPI\Caches\ namespace.

$client


    public
        Auth
    $client

The Auth object containing the username, IP address, and other authentication details of the individual interacting with this Model. If no value is assigned, a default Auth object will be defined. Note: Some Models require information from the $client; therefore, this value must always be assigned.

$config_path


    public
        string|null
    $config_path
     = null

The configuration path where this Model's object(s) are internally stored. This property is mandatory unless an $internal_callable is explicitly defined. If a $parent_model_class is assigned, this path will be relative to the parent Model's $config_path. Otherwise, this is an absolute config path.

$id


    public
        mixed
    $id
     = null

The ID of the current Model object. This applies exclusively to Models with $many enabled. New Model objects will not possess an ID until the create() method is executed.

$id_type


    public
        string
    $id_type
     = 'integer'

The data type of the ID field for this Model. In most cases, this should be set to 'integer'. In some cases, the ID field may be a 'string'. This field should be set accordingly to ensure documentation and validation processes are accurate. This applies exclusively to Models with $many enabled.

$initial_object


    public
        Model|null
    $initial_object
     = null

Contains the current Model object as stored in config/internally. This can be used to reference values that may have changed during creation, modification, or deletion.

$internal_callable


    public
        string
    $internal_callable
     = ''

For Models that do not interact with stored pfSense configuration values, specify the name of a callable method here to pull the internal values for this Model. This property cannot be used if a $config_path is already specified. This must be set to an existing method name assigned to this Model class.

$many


    public
        bool
    $many
     = false

If set to true, this Model will facilitate the creation of multiple objects of its kind and enable IDs for this field. If set to false, this Model will exclusively support a single object and abstain from utilizing IDs.

$many_maximum


    public
        int
    $many_maximum
     = 65535

Specifies the maximum number of associated Models that can be present at any time. If a new creation is requested, and it would result in the number of associated objects growing beyond this value, the creation will be denied. This condition is applicable only when the $many property is set to true.

$many_minimum


    public
        int
    $many_minimum
     = 0

Specifies the minimum number of associated Models that must be present at all times. If a deletion is requested, and it would result in the number of associated objects falling below this value, the deletion will be denied. This condition is applicable only when the $many property is set to true.

$package_includes


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

Assigns PHP files to include that are specific to one or more of the assigned $packages. These files will be imported during Model validation to prevent an error from being thrown if the Model is referenced on a system without these packages installed.

$packages


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

Specifies any add-on packages required for this Model to operate. This must be an array of package full-names (i.e., pfSense-pkg-sudo) or left empty to not require any add-on packages.

$parent_id


    public
        mixed
    $parent_id
     = null

For Models acting as children to a different Model class, this property will contain the ID of the parent model object. If a $parent_model_class is defined, this value MUST be specified during object construction.

$parent_id_type


    public
        string
    $parent_id_type
     = 'integer'

The data type of the parent ID field for this Model. In most cases, this should be set to 'integer'. In some cases, the parent ID field may be a 'string'. This field should be set accordingly to ensure documentation and validation processes are accurate. This applies exclusively to Models with a $parent_model_class assigned.

$parent_model


    public
        Model|null
    $parent_model
     = null

The parent Model object of this Model. This property is relevant only if a $parent_model_class is assigned. This property is automatically set using the $parent_model_class and $parent_id properties accordingly. If no parent Model class is found, or the parent object does not exist, this value will be null.

$parent_model_class


    public
        string
    $parent_model_class
     = ''

The class name of the parent Model class. This is necessary only if this Model is nested under another Model.

$placement


    public
        int|null
    $placement
     = null

Set the config index where this object should be written to. This allows objects to be moved or placed into any arbitrary index in the config. This property is only applicable if the $config_path and $many properties are set.

$protected_model_query


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

Defines query parameters for existing objects of this Model that should never be replaced or deleted. This can be used to protect built-in objects that should not be deleted. This property only applies to $many enabled Models.

$related_objects


    public
        ModelSet
    $related_objects

A ModelSet containing foreign Model objects related to this Model. These are primarily populated by ForeignModelFields assigned to this Model object. If no related Models are found, this ModelSet will not contain any Model objects. This property is primarily used by Endpoint classes to determine the correct HATEOAS link to include in REST API responses.

$skip_init


    public
        bool
    $skip_init
     = false

If set to true, this Model object will not be loaded from its internal representation during construction. This is useful when you need to create a Model object to be used as a reference without trigger logic that would normally occur by loading the object from its internal representation. This must be set as a parameter during object construction to have an effect.

$sort_by


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

Sets the field names this Model will use when sorting objects written to the pfSense configuration. These fields must be set to an existing property name from this Model, and that property must be assigned a Field class. Leave empty to disable sorting for this Model. In most cases, sorting should not be used.

$sort_order


    public
        int|null
    $sort_order
     = null

For $many enabled Models, this property can be used to set the PHP sort option 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

$subsystem


    public
        string
    $subsystem
     = ''

The pfSense subsystem this Model relates to. This is typically only relevant for Models that allow the internal config to be written but applied at a later time. The subsystem specified here will automatically be marked as 'dirty' (i.e., has unapplied changes) whenever this Model writes to the config. It will automatically have the subsystem 'dirty' status cleared after the apply() method(s) are called. The name of the pfSense subsystem depends on the pfSense configuration item this Model relates. Refer to the pfSense source files to determine what (if any) subsystem should be set. Typically, it will appear as a parameter value in the mark_subsystem_dirty() or clear_subsystem_dirty() pfSense functions.

$unique_together_fields


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

An array specifying field names that must be unique together. This is similar to the Field object's $unique property but requires the combination of each of these field's values to be unique from any other Model object of its kind. Each value specified here must be an existing property for this Model and must be assigned a Field class.

$update_strategy


    public
        string
    $update_strategy
     = 'merge'

Define how this Model should update existing values in configuration. Set to merge to only update the values that were actually changed in config, or set to replace to replace the entire Model object in config during updates. In general, replace works well for $many enabled Models, and merge works well for non $many enabled Models or for Models that share a $config_path with other Models.

$verbose_name


    public
        string
    $verbose_name
     = ''

Sets the human-readable name for this Model. This value is primarily used where this Model is referenced in Forms and the API documentation. By default, this property will attempt to be determined using the Model class name by separating capitalized words in the class name with a space. In some cases, this may not be accurately determined and can be manually set using this property if needed.

$verbose_name_plural


    public
        string
    $verbose_name_plural
     = ''

Manually specifies the plural representation of $verbose_name. By default, this property will be set to $verbose_name with s appended to the end, unless $verbose_name already ends in an s, in which es will be appended to the end instead. In some cases, this may not be accurate; this property can be manually set using this property if needed.

__construct()

Values to assign when a Model object is first constructed.


    public
                    __construct([mixed $id = null ][, mixed|null $parent_id = null ][, mixed $data = [] ], mixed ...$options) : mixed

Parameters

$id : mixed = null: If specified, the internal object with this ID will be obtained as the Model object.
$parent_id : mixed|null = null: The ID of the parent object this object is nested under. This is only applicable to Models with a parent_model_class assigned that is also a many Model.
$data : mixed = []: Allows objects to be obtained, created and/or updated using an array of field-value pairs. If this array contains an id field, the internal object with this ID will be obtained as the Model object first. Any additional Fields will be used to set the Model object's values.
$options : mixed: Additional arguments to provide to this Model. Any additional arguments provided will merged into the Model's $data parameter. This can be used to set Model field values using parameters instead of an array format via $data. Note: In the event that a field value is set in $data and $args, the value found in $args will be used.

apply()

Initializes the default 'apply' method. This method is intended to be overridden by a child model class and is responsible for reloading/restarting services after changes occur.


    public
                    apply() : mixed

check_many_maximum()

Checks if the creation of a new object would put the number of objects for this Model over the $many_maximum value.


    public
                    check_many_maximum() : void

check_many_minimum()

Checks if the deletion of this object would put the number of objects for this Model below the $many_minimum value.


    public
                    check_many_minimum() : void

create()

Perform validation, create this object internally and restart any associated services.


    public
        final            create([bool $apply = false ]) : Model

Parameters

$apply : bool = false: Set to true if you would like to immediately apply the changes after they are made.

Return values

Model —

Returns the created Model object (this object).

del_config()

Delete a key from the configuration


    public
            static        del_config(mixed $path) : mixed

Parameters

$path : mixed: string path with '/' separators

delete()

Perform validation, delete this object internally and restart any associated services.


    public
        final            delete([bool $apply = false ]) : Model

Parameters

$apply : bool = false: Set to true if you would like to immediately apply the changes after they are made.

Return values

Model —

Returns the deleted Model object (this object).

delete_all()

Deletes all Model objects for this Model. This method is only available for $many Models without a $parent_model_class.


    public
            static        delete_all() : ModelSet|Model

Return values

ModelSet|Model

delete_many()

Uses a query to delete many Model objects at once. This method is only available for $many Models.


    public
            static        delete_many([array<string|int, mixed> $query_params = [] ][, array<string|int, mixed> $excluded = [] ][, mixed|null $parent_id = null ][, int $limit = 0 ][, int $offset = 0 ], mixed ...$vl_query_params) : ModelSet

Parameters

$query_params : array<string|int, mixed> = []: An array of query parameters.
$excluded : array<string|int, mixed> = []: An array of field names to exclude from the query. This is helpful when query data may have extra values that you do not want to include in the query.
$parent_id : mixed|null = null: Specifies the ID of the parent Model to read all objects from. This is required for $many Models with a $parent_model_class. This value has no affect otherwise.
$limit : int = 0: The maximum number of Model objects to retrieve. This is only applicable to $many enabled Models.
$offset : int = 0: The starting point in the dataset to be used with $limit. This is only applicable to $many enabled Models.
$vl_query_params : mixed: Qyery parameters that are passed in using variable-length arguments https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list

Return values

ModelSet —

The queried ModelSet containing only Model objects that matched the query.

does_apply_immediately()

Determines if this Model applies changes immediately or if they must applied manually after changes are made.


    public
                    does_apply_immediately() : bool|null

This is intended to be used to more accurately determine the 'Applies immediately' value in the API documentation to prevent misleading information.

Return values

bool|null —

Returns true if this Model applies changes immediately, false if changes must be applied manually, or null if this does not apply to this Model.

from_internal()

Obtain this Model object from the internal pfSense configuration by object ID. If the specified ID exists in config, this Model object will be overwritten with the contents of that object.


    public
                    from_internal() : mixed

from_internal_object()

Converts an internal object to this Model object's representation. This method is used to convert the internal object obtained from the pfSense configuration to the representation values used by this Model object.


    public
                    from_internal_object(mixed $internal_object) : void

Parameters

$internal_object : mixed: The internal object obtained from the pfSense configuration. This should be an associative array, in the event that it's not (uninitialized configuration), it will become an empty array.

from_representation()

Loads the Model object using an array representation of the object.


    public
        final            from_representation([array<string|int, mixed> $data = [] ], mixed ...$options) : mixed

Parameters

$data : array<string|int, mixed> = []: The array of key-value pairs to use when loading the Model object from representation.
$options : mixed: Additional arguments to provide to this Model. Any additional arguments provided will merged into the Model's $data parameter. This can be used to set Model field values using parameters instead of an array format via $data. Note: In the event that a field value is set in $data and $args, the value found in $args will be used.

get_all_model_classes()

Obtains an array of all Model classes.


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

Parameters

$shortnames : mixed = false: bool Set to true to obtain the shortnames of all Model classes.

Return values

array<string|int, mixed> —

An array of all Model classes.

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_config()

Read the value of specific configuration section by path.


    public
            static        get_config(mixed $path[, mixed $default = null ]) : mixed

Parameters

$path : mixed: string config path with '/' as separators
$default : mixed = null: mixed value to return if the path is not found

get_config_path()

Retrieves the full config path including any assigned parent Model paths.


    public
                    get_config_path() : string|null

Return values

string|null

get_fields()

Populates an array of field names for this model.


    public
        final            get_fields([bool $required_only = false ]) : array<string|int, mixed>

Parameters

$required_only : bool = false: Only obtain required Fields

Return values

array<string|int, mixed> —

An array of field names for this model.

get_internal_objects()

Obtains all internal objects for this Model. When a `config_path` is specified, this method will obtain the internal objects directly from config. When an `internal_callable` is assigned, this method will return the output of the assigned callable.


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

Return values

array<string|int, mixed> —

The array of internal objects without any additional processing performed.

get_model_references()

Obtains external Models that reference this Model. This method checks Field objects assigned to this Model object for the `referenced_by` property. Any Model objects found that reference this Model object will be returned in a ModelSet object.


    public
                    get_model_references() : ModelSet

Return values

ModelSet —

A ModelSet containing any Model objects that reference this Model object.

get_next_id()

Default method for obtaining the next ID from the pfSense configuration. This searches for the next index ID for the model in the pfSense configuration and requires the model's `config_path` and `many` properties to be set.


    public
                    get_next_id() : string|int

For Models that do not use a config_path or does not use config index IDs, this method can be overridden by the child model class to add custom processes to obtain the next available ID.

Return values

string|int

get_parent_model()

Obtains the parent of this Model object if a parent Model is assigned.


    public
                    get_parent_model() : Model|null

Return values

Model|null —

The parent Model object with the provided parent_id or null if no parent Model is set.

get_related_endpoint()

Obtains the Endpoint this Model class is assigned to.


    public
                    get_related_endpoint(bool $many) : Endpoint|null

Parameters

$many : bool: Set to true to obtain the $many enabled Endpoint for this Model, set to false to obtain the Endpoint for this Model that does not have $many enabled.

Return values

Endpoint|null —

The Endpoint object that has this Model class assigned or null if none was found

get_related_link()

Obtains a HAL resource link to a specific Model object.


    public
            static        get_related_link(Model $model, string $rel[, string $method = 'GET' ][, bool $use_namespace = true ]) : ResourceLink

Parameters

$model : Model: The Model object to obtain a link for.
$rel : string: The HAL resource link name to assign this ResourceLink object
$method : string = 'GET'
$use_namespace : bool = true: Set to true to prefix this $rel with this project's HAL prefix value. This should be used for non-standard rel values.

Return values

ResourceLink —

The ResourceLink object containing the links and attributes of the given $model.

get_related_links()

Obtains REST API links to resources related to this Model object.


    public
                    get_related_links() : ResourceLinkSet

Return values

ResourceLinkSet —

A ResourceLinkSet containing REST API links to related Model objects.

is_config_enabled()

Checks if a specific config value is set. Toggle values are often set when enabled, or missing when they are not. This check is better suited for pfSense configurations than isset().


    public
            static        is_config_enabled(mixed $path[, mixed $enable_key = 'enable' ]) : bool

Parameters

$path : mixed: string path with '/' separators
$enable_key : mixed = 'enable': string an optional alternative key value for the enable key

Return values

bool

is_parent_model_many()

Checks if the parent Model class assigned to this Model class is a $many enabled Model.


    public
                    is_parent_model_many() : bool|null

Return values

bool|null —

Returns true if a $parent_model_class is assigned to this Model and the parent Model has $many enabled, false if a $parent_model_class is assigned to this Model and the parent Model does not have $many enabled, or null if no $parent_model_class is assigned to this Model.

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

merge_config()

Merges changed Model field values into the config. This is similar to `set_config()` but instead of replacing the entire config path with a set value, it only sets Field's known to this Model. Any Fields in the stored object that are not defined in a Field assigned to this Model will be left unchanged.


    public
                    merge_config(mixed $path) : mixed

Parameters

$path : mixed: string The Model config path including any Model ID

paginate()

Paginates a given array but obtaining a smaller subset of the array based on the provided limit and offset values.


    public
            static        paginate(array<string|int, mixed> $array, int $limit, int $offset[, bool $preserve_keys = false ]) : array<string|int, mixed>

Parameters

$array : array<string|int, mixed>: The array to paginate.
$limit : int: The maximum number of items to return in the paginated array. Use 0 to impose no limit.
$offset : int: The starting point in the array to begin the paginated array.
$preserve_keys : bool = false: Set to true to preserve the keys of the array. This is useful when the array is associative and you want to maintain the key-value pairs.

Return values

array<string|int, mixed> —

The paginated array containing only the subset of items that match the limit and offset values.

query()

Performs a query on all Model objects for this Model. This is essentially a shorthand way of calling `query()`. This method is only applicable to `many` Models.


    public
            static        query([array<string|int, mixed> $query_params = [] ][, array<string|int, mixed> $excluded = [] ][, mixed|null $parent_id = null ][, int $limit = 0 ][, int $offset = 0 ][, bool $reverse = false ][, array<string|int, mixed>|null $sort_by = null ][, int $sort_order = SORT_ASC ], mixed ...$vl_query_params) : ModelSet

Parameters

$query_params : array<string|int, mixed> = []: An array of query parameters.
$excluded : array<string|int, mixed> = []: An array of field names to exclude from the query. This is helpful when query data may have extra values that you do not want to include in the query.
$parent_id : mixed|null = null: Specifies the ID of the parent Model to read all objects from. This is required for $many Models with a $parent_model_class. This value has no affect otherwise.
$limit : int = 0: The maximum number of Model objects to retrieve. This is only applicable to $many enabled Models.
$offset : int = 0: The starting point in the dataset to be used with $limit. This is only applicable to $many enabled Models.
$reverse : bool = false: Set to true to reverse the order of the ModelSet. This is only applicable to $many enabled Models.
$sort_by : array<string|int, mixed>|null = null
$sort_order : int = SORT_ASC
$vl_query_params : mixed: Qyery parameters that are passed in using variable-length arguments https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list

Return values

ModelSet —

The queried ModelSet containing only Model objects that matched the query.

read()

Initializes the default 'read' method. By default, this method loads the Model object from its internal object using the current $this->id value and returns the ($this) Model object. Running this method will overwrite $this object.


    public
        final            read() : Model

Return values

Model —

Loads the Model object from its internal value using the current $this->id value and returns that object.

read_all()

Fetches Model objects for all objects stored in the internal pfSense values. If `config_path` is set, this will load Model objects for each object stored at the config path. If `internal_callable` is set, this will create Model objects for each object returned by the specified callable.


    public
            static        read_all([mixed|null $parent_id = null ][, int $limit = 0 ][, int $offset = 0 ][, bool $reverse = false ]) : ModelSet|Model

Parameters

$parent_id : mixed|null = null: Specifies the ID of the parent Model to read all objects from. This is required for $many Models with a $parent_model_class. This value has no affect otherwise.
$limit : int = 0: The maximum number of Model objects to retrieve. This is only applicable to $many enabled Models.
$offset : int = 0: The starting point in the dataset to be used with $limit. This is only applicable to $many enabled Models.
$reverse : bool = false: Set to true to reverse the order of the ModelSet. This is only applicable to $many enabled Models.

Return values

ModelSet|Model —

Returns a ModelSet of Models if many is enabled or a single Model object if many is not enabled.

reload_config()

Reloads the configuration to include any changes that may have occurred since the last config reload


    public
            static        reload_config([bool $force_parse = false ]) : void

Parameters

$force_parse : bool = false: Force an entire reparse of the config.xml file instead of the cached config.

replace_all()

Perform validation and replace all existing objects for this Model with a specified set of Model representations.


    public
        final            replace_all(mixed $data[, bool $apply = false ]) : ModelSet

This method is only available for $many Models.

Parameters

$data : mixed: An array of many Model representations to set. Any existing Model objects will be replaced with the objects defined in this array.
$apply : bool = false: Apply this change immediately after replacing all Model objects. Note: Models with the $always_apply property set to true will ignore this value.

Return values

ModelSet —

A ModelSet containing all the Model objects found in config after replacement.

set_config()

Set a value by path in the config.


    public
            static        set_config(mixed $path, mixed $value[, mixed $default = null ]) : mixed

Parameters

$path : mixed: string path with '/' separators
$value : mixed: mixed value to set
$default : mixed = null: mixed value to return if the path is not found

to_internal()

Converts this Model object into it's internal pfSense configuration form.


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

Return values

array<string|int, mixed>|string —

The internal value suitable for writing to the pfSense configuration.

to_openapi_schema()

Converts this Model object to a PHP array representation of its OpenAPI schema. This is used when auto-generating API documentation. This method can be extended to add additional options to the OpenAPI schema when necessary


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

Return values

array<string|int, mixed> —

A PHP array containing this Model as an OpenAPI schema.

to_representation()

Creates a serializable array representation of this object. This array is suitable for content serialization such as JSON, YAML, etc.


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

Return values

array<string|int, mixed> —

The serializable array representation of this object.

update()

Perform validation, update this object internally and restart any associated services.


    public
        final            update([bool $apply = false ][, bool $append = false ][, bool $remove = false ]) : Model

Parameters

$apply : bool = false: Set to true if you would like to immediately apply the changes after they are made.
$append : bool = false: Set to true if you would like to append changes to arrays in the existing object instead of replacing the entire array. This only applies to many enabled Fields.
$remove : bool = false: Set to true if you would like to remove values from arrays in the existing object instead of replacing the entire array. This only applies to many enabled Fields.

Return values

Model —

Returns the updated Model object (this object).

validate()

Performs a full validation on the API model. This includes checking that required packages are installed and validating all assigned Fields. Note: Fields are validated in the order they are defined in the class.


    public
        final            validate([bool $requires_id = false ][, bool $create_id = false ][, bool $only_id = false ][, bool $skip_parent = false ][, ModelSet|null $modelset = null ]) : bool

Parameters

$requires_id : bool = false: Whether the id field should be validated in this request. This is typically only necessary for update and delete actions.
$create_id : bool = false: If true, a new ID will be created for this object if this is a $many Model. This is primarily used for creations.
$only_id : bool = false: Only validate the id field. This is primarily used for deletions.
$skip_parent : bool = false: Skip validating the assigned parent ID. This only applies to Models that have a parent_model_class value assigned. In most cases, this should not be changed from the default. This is only intended for nested Model validation.
$modelset : ModelSet|null = null: Sets a specific ModelSet to use when validations require the use of all existing objects for this Model. The only current use case for this is in \RESTAPI\Fields\NestedModelField where we need to validate many objects before they are created.

Return values

bool —

true if the model's data is valid.

validate_extra()

Allows child classes to define extra validation for their Models. This can be used to build complex validations that check conditions between multiple Model fields.


    public
                    validate_extra() : void

write_config()

Write configuration changes to the config file


    public
        final            write_config(string $change_note[, int $attempts = 60 ]) : void

Parameters

$change_note : string: The message to write to the change log.
$attempts : int = 60: The number of write attempts to make before giving up in the event that a lock is present.

_create()

Initializes the default '_create' method. For Models with a `config_path` and `many` set, this method will automatically obtain the next model ID for the object and write this object to the pfSense config. Other Models will require this method to be overridden to support creations for this object.


    protected
                    _create() : mixed

_delete()

Initializes the default '_delete' method. For Models with a `config_path` and `many`, this method will automatically remove the existing object from configuration. Other Models must override this method with context-specific deletions.


    protected
                    _delete() : mixed

_update()

Initializes the default '_update' method. For Models with a `config_path`, this method will automatically write changes to the existing object in configuration. Other Models must override this method with context specific updates.


    protected
                    _update() : mixed

apply_create()

Performs steps and processes required to apply changes after the `create()` method runs. This can be overridden to add custom steps applying for just create actions. Defaults to simply calling `apply()`.


    protected
                    apply_create() : mixed

apply_delete()

Performs steps and processes required to apply changes after the `delete()` method runs. This can be overridden to add custom steps to apply after delete actions only. Defaults to simply calling `apply()`.


    protected
                    apply_delete() : mixed

apply_replace_all()

Performs steps and processes required to apply changes after the `replace_all()` method runs. This can be overridden to add custom steps to apply after replace all actions only. Defaults to simply calling `apply()`.


    protected
                    apply_replace_all(ModelSet $initial_objects, ModelSet $new_objects) : mixed

Parameters

$initial_objects : ModelSet: A ModelSet containing each existing object for this Model as they were when the replace_all() method was initially called. This is useful when a function or service needs to be restarted for each object before replacing the set.
$new_objects : ModelSet: A ModelSet containing each of the new objects for this Model. Note: at this point, each Model object within this ModelSet has already been written to config. This method is responsible for ensuring it is applied to any backend services.

apply_update()

Performs steps and processes required to apply changes after the `update()` method runs. This can be overridden to add custom steps to apply after update actions only. Defaults to simply calling `apply()`.


    protected
                    apply_update() : mixed

init_config()

Initialize the configuration array of a specific config path


    protected
            static        init_config(mixed $path) : mixed

Parameters

$path : mixed: string config path with '/' as separators

pre_apply()

Initializes the default 'pre_apply' method. This method is intended to be overidden by a child model class and is called immediately before the 'apply' method. This method runs regardless of whether an apply was requested.


    protected
                    pre_apply() : mixed

pre_apply_create()

Initializes the default 'pre_apply_create' method. This method is intended to be overridden by a child model class and is called immediately before the 'apply' method for create actions only. This method runs regardless of whether an apply was requested. By default, this method simply calls the global 'pre_apply' method.


    protected
                    pre_apply_create() : mixed

pre_apply_delete()

Initializes the default 'pre_apply_delete' method. This method is intended to be overridden by a child model class and is called immediately before the 'apply' method for delete actions only. This method runs regardless of whether an apply was requested. By default, this method simply calls the global 'pre_apply' method.


    protected
                    pre_apply_delete() : mixed

pre_apply_update()

Initializes the default 'pre_apply_update' method. This method is intended to be overridden by a child model class and is called immediately before the 'apply' method for update actions only. This method runs regardless of whether an apply was requested. By default, this method simply calls the global 'pre_apply' method.


    protected
                    pre_apply_update() : mixed

set_placement()

For $many enabled models, this method will place this object in a specific location in the list of stored objects. This is primarily used to


    protected
                    set_placement() : void

sort()

Sorts `many` Model entries internally before writing the changes to config. This is useful for Model's whose internal objects must be written in a specific order.


    protected
                    sort() : void

append_array_changes()

Appends changes between the current object and the initial object for `many` enabled fields. This allows for changes to array field values to be appended to the existing array during updates instead of replaced.


    private
                    append_array_changes() : void

check_packages()

Checks if the required pfSense packages for this model are installed.


    private
                    check_packages() : mixed

check_unique_together()

Checks that any Fields which must be unique together are unique from all other existing objects for this Model.


    private
                    check_unique_together([ModelSet|null $modelset = null ]) : void

Parameters

$modelset : ModelSet|null = null: Sets a specific ModelSet to use when validations require the use of all existing objects for this Model. The only current use case for this is in \RESTAPI\Fields\NestedModelField where we need to validate many objects before they are created.

construct_from_internal()

Attempts to construct this Model object by fetching an existing object from config/internally.


    private
                    construct_from_internal([mixed $id = null ][, mixed $parent_id = null ]) : void

Parameters

$id : mixed = null: The ID of the internal object to construct this object from
$parent_id : mixed = null

generate_verbose_name()

Auto-generates a verbose name for this Model class using its class name.


    private
                    generate_verbose_name() : string

Return values

string

generate_verbose_name_plural()

Auto-generates the plural version of this Model's $verbose_name for $many enabled Models


    private
                    generate_verbose_name_plural() : string

Return values

string

get_cache()

Obtains the Cache object of the class assigned in the $cache_class property.


    private
                    get_cache() : Cache|null

Return values

Cache|null

get_default_client()

Obtains a default $client Auth object for this Model object to use.


    private
                    get_default_client() : Auth

Return values

Auth

is_field_hidden()

Determines if a given Model field should be hidden in responses.


    private
                    is_field_hidden(string $field) : bool

Parameters

$field : string: The field name to check for sensitivity.

Return values

bool —

Returns true if the field is sensitive, false if it is not.

is_fields_internal_name_unique()

Checks to ensure each of this Model's Field object has an internal name that is unique to it's namespace.


    private
                    is_fields_internal_name_unique(string $field) : void

Parameters

$field : string: The name of the field to check for a unique internal name

remove_array_changes()

Removes changes between the current object and the initial object for `many` enabled fields. This allows for changes to array field values to be removed from the existing array during updates instead of being replaced.


    private
                    remove_array_changes() : void

set_construct_options()

Checks for options passed in during object construction and maps known options to Model properties. Any options that are not known options to the core Model will be returned so they can be merged into the Model data during construction.


    private
                    set_construct_options(array<string|int, mixed> $options) : array<string|int, mixed>

Parameters

$options : array<string|int, mixed>: The $options passed into the Model's __construct() method.

Return values

array<string|int, mixed> —

An array of additional options that do not relate to core Model properties.

setup_fields()

Provides this Model's Field object properties relevant information like its field name and provides this Model object as this Field's $context Model object.


    private
                    setup_fields() : void

Model in package RESTAPI uses BaseTraits

Table of Contents

Constants

Properties

Methods

Constants

WRITE_LOCK_FILE

Tags

Properties

$always_apply

$async

$cache

$cache_class

$client

$config_path

$id

$id_type

$initial_object

$internal_callable

$many

$many_maximum

$many_minimum

$package_includes

$packages

$parent_id

$parent_id_type

$parent_model

$parent_model_class

$placement

$protected_model_query

$related_objects

$skip_init

$sort_by

$sort_order

$subsystem

$unique_together_fields

$update_strategy

$verbose_name

$verbose_name_plural

Methods

__construct()

Parameters

apply()

check_many_maximum()

Tags

check_many_minimum()

Tags

create()

Parameters

Return values

del_config()

Parameters

Tags

delete()

Parameters

Tags

Return values

delete_all()

Return values

delete_many()

Parameters

Return values

does_apply_immediately()

Return values

from_internal()

Tags

from_internal_object()

Parameters

from_representation()

Parameters

get_all_model_classes()

Parameters

Return values

get_class_fqn()

Return values

get_class_shortname()

Return values

get_classes_in_namespace()

Parameters

Return values

Model
in package

RESTAPI

uses BaseTraits