pfSense-pkg-RESTAPI

NestedModelField extends Field
in package

Defines a Field object for storing nested Model objects in the pfSense configuration. This field allows certain Model objects to be stored as field values for another Model object.

Table of Contents

Constants

SENSITIVE_MASK  = '********'

Properties

$allow_empty  : bool
$allow_null  : bool
$choices  : array<string|int, mixed>
$choices_callable  : string
$conditions  : array<string|int, mixed>
$context  : Model|null
Represents the parent Model this Field object is assigned to. Use this to obtain additional context about the Model, and other Fields/attributes assigned to the parent Model.
$default  : mixed
$default_callable  : string
$delimiter  : string|null
$editable  : bool
$help_text  : string
$internal_name  : string
$internal_namespace  : string
$labels  : array<string|int, mixed>
Contains an array of validation labels assigned to this Field. These labels indicate that specific validations have already been performed and can be referenced, preventing redundant validation in the Model's `validate_*()` methods.
$many  : bool
$many_maximum  : int
$many_minimum  : int
$model  : Model
$model_class  : string
$name  : string
Sets the name of this Field object. Automatically set by the parent Model object to the Model's property name for this Field.
$read_only  : bool
$referenced_by  : array<string|int, mixed>
$representation_only  : bool
$required  : bool
$sensitive  : bool
$type  : string
$unique  : bool
$validators  : array<string|int, mixed>
$value  : mixed
Represents the current value for this Field.
$verbose_choices  : array<string|int, mixed>
Contains the verbose choices originally assigned in the $choices property during object construction.
$verbose_name  : string
$verbose_name_plural  : string
$write_only  : bool
$model_class_short  : string
$modelset  : ModelSet

Methods

__construct()  : mixed
Defines attributes for a Model Field.
__invoke()  : mixed
Allows the Field's current value to be obtained by invoking the field object.
check_field_names()  : void
Checks if this Field object has a valid `name` and `internal_name`. In the event that a `name` exists, but an `internal_name` was not specified, the `internal_name` will be assigned the same value as `name` by this method.
from_internal()  : void
Converts any nested Model objects from their internal values to their representation values.
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_conditions_text()  : string
Formats a descriptive string to explain the `conditions` for this Field. This is intended to be used for OpenAPI documentation generation.
get_default()  : mixed
Obtains the default value for this field.
get_related_model()  : Model|null
Retrieves the related Model object based on this Field's value. Child Field classes must override this method to define the necessary steps for retrieving related objects. This method can only be used on Fields with $many set to false.
get_related_models()  : ModelSet
Retrieves all related Model object based on this Field's value. Child Field classes must override this method to define the necessary steps for retrieving related objects. This method can only be used on Fields with $many set to true.
has_label()  : bool
Checks if this Field object has a specific label assigned. Labels are specific attributes that assigned Validator objects found during validation that may need to be referenced again after validation.
is_referenced_by()  : ModelSet
Uses this Field's $referenced_by property to search for existing Model objects that reference this Field's current value.
log_error()  : void
Logs an error to the syslog.
set_choices()  : void
Accepts a given array of choices and sets the `choices` and `verbose_choices` properties accordingly.
set_choices_from_callable()  : void
Sets choices by calling the `choices_callable` method if present.
set_names()  : void
Sets this Field's name property and assumes defaults based on current name assignments. This field is intended to be called by the parent Model that is assigned this Field objects. Names are based off the name of the property assigned this Field in the parent Model.
sort()  : void
Sorts the nested Model data use the nested Model's `sort_order` and `sort_by` setting. This method closely resembles the Model->sort() method, but does not require values to be set in config beforehand.
to_form_input()  : object
Converts this Field object into a pfSense webConfigurator form input. This method can be overridden by a child class to add custom input field creation.
to_internal()  : array<string|int, mixed>|string|null
Converts the value from its representation value to its internal value.
to_openapi_property()  : array<string|int, mixed>
Converts this NestedModelField object to a PHP array representation of an OpenAPI schema property configuration.
validate()  : bool
Extends the default Field validation method to clear the validation_modelset before starting validation
validate_extra()  : void
Validates the incoming value using the assigned Model's `validate()` method.
_from_internal()  : mixed
Converts the stored internal config value to a represented value. This method must be overridden by a child Field class with the necessary steps to convert the internal value to the representation value. This method must return value in it's represented form! In the case of a `many` field, this method will be called for each individual value after it's been converted to an array by from_internal(). You do not need to worry about converting the $internal_value to an array in this method!
_to_internal()  : array<string|int, mixed>|string|null
Converts the represented value into the internal pfSense value. In most cases child Field classes do not need to override this method as the default behavior of converting the value into a string is sufficient. However, this method can be overridden by a child Field class with custom steps to convert the represented value back into the internal value if needed. This method must return the value in its internal form! In the case of a `many` field, this method will be called for each `$this->value` before it's been joined into it's internal string by to_internal(). If `$this->value` is an array, you do not need to worry about joining `$this->value` into a string. Leave it as an array.
check_value_type()  : mixed
Checks if a given value's type matches this Field object's primary `type`
has_default()  : bool
Checks if this field has a default or default_callable assigned.
are_conditions_met()  : bool
Checks if the conditions defined in the `conditions` property are met.
check_construct()  : void
Checks that values passed in during __construct are valid and do not conflict.
check_field_read_only()  : void
Ensures read-only values do not have a value, default or choices.
check_field_required()  : void
When the field is required, checks if a value is set and checks if mutually exclusive options are both set.
check_field_unique()  : void
Checks if a 'unique' field is actually unique from all other objects related to the $context Model's config path.
check_many_value_length()  : void
Checks the length of the value array when `many` is enabled. This ensures there are at least as many array entries as specified with `many_minimum` but no more array entries than specified with `many_maximum`.
check_model_context()  : void
Ensures this field has a parent model context assigned if a parent model context is required.
check_value_choice()  : void
Checks if a given `value` is a valid `choice` option when `choices` are specified.
check_value_empty()  : bool
Checks if a given `value` is an empty array or string and checks if empty values are allowed.
get_default_from_callable()  : mixed
Obtains this Field's default value by calling the `default_callable` method if defined.
get_value_as_array()  : array<string|int, mixed>|null
Obtains an array of individual values for this field. If `many` is enabled, this method will ensure `value` is already an array and simply return the array value. If `many` is not enabled, the individual `value` will be wrapped in an array and returned. This intended to obtain ALL values that need to validated into an array format for looping purposes.
is_value_editable()  : void
Checks if this Field should allow changed values. If this is not a `editable` Field, and the value given differs from the stored value from the parent Model context an error will be thrown

