pfSense-pkg-RESTAPI

DateTimeField extends Field
in package

RESTAPI

Defines a Field object for storing and validating DateTime values.

Constants

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

Properties

$allow_empty : bool
$allow_null : bool
$auto_add_now : bool
$auto_update_now : 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.
$datetime_format : string
$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 the DateTimeField 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.
is_valid_datetime() : bool
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: Add extra validation to DateTimeFields to ensure the value matches the DateTime format.
_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 represented value into the internal pfSense value. In the event that `auto_update_now` is set, this method will automatically update the current value to the current datetime before converting the value to internal.
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

SENSITIVE_MASK


    public
        mixed
    SENSITIVE_MASK
    = '********'

$allow_empty


    public
        bool
    $allow_empty
     = false

$allow_null


    public
        bool
    $allow_null
     = false

$auto_add_now


    public
        bool
    $auto_add_now
     = false

$auto_update_now


    public
        bool
    $auto_update_now
     = 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

$datetime_format


    public
        string
    $datetime_format
     = 'm/d/Y'

$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

__construct()

Defines the DateTimeField object and sets its options.


    public
                    __construct([bool $required = false ][, bool $unique = false ][, mixed|null $default = null ][, string $default_callable = '' ][, array<string|int, mixed> $choices = [] ][, string $choices_callable = '' ][, string $datetime_format = 'm/d/Y' ][, bool $auto_add_now = false ][, bool $auto_update_now = false ][, bool $allow_empty = false ][, bool $allow_null = false ][, bool $editable = true ][, bool $read_only = false ][, bool $write_only = 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

$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.
$choices : array<string|int, mixed> = []: An array of value choices this Field can be assigned. This can either be an indexed array of the exact choice values, or an associative array where the array key is the exact choice value and the array value is a verbose name for the choice. Verbose choice name are used by ModelForms when generating web pages for a given Model.
$choices_callable : string = '': Assign a callable method from this Field object OR the parent Model context to execute to populate choices for this field. This callable must be a method assigned on this Field object OR the parent Model object that returns an array of valid choices in the same format as $choices. This is helpful when choices are dynamic and must be populated at runtime instead of pre-determined sets of values.
$datetime_format : string = 'm/d/Y': the PHP DateTime format this value should be formatted as. https://www.php.net/manual/en/datetime.format.php
$auto_add_now : bool = false: Automatically set the value of this field to the current DateTime during initial creation. This field can be manually updated when this value is set.
$auto_update_now : bool = false: Automatically update the value of this field to the current DateTime whenever the field is first created and whenever it is updated. This field will become read-only whenever this field is set.
$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.
$write_only : bool = false: Set the 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.
$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 to true. 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 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 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 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

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

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

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

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

is_valid_datetime()


    public
            static        is_valid_datetime(string $datetime, string $format) : bool

Parameters

$datetime : string: The datetime string to validate. (i.e. 12/31/1999)
$format : string: The DateTime format of the $datetime string. (i.e. m/d/Y)

Return values

bool —

true when the datetime string is valid, false when it is not.

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

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.

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>

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

Add extra validation to DateTimeFields to ensure the value matches the DateTime format.


    public
                    validate_extra(mixed $value) : void

Parameters

$value : mixed: The incoming

_from_internal()

Converts the field value to its representation form from it's internal pfSense configuration value.


    protected
                    _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 represented value into the internal pfSense value. In the event that `auto_update_now` is set, this method will automatically update the current value to the current datetime before converting the value to internal.


    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.

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

Return values

bool

check_construct()

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


    private
                    check_construct() : void

check_field_read_only()

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


    private
                    check_field_read_only() : void

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

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.

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

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.

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.

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

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

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

DateTimeField extends Field in package RESTAPI

Table of Contents

Constants

Properties

Methods

Constants

SENSITIVE_MASK

Tags

Properties

$allow_empty

$allow_null

$auto_add_now

$auto_update_now

$choices

$choices_callable

$conditions

$context

$datetime_format

$default

$default_callable

$delimiter

$editable

$help_text

$internal_name

$internal_namespace

$labels

$many

$many_maximum

$many_minimum

$name

$read_only

$referenced_by

$representation_only

$required

$sensitive

$type

$unique

$validators

$value

$verbose_choices

$verbose_name

$verbose_name_plural

$write_only

Methods

__construct()

Parameters

__invoke()

Tags

check_field_names()

Tags

from_internal()

Parameters

get_class_fqn()

Return values

get_class_shortname()

Return values

get_classes_in_namespace()

Parameters

Return values

get_conditions_text()

Return values

get_default()

Return values

get_related_model()

Tags

Return values

get_related_models()

Tags

Return values

has_label()

Parameters

Return values

is_referenced_by()

Return values

is_valid_datetime()

Parameters

Return values

log_error()

Parameters

set_choices()

DateTimeField extends Field
in package

RESTAPI