pfSense-pkg-RESTAPI

Field
in package
uses BaseTraits

Defines Model Fields and their attributes. Field's define how value should be obtained on pfSense internally, and converted into its representation form. Fields are also responsible for validation of this Field's value. This includes strict type validation, choice options, whether the value can be null or empty, etc. Field's can also be assigned custom Validator objects to add custom validation to the Field. Field's must be assigned as a properties Model objects.

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
$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

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
Sets a public version of _from_internal() that calls the Field's _from_internal() method. In the case of a `many` Field, the internal value will be expanded into it's array form and _from_internal() will run against each item within that array. This method will automatically assign the representation value to the `value` property for this object.
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.
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
Sets a public version of _to_internal() that calls the Field's _to_internal() method. In the case of a `many` Field, _to_internal() method will run against all current values and will then be joined back into the internal string value suitable for writing to the pfSense configuration.
to_openapi_property()  : array<string|int, mixed>
Converts this Field object to a PHP array representation of an OpenAPI schema property configuration. This is used when auto-generating API documentation. This method can be extended to add additional options to the OpenAPI schema property.
validate()  : bool
Runs all validations for this field.
validate_extra()  : void
This method can be overridden by a child Field class to added extra validation for the Field. This method is executed at the end of the `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 $type = '' ][, bool $required = false ][, bool $unique = false ][, mixed $default = null ][, string $default_callable = '' ][, array<string|int, mixed> $choices = [] ][, string $choices_callable = '' ][, bool $allow_empty = false ][, bool $allow_null = false ][, bool $editable = true ][, bool $read_only = false ][, bool $write_only = false ][, bool $sensitive = false ][, bool $representation_only = false ][, bool $many = false ][, int $many_minimum = 0 ][, int $many_maximum = 128 ][, string|null $delimiter = ',' ][, string $verbose_name = '' ][, string $verbose_name_plural = '' ][, string $internal_name = '' ][, string $internal_namespace = '' ][, array<string|int, mixed> $referenced_by = [] ][, array<string|int, mixed> $conditions = [] ][, array<string|int, mixed> $validators = [] ][, string $help_text = '' ]) : mixed
Parameters
$type : string = ''

The data type representation. Must match the type of the $value property.

  • If $allow_null is true, $value can also be null.
  • If $many is true, $value must be an array of the specified type. Format must be recognized by the PHP gettype() function.
$required : bool = false

Make this a required field. If false, a valid $default, $default_callable or $allow_null must be set.

$unique : bool = false

If true, $value must be unique among all parent Model objects (only for parent Models with $many set to true).

$default : mixed = null

The default $value for this field if none is assigned. The default specified here should be static. If the default for this field is dynamic in nature, use a $default_callable instead.

$default_callable : string = ''

Defines a callable method that should be called to populate the default value for this field. It is strongly encouraged to use a default callable when the default is variable and may change dynamically.

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

Defines explicit value choices for $value. Can be a linear array or associative array with verbose descriptions. After construction, verbose choices move to $verbose_choices.

$choices_callable : string = ''
$allow_empty : bool = false

If true, accepts empty values in $value (only for string type Fields and empty arrays for $many enabled Fields).

$allow_null : bool = false

If true, accepts null values in $value.

$editable : bool = true

If false, $value cannot be changed after initial set.

$read_only : bool = false

If true, marks this Field as read-only to remote clients.

$write_only : bool = false

If true, marks this Field as write-only, excluding it from API Responses.

$sensitive : bool = false

If true, marks this Field as 'sensitive', masking its value in web form input Fields.

$representation_only : bool = false

If true, excludes this Field when writing the parent Model object to configuration.

$many : bool = false

If true, $value must be an array of the specified type, with individual values validated separately.

$many_minimum : int = 0

Minimum number of values required for Fields with $many enabled.

$many_maximum : int = 128

Maximum number of values allowed for Fields with $many enabled.

$delimiter : string|null = ','

Specifies the delimiter used to store this value in internal pfSense. Set to null for array storage.

$verbose_name : string = ''

Human-friendly name used for input field names in associated \RESTAPI\Core\Form classes.

$verbose_name_plural : string = ''

Plural form of $verbose_name. Defaults to appending 's' or 'es' to $verbose_name.

$internal_name : string = ''

Name of this Field as shown in the pfSense configuration or internal callable.

$internal_namespace : string = ''

If $internal_value is nested, set to the associative array's key.

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

Array specifying Models and Fields referencing this Field's parent Model using this Field's value.

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

Array of conditions for inclusion based on other Fields in the parent Model context.

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

Array of \RESTAPI\Core\Validator objects for validating this field.

$help_text : string = ''

Help text used to describe this Field in OpenAPI documentation and associated \RESTAPI\Core\Form input Fields.

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

Sets a public version of _from_internal() that calls the Field's _from_internal() method. In the case of a `many` Field, the internal value will be expanded into it's array form and _from_internal() will run against each item within that array. This method will automatically assign the representation value to the `value` property for this object.

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.

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

Sets a public version of _to_internal() that calls the Field's _to_internal() method. In the case of a `many` Field, _to_internal() method will run against all current values and will then be joined back into the internal string value suitable for writing to the pfSense configuration.

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

The internal array or string value suitable for writing the pfSense configuration.

to_openapi_property()

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

public to_openapi_property() : array<string|int, mixed>
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()

Runs all validations for this field.

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

Sets a specific ModelSet to use when validations require the use of all existing objects for this Field's $context 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 all validation succeeded.

validate_extra()

This method can be overridden by a child Field class to added extra validation for the Field. This method is executed at the end of the `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.

_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