Phalcon forms

NOTE

All classes are prefixed with Phalcon

Forms\Element\AbstractElement ¶

Namespace
- Phalcon\Forms\Element
Uses
- InvalidArgumentException
- Phalcon\Di\Di
- Phalcon\Di\DiInterface
- Phalcon\Filter\Validation\ValidatorInterface
- Phalcon\Forms\Exception
- Phalcon\Forms\Form
- Phalcon\Html\TagFactory
- Phalcon\Messages\MessageInterface
- Phalcon\Messages\Messages
Extends
Implements
- ElementInterface

This is a base class for form elements

Properties¶

/**
 * @var array
 */
protected $attributes;

/**
 * @var array
 */
protected $filters;

/**
 * @var Form|null
 */
protected $form;

/**
 * @var string|null
 */
protected $label;

/**
 * @var string
 */
protected $method = inputText;

/**
 * @var Messages
 */
protected $messages;

/**
 * @var string
 */
protected $name;

/**
 * @var array
 */
protected $options;

/**
 * @var TagFactory|null
 */
protected $tagFactory;

/**
 * @var array
 */
protected $validators;

/**
 * @var mixed|null
 */
protected $value;

Methods¶

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

Constructor

public function __toString(): string;

Magic method __toString renders the widget without attributes

public function addFilter( string $filter ): ElementInterface;

Adds a filter to current list of filters

public function addValidator( ValidatorInterface $validator ): ElementInterface;

Adds a validator to the element

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

Adds a group of validators

public function appendMessage( MessageInterface $message ): ElementInterface;

Appends a message to the internal message list

public function clear(): ElementInterface;

Clears element to its default value

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

Returns the value of an attribute if present

public function getAttributes(): array;

Returns the default attributes for the element

public function getDefault(): mixed;

Returns the default value assigned to the element

public function getFilters();

Returns the element filters

public function getForm(): Form;

Returns the parent form to the element

public function getLabel(): string | null;

Returns the element label

public function getMessages(): Messages;

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

public function getName(): string;

Returns the element name

public function getTagFactory(): TagFactory | null;

Returns the tagFactory; throws exception if not present

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

Returns the value of an option if present

public function getUserOptions(): array;

Returns the options for the element

public function getValidators(): ValidatorInterface[];

Returns the validators registered for the element

public function getValue(): mixed;

Returns the element's value

public function hasMessages(): bool;

Checks whether there are messages attached to the element

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

Generate the HTML to label the element

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

Renders the element widget returning HTML

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

Sets a default attribute for the element

public function setAttributes( array $attributes ): ElementInterface;

Sets default attributes for the element

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

public function setFilters( mixed $filters ): ElementInterface;

Sets the element filters

public function setForm( Form $form ): ElementInterface;

Sets the parent form to the element

public function setLabel( string $label ): ElementInterface;

Sets the element label

public function setMessages( Messages $messages ): ElementInterface;

Sets the validation messages related to the element

public function setName( string $name ): ElementInterface;

Sets the element name

public function setTagFactory( TagFactory $tagFactory ): AbstractElement;

Sets the TagFactory

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

Sets an option for the element

public function setUserOptions( array $options ): ElementInterface;

Sets options for the element

protected function getLocalTagFactory(): TagFactory;

Returns the tagFactory; throws exception if not present

Forms\Element\Check¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
Extends

AbstractElement
Implements

Component INPUT[type=check] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputCheckbox;

/**
 * @var mixed
 */
protected $uncheckedValue;

/**
 * @var bool
 */
protected $uncheckedValueSet = false;

Methods¶

public function getUncheckedValue(): mixed;

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

public function hasUncheckedValue(): bool;

Whether an "unchecked value" has been explicitly registered.

public function setUncheckedValue( mixed $value ): Check;

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¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Html\TagFactory
Extends

AbstractElement
Implements

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

Properties¶

/**
 * @var array
 */
protected $options;

Methods¶

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

Constructor

public function getOptions(): array;

Returns the group options

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

Renders the checkbox group returning HTML

public function setOptions( array $options ): ElementInterface;

Sets the group options

Forms\Element\Date¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=date] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputDate;

Forms\Element\ElementInterface ¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Filter\Validation\ValidatorInterface
- Phalcon\Forms\Form
- Phalcon\Messages\MessageInterface
- Phalcon\Messages\Messages
Extends
Implements

Interface for Phalcon\Forms\Element classes

Methods¶

public function addFilter( string $filter ): ElementInterface;

Adds a filter to current list of filters

public function addValidator( ValidatorInterface $validator ): ElementInterface;

Adds a validator to the element

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

Adds a group of validators

public function appendMessage( MessageInterface $message ): ElementInterface;