Constants

SENSITIVE_MASK

public mixed SENSITIVE_MASK = '********'
Tags
const

SENSITIVE_MASK The value that is used to mask the value of a $sensitive Field object. This only applies to values shown in the webConfigurator.

Properties

$allow_empty

public bool $allow_empty = false

$allow_null

public bool $allow_null = false

$choices

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

$choices_callable

public string $choices_callable = ''

$conditions

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

$context

Represents the parent Model this Field object is assigned to. Use this to obtain additional context about the Model, and other Fields/attributes assigned to the parent Model.

public Model|null $context = null

$default

public mixed $default = null

$default_callable

public string $default_callable = ''

$delimiter

public string|null $delimiter = ','

$editable

public bool $editable = true

$help_text

public string $help_text = ''

$internal_name

public string $internal_name = ''

$internal_namespace

public string $internal_namespace = ''

$labels

Contains an array of validation labels assigned to this Field. These labels indicate that specific validations have already been performed and can be referenced, preventing redundant validation in the Model's `validate_*()` methods.

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

$many

public bool $many = false

$many_maximum

public int $many_maximum = 128

$many_minimum

public int $many_minimum = 0

$name

Sets the name of this Field object. Automatically set by the parent Model object to the Model's property name for this Field.

public string $name = ''

Do not attempt to modify this name outside the parent Model class.

$read_only

public bool $read_only = false

$referenced_by

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

$representation_only

public bool $representation_only = false

$required

public bool $required = false

$sensitive

public bool $sensitive = false

$type

public string $type = ''

$unique

public bool $unique = false

$validators

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

$value

Represents the current value for this Field.

public mixed $value = null

$verbose_choices

Contains the verbose choices originally assigned in the $choices property during object construction.

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

This array is automatically populated using the $choices value passed in during object creation.

An associative array where the key is the exact choice value, and the value is the verbose description for the choice.

$verbose_name

public string $verbose_name = ''

$verbose_name_plural

public string $verbose_name_plural = ''

$write_only

public bool $write_only = false

Methods

__construct()

Defines attributes for a Model Field.

