Формы

Phalcon\Forms — это компонент, помогающий разработчику создавать и поддерживать формы в веб-приложениях.

Следующий пример демонстрирует его базовое использование:

use Phalcon\Forms\Form,
    Phalcon\Forms\Element\Text,
    Phalcon\Forms\Element\Select;

$form = new Form();

$form->add(new Text("name"));

$form->add(new Text("telephone"));

$form->add(new Select("telephoneType", array(
    'H' => 'Home',
    'C' => 'Cell'
)));

Формы могут быть отображены на основе определения формы:

<h1>Contacts</h1>

<form method="post">

    <p>
        <label>Name</label>
        <?php echo $form->render("name") ?>
    </p>

    <p>
        <label>Telephone</label>
        <?php echo $form->render("telephone") ?>
    </p>

    <p>
        <label>Type</label>
        <?php echo $form->render("telephoneType") ?>
    </p>

    <p>
        <input type="submit" value="Save" />
    </p>

</form>

Каждый элемент формы может быть отображён в соответствии с требованиями разработчика. Внутренне, для создания правильного HTML для каждого элемента используется Phalcon\Tag. Дополнительные атрибуты HTML можно передать как второй параметр для render:

<p>
    <label>Name</label>
    <?php echo $form->render("name", array('maxlength' => 30, 'placeholder' => 'Type your name')) ?>
</p>

Атрибуты HTML также могут быть установлены в определении элемента:

$form->add(new Text("name", array(
    'maxlength' => 30,
    'placeholder' => 'Type your name'
)));

Инициализация форм

Как видно ранее, формы можно инициализировать вне класса формы, добавляя элементы в него. Вы можете повторно использовать код или организовать свои классы форм, реализуя форму в отдельном файле:

use Phalcon\Forms\Form,
    Phalcon\Forms\Element\Text,
    Phalcon\Forms\Element\Select;

class ContactForm extends Form
{
    public function initialize()
    {
        $this->add(new Text("name"));

        $this->add(new Text("telephone"));

        $this->add(new Select("telephoneType", TelephoneTypes::find(), array(
            'using' => array('id', 'name')
        )));
    }
}

Phalcon\Forms\Form расширяет Phalcon\DI\Injectable, поэтому у вас есть доступ к службам приложения, если это необходимо:

use Phalcon\Forms\Form,
    Phalcon\Forms\Element\Text,
    Phalcon\Forms\Element\Hidden;

class ContactForm extends Form
{

    /**
     * This method returns the default value for field 'csrf'
     */
    public function getCsrf()
    {
        return $this->security->getToken();
    }

    public function initialize()
    {

        //Set the same form as entity
        $this->setEntity($this);

        //Add a text element to capture the 'email'
        $this->add(new Text("email"));

        //Add a text element to put a hidden csrf
        $this->add(new Hidden("csrf"));
    }
}

Связанная сущность, добавленная в форму при инициализации, и пользовательские опции передаются в конструктор формы:

use Phalcon\Forms\Form,
    Phalcon\Forms\Element\Text,
    Phalcon\Forms\Element\Hidden;

class UsersForm extends Form
{
    /**
     * Forms initializer
     *
     * @param Users $user
     * @param array $options
     */
    public function initialize($user, $options)
    {

        if ($options['edit']) {
            $this->add(new Hidden('id'));
        } else {
            $this->add(new Text('id'));
        }

        $this->add(new Text('name'));
    }
}

При создании экземпляра формы необходимо использовать:

$form = new UsersForm(new Users(), array('edit' => true));

Валидация

Формы Phalcon интегрированы с компонентом валидации, чтобы обеспечить мгновенную валидацию. Встроенные или пользовательские валидаторы могут быть установлены для каждого элемента:

use Phalcon\Forms\Element\Text,
    Phalcon\Validation\Validator\PresenceOf,
    Phalcon\Validation\Validator\StringLength;

$name = new Text("name");

$name->addValidator(new PresenceOf(array(
    'message' => 'The name is required'
)));

$name->addValidator(new StringLength(array(
    'min' => 10,
    'messageMinimum' => 'The name is too short'
)));

$form->add($name);

Затем вы можете валидировать форму в соответствии с введенными пользователем данными:

if (!$form->isValid($_POST)) {
    foreach ($form->getMessages() as $message) {
        echo $message, '<br>';
    }
}

Валидаторы выполняются в том же порядке, в котором они были зарегистрированы.

По умолчанию сообщения, сгенерированные всеми элементами формы, объединяются, поэтому их можно пройти, используя один цикл foreach. Вы можете изменить это поведение, чтобы получить сообщения, разделенные по полю:

foreach ($form->getMessages(false) as $attribute => $messages) {
    echo 'Messages generated by ', $attribute, ':', "\n";
    foreach ($messages as $message) {
        echo $message, '<br>';
    }
}

