Luminova Framework

PHP Luminova: Form Inputs Element Builder

Last updated: 2024-09-19 19:02:11

The form inputs builder class provides static methods for programmatically generating HTML markups for form input elements.

The Luminova Inputs class offers a set of static methods for dynamically generating HTML form input elements, providing a simple and efficient way to build forms programmatically. It abstracts the manual creation of form elements by handling various input types, attributes, and custom options through its flexible method signatures.

For detailed instructions on generating elements, refer to the Form Input Examples Documentation to learn how to use the class for creating various form elements.

Key Features:

  • Wide Input Support: Generate standard HTML inputs like text, email, password, radio, checkbox, and more, using the element method.
  • Dynamic Element Generation: Automatically handles different input types by calling methods like Inputs::text(), Inputs::email(), etc., or even additional custom types Inputs::FooInputBar().
  • Customizable Attributes: Easily add custom attributes like class, id, data-*, or aria-* through an associative array of attributes.
  • Optgroup & Datalist Support: Provides methods to handle advanced input elements like select dropdowns with option groups and searchable datalists.
  • Flexible Naming and Value Handling: Automatically handle input names, values, and types in a flexible and scalable way for various form scenarios.

Class Declaration

  • Class namespace: \Luminova\Builder\Inputs
  • Parent class: \Luminova\Builder\Document

Properties

template

The document element style to use (e.g, Inputs::HTML5, Inputs::BOOTSTRAP5).

public static int $template = Inputs::HTML5;

encoding

Use encoding for escaping document element, contents and attributes.

public static string $encoding = 'UTF-8'

xhtmlStrictTagNames

This property determines whether element tag names should be automatically converted to lowercase (in strict XHTML mode) or preserved as they were passed, which can be useful for applications using custom template elements or case-sensitive tags (such as when working with XML-like data structures).

public static bool $xhtmlStrictTagNames = true;

Usage Examples:

Inputs::$xhtmlStrictTagNames = true;

echo Inputs::element('InputPasswordText', 'password', 'password'); 
// Generates: <inputpasswordtext type="password" name="password" />
Inputs::$xhtmlStrictTagNames = false;

echo Inputs::element('InputPasswordText', 'password', 'password'); 
// Generates: <InputPasswordText type="password" name="password" />

Methods

__callStatic

Dynamically generates an HTML input element, the type is derived based on the called static method name.

public static __callStatic(string $method, array $arguments): string

Parameters:

ParameterTypeDescription
$methodstringThe input type (method name being called).
$argumentsarrayThe arguments: (?string $name, ?mixed $value, bool $close, array $attributes).
- $name (string|null): The name attribute of the input.
- $value (string|null): The value attribute of the input (optional).
- $close (bool): Whether the input is self-closing (default: false).
- $attributes (array): Additional attributes for the input element (optional).

Return Value:

string - Return the generated HTML input element.

Supported Method Names:Method names should correspond to valid input types. For input types like datetime-local, use underscores (e.g., Inputs::datetime_local() for datetime-local).

Example Usage:

<?php
echo Inputs::email(
    'user-email', 
    '[email protected]', 
    ['class' => 'form-control user-input', 'id' => 'email']
);

element

Generate an HTML element (input, button, etc...) with the specified attributes.

public static element(
    string $tag, 
    ?string $type = null, 
    ?string $name = null, 
    ?string $value = null, 
    bool $closeElement = false, 
    array<string,mixed> $attributes = []
): string

Parameters:

ParameterTypeDescription
$tagstringThe HTML tag to create (e.g., 'input', 'button').
$typestring|nullOptional input type (e.g., 'text', 'password', 'submit').
$namestring|nullOptional name attribute of the element.
$valuestring|nullOptional value for the input or the text content for the button.
$closeElementboolWhether to close the tag with content (e.g., &lt;button&gt;) or self-close (default: false).
$attributesarray<string,mixed>Additional HTML attributes (e.g., 'class', 'id', 'data-*').

Return Value:

string - Return the generated HTML tag string.


elements

Generates multiple HTML form inputs elements based on an array of element specifications.