public __construct(string $model_class[, bool $required = false ][, mixed|null $default = null ][, bool $allow_empty = false ][, bool $allow_null = false ][, bool $editable = true ][, bool $read_only = false ][, bool $write_only = false ][, string $internal_name = '' ][, string $internal_namespace = '' ][, string $verbose_name = '' ][, string $verbose_name_plural = '' ][, array<string|int, mixed> $conditions = [] ][, string $help_text = '' ]) : mixed
Parameters
$model_class : string

The Model class that is nested within this Field.

$required : bool = false

Set to true if this field is required to be explicitly set. $required and $default are mutually exclusive.

$default : mixed|null = null

The default value to assign this field if no value was found. If not set, it assumed this Field requires a value and should fail validation if no value was found.

$allow_empty : bool = false

If true, empty strings will be allowed by this field.

$allow_null : bool = false

Set to true if null values should be supported for this field. When null values are supported, the underlying pfSense configuration field will be removed entirely when receiving a null value.

$editable : bool = true

Set to false to prevent this field's value from being changed after its initial creation.

$read_only : bool = false

Set to true to make this field read-only. Attempts to write to a read-only field will result in a thrown exception.

$write_only : bool = false

Set to true to make this field write-only. This will prevent the field's current value from being displayed in the representation data. This is ideal for potentially sensitive Fields like passwords, keys, and hashes.

$internal_name : string = ''

The name of the field as it is represented in the pfSense configuration. This name should match the name used in the pfSense configuration.

$internal_namespace : string = ''

The namespace of the field as it is represented in the pfSense configuration. This namespace should match the namespace used in the pfSense configuration.

$verbose_name : string = ''

The detailed name for this Field. This name will be used in non-programmatic areas like web pages and help text. This Field will default to property name assigned to the parent Model with underscores converted to spaces.

$verbose_name_plural : string = ''

The plural form of $verbose_name. This defaults to $verbose_name with s suffixed or es suffixes to strings already ending with s.

$conditions : array<string|int, mixed> = []

An array of conditions the field must meet to be included. This allows you to specify conditions of other Fields within the parent Model context. For example, if the parent Model context has two Fields, one field named type and the other being this field; and you only want this field to be included if type is equal to type1, you could assign ["type" => "type1"] to this parameter.

$help_text : string = ''

Sets a description for this field. This description will be used as the description for this field in the API documentation.

__invoke()

Allows the Field's current value to be obtained by invoking the field object.

public final __invoke() : mixed
Tags
note

This doesn't work in the context of a Model object because you cannot invoke a class property that is assigned an invocable object.

returns

mixed The value currently set in $this->value

check_field_names()

Checks if this Field object has a valid `name` and `internal_name`. In the event that a `name` exists, but an `internal_name` was not specified, the `internal_name` will be assigned the same value as `name` by this method.

public check_field_names() : void
Tags
throws
ServerError

When this object's name has not been set.

from_internal()

Converts any nested Model objects from their internal values to their representation values.

public from_internal(string|null $internal_value) : void
Parameters
$internal_value : string|null

The raw internal config value to convert to a representation value.

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

Formats a descriptive string to explain the `conditions` for this Field. This is intended to be used for OpenAPI documentation generation.

public get_conditions_text() : string
Return values
string —

A descriptive string explaining the conditions for this Field.

get_default()

Obtains the default value for this field.

public final get_default() : mixed
Return values
mixed —

When the $default property is set, its value will be returned. If the $default_callable is set, the return value of that callable will be returned. If no default has been specified, null will be returned.

get_related_model()

Retrieves the related Model object based on this Field's value. Child Field classes must override this method to define the necessary steps for retrieving related objects. This method can only be used on Fields with $many set to false.

public get_related_model() : Model|null
Tags
returns

Model Returns the single Model object related to this Field's current value or null if no related Model was found.

Return values
Model|null

get_related_models()

Retrieves all related Model object based on this Field's value. Child Field classes must override this method to define the necessary steps for retrieving related objects. This method can only be used on Fields with $many set to true.

public get_related_models() : ModelSet
Tags
returns

ModelSet Returns a ModelSet of all related objects associated with this Fields current values.

Return values
ModelSet

has_label()

Checks if this Field object has a specific label assigned. Labels are specific attributes that assigned Validator objects found during validation that may need to be referenced again after validation.

public has_label(string $label_name) : bool
Parameters
$label_name : string