Или получить конкретные сообщения для элемента:

foreach ($form->getMessagesFor('name') as $message) {
    echo $message, '<br>';
}

Фильтрование

Форма также может фильтровать данные перед валидацией. Фильтры можно установить для каждого элемента:

Установка пользовательских опций

Формы + Сущности

Сущность, такая как модель/коллекция/простой экземпляр или просто обычный класс PHP, может быть связана с формой, чтобы установить значения по умолчанию в элементах формы или легко назначить значения из формы сущности:

$robot = Robots::findFirst();

$form = new Form($robot);

$form->add(new Text("name"));

$form->add(new Text("year"));

После отображения формы, если элементам не назначены значения по умолчанию, будут использованы значения, предоставленные сущностью:

<?php echo $form->render('name') ?>

Вы можете валидировать форму и назначить значения из пользовательского ввода следующим образом:

$form->bind($_POST, $robot);

//Check if the form is valid
if ($form->isValid()) {

    //Save the entity
    $robot->save();
}

Также возможно установить обычный класс в качестве сущности:

class Preferences
{

    public $timezone = 'Europe/Amsterdam';

    public $receiveEmails = 'No';

}

Использование этого класса в качестве сущности позволяет форме принимать значения по умолчанию из него:

$form = new Form(new Preferences());

$form->add(new Select("timezone", array(
    'America/New_York' => 'New York',
    'Europe/Amsterdam' => 'Amsterdam',
    'America/Sao_Paulo' => 'Sao Paulo',
    'Asia/Tokyo' => 'Tokyo',
)));

$form->add(new Select("receiveEmails", array(
    'Yes' => 'Yes, please!',
    'No' => 'No, thanks'
)));

Сущности могут реализовывать методы-геттеры, которые имеют больший приоритет, чем публичные свойства. Эти методы дают вам большую свободу в создании значений:

class Preferences
{

    public $timezone;

    public $receiveEmails;

    public function getTimezone()
    {
        return 'Europe/Amsterdam';
    }

    public function getTimezone()
    {
        return 'No';
    }

}

Элементы форм

Phalcon предоставляет набор встроенных элементов для использования в формах. Все эти элементы находятся в пространстве имен Phalcon\Forms\Element:

Обработчики событий

В случае реализации форм в виде классов, можно реализовать обработчики: beforeValidation и afterValidation в классе формы для выполнения предобработки и послеобработки валидации:

class ContactForm extends Phalcon\Mvc\Form
{
    public function beforeValidation()
    {

    }
}

Отображение форм

Вы можете отобразить форму с полной гибкостью. Следующий пример демонстрирует, как отобразить каждый элемент, используя стандартную процедуру:

<?php

<form method="post">
    <?php
        //Traverse the form
        foreach ($form as $element) {

            //Get any generated messages for the current element
            $messages = $form->getMessagesFor($element->getName());

            if (count($messages)) {
                //Print each element
                echo '<div class="messages">';
                foreach ($messages as $message) {
                    echo $message;
                }
                echo '</div>';
            }

            echo '<p>';
            echo '<label for="', $element->getName(), '">', $element->getLabel(), '</label>';
            echo $element;
            echo '</p>';

        }
    ?>
    <input type="submit" value="Send"/>
</form>

Или повторно использовать логику в вашем классе формы:

class ContactForm extends Phalcon\Forms\Form
{
    public function initialize()
    {
        //...
    }

    public function renderDecorated($name)
    {
        $element = $this->get($name);

        //Get any generated messages for the current element
        $messages = $this->getMessagesFor($element->getName());

        if (count($messages)) {
            //Print each element
            echo '<div class="messages">';
            foreach ($messages as $message) {
                echo $this->flash->error($message);
            }
            echo '</div>';
        }

        echo '<p>';
        echo '<label for="', $element->getName(), '">', $element->getLabel(), '</label>';
        echo $element;
        echo '</p>';
    }

}

В представлении:

echo $element->renderDecorated('name');

echo $element->renderDecorated('telephone');

Создание элементов формы

В дополнение к элементам формы, предоставляемым Phalcon, вы можете создавать свои собственные пользовательские элементы:

use Phalcon\Forms\Element;

class MyElement extends Element
{
    public function render($attributes=null)
    {
        $html = //... produce some html
        return $html;
    }
}

Менеджер форм

Этот компонент предоставляет менеджер форм, который может использоваться разработчиком для регистрации форм и доступа к ним через локатор сервисов:

$di['forms'] = function() {
    return new Phalcon\Forms\Manager();
};

Формы добавляются в менеджер форм и ссылаются на них с помощью уникального имени:

$this->forms->set('login', new LoginForm());

Используя уникальное имя, формы можно получить в любой части приложения:

echo $this->forms->get('login')->render();

Внешние ресурсы

• Vökuró, это пример приложения, использующего конструктор форм для создания и управления формами, [Github]