pfSense-pkg-RESTAPI

Form
in package

RESTAPI

uses BaseTraits

Defines a Form object that can be used to dynamically generate custom pfSense webConfigurator pages for a specified Model object.

Properties

$buttons : array<string|int, mixed>
$custom_css : string
$custom_js : string
$deletable : bool
$editable : bool
$form_data : array<string|int, mixed>
$id : mixed
$many : bool
$many_sub_url : string
$model_class : string
$sections : array<string|int, mixed>|array<string|int, array<string|int, mixed>>
$table_fields : array<string|int, mixed>
$tabs : array<string|int, mixed>
$title_path : array<string|int, mixed>
$url : string
$verbose_name : string
$model : Model|mixed

Methods

__construct() : mixed: Construct the Form object
build_form_url() : bool: Generate an endpoint for this Form in the pfSense webroot.
generate_pfsense_privs() : array<string|int, mixed>: Utilizes the $url properties of this Form to generate pfSense privileges specific to this Form class.
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_form() : Form: Populates the form sections with the desired Fields and returns an array of
get_priv_name() : string: Obtains the pfSense privilege name for this Form. This privilege name is automatically generated using the $url attribute and formats it to be consistent with the other webConfigurator page privileges.
get_table() : mixed: Obtains a PHP table that contains all current Model objects for `many` Forms.
log_error() : void: Logs an error to the syslog.
on_delete() : void: Tries to delete the Model object when requested.
on_load() : void: Performs tasks when the Form page is initially loaded. This method is intended to be overridden by the child class.
on_save() : void: Performs validation and saves the Model assigned to this ModelForm.
print_form() : void: Prints this form as a web page. This method is intended to be called by a PHP endpoint somewhere in the pfSense web root.
print_info_banner() : void: Prints an info/warning banner at the top of the form page.
print_input_error_banner() : void: Prints the input error banner at the top of the form page.
print_success_banner() : void: Prints the green success banner at the top of the form page.
form_data_to_model_representation() : array<string|int, mixed>: Converts POST form data submitted by the pfSense webConfigurator to a valid representation of a provided Model object return array The POST form data in an acceptable representation for the provided Model object.
generate_verbose_name() : string: Auto-generates a verbose name for this Form class using its class name.

$buttons


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

Defines additional buttons to add to the form page. This must be an array of arrays where the key is the ID name to give the button, and the value is an array of button attributes. Valid button attributes are: 'title' the verbose name to display on the button itself. 'icon' the pfSense CSS icon class for this button (i.e. fa-repeat, fa-question-circle, etc.) 'classes' an array of additional CSS classes to assign the button. 'on_click' the JS to trigger when the button is clicked. 'callable' the Form method to call when the button is click. This must be the method name as a string. 'link' the URL to link to when the button is clicked.

$custom_css


    public
        string
    $custom_css
     = ''

The URL to a custom CSS file for this Form page to use.

$custom_js


    public
        string
    $custom_js
     = ''

The URL to a custom JS file for this Form page to use.

$deletable


    public
        bool
    $deletable
     = true

$editable


    public
        bool
    $editable
     = true

When true, the edit button will be displayed on the table for each Model object. This is only applicable when $many is true. If false, Model objects cannot be edited via this form.

$form_data


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

The POSTed data from the client using the Form.

$id


    public
        mixed
    $id
     = null

The ID of the Model object this Form is currently interacting with. This is generally only applicable when $many is set to false.

$many


    public
        bool
    $many
     = false

Indicate whether this Form should interact with many Model object at once. When true, the Form display models as a table and can be configured using the $title_path, $editable, and $deletable properties. When false, the Form will only display one model at a time. This field is only appliacble if the $model_class is a many enabled Model.

$many_sub_url


    public
        string
    $many_sub_url
     = ''

The URL that the edit button should link to when clicked. This URL should not contain Model specific values like IDs. In most cases, this will link the $url of another non-many Form object. This property is only applicable when $many is enabled for this Form.

$model_class


    public
        string
    $model_class
     = ''

The shortname of the Model class this Form interacts with.

$sections


    public
        array<string|int, mixed>|array<string|int, array<string|int, mixed>>
    $sections
     = ['General' => ['fields' => [], 'classes' => []]]

Defines subsections for this Form and assigns specific Model fields to display in each section. This value must be an array where the array keys are the name of the Form section, and the value is an array of attributes. Valid section attributes are: 'fields' an array of Model field names to include in the section. 'classes' an array of CSS class names to assign the section.

$table_fields


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

Sets the fields that will generate columns for the Form table. This is only applicable when $many is true.

$tabs


    public
        array<string|int, mixed>
    $tabs