The name of the label to check for (e.g. is_ipaddrv4)

Return values
bool —

Returns true if this Field object is assigned the $label_name, false if it is not.

is_referenced_by()

Uses this Field's $referenced_by property to search for existing Model objects that reference this Field's current value.

public is_referenced_by() : ModelSet
Return values
ModelSet

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

set_choices()

Accepts a given array of choices and sets the `choices` and `verbose_choices` properties accordingly.

public set_choices(array<string|int, mixed> $choices) : void
Parameters
$choices : array<string|int, mixed>

An array of incoming choices to set

set_choices_from_callable()

Sets choices by calling the `choices_callable` method if present.

public set_choices_from_callable() : void
Tags
throws
ServerError

When the choices_callable could not be found in either this Field object or its parent Model

set_names()

Sets this Field's name property and assumes defaults based on current name assignments. This field is intended to be called by the parent Model that is assigned this Field objects. Names are based off the name of the property assigned this Field in the parent Model.

public set_names(string $name) : void
Parameters
$name : string

The name to assign this Field.

sort()

Sorts the nested Model data use the nested Model's `sort_order` and `sort_by` setting. This method closely resembles the Model->sort() method, but does not require values to be set in config beforehand.

public sort() : void

to_form_input()

Converts this Field object into a pfSense webConfigurator form input. This method can be overridden by a child class to add custom input field creation.

public to_form_input([string $type = 'text' ][, array<string|int, mixed> $attributes = [] ]) : object
Parameters
$type : string = 'text'

The HTML input tag type. Not all Fields support input types.

$attributes : array<string|int, mixed> = []

An array of additional HTML input tag attributes. Not all Fields support input attributes.

Tags
link
https://github.com/pfsense/pfsense/tree/master/src/usr/local/www/classes/Form
Return values
object —

The pfSense webConfigurator form input object.

to_internal()

Converts the value from its representation value to its internal value.

public to_internal() : array<string|int, mixed>|string|null
Return values
array<string|int, mixed>|string|null —

The internal value to be stored in the pfSense config

to_openapi_property()

Converts this NestedModelField object to a PHP array representation of an OpenAPI schema property configuration.

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

This is used when auto-generating API documentation.

Tags
link
https://swagger.io/docs/specification/data-models/
Return values
array<string|int, mixed> —

A PHP array containing this field as an OpenAPI schema property configuration.

validate()

Extends the default Field validation method to clear the validation_modelset before starting validation

public validate([ModelSet|null $modelset = null ]) : bool
Parameters
$modelset : ModelSet|null = null
Return values
bool —

Returns true if the validation was successful.

validate_extra()

Validates the incoming value using the assigned Model's `validate()` method.

public validate_extra(mixed $value) : void
Parameters
$value : mixed

The value being validated. In the event that this is a many field, this method will receive each value of the array individually, not the array value itself.

Tags
throws
ValidationError

If any Response error occurred when validating the nested Model object

_from_internal()

Converts the stored internal config value to a represented value. This method must be overridden by a child Field class with the necessary steps to convert the internal value to the representation value. This method must return value in it's represented form! In the case of a `many` field, this method will be called for each individual value after it's been converted to an array by from_internal(). You do not need to worry about converting the $internal_value to an array in this method!

protected _from_internal(string $internal_value) : mixed
Parameters
$internal_value : string

The internal config value to convert to a representation value.

Tags
throws
ServerError

When the child Field class does not override this method.

_to_internal()

Converts the represented value into the internal pfSense value. In most cases child Field classes do not need to override this method as the default behavior of converting the value into a string is sufficient. However, this method can be overridden by a child Field class with custom steps to convert the represented value back into the internal value if needed. This method must return the value in its internal form! In the case of a `many` field, this method will be called for each `$this->value` before it's been joined into it's internal string by to_internal(). If `$this->value` is an array, you do not need to worry about joining `$this->value` into a string. Leave it as an array.

protected _to_internal(mixed $representation_value) : array<string|int, mixed>|string|null
Parameters
$representation_value : mixed

The value to convert into it's internal form.

Return values
array<string|int, mixed>|string|null —

The internal value(s) suitable for writing to the pfSense configuration.

check_value_type()

Checks if a given value's type matches this Field object's primary `type`

protected check_value_type(mixed $value) : mixed
Parameters
$value : mixed

The value to check against assigned type.

