pfSense-pkg-RESTAPI

BooleanField extends Field
in package

Defines a Field object for storing boolean values in the pfSense configuration.

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
$indicates_false  : mixed
$indicates_true  : 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
$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 the StringField object and sets its options.
__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()  : bool
Converts the field value to its representation form from it's internal pfSense configuration value.
_to_internal()  : string|null
Converts the field value to its internal form that is suitable for writing to the pfSense config.
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 = ''

$indicates_false

public mixed $indicates_false

The internal value that indicates a false boolean. This will typically be null, 'off', 'no', 'disabled', etc.

$indicates_true

public mixed $indicates_true

The internal value that indicates a true boolean. This will typically be an empty string, 'on', 'yes', 'enabled', etc.

$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 the StringField object and sets its options.

public __construct([bool $required = false ][, bool $unique = false ][, mixed|null $default = null ][, string $default_callable = '' ][, bool $allow_empty = false ][, bool $allow_null = false ][, bool $editable = true ][, bool $read_only = false ][, bool $write_only = false ][, bool $representation_only = false ][, mixed $indicates_true = '' ][, mixed $indicates_false = null ][, 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 a config_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.

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

$editable : bool = true

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

$read_only : bool = false

If true, this field can only read its value and cannot write its value to config. $many is enabled.

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

$indicates_true : mixed = ''

The internal string that indicates whether a value is true.

$indicates_false : mixed = null

The internal value that indicates whether a value is false. Use null if the lack of a value for this field indicates false internally.

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

$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 field 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 if type is equal to type1, 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
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.

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

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 field value to its representation form from it's internal pfSense configuration value.

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

The internal value from the pfSense configuration.

Return values
bool

The field value in its representation form.

_to_internal()

Converts the field value to its internal form that is suitable for writing to the pfSense config.

protected _to_internal(mixed $representation_value) : string|null
Parameters
$representation_value : mixed

The representation form of this field to convert to internal.

Return values
string|null

The internal string used to indicate if the value is true or false.

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