---
title: "Phalcon Forms"
version: "5.20"
---
> 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
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)
`Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Contracts\Html\HtmlTypes` · `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` · `Stringable`
### Method Summary
Constructor
Magic method __toString renders the widget without attributes
Adds a filter to current list of filters
Adds a validator to the element
Adds a group of validators
Appends a message to the internal message list
Clears element to its default value
Returns the value of an attribute if present
Returns the default attributes for the element
Returns the default value assigned to the element
Returns the element filters
Returns the parent form to the element
Returns the element label
Returns the messages that belongs to the element
Returns the element name
Returns the tagFactory; throws exception if not present
Returns the value of an option if present
Returns the options for the element
Returns the validators registered for the element
Returns the element's value
Checks whether there are messages attached to the element
Generate the HTML to label the element
Renders the element widget returning HTML
Sets a default attribute for the element
Sets default attributes for the element
Sets a default value in case the form does not use an entity
Sets the element filters
Sets the parent form to the element
Sets the element label
Sets the validation messages related to the element
Sets the element name
Sets the TagFactory
Sets an option for the element
Sets options for the element
Returns the tagFactory; throws exception if not present
### Properties
### Methods
```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
```php
protected function getLocalTagFactory(): TagFactory;
```
Returns the tagFactory; throws exception if not present
## Forms\Element\Check
Class
Component INPUT[type=check] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Check`**
### Method Summary
Returns the value to bind when the checkbox is absent from submitted
Whether an "unchecked value" has been explicitly registered.
Registers a value to bind when the checkbox is absent from submitted
### Properties
### Methods
```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
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`**
`Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Contracts\Html\HtmlTypes` · `Phalcon\Html\TagFactory`
### Method Summary
Constructor
Returns the group options
Renders the checkbox group returning HTML
Sets the group options
### Properties
### Methods
```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
Component INPUT[type=date] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Date`**
### Properties
## Forms\Element\ElementInterface
Interface
Interface for Phalcon\Forms\Element classes
- **`Phalcon\Forms\Element\ElementInterface`**
`Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Contracts\Html\HtmlTypes` · `Phalcon\Filter\Validation\ValidatorInterface` · `Phalcon\Forms\Form` · `Phalcon\Messages\MessageInterface` · `Phalcon\Messages\Messages`
### Method Summary
Adds a filter to current list of filters
Adds a validator to the element
Adds a group of validators
Appends a message to the internal message list
Clears every element in the form to its default value
Returns the value of an attribute if present
Returns the default attributes for the element
Returns the default value assigned to the element
Returns the element's filters
Returns the parent form to the element
Returns the element's label
Returns the messages that belongs to the element
Returns the element's name
Returns the value of an option if present
Returns the options for the element
Returns the validators registered for the element
Returns the element's value
Checks whether there are messages attached to the element
Generate the HTML to label the element
Renders the element widget
Sets a default attribute for the element
Sets default attributes for the element
Sets a default value in case the form does not use an entity
Sets the element's filters
Sets the parent form to the element
Sets the element label
Sets the validation messages related to the element
Sets the element's name
Sets an option for the element
Sets options for the element
### Methods
```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
Component INPUT[type=email] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Email`**
### Properties
## Forms\Element\File
Class
Component INPUT[type=file] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\File`**
### Properties
## Forms\Element\Hidden
Class
Component INPUT[type=hidden] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Hidden`**
### Properties
## Forms\Element\Numeric
Class
Component INPUT[type=number] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Numeric`**
### Properties
## Forms\Element\Password
Class
Component INPUT[type=password] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Password`**
### Properties
## Forms\Element\Radio
Class
Component INPUT[type=radio] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Radio`**
### Properties
## Forms\Element\RadioGroup
Class
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`**
`Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Contracts\Html\HtmlTypes` · `Phalcon\Html\Helper\Input\RadioGroup` · `Phalcon\Html\TagFactory`
### Method Summary
Constructor
Returns the group options
Renders the radio group returning HTML
Sets the group options
### Properties
### Methods
```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
Component SELECT (choice) for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Select`**
`Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Contracts\Html\HtmlTypes` · `Phalcon\Tag\Select`
### Method Summary
Constructor
Adds an option to the current options
Returns the choices' options
Renders the element widget returning HTML
Set the choice's options
Returns an array of prepared attributes for Phalcon\Html\TagFactory
### Properties
### Methods
```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
```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
Component INPUT[type=submit] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Submit`**
### Properties
## Forms\Element\Text
Class
Component INPUT[type=text] for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\Text`**
## Forms\Element\TextArea
Class
Component TEXTAREA for forms
- [`Phalcon\Forms\Element\AbstractElement`](#formselementabstractelement)
- **`Phalcon\Forms\Element\TextArea`**
### Properties
## Forms\Exception
Class
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
```php
public static function tagFactoryNotFound(): self;
```
```php
public static function usingParameterRequired(): self;
```
## Forms\Exceptions\ElementNotInForm
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\ElementNotInForm`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct( string $name );
```
## Forms\Exceptions\FormElementNameRequired
Class
- `\InvalidArgumentException`
- **`Phalcon\Forms\Exceptions\FormElementNameRequired`**
`InvalidArgumentException`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Exceptions\FormNotInLocator
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\FormNotInLocator`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct( string $name );
```
## Forms\Exceptions\FormNotRegistered
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\FormNotRegistered`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct( string $name );
```
## Forms\Exceptions\InvalidEntity
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\InvalidEntity`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Exceptions\InvalidFilterType
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\InvalidFilterType`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Exceptions\InvalidJsonSchema
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\InvalidJsonSchema`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct( string $detail );
```
## Forms\Exceptions\JsonSchemaNotArray
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\JsonSchemaNotArray`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Exceptions\NoFormElements
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\NoFormElements`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Exceptions\SchemaEntryMissingKey
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\SchemaEntryMissingKey`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct(
int $index,
string $key
);
```
## Forms\Exceptions\SchemaEntryNotArray
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\SchemaEntryNotArray`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( int $index );
```
## Forms\Exceptions\UnknownFormElementType
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\UnknownFormElementType`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct( string $type );
```
## Forms\Exceptions\YamlExtensionRequired
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\YamlExtensionRequired`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Exceptions\YamlSchemaNotArray
Class
- `\Exception`
- [`Phalcon\Forms\Exception`](#formsexception)
- **`Phalcon\Forms\Exceptions\YamlSchemaNotArray`**
`Phalcon\Forms\Exception`
### Method Summary
### Methods
```php
public function __construct();
```
## Forms\Form
Class
This component allows to build forms using an object-oriented interface
@implements Iterator<int, ElementInterface>
- `\stdClass`
- [`Phalcon\Di\Injectable`](/5.20/api/phalcon_di/#diinjectable)
- **`Phalcon\Forms\Form`** - implements `\Countable`, `\Iterator`, [`Phalcon\Html\Attributes\AttributesInterface`](/5.20/api/phalcon_html/#htmlattributesattributesinterface)
`Countable` · `Iterator` · `Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Contracts\Forms\Schema` · `Phalcon\Contracts\Html\HtmlTypes` · `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
Phalcon\Forms\Form constructor
Adds an element to the form
Binds data to the entity
Clears every element in the form to its default value
Returns the number of elements in the form
Returns the current element in the iterator
Returns an element added to the form by its name
Returns the form's action
Get Form attributes collection
Returns the form elements added to the form
Returns the entity related to the model
Gets a value from the internal filtered data or calls getValue(name)
Returns a label for an element
Returns the messages generated in the validation.
Returns the messages generated for a specific element
Returns the tagFactory object
Returns the value of an option if present
Returns the options for the element
return ValidationInterface|null
Gets a value from the internal related entity or from the default value
Check if the form contains an element
Check if messages were generated for a specific element
Validates the form
Returns the current position/key in the iterator
Generate the label of an element added to the form including HTML
Loads elements into the form from a Schema source.
Moves the internal iteration pointer to the next position
Removes an element from the form
Renders a specific item in the form
Rewinds the internal iterator
Sets the form's action
Set form attributes collection
Sets the entity related to the model
Sets the tagFactory for the form
Sets an option for the form
Sets options for the element
Sets the default validation
Sets the default whitelist
Check if the current element in the iterator is valid
### Properties
### Methods
```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;
```
```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
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`**
`Phalcon\Contracts\Forms\FormsTypes` · `Phalcon\Forms\Element\Check` · `Phalcon\Forms\Element\CheckGroup` · `Phalcon\Forms\Element\Date` · `Phalcon\Forms\Element\ElementInterface` · `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
Returns the named form.
Returns the factory callable for the given element type.
Checks whether a named form factory is registered.
Checks whether an element type is registered.
Registers or replaces a named form factory.
Registers or replaces an element type factory.
Returns the built-in element type factories.
### Methods
```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.
```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
Supplies form element definitions from a PHP array.
- **`Phalcon\Forms\Loader\ArrayLoader`** - implements [`Phalcon\Contracts\Forms\Schema`](/5.20/api/phalcon_contracts/#contractsformsschema)
`Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exception` · `Phalcon\Forms\Exceptions\SchemaEntryMissingKey` · `Phalcon\Forms\Exceptions\SchemaEntryNotArray`
### Method Summary
### Properties
### Methods
```php
public function __construct( array $definitions );
```
```php
public function load(): array;
```
```php
protected function validateDefinition(
mixed $definition,
int $index
): void;
```
## Forms\Loader\JsonLoader
Class
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.20/api/phalcon_contracts/#contractsformsschema)
`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
```php
public function __construct( string $source );
```
```php
public function load(): array;
```
## Forms\Loader\YamlLoader
Class
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.20/api/phalcon_contracts/#contractsformsschema)
`Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exception` · `Phalcon\Forms\Exceptions\YamlExtensionRequired` · `Phalcon\Forms\Exceptions\YamlSchemaNotArray` · `Phalcon\Traits\Php\InfoTrait`
### Method Summary
### Properties
### Methods
```php
public function __construct( string $source );
```
```php
public function load(): array;
```
## Forms\Manager
Class
Forms Manager
- **`Phalcon\Forms\Manager`**
`Phalcon\Contracts\Forms\Schema` · `Phalcon\Forms\Exceptions\FormNotRegistered` · `Phalcon\Forms\Form`
### Method Summary
Manager constructor.
Creates a form registering it in the forms manager
Returns a form by its name
Returns the FormsLocator instance.
Checks if a form is registered in the forms manager
Creates a form from a Schema source, registers it in the manager,
Registers a form in the Forms Manager
### Properties
### Methods
```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.20/api/phalcon_forms/index.mdx