InterfaceField
extends StringField
in package
Defines an Field object for storing interface values in the pfSense configuration. This field will also be responsible for representing the interface according to the REST API `represent_interfaces_as` setting.
Table of Contents
Constants
- SENSITIVE_MASK = '********'
Properties
- $allow_carp_interface : bool
- $allow_custom : array<string|int, mixed>
- $allow_empty : bool
- $allow_interface_groups : bool
- $allow_ipsec_interface : bool
- $allow_localhost_interface : bool
- $allow_null : bool
- $allow_openvpn_interface : 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
- $interface_query : array<string|int, mixed>
- $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
- $maximum_length : int
- $minimum_length : 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
- $represented_as : string
- $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 the StringField object and sets its options.
- __invoke() : mixed
- Allows the Field's current value to be obtained by invoking the field object.
- _from_internal() : string
- Converts the field value to its representation form from it's internal pfSense configuration value.
- _to_internal() : array<string|int, mixed>|string|null
- Converts the field's representation value into it's internal pfSense value.
- 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_interface_choices() : array<string|int, mixed>
- Enumerates a list of every interface choice available to this Field.
- get_related_model() : Model|null
- Fetches the NetworkInterface Model object associated with this field's current value
- get_related_models() : ModelSet
- Fetches all NetworkInterface objects associated with this Field's current values when $many is enabled.
- 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_internal_interfaces() : array<string|int, mixed>|string
- Obtains this Fields current interface values as an array of their internal values.
- 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.
- 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
Properties
$allow_carp_interface
public
bool
$allow_carp_interface
= false
$allow_custom
public
array<string|int, mixed>
$allow_custom
= []
$allow_empty
public
bool
$allow_empty
= false
$allow_interface_groups
public
bool
$allow_interface_groups
= false
$allow_ipsec_interface
public
bool
$allow_ipsec_interface
= false
$allow_localhost_interface
public
bool
$allow_localhost_interface
= false
$allow_null
public
bool
$allow_null
= false
$allow_openvpn_interface
public
bool
$allow_openvpn_interface
= 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
= ''
$interface_query
public
array<string|int, mixed>
$interface_query
= []
$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
$maximum_length
public
int
$maximum_length
= 1024
$minimum_length
public
int
$minimum_length
= 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
$represented_as
public
string
$represented_as
The interface field that interfaces are represented as by this field. This value
directly corresponds with the REST API setting's represent_interfaces_as
field.
$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 the StringField object and sets its options.
public
__construct([bool $required = false ][, bool $unique = false ][, mixed|null $default = null ][, string $default_callable = '' ][, array<string|int, mixed> $interface_query = [] ][, bool $allow_interface_groups = false ][, bool $allow_ipsec_interface = false ][, bool $allow_openvpn_interface = false ][, bool $allow_carp_interface = false ][, bool $allow_localhost_interface = false ][, array<string|int, mixed> $allow_custom = [] ][, bool $allow_empty = false ][, bool $allow_null = false ][, bool $read_only = false ][, bool $write_only = false ][, bool $representation_only = false ][, bool $editable = true ][, 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
- $required : bool = false
-
If
true
, this field is required to have a value at all times. - $unique : bool = false
-
If
true
, this field must be unique from all other parent model objects. Enabling this option requires the Model $context to be set AND the Model $context must have aconfig_path
set. - $default : mixed|null = null
-
Assign a default string value to assign this Field if no value is present.
- $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.
- $interface_query : array<string|int, mixed> = []
-
Set query parameters to limit the scope of NetworkInterface lookups for this field. Leave as an empty array to include all NetworkInterface objects in lookups.
- $allow_interface_groups : bool = false
-
If
true
, all existing interface groups will be included as valid choices. - $allow_ipsec_interface : bool = false
-
If
true
, IPsec'senc0
interface will included as a valid choice. - $allow_openvpn_interface : bool = false
-
If
true
, theopenvpn
interface will be included as valid choice. - $allow_carp_interface : bool = false
-
If
true
, all CARP unique IDs will be included as valid choices. - $allow_localhost_interface : bool = false
-
If
true
, the localhost interface will be included as a valid choice. - $allow_custom : array<string|int, mixed> = []
-
An array of keywords that are allowed to be used as interface values.
- $allow_empty : bool = false
-
If
true
, empty strings will be allowed by this field. - $allow_null : bool = false
-
If
true
, null values will be allowed by this field. - $read_only : bool = false
-
If
true
, this field can only read its value and cannot write its value to config. - $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. - $representation_only : bool = false
-
Set to
true
to make this field only present in its representation form. This effectively prevents the Field from being converted to an internal value which is saved to the pfSense config. This should only be used for Fields that do not relate directly to a configuration value. - $editable : bool = true
-
Set to
false
to prevent this field's value from being changed after its initial creation. - $many : bool = false
-
If
true
, the value must be an array of many strings. - $many_minimum : int = 0
-
When $many is set to
true
, this sets the minimum number of array entries required. - $many_maximum : int = 128
-
When $many is set to
true
, this sets the maximum number of array entries allowed. - $delimiter : string|null = ','
-
Assigns the string delimiter to use when writing array values to config. Use
null
if this field is stored as an actual array in config. This is only available if $many is set totrue
. Defaults to,
to store as comma-separated string. - $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 ores
suffixes to strings already ending withs
. - $internal_name : string = ''
-
Assign a different field name to use when referring to the internal field as it's stored in the pfSense configuration.
- $internal_namespace : string = ''
-
Sets the namespace this field belongs to internally. This can be used to nest the Fields internal value under a specific namespace as an associative array. This only applies to the internal value, not the representation value.
- $referenced_by : array<string|int, mixed> = []
-
An array that specifies other Models and Field's that reference this Field's parent Model using this Field's value. This will prevent the parent Model object from being deleted while it is actively referenced by another Model object. The array key must be the name of the Model class that references this Field, and the value must be a Field within that Model. The framework will automatically search for any existing Model objects that have the referenced Field assigned a value that matches this Field's value.
- $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 iftype
is equal totype1
, you could assign ["type" => "type1"] to this parameter. - $validators : array<string|int, mixed> = []
-
An array of Validator objects to run against this field.
- $help_text : string = ''
-
Set a description for this field. This description will be used in API documentation.
__invoke()
Allows the Field's current value to be obtained by invoking the field object.
public
final __invoke() : mixed
Tags
_from_internal()
Converts the field value to its representation form from it's internal pfSense configuration value.
public
_from_internal(mixed $internal_value) : string
Parameters
- $internal_value : mixed
-
The internal value from the pfSense configuration.
Return values
string —The field value in its representation form.
_to_internal()
Converts the field's representation value into it's internal pfSense value.
public
_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_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
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_interface_choices()
Enumerates a list of every interface choice available to this Field.
public
get_interface_choices() : array<string|int, mixed>
Return values
array<string|int, mixed> —A list of every interface option available to this Field.
get_related_model()
Fetches the NetworkInterface Model object associated with this field's current value
public
get_related_model() : Model|null
Tags
Return values
Model|null —The NetworkInterface Model object associated with this Field's current value for non-many Fields.
get_related_models()
Fetches all NetworkInterface objects associated with this Field's current values when $many is enabled.
public
get_related_models() : ModelSet
Return values
ModelSet —Returns a ModelSet containing the NetworkInterface Model's associated with this Field's
current values, or null
if no
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
ModelSetlog_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
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
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_internal_interfaces()
Obtains this Fields current interface values as an array of their internal values.
public
to_internal_interfaces() : array<string|int, mixed>|string
Return values
array<string|int, mixed>|string —An array of the internal interfaces assigned to this Field (e.g. ["wan", "lan", "opt1"])
when this is a many
Field, or the internal interface value as a string
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
Return values
array<string|int, mixed> —A PHP array containing this field as a 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.
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
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
Return values
boolcheck_construct()
Checks that values passed in during __construct are valid and do not conflict.
private
check_construct() : void
Tags
check_field_read_only()
Ensures read-only values do not have a value, default or choices.
private
check_field_read_only() : void
Tags
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
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
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
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
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
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
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
Return values
array<string|int, mixed>|nullis_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