Tags
throws
ValidationError

If the specified value is not a supported type.

has_default()

Checks if this field has a default or default_callable assigned.

protected final has_default() : bool
Return values
bool —

Returns true if this field has a default or default_callable assigned, returns false otherwise.

are_conditions_met()

Checks if the conditions defined in the `conditions` property are met.

private are_conditions_met() : bool
Tags
note

The context of the condition can be inverted by prefixing ! to the conditions array key.

note

The condition can reference a parent's Model Field by prefixing parent__ to the conditions array key.

returns

bool true if all conditions were met, false if any conditions failed.

Return values
bool

check_construct()

Checks that values passed in during __construct are valid and do not conflict.

private check_construct() : void
Tags
throws
ServerError

When any Field properties have conflicting values.

check_field_read_only()

Ensures read-only values do not have a value, default or choices.

private check_field_read_only() : void
Tags
throws
ServerError

When read_only is set and choices or default are also set.

throws
ValidationError

When read_only is set and a non-null value was requested.

check_field_required()

When the field is required, checks if a value is set and checks if mutually exclusive options are both set.

private check_field_required() : void
Tags
throws
ServerError

When required and default are both set OR required and allow_null are both set.

throws
ValidationError

If required is set but no value was assigned.

check_field_unique()

Checks if a 'unique' field is actually unique from all other objects related to the $context Model's config path.

private check_field_unique(mixed $value[, ModelSet|null $modelset = null ]) : void

The $context Model must have a config_path set AND have it's many value set to true to support unique validation.

Parameters
$value : mixed

The value to being checked for uniqueness.

$modelset : ModelSet|null = null

Sets a specific ModelSet to use when checking uniqueness. If set, this Field's value must be unique from all other Models in this ModelSet. If no value is specified here, a ModelSet will automatically be obtained for all existing Model objects for this Field's $context Model. Note: This is rarely needed. The only current use case is \RESTAPI\Fields\NestedModelField as it needs to check the uniqueness of a set of Model objects before they are created.

Tags
throws
ValidationError

When the assigned $context Model does not have a config_path set OR the assigned $context Model does not have it's $many value to true.

throws
ServerError

When $unique is enabled but a $config_path is not assigned to the parent model $context

throws
ServerError

When $unique is enabled, but the parent model $context does not have $many enabled

check_many_value_length()

Checks the length of the value array when `many` is enabled. This ensures there are at least as many array entries as specified with `many_minimum` but no more array entries than specified with `many_maximum`.

private check_many_value_length() : void

check_model_context()

Ensures this field has a parent model context assigned if a parent model context is required.

private check_model_context() : void
Tags
throws
ServerError

When unique or conditions are set, but no Model context has been assigned.

check_value_choice()

Checks if a given `value` is a valid `choice` option when `choices` are specified.

private check_value_choice(mixed $value) : void
Parameters
$value : mixed

The value to check against available choices.

Tags
returns

ValidationError When the $value is not an available choice.

check_value_empty()

Checks if a given `value` is an empty array or string and checks if empty values are allowed.

private check_value_empty(mixed $value) : bool
Parameters
$value : mixed

The value to check for emptiness.

Tags
throws
ValidationError

When the $value is empty but empty empty values are not allowed

Return values
bool —

Returns true if value is empty and empty values are allowed. Returns false otherwise.

get_default_from_callable()

Obtains this Field's default value by calling the `default_callable` method if defined.

private get_default_from_callable() : mixed
Tags
throws
ServerError

When the default_callable could not be found in either this Field object or its parent Model

Return values
mixed —

The return value of the default_callable if defined. Otherwise, returns null.

get_value_as_array()

Obtains an array of individual values for this field. If `many` is enabled, this method will ensure `value` is already an array and simply return the array value. If `many` is not enabled, the individual `value` will be wrapped in an array and returned. This intended to obtain ALL values that need to validated into an array format for looping purposes.

private get_value_as_array() : array<string|int, mixed>|null
Tags
returns

array An array containing all individual values that need validation.

throws
ValidationError

When many is enabled, but value is not an array.

Return values
array<string|int, mixed>|null

is_value_editable()

Checks if this Field should allow changed values. If this is not a `editable` Field, and the value given differs from the stored value from the parent Model context an error will be thrown

private is_value_editable() : void
Tags
throws
ValidationError

When this is not an editable Field, but the value given differs from the value stored for the parent Model context


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results