Phalcon Forms

Forms\Element\AbstractElement

This is a base class for form elements

Uses 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

Properties

Methods

__construct()

public function __construct(
    string $name,
    array $attributes = []
);

Constructor

__toString()

public function __toString(): string;

Magic method __toString renders the widget without attributes

addFilter()

public function addFilter( string $filter ): ElementInterface;

Adds a filter to current list of filters

addValidator()

public function addValidator( ValidatorInterface $validator ): ElementInterface;

Adds a validator to the element

addValidators()

public function addValidators(
    array $validators,
    bool $merge = true
): ElementInterface;

Adds a group of validators

appendMessage()

public function appendMessage( MessageInterface $message ): ElementInterface;

Appends a message to the internal message list

clear()

public function clear(): ElementInterface;

Clears element to its default value

getAttribute()

public function getAttribute(
    string $attribute,
    mixed $defaultValue = null
): mixed;

Returns the value of an attribute if present

getAttributes()

public function getAttributes(): array;

Returns the default attributes for the element

getDefault()

public function getDefault(): mixed;

Returns the default value assigned to the element

getFilters()

public function getFilters();

Returns the element filters

getForm()

public function getForm(): Form;

Returns the parent form to the element

getLabel()

public function getLabel(): string|null;

Returns the element label

getMessages()

public function getMessages(): Messages;

Returns the messages that belongs to the element The element needs to be attached to a form

getName()

public function getName(): string;

Returns the element name

getTagFactory()

public function getTagFactory(): TagFactory|null;

Returns the tagFactory; throws exception if not present

getUserOption()

public function getUserOption(
    string $option,
    mixed $defaultValue = null
): mixed;

Returns the value of an option if present

getUserOptions()

public function getUserOptions(): array;

Returns the options for the element

getValidators()

public function getValidators(): ValidatorInterface[];

Returns the validators registered for the element

getValue()

public function getValue(): mixed;

Returns the element’s value

hasMessages()

public function hasMessages(): bool;

Checks whether there are messages attached to the element

label()

public function label( array $attributes = [] ): string;

Generate the HTML to label the element

render()

public function render( array $attributes = [] ): string;

Renders the element widget returning HTML

setAttribute()

public function setAttribute(
    string $attribute,
    mixed $value
): ElementInterface;

Sets a default attribute for the element

setAttributes()

public function setAttributes( array $attributes ): ElementInterface;

Sets default attributes for the element

setDefault()

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

setFilters()

public function setFilters( mixed $filters ): ElementInterface;

Sets the element filters

setForm()

public function setForm( Form $form ): ElementInterface;

Sets the parent form to the element

setLabel()

public function setLabel( string $label ): ElementInterface;

Sets the element label

setMessages()

public function setMessages( Messages $messages ): ElementInterface;

Sets the validation messages related to the element

setName()

public function setName( string $name ): ElementInterface;

Sets the element name

setTagFactory()

public function setTagFactory( TagFactory $tagFactory ): static;

Sets the TagFactory

setUserOption()

public function setUserOption(
    string $option,
    mixed $value
): ElementInterface;

Sets an option for the element

setUserOptions()

public function setUserOptions( array $options ): ElementInterface;

Sets options for the element

getLocalTagFactory()

protected function getLocalTagFactory(): TagFactory;

Returns the tagFactory; throws exception if not present

Forms\Element\Check

Component INPUT[type=check] for forms

Method Summary

Properties

Methods

getUncheckedValue()

public function getUncheckedValue(): mixed;

Returns the value to bind when the checkbox is absent from submitted data. Only meaningful when hasUncheckedValue() is true.

hasUncheckedValue()

public function hasUncheckedValue(): bool;

Whether an “unchecked value” has been explicitly registered.

setUncheckedValue()

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

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]]

Uses Phalcon\Contracts\Forms\FormsTypes · Phalcon\Contracts\Html\HtmlTypes · Phalcon\Html\TagFactory

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $name,
    array $options = [],
    array $attributes = []
);

Constructor

getOptions()

public function getOptions(): array;

Returns the group options

render()

public function render( array $attributes = [] ): string;

Renders the checkbox group returning HTML

setOptions()