Appends a message to the internal message list

public function clear(): ElementInterface;

Clears every element in the form to its default value

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

Returns the value of an attribute if present

public function getAttributes(): array;

Returns the default attributes for the element

public function getDefault(): mixed;

Returns the default value assigned to the element

public function getFilters();

Returns the element's filters

public function getForm(): Form;

Returns the parent form to the element

public function getLabel(): string | null;

Returns the element's label

public function getMessages(): Messages;

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

public function getName(): string;

Returns the element's name

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

Returns the value of an option if present

public function getUserOptions(): array;

Returns the options for the element

public function getValidators(): ValidatorInterface[];

Returns the validators registered for the element

public function getValue(): mixed;

Returns the element's value

public function hasMessages(): bool;

Checks whether there are messages attached to the element

public function label(): string;

Generate the HTML to label the element

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

Renders the element widget

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

Sets a default attribute for the element

public function setAttributes( array $attributes ): ElementInterface;

Sets default attributes for the element

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

public function setFilters( mixed $filters ): ElementInterface;

Sets the element's filters

public function setForm( Form $form ): ElementInterface;

Sets the parent form to the element

public function setLabel( string $label ): ElementInterface;

Sets the element label

public function setMessages( Messages $messages ): ElementInterface;

Sets the validation messages related to the element

public function setName( string $name ): ElementInterface;

Sets the element's name

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

Sets an option for the element

public function setUserOptions( array $options ): ElementInterface;

Sets options for the element

Forms\Element\Email¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=email] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputEmail;

Forms\Element\File¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=file] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputFile;

Forms\Element\Hidden¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=hidden] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputHidden;

Forms\Element\Numeric¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=number] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputNumeric;

Forms\Element\Password¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=password] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputPassword;

Forms\Element\Radio¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=radio] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputRadio;

Forms\Element\RadioGroup¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Html\TagFactory
Extends

AbstractElement
Implements

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

Properties¶

/**
 * @var array
 */
protected $options;

Methods¶

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

Constructor

public function getOptions(): array;

Returns the group options

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

Renders the radio group returning HTML

public function setOptions( array $options ): ElementInterface;

Sets the group options

Forms\Element\Select¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag\Select
Extends

AbstractElement
Implements

Component SELECT (choice) for forms

Properties¶

/**
 * @var object|array|null
 */
protected $optionsValues;

Methods¶

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

Constructor

public function addOption( mixed $option ): ElementInterface;

Adds an option to the current options

public function getOptions();

Returns the choices' options

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

Renders the element widget returning HTML

public function setOptions( mixed $options ): ElementInterface;

Set the choice's options

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¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component INPUT[type=submit] for forms

Properties¶

/**
 * @var string
 */
protected $method = inputSubmit;

Forms\Element\Text¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Forms\Exception
Extends

AbstractElement
Implements

Component INPUT[type=text] for forms

Forms\Element\TextArea¶

Source on GitHub

Namespace
- Phalcon\Forms\Element
Uses
- Phalcon\Tag
Extends

AbstractElement
Implements

Component TEXTAREA for forms

Properties¶

/**
 * @var string
 */
protected $method = inputTextarea;

Forms\Exception¶

Source on GitHub

Namespace
- Phalcon\Forms
Uses
Extends

\Exception
Implements

Exceptions thrown in Phalcon\Forms will use this class

Methods¶

public static function tagFactoryNotFound(): Exception;

public static function usingParameterRequired(): Exception;

Forms\Form¶

Source on GitHub

Namespace
- Phalcon\Forms
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\Html\Attributes
- Phalcon\Html\Attributes\AttributesInterface
- Phalcon\Html\TagFactory
- Phalcon\Messages\Messages
- Phalcon\Support\Settings
- Phalcon\Tag
Extends

Injectable
Implements
- AttributesInterface
- Countable
- Iterator

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

Properties¶

/**
 * @var AttributesInterface|null
 */
protected $attributes;

/**
 * @var array
 */
protected $data;

/**
 * @var array
 */
protected $filteredData;

/**
 * @var array
 */
protected $elements;

/**
 * @var array
 */
protected $elementsIndexed;

/**
 * @var object|null
 */
protected $entity;

/**
 * @var Messages|array|null
 */
protected $messages;

/**
 * @var int
 */
protected $position = ;

/**
 * @var array
 */
protected $options;

/**
 * @var TagFactory|null
 */
protected $tagFactory;

/**
 * @var ValidationInterface|null
 */
protected $validation;

/**
 * @var array
 */
protected $whitelist;

Methods¶

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

Phalcon\Forms\Form constructor

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

Adds an element to the form

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

Binds data to the entity

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

Clears every element in the form to its default value

