pfSense-pkg-RESTAPI

Form
in package
uses BaseTraits

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

Table of Contents

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.

Properties

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

Methods

__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
Tags
returns

bool Returns true if the form was successfully built, otherwise false.

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

Tags
returns

array The pfSense priv list entry array corresponding to the privileges of this Endpoint.

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
Tags
returns

string The pfSense privilege name for this Form (i.e. page-test-form)

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
Tags
returns

string The human-readable name for this Form class.

Return values
string

        
On this page

Search results