public function setOptions( array $options ): ElementInterface;

Sets the group options

Forms\Element\Date

Component INPUT[type=date] for forms

Properties

Forms\Element\ElementInterface

Interface for Phalcon\Forms\Element classes

Uses Phalcon\Contracts\Forms\FormsTypes · Phalcon\Contracts\Html\HtmlTypes · Phalcon\Filter\Validation\ValidatorInterface · Phalcon\Forms\Form · Phalcon\Messages\MessageInterface · Phalcon\Messages\Messages

Method Summary

Methods

addFilter()

public function addFilter( string $filter ): ElementInterface;

Adds a filter to current list of filters

addValidator()

public function addValidator( ValidatorInterface $validator ): ElementInterface;

Adds a validator to the element

addValidators()

public function addValidators(
    array $validators,
    bool $merge = true
): ElementInterface;

Adds a group of validators

appendMessage()

public function appendMessage( MessageInterface $message ): ElementInterface;

Appends a message to the internal message list

clear()

public function clear(): ElementInterface;

Clears every element in the form to its default value

getAttribute()

public function getAttribute(
    string $attribute,
    mixed $defaultValue = null
): mixed;

Returns the value of an attribute if present

getAttributes()

public function getAttributes(): array;

Returns the default attributes for the element

getDefault()

public function getDefault(): mixed;

Returns the default value assigned to the element

getFilters()

public function getFilters();

Returns the element’s filters

getForm()

public function getForm(): Form;

Returns the parent form to the element

getLabel()

public function getLabel(): string|null;

Returns the element’s label

getMessages()

public function getMessages(): Messages;

Returns the messages that belongs to the element The element needs to be attached to a form

getName()

public function getName(): string;

Returns the element’s name

getUserOption()

public function getUserOption(
    string $option,
    mixed $defaultValue = null
): mixed;

Returns the value of an option if present

getUserOptions()

public function getUserOptions(): array;

Returns the options for the element

getValidators()

public function getValidators(): ValidatorInterface[];

Returns the validators registered for the element

getValue()

public function getValue(): mixed;

Returns the element’s value

hasMessages()

public function hasMessages(): bool;

Checks whether there are messages attached to the element

label()

public function label(): string;

Generate the HTML to label the element

render()

public function render( array $attributes = [] ): string;

Renders the element widget

setAttribute()

public function setAttribute(
    string $attribute,
    mixed $value
): ElementInterface;

Sets a default attribute for the element

setAttributes()

public function setAttributes( array $attributes ): ElementInterface;

Sets default attributes for the element

setDefault()

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

setFilters()

public function setFilters( mixed $filters ): ElementInterface;

Sets the element’s filters

setForm()

public function setForm( Form $form ): ElementInterface;

Sets the parent form to the element

setLabel()

public function setLabel( string $label ): ElementInterface;

Sets the element label

setMessages()

public function setMessages( Messages $messages ): ElementInterface;

Sets the validation messages related to the element

setName()

public function setName( string $name ): ElementInterface;

Sets the element’s name

setUserOption()

public function setUserOption(
    string $option,
    mixed $value
): ElementInterface;

Sets an option for the element

setUserOptions()

public function setUserOptions( array $options ): ElementInterface;

Sets options for the element

Forms\Element\Email

Component INPUT[type=email] for forms

Properties

Forms\Element\File

Component INPUT[type=file] for forms

Properties

Forms\Element\Hidden

Component INPUT[type=hidden] for forms

Properties

Forms\Element\Numeric

Component INPUT[type=number] for forms

Properties

Forms\Element\Password

Component INPUT[type=password] for forms

Properties

Forms\Element\Radio

Component INPUT[type=radio] for forms

Properties

Forms\Element\RadioGroup

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]]

Uses Phalcon\Contracts\Forms\FormsTypes · Phalcon\Contracts\Html\HtmlTypes · Phalcon\Html\Helper\Input\RadioGroup · Phalcon\Html\TagFactory

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $name,
    array $options = [],
    array $attributes = []
);

Constructor

getOptions()

public function getOptions(): array;

Returns the group options

render()

public function render( array $attributes = [] ): string;

Renders the radio group returning HTML

