Формы

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

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

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

$form = new Form();

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

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

$form->add(
    new Select(
        "telephoneType",
        [
            "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>

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

<p>
    <label>
        Name
    </label>

    <?php echo $form->render("name", ["maxlength" => 30, "placeholder" => "Type your name"]); ?>
</p>

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

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

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

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

use Phalcon\Forms\Form;
use Phalcon\Forms\Element\Text;
use 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(),
                [
                    "using" => [
                        "id",
                        "name",
                    ]
                ]
            )
        );
    }
}

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

use Phalcon\Forms\Form;
use Phalcon\Forms\Element\Text;
use 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;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Element\Hidden;

class UsersForm extends Form
{
    /**
     * Forms initializer
     *
     * @param Users $user
     * @param array $options
     */
    public function initialize(Users $user, array $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(),
    [
        "edit" => true,
    ]
);

Валидация

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

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

$name = new Text(
    "name"
);

$name->addValidator(
    new PresenceOf(
        [
            "message" => "The name is required",
        ]
    )
);

$name->addValidator(
    new StringLength(
        [
            "min"            => 10,
            "messageMinimum" => "The name is too short",
        ]
    )
);

$form->add($name);

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

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

    foreach ($messages 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>";
    }
}

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

$messages = $form->getMessagesFor("name");

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

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

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

use Phalcon\Forms\Element\Text;

$name = new Text(
    "name"
);

// Set multiple filters
$name->setFilters(
    [
        "string",
        "trim",
    ]
);

$form->add($name);



$email = new Text(
    "email"
);

// Set one filter
$email->setFilters(
    "email"
);

$form->add($email);

Узнайте больше о фильтрации в Phalcon, прочитав документацию по фильтрам.

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

Сущность, такая как модель/коллекция/простой экземпляр или просто обычный класс 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",
        [
            "America/New_York"  => "New York",
            "Europe/Amsterdam"  => "Amsterdam",
            "America/Sao_Paulo" => "Sao Paulo",
            "Asia/Tokyo"        => "Tokyo",
        ]
    )
);

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

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

class Preferences
{
    public $timezone;

    public $receiveEmails;



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

    public function getReceiveEmails()
    {
        return "No";
    }
}

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

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

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

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

use Phalcon\Forms\Form;

class ContactForm extends 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>

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

use Phalcon\Forms\Form;

class ContactForm extends 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;
    }
}

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

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

use Phalcon\Forms\Manager as FormsManager;

$di["forms"] = function () {
    return new FormsManager();
};

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

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

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

$loginForm = $this->forms->get("login");

echo $loginForm->render();

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

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