Phalcon forms

Forms\Element\AbstractElement¶

Abstract Source on GitHub

This is a base class for form elements

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¶

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¶

Class Source on GitHub

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¶

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

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

Class Source on GitHub

Component INPUT[type=date] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\ElementInterface¶

Interface Source on GitHub

Interface for Phalcon\Forms\Element classes

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

Class Source on GitHub

Component INPUT[type=email] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\File¶

Class Source on GitHub

Component INPUT[type=file] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\Hidden¶

Class Source on GitHub

Component INPUT[type=hidden] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\Numeric¶

Class Source on GitHub

Component INPUT[type=number] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\Password¶

Class Source on GitHub

Component INPUT[type=password] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\Radio¶

Class Source on GitHub

Component INPUT[type=radio] for forms

Uses Phalcon\Tag

Properties¶

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

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

Class Source on GitHub

Component SELECT (choice) for forms

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

Class Source on GitHub

Component INPUT[type=submit] for forms

Uses Phalcon\Tag

Properties¶

Forms\Element\Text¶

Class Source on GitHub

Component INPUT[type=text] for forms

Uses Phalcon\Forms\Exception

Forms\Element\TextArea¶

Class Source on GitHub

Component TEXTAREA for forms

Uses Phalcon\Tag

Properties¶

Forms\Exception¶

Class Source on GitHub

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¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct( string $name );

Forms\Exceptions\FormElementNameRequired¶

Class Source on GitHub

Uses InvalidArgumentException

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Exceptions\FormNotInLocator¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct( string $name );

Forms\Exceptions\FormNotRegistered¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct( string $name );

Forms\Exceptions\InvalidEntity¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Exceptions\InvalidFilterType¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Exceptions\InvalidJsonSchema¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct( string $detail );

Forms\Exceptions\JsonSchemaNotArray¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Exceptions\NoFormElements¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Exceptions\SchemaEntryMissingKey¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

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

Forms\Exceptions\SchemaEntryNotArray¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct( int $index );

Forms\Exceptions\UnknownFormElementType¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct( string $type );

Forms\Exceptions\YamlExtensionRequired¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Exceptions\YamlSchemaNotArray¶

Class Source on GitHub

Uses Phalcon\Forms\Exception

Method Summary¶

Methods¶

__construct()¶

public function __construct();

Forms\Form¶

Class Source on GitHub

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

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¶

Properties¶

Methods¶

__construct()¶

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

Phalcon\Forms\Form constructor

add()¶

public function add(
    ElementInterface $element,
    string $position = null,
    bool $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;

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

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

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¶

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

Class Source on GitHub

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¶

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.

Uses InvalidArgumentException · Phalcon\Contracts\Forms\Schema · Phalcon\Forms\Exception · Phalcon\Forms\Exceptions\InvalidJsonSchema · Phalcon\Forms\Exceptions\JsonSchemaNotArray · Phalcon\Support\Helper\Json\Decode

Method Summary¶

Properties¶

Methods¶

__construct()¶

public function __construct( string $source );

load()¶

public function load(): array;

phpFileGetContents()¶

protected function phpFileGetContents( string $filename );

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.

Uses Phalcon\Contracts\Forms\Schema · Phalcon\Forms\Exception · Phalcon\Forms\Exceptions\YamlExtensionRequired · Phalcon\Forms\Exceptions\YamlSchemaNotArray

Method Summary¶

Properties¶

Methods¶

__construct()¶

public function __construct( string $source );

load()¶

public function load(): array;

Forms\Manager¶

Class Source on GitHub

Forms Manager

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

Method Summary¶

Properties¶

Methods¶

__construct()¶

public function __construct( FormsLocator $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