setOptions()

public function setOptions( array $options ): ElementInterface;

Sets the group options

Forms\Element\Select

Component SELECT (choice) for forms

Uses Phalcon\Contracts\Forms\FormsTypes · Phalcon\Contracts\Html\HtmlTypes · Phalcon\Tag\Select

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $name,
    mixed $options = null,
    array $attributes = []
);

Constructor

addOption()

public function addOption( mixed $option ): ElementInterface;

Adds an option to the current options

getOptions()

public function getOptions();

Returns the choices’ options

render()

public function render( array $attributes = [] ): string;

Renders the element widget returning HTML

setOptions()

public function setOptions( mixed $options ): ElementInterface;

Set the choice’s options

prepareAttributes()

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

Component INPUT[type=submit] for forms

Properties

Forms\Element\Text

Component INPUT[type=text] for forms

Forms\Element\TextArea

Component TEXTAREA for forms

Properties

Forms\Exception

Exceptions thrown in Phalcon\Forms will use this class

Method Summary

Methods

tagFactoryNotFound()

public static function tagFactoryNotFound(): self;

usingParameterRequired()

public static function usingParameterRequired(): self;

Forms\Exceptions\ElementNotInForm

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Forms\Exceptions\FormElementNameRequired

Uses InvalidArgumentException

Method Summary

Methods

__construct()

public function __construct();

Forms\Exceptions\FormNotInLocator

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Forms\Exceptions\FormNotRegistered

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Forms\Exceptions\InvalidEntity

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct();

Forms\Exceptions\InvalidFilterType

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct();

Forms\Exceptions\InvalidJsonSchema

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct( string $detail );

Forms\Exceptions\JsonSchemaNotArray

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct();

Forms\Exceptions\NoFormElements

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct();

Forms\Exceptions\SchemaEntryMissingKey

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct(
    int $index,
    string $key
);

Forms\Exceptions\SchemaEntryNotArray

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct( int $index );

Forms\Exceptions\UnknownFormElementType

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct( string $type );

Forms\Exceptions\YamlExtensionRequired

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct();

Forms\Exceptions\YamlSchemaNotArray

Uses Phalcon\Forms\Exception

Method Summary

Methods

__construct()

public function __construct();

Forms\Form

This component allows to build forms using an object-oriented interface

@implements Iterator<int, ElementInterface>

Uses 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

Properties

Methods

__construct()

public function __construct(
    mixed $entity = null,
    array $userOptions = []
);

Phalcon\Forms\Form constructor

add()

public function add(
    ElementInterface $element,
    string|null $position = null,
    bool|null $type = null
): static;

Adds an element to the form

bind()

public function bind(
    array $data,
    mixed $entity = null,
    array $whitelist = []
): static;

Binds data to the entity

clear()

public function clear( mixed $fields = null ): static;

Clears every element in the form to its default value

count()

public function count(): int;

Returns the number of elements in the form

current()

public function current(): mixed;

Returns the current element in the iterator

get()

public function get( string $name ): ElementInterface;

Returns an element added to the form by its name

getAction()

public function getAction(): string;

Returns the form’s action

getAttributes()

public function getAttributes(): Attributes;

Get Form attributes collection

getElements()

public function getElements(): ElementInterface[];

Returns the form elements added to the form

getEntity()

public function getEntity();

Returns the entity related to the model

getFilteredValue()

public function getFilteredValue( string $name ): mixed|null;

Gets a value from the internal filtered data or calls getValue(name)

getLabel()

public function getLabel( string $name ): string;

Returns a label for an element

getMessages()

public function getMessages(): Messages;

Returns the messages generated in the validation.

if ($form->isValid($_POST) == false) {
    $messages = $form->getMessages();

    foreach ($messages as $message) {
        echo $message, "<br>";
    }
}

getMessagesFor()

public function getMessagesFor( string $name ): Messages;

Returns the messages generated for a specific element

getTagFactory()

public function getTagFactory(): TagFactory|null;

Returns the tagFactory object

getUserOption()

public function getUserOption(
    string $option,
    mixed $defaultValue = null
): mixed;

Returns the value of an option if present

getUserOptions()

