---
title: "Phalcon Forms"
version: "5.19"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Forms
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Forms\Element\AbstractElement
Abstract
Source on GitHub
This is a base class for form elements
- **`Phalcon\Forms\Element\AbstractElement`** - implements [`Phalcon\Forms\Element\ElementInterface`](#formselementelementinterface)
- [`Phalcon\Forms\Element\Check`](#formselementcheck)
- [`Phalcon\Forms\Element\CheckGroup`](#formselementcheckgroup)
- [`Phalcon\Forms\Element\Date`](#formselementdate)
- [`Phalcon\Forms\Element\Email`](#formselementemail)
- [`Phalcon\Forms\Element\File`](#formselementfile)
- [`Phalcon\Forms\Element\Hidden`](#formselementhidden)
- [`Phalcon\Forms\Element\Numeric`](#formselementnumeric)
- [`Phalcon\Forms\Element\Password`](#formselementpassword)
- [`Phalcon\Forms\Element\Radio`](#formselementradio)
- [`Phalcon\Forms\Element\RadioGroup`](#formselementradiogroup)
- [`Phalcon\Forms\Element\Select`](#formselementselect)
- [`Phalcon\Forms\Element\Submit`](#formselementsubmit)
- [`Phalcon\Forms\Element\Text`](#formselementtext)
- [`Phalcon\Forms\Element\TextArea`](#formselementtextarea)
__Uses__ `InvalidArgumentException` · `Phalcon\Di\Di` · `Phalcon\Di\DiInterface` · `Phalcon\Filter\Validation\ValidatorInterface` · `Phalcon\Forms\Exception` · `Phalcon\Forms\Exceptions\FormElementNameRequired` · `Phalcon\Forms\Exceptions\InvalidFilterType` · `Phalcon\Forms\Form` · `Phalcon\Html\TagFactory` · `Phalcon\Messages\MessageInterface` · `Phalcon\Messages\Messages`
### Method Summary
### Properties
protected
array
$attributes = []
protected
array
$filters = []
protected
Form|null
$form = null
protected
string|null
$label = null
protected
Messages
$messages
protected
string
$method = "inputText"
protected
string
$name
protected
array
$options = []
protected
TagFactory|null
$tagFactory = null
protected
array
$validators = []
protected
mixed|null
$value = null
### Methods
Public · 34
```php
public function __construct(
string $name,
array $attributes = []
);
```
Constructor
```php
public function __toString(): string;
```
Magic method __toString renders the widget without attributes
```php
public function addFilter( string $filter ): ElementInterface;
```
Adds a filter to current list of filters
```php
public function addValidator( ValidatorInterface $validator ): ElementInterface;
```
Adds a validator to the element
```php
public function addValidators(
array $validators,
bool $merge = true
): ElementInterface;
```
Adds a group of validators
```php
public function appendMessage( MessageInterface $message ): ElementInterface;
```
Appends a message to the internal message list
```php
public function clear(): ElementInterface;
```
Clears element to its default value
```php
public function getAttribute(
string $attribute,
mixed $defaultValue = null
): mixed;
```
Returns the value of an attribute if present
```php
public function getAttributes(): array;
```
Returns the default attributes for the element
```php
public function getDefault(): mixed;
```
Returns the default value assigned to the element
```php
public function getFilters();
```
Returns the element filters
```php
public function getForm(): Form;
```
Returns the parent form to the element
```php
public function getLabel(): string|null;
```
Returns the element label
```php
public function getMessages(): Messages;
```
Returns the messages that belongs to the element
The element needs to be attached to a form
```php
public function getName(): string;
```
Returns the element name
```php
public function getTagFactory(): TagFactory|null;
```
Returns the tagFactory; throws exception if not present
```php
public function getUserOption(
string $option,
mixed $defaultValue = null
): mixed;
```
Returns the value of an option if present
```php
public function getUserOptions(): array;
```
Returns the options for the element
```php
public function getValidators(): ValidatorInterface[];
```
Returns the validators registered for the element
```php
public function getValue(): mixed;
```
Returns the element's value
```php
public function hasMessages(): bool;
```
Checks whether there are messages attached to the element
```php
public function label( array $attributes = [] ): string;
```
Generate the HTML to label the element
```php
public function render( array $attributes = [] ): string;
```
Renders the element widget returning HTML
```php
public function setAttribute(
string $attribute,
mixed $value
): ElementInterface;
```
Sets a default attribute for the element
```php
public function setAttributes( array $attributes ): ElementInterface;
```
Sets default attributes for the element
```php
public function setDefault( mixed $value ): ElementInterface;
```
Sets a default value in case the form does not use an entity
or there is no value available for the element in _POST
```php
public function setFilters( mixed $filters ): ElementInterface;
```
Sets the element filters
```php
public function setForm( Form $form ): ElementInterface;
```
Sets the parent form to the element
```php
public function setLabel( string $label ): ElementInterface;
```
Sets the element label
```php
public function setMessages( Messages $messages ): ElementInterface;
```
Sets the validation messages related to the element
```php
public function setName( string $name ): ElementInterface;
```
Sets the element name
```php
public function setTagFactory( TagFactory $tagFactory ): static;
```
Sets the TagFactory
```php
public function setUserOption(
string $option,
mixed $value
): ElementInterface;
```
Sets an option for the element
```php
public function setUserOptions( array $options ): ElementInterface;
```
Sets options for the element
Protected · 1
```php
protected function getLocalTagFactory(): TagFactory;
```
Returns the tagFactory; throws exception if not present
## Forms\Element\Check
Class
Source on GitHub
Component INPUT[type=check] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Check`**
### Method Summary
### Properties
protected
string
$method = "inputCheckbox"
protected
mixed
$uncheckedValue = null
protected
bool
$uncheckedValueSet = false
### Methods
Public · 3
```php
public function getUncheckedValue(): mixed;
```
Returns the value to bind when the checkbox is absent from submitted
data. Only meaningful when hasUncheckedValue() is true.
```php
public function hasUncheckedValue(): bool;
```
Whether an "unchecked value" has been explicitly registered.
```php
public function setUncheckedValue( mixed $value ): static;
```
Registers a value to bind when the checkbox is absent from submitted
data (the typical browser behavior for an unchecked input). Without
this opt-in, an unchecked checkbox leaves the entity property
untouched. See cphalcon issue #16982.
## Forms\Element\CheckGroup
Class
Source on GitHub
Component for a group of INPUT[type=checkbox] elements.
The name is automatically suffixed with [] when not already present so that
PHP collects all checked values into an array on form submission.
Options are passed as an associative array:
['value' => 'Label']
or with per-item attributes:
['value' => ['label' => 'Label', 'disabled' => true]]
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\CheckGroup`**
__Uses__ `Phalcon\Html\TagFactory`
### Method Summary
### Properties
protected
array
$options = []
### Methods
Public · 4
```php
public function __construct(
string $name,
array $options = [],
array $attributes = []
);
```
Constructor
```php
public function getOptions(): array;
```
Returns the group options
```php
public function render( array $attributes = [] ): string;
```
Renders the checkbox group returning HTML
```php
public function setOptions( array $options ): ElementInterface;
```
Sets the group options
## Forms\Element\Date
Class
Source on GitHub
Component INPUT[type=date] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Date`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputDate"
## Forms\Element\ElementInterface
Interface
Source on GitHub
Interface for Phalcon\Forms\Element classes
- **`Phalcon\Forms\Element\ElementInterface`**
__Uses__ `Phalcon\Filter\Validation\ValidatorInterface` · `Phalcon\Forms\Form` · `Phalcon\Messages\MessageInterface` · `Phalcon\Messages\Messages`
### Method Summary
### Methods
Public · 30
```php
public function addFilter( string $filter ): ElementInterface;
```
Adds a filter to current list of filters
```php
public function addValidator( ValidatorInterface $validator ): ElementInterface;
```
Adds a validator to the element
```php
public function addValidators(
array $validators,
bool $merge = true
): ElementInterface;
```
Adds a group of validators
```php
public function appendMessage( MessageInterface $message ): ElementInterface;
```
Appends a message to the internal message list
```php
public function clear(): ElementInterface;
```
Clears every element in the form to its default value
```php
public function getAttribute(
string $attribute,
mixed $defaultValue = null
): mixed;
```
Returns the value of an attribute if present
```php
public function getAttributes(): array;
```
Returns the default attributes for the element
```php
public function getDefault(): mixed;
```
Returns the default value assigned to the element
```php
public function getFilters();
```
Returns the element's filters
```php
public function getForm(): Form;
```
Returns the parent form to the element
```php
public function getLabel(): string|null;
```
Returns the element's label
```php
public function getMessages(): Messages;
```
Returns the messages that belongs to the element
The element needs to be attached to a form
```php
public function getName(): string;
```
Returns the element's name
```php
public function getUserOption(
string $option,
mixed $defaultValue = null
): mixed;
```
Returns the value of an option if present
```php
public function getUserOptions(): array;
```
Returns the options for the element
```php
public function getValidators(): ValidatorInterface[];
```
Returns the validators registered for the element
```php
public function getValue(): mixed;
```
Returns the element's value
```php
public function hasMessages(): bool;
```
Checks whether there are messages attached to the element
```php
public function label(): string;
```
Generate the HTML to label the element
```php
public function render( array $attributes = [] ): string;
```
Renders the element widget
```php
public function setAttribute(
string $attribute,
mixed $value
): ElementInterface;
```
Sets a default attribute for the element
```php
public function setAttributes( array $attributes ): ElementInterface;
```
Sets default attributes for the element
```php
public function setDefault( mixed $value ): ElementInterface;
```
Sets a default value in case the form does not use an entity
or there is no value available for the element in _POST
```php
public function setFilters( mixed $filters ): ElementInterface;
```
Sets the element's filters
```php
public function setForm( Form $form ): ElementInterface;
```
Sets the parent form to the element
```php
public function setLabel( string $label ): ElementInterface;
```
Sets the element label
```php
public function setMessages( Messages $messages ): ElementInterface;
```
Sets the validation messages related to the element
```php
public function setName( string $name ): ElementInterface;
```
Sets the element's name
```php
public function setUserOption(
string $option,
mixed $value
): ElementInterface;
```
Sets an option for the element
```php
public function setUserOptions( array $options ): ElementInterface;
```
Sets options for the element
## Forms\Element\Email
Class
Source on GitHub
Component INPUT[type=email] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Email`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputEmail"
## Forms\Element\File
Class
Source on GitHub
Component INPUT[type=file] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\File`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputFile"
## Forms\Element\Hidden
Class
Source on GitHub
Component INPUT[type=hidden] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Hidden`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputHidden"
## Forms\Element\Numeric
Class
Source on GitHub
Component INPUT[type=number] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Numeric`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputNumeric"
## Forms\Element\Password
Class
Source on GitHub
Component INPUT[type=password] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Password`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputPassword"
## Forms\Element\Radio
Class
Source on GitHub
Component INPUT[type=radio] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Radio`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputRadio"
## Forms\Element\RadioGroup
Class
Source on GitHub
Component for a group of INPUT[type=radio] elements.
Options are passed as an associative array:
['value' => 'Label']
or with per-item attributes:
['value' => ['label' => 'Label', 'disabled' => true]]
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\RadioGroup`**
__Uses__ `Phalcon\Html\TagFactory`
### Method Summary
### Properties
protected
array
$options = []
### Methods
Public · 4
```php
public function __construct(
string $name,
array $options = [],
array $attributes = []
);
```
Constructor
```php
public function getOptions(): array;
```
Returns the group options
```php
public function render( array $attributes = [] ): string;
```
Renders the radio group returning HTML
```php
public function setOptions( array $options ): ElementInterface;
```
Sets the group options
## Forms\Element\Select
Class
Source on GitHub
Component SELECT (choice) for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Select`**
__Uses__ `Phalcon\Tag\Select`
### Method Summary
### Properties
protected
object|array|null
$optionsValues = null
### Methods
Public · 5
```php
public function __construct(
string $name,
mixed $options = null,
array $attributes = []
);
```
Constructor
```php
public function addOption( mixed $option ): ElementInterface;
```
Adds an option to the current options
```php
public function getOptions();
```
Returns the choices' options
```php
public function render( array $attributes = [] ): string;
```
Renders the element widget returning HTML
```php
public function setOptions( mixed $options ): ElementInterface;
```
Set the choice's options
Protected · 1
```php
protected function prepareAttributes( array $attributes = [] ): array;
```
Returns an array of prepared attributes for Phalcon\Html\TagFactory
helpers according to the element parameters
## Forms\Element\Submit
Class
Source on GitHub
Component INPUT[type=submit] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Submit`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputSubmit"
## Forms\Element\Text
Class
Source on GitHub
Component INPUT[type=text] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Text`**
__Uses__ `Phalcon\Forms\Exception`
## Forms\Element\TextArea
Class
Source on GitHub
Component TEXTAREA for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\TextArea`**
__Uses__ `Phalcon\Tag`
### Properties
protected
string
$method = "inputTextarea"
## Forms\Exception
Class
Source on GitHub
Exceptions thrown in Phalcon\Forms will use this class
- `\Exception`
- **`Phalcon\Forms\Exception`**
- [`Phalcon\Forms\Exceptions\ElementNotInForm`](#formsexceptionselementnotinform)
- [`Phalcon\Forms\Exceptions\FormNotInLocator`](#formsexceptionsformnotinlocator)
- [`Phalcon\Forms\Exceptions\FormNotRegistered`](#formsexceptionsformnotregistered)
- [`Phalcon\Forms\Exceptions\InvalidEntity`](#formsexceptionsinvalidentity)
- [`Phalcon\Forms\Exceptions\InvalidFilterType`](#formsexceptionsinvalidfiltertype)
- [`Phalcon\Forms\Exceptions\InvalidJsonSchema`](#formsexceptionsinvalidjsonschema)
- [`Phalcon\Forms\Exceptions\JsonSchemaNotArray`](#formsexceptionsjsonschemanotarray)
- [`Phalcon\Forms\Exceptions\NoFormElements`](#formsexceptionsnoformelements)
- [`Phalcon\Forms\Exceptions\SchemaEntryMissingKey`](#formsexceptionsschemaentrymissingkey)
- [`Phalcon\Forms\Exceptions\SchemaEntryNotArray`](#formsexceptionsschemaentrynotarray)
- [`Phalcon\Forms\Exceptions\UnknownFormElementType`](#formsexceptionsunknownformelementtype)
- [`Phalcon\Forms\Exceptions\YamlExtensionRequired`](#formsexceptionsyamlextensionrequired)
- [`Phalcon\Forms\Exceptions\YamlSchemaNotArray`](#formsexceptionsyamlschemanotarray)
### Method Summary
### Methods
Public · 2
```php
public static function tagFactoryNotFound(): self;
```
```php
public static function usingParameterRequired(): self;
```
## Forms\Exceptions\ElementNotInForm
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\ElementNotInForm`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct( string $name );
```
## Forms\Exceptions\FormElementNameRequired
Class
Source on GitHub
- `\InvalidArgumentException`
- **`Phalcon\Forms\Exceptions\FormElementNameRequired`**
__Uses__ `InvalidArgumentException`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Exceptions\FormNotInLocator
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\FormNotInLocator`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct( string $name );
```
## Forms\Exceptions\FormNotRegistered
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\FormNotRegistered`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct( string $name );
```
## Forms\Exceptions\InvalidEntity
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\InvalidEntity`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Exceptions\InvalidFilterType
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\InvalidFilterType`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Exceptions\InvalidJsonSchema
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\InvalidJsonSchema`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct( string $detail );
```
## Forms\Exceptions\JsonSchemaNotArray
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\JsonSchemaNotArray`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Exceptions\NoFormElements
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\NoFormElements`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Exceptions\SchemaEntryMissingKey
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\SchemaEntryMissingKey`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct(
int $index,
string $key
);
```
## Forms\Exceptions\SchemaEntryNotArray
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\SchemaEntryNotArray`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct( int $index );
```
## Forms\Exceptions\UnknownFormElementType
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\UnknownFormElementType`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct( string $type );
```
## Forms\Exceptions\YamlExtensionRequired
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\YamlExtensionRequired`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Exceptions\YamlSchemaNotArray
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\YamlSchemaNotArray`**
__Uses__ `Phalcon\Forms\Exception`
### Method Summary
### Methods
Public · 1
```php
public function __construct();
```
## Forms\Form
Class
Source on GitHub
This component allows to build forms using an object-oriented interface
- `\stdClass`
- [`Phalcon\Di\Injectable`](/5.19/api/phalcon_di/#diinjectable)
- **`Phalcon\Forms\Form`** - implements `\Countable`, `\Iterator`, [`Phalcon\Html\Attributes\AttributesInterface`](/5.19/api/phalcon_html/#htmlattributesattributesinterface)
__Uses__ `Countable` · `Iterator` · `Phalcon\Contracts\Forms\Schema` · `Phalcon\Di\DiInterface` · `Phalcon\Di\Injectable` · `Phalcon\Filter\FilterInterface` · `Phalcon\Filter\Validation` · `Phalcon\Filter\Validation\ValidationInterface` · `Phalcon\Forms\Element\Check` · `Phalcon\Forms\Element\ElementInterface` · `Phalcon\Forms\Exceptions\ElementNotInForm` · `Phalcon\Forms\Exceptions\InvalidEntity` · `Phalcon\Forms\Exceptions\NoFormElements` · `Phalcon\Html\Attributes` · `Phalcon\Html\Attributes\AttributesInterface` · `Phalcon\Html\TagFactory` · `Phalcon\Messages\Messages` · `Phalcon\Support\Settings` · `Phalcon\Tag`
### Method Summary
public
__construct(mixed $entity = null,array $userOptions = [])
Phalcon\Forms\Form constructor
public
static
add(ElementInterface $element,string|null $position = null,bool|null $type = null)
Adds an element to the form
public
static
bind(array $data,mixed $entity = null,array $whitelist = [])
Binds data to the entity
public
static
clear( mixed $fields = null )
Clears every element in the form to its default value
public
int
count()
Returns the number of elements in the form
public
mixed
current()
Returns the current element in the iterator
public
ElementInterface
get( string $name )
Returns an element added to the form by its name
public
string
getAction()
Returns the form's action
public
Attributes
getAttributes()
Get Form attributes collection
public
ElementInterface[]
getElements()
Returns the form elements added to the form
public
getEntity()
Returns the entity related to the model
public
mixed|null
getFilteredValue( string $name )
Gets a value from the internal filtered data or calls getValue(name)
public
string
getLabel( string $name )
Returns a label for an element
public
Messages
getMessages()
Returns the messages generated in the validation.
public
Messages
getMessagesFor( string $name )
Returns the messages generated for a specific element
public
TagFactory|null
getTagFactory()
Returns the tagFactory object
public
mixed
getUserOption(string $option,mixed $defaultValue = null)
Returns the value of an option if present
public
array
getUserOptions()
Returns the options for the element
public
ValidationInterface|null
getValidation()
return ValidationInterface|null
public
mixed|null
getValue( string $name )
Gets a value from the internal related entity or from the default value
public
array
getWhitelist()
return array
public
bool
has( string $name )
Check if the form contains an element
public
bool
hasMessagesFor( string $name )
Check if messages were generated for a specific element
public
bool
isValid(mixed $data = null,mixed $entity = null,array $whitelist = [])
Validates the form
public
int
key()
Returns the current position/key in the iterator
public
string
label(string $name,array $attributes = [])
Generate the label of an element added to the form including HTML
public
static
load(Schema $schema,FormsLocator $locator)
Loads elements into the form from a Schema source.
public
void
next()
Moves the internal iteration pointer to the next position
public
bool
remove( string $name )
Removes an element from the form
public
string
render(string $name,array $attributes = [])
Renders a specific item in the form
public
void
rewind()
Rewinds the internal iterator
public
static
setAction( string $action )
Sets the form's action
public
static
setAttributes( Attributes $attributes )
Set form attributes collection
public
static
setEntity( mixed $entity )
Sets the entity related to the model
public
static
setTagFactory( TagFactory $tagFactory )
Sets the tagFactory for the form
public
static
setUserOption(string $option,mixed $value)
Sets an option for the form
public
static
setUserOptions( array $options )
Sets options for the element
public
static
setValidation( ValidationInterface $validation )
Sets the default validation
public
static
setWhitelist( array $whitelist )
Sets the default whitelist
public
bool
valid()
Check if the current element in the iterator is valid
### Properties
protected
AttributesInterface|null
$attributes = null
protected
array
$data = []
protected
array
$elements = []
protected
array
$elementsIndexed = []
protected
object|null
$entity = null
protected
array
$filteredData = []
protected
Messages
$messages
protected
array
$options = []
protected
int
$position = 0
protected
TagFactory|null
$tagFactory = null
protected
ValidationInterface|null
$validation = null
protected
array
$whitelist = []
### Methods
Public · 40
```php
public function __construct(
mixed $entity = null,
array $userOptions = []
);
```
Phalcon\Forms\Form constructor
```php
public function add(
ElementInterface $element,
string|null $position = null,
bool|null $type = null
): static;
```
Adds an element to the form
```php
public function bind(
array $data,
mixed $entity = null,
array $whitelist = []
): static;
```
Binds data to the entity
```php
public function clear( mixed $fields = null ): static;
```
Clears every element in the form to its default value
```php
public function count(): int;
```
Returns the number of elements in the form
```php
public function current(): mixed;
```
Returns the current element in the iterator
```php
public function get( string $name ): ElementInterface;
```
Returns an element added to the form by its name
```php
public function getAction(): string;
```
Returns the form's action
```php
public function getAttributes(): Attributes;
```
Get Form attributes collection
```php
public function getElements(): ElementInterface[];
```
Returns the form elements added to the form
```php
public function getEntity();
```
Returns the entity related to the model
```php
public function getFilteredValue( string $name ): mixed|null;
```
Gets a value from the internal filtered data or calls getValue(name)
```php
public function getLabel( string $name ): string;
```
Returns a label for an element
```php
public function getMessages(): Messages;
```
Returns the messages generated in the validation.
```php
if ($form->isValid($_POST) == false) {
$messages = $form->getMessages();
foreach ($messages as $message) {
echo $message, "
";
}
}
```
```php
public function getMessagesFor( string $name ): Messages;
```
Returns the messages generated for a specific element
```php
public function getTagFactory(): TagFactory|null;
```
Returns the tagFactory object
```php
public function getUserOption(
string $option,
mixed $defaultValue = null
): mixed;
```
Returns the value of an option if present
```php
public function getUserOptions(): array;
```
Returns the options for the element
```php
public function getValidation(): ValidationInterface|null;
```
return ValidationInterface|null
```php
public function getValue( string $name ): mixed|null;
```
Gets a value from the internal related entity or from the default value
```php
public function getWhitelist(): array;
```
return array
```php
public function has( string $name ): bool;
```
Check if the form contains an element
```php
public function hasMessagesFor( string $name ): bool;
```
Check if messages were generated for a specific element
```php
public function isValid(
mixed $data = null,
mixed $entity = null,
array $whitelist = []
): bool;
```
Validates the form
```php
public function key(): int;
```
Returns the current position/key in the iterator
```php
public function label(
string $name,
array $attributes = []
): string;
```
Generate the label of an element added to the form including HTML
```php
public function load(
Schema $schema,
FormsLocator $locator
): static;
```
Loads elements into the form from a Schema source.
Each definition in the schema must have at least 'type' and 'name'.
The locator resolves the type string to an element factory; custom
types can be registered on the locator with setElement().
```php
public function next(): void;
```
Moves the internal iteration pointer to the next position
```php
public function remove( string $name ): bool;
```
Removes an element from the form
```php
public function render(
string $name,
array $attributes = []
): string;
```
Renders a specific item in the form
```php
public function rewind(): void;
```
Rewinds the internal iterator
```php
public function setAction( string $action ): static;
```
Sets the form's action
```php
public function setAttributes( Attributes $attributes ): static;
```
Set form attributes collection
```php
public function setEntity( mixed $entity ): static;
```
Sets the entity related to the model
```php
public function setTagFactory( TagFactory $tagFactory ): static;
```
Sets the tagFactory for the form
```php
public function setUserOption(
string $option,
mixed $value
): static;
```
Sets an option for the form
```php
public function setUserOptions( array $options ): static;
```
Sets options for the element
```php
public function setValidation( ValidationInterface $validation ): static;
```
Sets the default validation
```php
public function setWhitelist( array $whitelist ): static;
```
Sets the default whitelist
```php
public function valid(): bool;
```
Check if the current element in the iterator is valid
## Forms\FormsLocator
Class
Source on GitHub
A closure-based registry for named forms and element type factories.
**Form registry** (`get`/`has`/`set`):
Each entry is a callable `fn(?object $entity): Form`. Without an entity the
resolved form is cached; with an entity a fresh form is always produced.
**Element registry** (`getElement`/`hasElement`/`setElement`):
Maps type strings (e.g. 'text', 'email') to factories used by Form::load().
Each callable has the signature `fn(string $name, array $options, array $attributes): ElementInterface`.
Default types are seeded by `getDefaultServices()`. Users may add or override
types with `setElement()`.
- **`Phalcon\Forms\FormsLocator`**
__Uses__ `Phalcon\Forms\Element\Check` · `Phalcon\Forms\Element\CheckGroup` · `Phalcon\Forms\Element\Date` · `Phalcon\Forms\Element\Email` · `Phalcon\Forms\Element\File` · `Phalcon\Forms\Element\Hidden` · `Phalcon\Forms\Element\Numeric` · `Phalcon\Forms\Element\Password` · `Phalcon\Forms\Element\Radio` · `Phalcon\Forms\Element\RadioGroup` · `Phalcon\Forms\Element\Select` · `Phalcon\Forms\Element\Submit` · `Phalcon\Forms\Element\Text` · `Phalcon\Forms\Element\TextArea` · `Phalcon\Forms\Exceptions\FormNotInLocator` · `Phalcon\Forms\Exceptions\UnknownFormElementType`
### Method Summary
### Methods
Public · 7
```php
public function __construct( array $definitions = [] );
```
```php
public function get(
string $name,
mixed $entity = null
): Form;
```
Returns the named form.
Without an entity the result is lazily created and cached.
With an entity a fresh form is always produced.
```php
public function getElement( string $type );
```
Returns the factory callable for the given element type.
```php
public function has( string $name ): bool;
```
Checks whether a named form factory is registered.
```php
public function hasElement( string $type ): bool;
```
Checks whether an element type is registered.
```php
public function set(
string $name,
mixed $factory
): void;
```
Registers or replaces a named form factory.
The callable must accept one argument (?object $entity) and return a
Form instance. Replacing a registration clears any cached instance so
the next get() call rebuilds from the new factory.
```php
public function setElement(
string $type,
mixed $factory
): void;
```
Registers or replaces an element type factory.
The callable must accept (string $name, array $options, array $attributes)
and return an ElementInterface instance.
Protected · 1
```php
protected function getDefaultServices(): array;
```
Returns the built-in element type factories.
Each value is a callable: fn(string $name, array $options, array $attributes): ElementInterface
## Forms\Loader\ArrayLoader
Class
Source on GitHub
Supplies form element definitions from a PHP array.
- **`Phalcon\Forms\Loader\ArrayLoader`** - implements [`Phalcon\Contracts\Forms\Schema`](/5.19/api/phalcon_contracts/#contractsformsschema)
__Uses__ `Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exception` · `Phalcon\Forms\Exceptions\SchemaEntryMissingKey` · `Phalcon\Forms\Exceptions\SchemaEntryNotArray`
### Method Summary
### Properties
protected
array
$definitions
### Methods
Public · 2
```php
public function __construct( array $definitions );
```
```php
public function load(): array;
```
Protected · 1
```php
protected function validateDefinition(
mixed $definition,
int $index
): void;
```
## Forms\Loader\JsonLoader
Class
Source on GitHub
Supplies form element definitions from a JSON string or file.
When $source looks like an existing, readable file path it is read from
disk first; otherwise the value is treated as a raw JSON string.
- **`Phalcon\Forms\Loader\JsonLoader`** - implements [`Phalcon\Contracts\Forms\Schema`](/5.19/api/phalcon_contracts/#contractsformsschema)
__Uses__ `InvalidArgumentException` · `Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exception` · `Phalcon\Forms\Exceptions\InvalidJsonSchema` · `Phalcon\Forms\Exceptions\JsonSchemaNotArray` · `Phalcon\Support\Helper\Json\Decode` · `Phalcon\Traits\Php\FileTrait`
### Method Summary
### Properties
### Methods
Public · 2
```php
public function __construct( string $source );
```
```php
public function load(): array;
```
## Forms\Loader\YamlLoader
Class
Source on GitHub
Supplies form element definitions from a YAML string or file.
Requires the PHP `yaml` extension (pecl/yaml).
When $source is an existing, readable file path the file is parsed
directly; otherwise the value is treated as a raw YAML string.
- **`Phalcon\Forms\Loader\YamlLoader`** - implements [`Phalcon\Contracts\Forms\Schema`](/5.19/api/phalcon_contracts/#contractsformsschema)
__Uses__ `Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exception` · `Phalcon\Forms\Exceptions\YamlExtensionRequired` · `Phalcon\Forms\Exceptions\YamlSchemaNotArray` · `Phalcon\Traits\Php\InfoTrait`
### Method Summary
### Properties
### Methods
Public · 2
```php
public function __construct( string $source );
```
```php
public function load(): array;
```
## Forms\Manager
Class
Source on GitHub
Forms Manager
- **`Phalcon\Forms\Manager`**
__Uses__ `Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exceptions\FormNotRegistered` · `Phalcon\Forms\Form`
### Method Summary
### Properties
protected
array
$forms = []
protected
FormsLocator
$locator
### Methods
Public · 7
```php
public function __construct( FormsLocator|null $locator = null );
```
Manager constructor.
```php
public function create(
string $name,
mixed $entity = null
): Form;
```
Creates a form registering it in the forms manager
```php
public function get( string $name ): Form;
```
Returns a form by its name
```php
public function getLocator(): FormsLocator;
```
Returns the FormsLocator instance.
```php
public function has( string $name ): bool;
```
Checks if a form is registered in the forms manager
```php
public function loadForm(
string $name,
Schema $schema,
mixed $entity = null
): Form;
```
Creates a form from a Schema source, registers it in the manager,
and registers a factory in the locator for entity-aware retrieval.
```php
public function set(
string $name,
Form $form
): static;
```
Registers a form in the Forms Manager
Source: https://docs.phalcon.io/5.19/api/phalcon_forms/index.mdx