An array of additional tabs that should be display for this form. These tabs are quick links to other pages or Form objects that are directly related to this Form's Model. These value must be an array of arrays, each listed array must have three items in this order: 1. The name to show on the tab. 2. A boolean indicating whether we are currently on this tab. 3. The URL of the page to link to when the tab is selected.

$title_path


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

The path to display at the top of the webConfigurator page. This path typically indicates which pages were navigated to in order to reach this Form page with the last item representing the page we are currently on. (i.e. ["System", "REST API", "Settings"])

$url


    public
        string
    $url

The URL this Form can be accessed at.

$verbose_name


    public
        string
    $verbose_name
     = ''

Defines a verbose name for this Form page. If none is specified, a default verbose name will be generated using this Form class's shortname.

$model


    protected
        Model|mixed
    $model

The Model object this Form is interacting with.

__construct()

Construct the Form object


    public
                    __construct() : mixed

build_form_url()

Generate an endpoint for this Form in the pfSense webroot.


    public
                    build_form_url() : bool

Return values

bool

generate_pfsense_privs()

Utilizes the $url properties of this Form to generate pfSense privileges specific to this Form class.


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

The resulting array is then supplied to the pfSense privilege system located at /etc/inc/priv/.

Return values

array<string|int, mixed>

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

Populates the form sections with the desired Fields and returns an array of


    public
        final            get_form() : Form

Return values

Form —

The pfSense webConfigurator \Form object.

get_priv_name()

Obtains the pfSense privilege name for this Form. This privilege name is automatically generated using the $url attribute and formats it to be consistent with the other webConfigurator page privileges.


    public
                    get_priv_name() : string

Return values

string

get_table()

Obtains a PHP table that contains all current Model objects for `many` Forms.


    public
                    get_table() : mixed

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

on_delete()

Tries to delete the Model object when requested.


    public
                    on_delete(int|string $id) : void

Parameters

$id : int|string: The ID of the Model object to delete.

on_load()

Performs tasks when the Form page is initially loaded. This method is intended to be overridden by the child class.


    public
                    on_load() : void

on_save()

Performs validation and saves the Model assigned to this ModelForm.


    public
                    on_save([string $success_banner_msg = '' ]) : void

Parameters

$success_banner_msg : string = '': The message to append to the success banner when the Model is saved.

print_form()

Prints this form as a web page. This method is intended to be called by a PHP endpoint somewhere in the pfSense web root.


    public
        final            print_form() : void

print_info_banner()

Prints an info/warning banner at the top of the form page.


    public
                    print_info_banner([string $message = '' ][, string $class = 'alert-warning' ]) : void

Parameters

$message : string = '': The message to display on the banner.
$class : string = 'alert-warning': The CSS class to use for the banner.

print_input_error_banner()

Prints the input error banner at the top of the form page.


    public
                    print_input_error_banner([string $message = '' ]) : void

Parameters

$message : string = '': Adds an extra message to the banner.

print_success_banner()

Prints the green success banner at the top of the form page.


    public
                    print_success_banner([string $message = '' ]) : void

Parameters

$message : string = '': Adds an extra message to the banner.

form_data_to_model_representation()

Converts POST form data submitted by the pfSense webConfigurator to a valid representation of a provided Model object return array The POST form data in an acceptable representation for the provided Model object.


    protected
                    form_data_to_model_representation(array<string|int, mixed> $form_data, Model $model) : array<string|int, mixed>

Parameters

$form_data : array<string|int, mixed>: The incoming $_POST or $_GET form data from the pfSense webConfigurator.
$model : Model: The Model object to represent.

Return values

array<string|int, mixed> —

The representation of the Model object from the form data.

generate_verbose_name()

Auto-generates a verbose name for this Form class using its class name.


    private
                    generate_verbose_name() : string

Return values

string

Form in package RESTAPI uses BaseTraits

Table of Contents

Properties

Methods

Properties

$buttons

$custom_css

$custom_js

$deletable

$editable

$form_data

$id

$many

$many_sub_url

$model_class

$sections

$table_fields

$tabs

$title_path

$url

$verbose_name

$model

Methods

__construct()

build_form_url()

Tags

Return values

generate_pfsense_privs()

Tags

Return values

get_class_fqn()

Return values

get_class_shortname()

Return values

get_classes_in_namespace()

Parameters

Return values

get_form()

Return values

get_priv_name()

Tags

Return values

get_table()

log_error()

Parameters

on_delete()

Parameters

on_load()

on_save()

Parameters

print_form()

print_info_banner()

Parameters

print_input_error_banner()

Parameters

print_success_banner()

Parameters

form_data_to_model_representation()

Parameters

Return values

generate_verbose_name()

Tags

Return values

Form
in package

RESTAPI

uses BaseTraits