public function getUserOptions(): array;

Returns the options for the element

getValidation()

public function getValidation(): ValidationInterface|null;

return ValidationInterface|null

getValue()

public function getValue( string $name ): mixed|null;

Gets a value from the internal related entity or from the default value

getWhitelist()

public function getWhitelist(): array;

has()

public function has( string $name ): bool;

Check if the form contains an element

hasMessagesFor()

public function hasMessagesFor( string $name ): bool;

Check if messages were generated for a specific element

isValid()

public function isValid(
    mixed $data = null,
    mixed $entity = null,
    array $whitelist = []
): bool;

Validates the form

key()

public function key(): int;

Returns the current position/key in the iterator

label()

public function label(
    string $name,
    array $attributes = []
): string;

Generate the label of an element added to the form including HTML

load()

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

next()

public function next(): void;

Moves the internal iteration pointer to the next position

remove()

public function remove( string $name ): bool;

Removes an element from the form

render()

public function render(
    string $name,
    array $attributes = []
): string;

Renders a specific item in the form

rewind()

public function rewind(): void;

Rewinds the internal iterator

setAction()

public function setAction( string $action ): static;

Sets the form’s action

setAttributes()

public function setAttributes( Attributes $attributes ): static;

Set form attributes collection

setEntity()

public function setEntity( mixed $entity ): static;

Sets the entity related to the model

setTagFactory()

public function setTagFactory( TagFactory $tagFactory ): static;

Sets the tagFactory for the form

setUserOption()

public function setUserOption(
    string $option,
    mixed $value
): static;

Sets an option for the form

setUserOptions()

public function setUserOptions( array $options ): static;

Sets options for the element

setValidation()

public function setValidation( ValidationInterface $validation ): static;

Sets the default validation

setWhitelist()

public function setWhitelist( array $whitelist ): static;

Sets the default whitelist

valid()

public function valid(): bool;

Check if the current element in the iterator is valid

Forms\FormsLocator

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

Uses 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

Methods

__construct()

public function __construct( array $definitions = [] );

get()

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.

getElement()

public function getElement( string $type );

Returns the factory callable for the given element type.

has()

public function has( string $name ): bool;

Checks whether a named form factory is registered.

hasElement()

public function hasElement( string $type ): bool;

Checks whether an element type is registered.

set()

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.

setElement()

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.

getDefaultServices()

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

Supplies form element definitions from a PHP array.

Uses Phalcon\Contracts\Forms\Schema · Phalcon\Forms\Exception · Phalcon\Forms\Exceptions\SchemaEntryMissingKey · Phalcon\Forms\Exceptions\SchemaEntryNotArray

Method Summary

Properties

Methods

__construct()

public function __construct( array $definitions );

load()

public function load(): array;

validateDefinition()

protected function validateDefinition(
    mixed $definition,
    int $index
): void;

Forms\Loader\JsonLoader

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.

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

__construct()

public function __construct( string $source );

load()

public function load(): array;

Forms\Loader\YamlLoader

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.

Uses Phalcon\Contracts\Forms\Schema · Phalcon\Forms\Exception · Phalcon\Forms\Exceptions\YamlExtensionRequired · Phalcon\Forms\Exceptions\YamlSchemaNotArray · Phalcon\Traits\Php\InfoTrait

Method Summary

Properties

Methods

__construct()

public function __construct( string $source );

load()

public function load(): array;

Forms\Manager

Forms Manager

Uses Phalcon\Contracts\Forms\Schema · Phalcon\Forms\Exceptions\FormNotRegistered · Phalcon\Forms\Form

Method Summary

Properties

Methods

__construct()

public function __construct( FormsLocator|null $locator = null );

Manager constructor.

create()

public function create(
    string $name,
    mixed $entity = null
): Form;

Creates a form registering it in the forms manager

get()

public function get( string $name ): Form;

Returns a form by its name

getLocator()

public function getLocator(): FormsLocator;

Returns the FormsLocator instance.

has()

public function has( string $name ): bool;

Checks if a form is registered in the forms manager

loadForm()

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.

set()

public function set(
    string $name,
    Form $form
): static;

Registers a form in the Forms Manager