Each element in the array should be an associative array containing the following keys:

  • tag (string): The HTML tag to generate (e.g., 'input', 'button').
  • type (string): Optional type attribute for elements like 'input' (default: empty string).
  • name (string): Optional name attribute for the element (default: empty string).
  • value (string): Optional value to be placed inside the element, or for 'input' elements (default: empty string).
  • closeElement (bool): Whether to close the tag with content or self-close it (default: false).
  • attributes (array): Optional associative array of HTML attributes for the element (default: empty array).
public static elements(array $inputs): string

Parameters:

ParameterTypeDescription
$inputsarray<int,string>An array of associative arrays where each represents an HTML element and its attributes.

Return Value:

string - Returns the generated HTML input elements as a concatenated string.

Example usage:

$inputs = [
    [
        'tag' => 'input',
        'type' => 'text',
        'name' => 'username',
        'value' => 'JohnDoe',
        'closeElement' => false,
        'attributes' => ['class' => 'form-control']
    ],
    [
        'tag' => 'input',
        'type' => 'password',
        'name' => 'password',
        'attributes' => ['class' => 'form-control']
    ]
];

echo Inputs::elements($inputs);

form

Generate an HTML form block.

public static form(
    string|array<int,array> $inputs, 
    string $action = '', 
    string $method = 'GET',
    array<string,mixed> $attributes = []
): string

Parameters:

ParameterTypeDescription
$inputsstring|array<int,array>The form inputs (pre-generated) or an array of inputs.
$actionstringThe form action URL (default: '').
$methodstringThe form submission method (e.g, 'POST', 'GET').
$attributesarray<string,mixed>Additional HTML attributes for the form tag.

Return Value:

string - Return the generated form HTML.


input

Generate an HTML input field.

public static input(string $type, string $name, string $value = '', array<string,string> $attributes = []): string

Parameters:

ParameterTypeDescription
$typestringThe type of input (e.g., 'text', 'password', 'email').
$namestringThe name of the input.
$valuestringThe value of the input field.
$attributesarray<string,string>Additional HTML attributes (e.g, classNames, id's, data-attributes).

Return Value:

string - Return the generated input HTML.


file

Generates an HTML file input element for uploading files, with optional capture settings.

public static file(string $name, ?string $capture = null, array $attributes = []): string

Parameters:

ParameterTypeDescription
$namestringThe name attribute for the input element.
$capturestring|nullSpecifies the camera to be used for capturing files (default: null):
- 'front': Use the front camera (user-facing).
- 'back': Use the back camera (environment-facing).
- 'switch': Allow the user to choose which camera to use.
- null: No specific camera preference.
$attributesarrayOptional additional attributes for the input element.

Return Value:

string - Returns the generated HTML file input element as a string.


label

Generates an HTML label element with associated attributes.

public static label(string $for, string $text, array $attributes = []): string

Parameters:

ParameterTypeDescription
$forstringThe ID of the input element this label is for.
$textstringThe text displayed inside the label.
$attributesarrayOptional additional HTML attributes (e.g., 'class', 'style').

Return Value:

string - Return the generated HTML label element.


button

Generate a button element.

public static button(string $type, string $name = '', string $text = 'Submit', array<string,string> $attributes = []): string

Parameters:

ParameterTypeDescription
$typestringThe type of the button (e.g., 'submit', 'button').
$namestringThe name attribute of the button.
$textstringThe button text.
$attributesarray<string,string>Additional HTML attributes (e.g, classNames, id's, data-attributes).

Return Value:

string - Return the generated button HTML.


textarea

Generate a textarea field.

public static textarea(string $name, string $value = '', array<string,string> $attributes = []): string

Parameters:

ParameterTypeDescription
$namestringThe name of the textarea.
$valuestringThe value inside the textarea.
$attributesarray<string,string>Additional HTML attributes (e.g, classNames, id's, data-attributes).

Return Value:

string - Return the generated textarea HTML.


checkbox

Generate a checkbox input field.

public static checkbox(string $name, string $value = '', bool $checked = false, array<string,string> $attributes = []): string

Parameters:

ParameterTypeDescription
$namestringThe name of the input.
$valuestringThe value of the checkbox.
$checkedboolWeather input is checked (default: false).
$attributesarray<string,string>Additional HTML attributes (e.g, classNames, id's, data-attributes).

Return Value:

string - Return the generated checkbox input HTML.


radio

Generate a radio input field.

public static radio(string $name, string $value = '', bool $checked = false, array<string,string> $attributes = []): string

Parameters:

ParameterTypeDescription
$namestringThe name of the input.
$valuestringThe value of the radio input.
$checkedboolWeather input is checked (default: false).
$attributesarray<string,string>Additional HTML attributes (e.g, classNames, id's, data-attributes).

Return Value:

string - Return the generated checkbox input HTML.


option

Generate a single HTML &lt;option&gt; element.

public static option(string|int $key, ?string $value = null, bool $selected = false, bool $disabled = false): string

Parameters:

ParameterTypeDescription
$keystring|intThe key-value attribute of the option element.
$valuestring|nullThe display text for the option element or null for self-closing.
$selectedboolWhether the option should be marked as selected (default: false).
$disabledboolWhether the option should be marked as disabled (default: false).

Return Value:

string - Return the generated HTML &lt;option&gt; element with proper escaping.


optgroup

Generate an HTML &lt;optgroup&gt; element with options.

public static optgroup(
    array<string|int,string>|string $options, 
    bool $indexedKey = true, 
    string|array $selected = '', 
    string|array $disabled = '', 
    array<string,string> $attributes = []
): string

Parameters:

ParameterTypeDescription
$optionsarray<string|int,string>|stringAn HTML of options or Array options as key-value pairs,
where the key is the option value and the value is the display text.
$indexedKeyboolIf true, use the original keys; if false, use values as keys on indexed option keys.
$selectedstring|arrayThe selected value(s). Can be a string for single select or an array for multiple select.
$disabledstring|arrayThe disabled value(s). Can be a string for single select or an array for multiple select.
$attributesarray<string,string>Additional HTML attributes for the &lt;optgroup&gt; element.

Return Value:

string - Return the generated HTML &lt;optgroup&gt; element containing the option elements.


select

Generate an HTML <select> dropdown element with optional optgroup support.

This method creates a <select> element with a name attribute, and can handle both regular options and grouped options using <optgroup>. Selected options can be pre-defined by providing their values in the $value parameter.Additional HTML attributes can be supplied for the select element.

public static select(
    string $name, 
    array<string|int,string|array<string|int,string>|string $options,
    array<int,string|int|float>|string $selected = '', 
    array<int,string|int|float>|string $disabled = '', 
    array<string,string> $attributes = [], 
    bool $indexedKey = true
): string

Parameters:

ParameterTypeDescription
$namestringThe name attribute of the <select> element.
$optionsarray<string|int,string|array<string|int,string>>|stringAn HTML string of options or an array of options,
where the key is the option value and the value is the display text, or an array with optgroup entries (e.g., [['foo' => 'Foo', 'bar' => 'Bar'], ...]).
$selectedarray<int,string|int|float>|stringThe selected value(s). Can be a string for single select or an array for multiple select.
$disabledarray<int,string|int|float>|stringThe disabled value(s). Can be a string for single select or an array for multiple select.
$attributesarray<string,string>Additional HTML attributes for the &lt;select&gt; element.
$indexedKeyboolWeather to retain the option array index key as option value or use the text as the value (default: true).

Return Value:

string - Return the generated HTML string for the <select> dropdown.


datalist

Generate an HTML <datalist> dropdown element with searchable input support.

This method creates a <select> element with a name attribute, and can handleboth regular options and grouped options using <optgroup>. Selected optionscan be pre-defined by providing their values in the $value parameter.Additional HTML attributes can be supplied for the select element.

public static datalist(string $name, array<int,string>|string $options, array<string,string> $attributes = []): string

Parameters:

ParameterTypeDescription
$namestringThe name attribute of the <input> element.
$optionsarray<int,string>|stringAn HTML string of options or an array of options values.
$attributesarray<string,string>Additional HTML attributes for the &lt;datalist&gt; element.

Return Value:

string - Return the generated HTML string for the <datalist> dropdown.

See Also:

  • https://www.w3schools.com/html/tryit.asp?filename=tryhtml_elem_datalist