public function count(): int;

Returns the number of elements in the form

public function current(): mixed;

Returns the current element in the iterator

public function get( string $name ): ElementInterface;

Returns an element added to the form by its name

public function getAction(): string;

Returns the form's action

public function getAttributes(): Attributes;

Get Form attributes collection

public function getElements(): ElementInterface[];

Returns the form elements added to the form

public function getEntity();

Returns the entity related to the model

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

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

public function getLabel( string $name ): string;

Returns a label for an element

public function getMessages(): Messages | array;

Returns the messages generated in the validation.

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

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

public function getMessagesFor( string $name ): Messages;

Returns the messages generated for a specific element

public function getTagFactory(): TagFactory | null;

Returns the tagFactory object

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

Returns the value of an option if present

public function getUserOptions(): array;

Returns the options for the element

public function getValidation(): ValidationInterface | null;

return ValidationInterface|null

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

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

public function getWhitelist(): array;

return array

public function has( string $name ): bool;

Check if the form contains an element

public function hasMessagesFor( string $name ): bool;

Check if messages were generated for a specific element

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

Validates the form

public function key(): int;

Returns the current position/key in the iterator

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

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

public function load( Schema $schema, FormsLocator $locator ): Form;

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

public function next(): void;

Moves the internal iteration pointer to the next position

public function remove( string $name ): bool;

Removes an element from the form

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

Renders a specific item in the form

public function rewind(): void;

Rewinds the internal iterator

public function setAction( string $action ): Form;

Sets the form's action

public function setAttributes( Attributes $attributes ): AttributesInterface;

Set form attributes collection

public function setEntity( mixed $entity ): Form;

Sets the entity related to the model

public function setTagFactory( TagFactory $tagFactory ): Form;

Sets the tagFactory for the form

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

Sets an option for the form

public function setUserOptions( array $options ): Form;

Sets options for the element

public function setValidation( ValidationInterface $validation ): Form;

Sets the default validation

public function setWhitelist( array $whitelist ): Form;

Sets the default whitelist

public function valid(): bool;

Check if the current element in the iterator is valid

Forms\FormsLocator¶

Source on GitHub

Namespace
- Phalcon\Forms
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
Extends
Implements

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

Properties¶

/**
 * Element type → factory callable.
 *
 * @var array
 */
private $elements;

/**
 * Form name → factory callable.
 *
 * @var array
 */
private $factories;

/**
 * Cached entity-less form instances.
 *
 * @var array
 */
private $instances;

Methods¶

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

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.

public function getElement( string $type );

Returns the factory callable for the given element type.

public function has( string $name ): bool;

Checks whether a named form factory is registered.

public function hasElement( string $type ): bool;

Checks whether an element type is registered.

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.

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

Source on GitHub

Namespace
- Phalcon\Forms\Loader
Uses
- Phalcon\Contracts\Forms\Schema
- Phalcon\Forms\Exception
Extends
Implements
- Schema

Supplies form element definitions from a PHP array.

Properties¶

/**
 * @var array
 */
protected $definitions;

Methods¶

public function __construct( array $definitions );

public function load(): array;

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

Forms\Loader\JsonLoader¶

Source on GitHub

Namespace
- Phalcon\Forms\Loader
Uses
- InvalidArgumentException
- Phalcon\Contracts\Forms\Schema
- Phalcon\Forms\Exception
- Phalcon\Support\Helper\Json\Decode
Extends
Implements
- Schema

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.

Properties¶

/**
 * @var string
 */
protected $source;

Methods¶

public function __construct( string $source );

public function load(): array;

protected function phpFileGetContents( string $filename );

Forms\Loader\YamlLoader¶

Source on GitHub

Namespace
- Phalcon\Forms\Loader
Uses
- Phalcon\Contracts\Forms\Schema
- Phalcon\Forms\Exception
Extends
Implements
- Schema

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.

Properties¶

/**
 * @var string
 */
protected $source;

Methods¶

public function __construct( string $source );

public function load(): array;

Forms\Manager¶

Source on GitHub

Namespace
- Phalcon\Forms
Uses
- Phalcon\Contracts\Forms\Schema
- Phalcon\Forms\Form
Extends
Implements

Forms Manager

Properties¶

/**
 * @var array
 */
protected $forms;

/**
 * @var FormsLocator
 */
protected $locator;

Methods¶

public function __construct( FormsLocator $locator = null );

Manager constructor.

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

Creates a form registering it in the forms manager

public function get( string $name ): Form;

Returns a form by its name

public function getLocator(): FormsLocator;

Returns the FormsLocator instance.

public function has( string $name ): bool;

Checks if a form is registered in the forms manager

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.

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

Registers a form in the Forms Manager