repo_zf1/documentation/manual/ru/module_specs/Zend_Validate.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.validate.introduction">

    <title>Введение</title>

    <para>
        Компонента <classname>Zend_Validate</classname> предоставляет набор наиболее часто
        используемых валидаторов. Она также предоставляет простой механизм
        формирования цепочки валидаторов, посредством которого к одним и
        тем же данным может быть применено несколько валидаторов в порядке,
        заданном пользователем.
    </para>

    <sect2 id="zend.validate.introduction.definition">
    
        <title>Что такое валидатор?</title>
    
        <para>
            Валидатор проверяет входные данные на предмет соответствия
            требованиям и возвращает результат булевого типа. Если входные
            данные не соответствуют требованиям, то валидатор может
            предоставить информацию о том, какому требованию (требованиям)
            не соответствуют входные данные.
        </para>
    
        <para>
            Например, веб-приложение может требовать, чтобы имя пользователя
            было длиной от 6 до 12 символов и содержало только
            алфавитно-цифровые символы. Для того, чтобы проверить,
            соответствует ли имя пользователя этим требованиям, можно
            использовать валидатор. Если выбранное имя пользователя не
            соответствует одному из требований (или обоим требованиям),
            то будет также полезно знать, каким именно требованиям не
            соответствует имя пользователя.
        </para>
    
    </sect2>

    <sect2 id="zend.validate.introduction.using">

        <title>Базовое использование валидаторов</title>

        <para>
            Такое определение валидации дает основу для
            <classname>Zend_Validate_Interface</classname>, который определяет два
            метода - <code>isValid()</code> и <code>getMessages()</code>.
            Метод <code>isValid()</code> выполняет валидацию переданного
            значения, возвращая <constant>TRUE</constant> тогда и только тогда, когда
            значение прошло проверку по критериям валидации.
        </para>
        
        <para>
            Если <code>isValid()</code> возвращает <constant>FALSE</constant>, то
            <code>getMessages()</code> возвращает массив
            сообщений, поясняющих, по каким причинам валидация не была
            пройдена.
            Ключи массива являются короткими строками, идентифицирующими
            причины, по которым не была пройдена валидация. Значения массива
            являются строками сообщений, понятных человеку.
            Ключи и значения зависят от класса валидатора - каждый класс
            валидатора определяет собственный набор сообщений об ошибке и
            уникальных ключей-идентификаторов.
            Каждый класс также определяет константы, соответствующие
            идентификаторам причин, по которым валидация не была пройдена.
        </para>

        <note>
            <para>
                Метод <code>getMessages()</code> возвращает сообщения ошибок
                валидации только для последнего вызова <code>isValid()</code>.
                Любой вызов метода <code>isValid()</code> стирает все сообщения
                и ошибки с его прошлого вызова, т.к. вероятно,
                что отдельные вызовы <code>isValid()</code> производятся для
                различных входных значений.
            </para>
        </note>

        <para>
            Следующий пример демонстрирует проверку адреса e-mail:
    
            <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    // email прошел валидацию
} else {
    // email не прошел валидацию; вывод причин этого
    foreach ($validator->getMessages() as $messageId => $message) {
        echo "Validation failure '$messageId': $message\n";
    }
}
]]></programlisting>
    
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.messages">

        <title>Установка собственных сообщений от ошибках</title>

        <para>
            Классы валидации предоставляют метод <code>setMessage()</code>,
            с помощью которого вы можете устанавливать формат сообщения,
            возвращаемого методом <code>getMessages()</code> в случае,
            если валидация не была пройдена.
            Первый аргумент этого метода является строкой, содержащей текст
            сообщения об ошибке.
            Вы можете включать в нее маркеры, которые будут замещаться данными,
            относящимися к валидатору.
            Маркер <code>%value%</code> поддерживается всеми валидаторами, он
            заменяется значением, который вы передали методу
            <code>isValid()</code>. Другие маркеры могут поддерживаться не во
            всех валидаторах. Например, <code>%max%</code>
            является маркером, поддерживаемым валидатором
            <classname>Zend_Validate_LessThan</classname>.
            Метод <code>getMessageVariables()</code> возвращает массив маркеров,
            поддерживаемых валидатором.
        </para>

        <para>
            Второй необязательный аргумент является строкой, которую нужно
            установить в качестве идентификатора шаблона сообщения,
            это может быть полезным в том случае, когда класс валидации
            предусматривает несколько причин, по которым валидация может быть не
            пройдена.
            Если вы опустите второй аргумент, то <code>setMessage()</code>
            предполагает, что переданное вами сообщение должно
            использоваться в качестве первого шаблона сообщения, объявленного
            в классе валидации.
            Многие классы валидации имеют только один шаблон
            сообщения об ошибке, поэтому в большинстве случаев нет необходимости
            указывать, какой именно шаблон требуется изменить.
        </para>

        <para>
            <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8);

$validator->setMessage(
    'Строка \'%value%\' слишком короткая. Она должна быть длиной как минимум ' .
    '%min% символов',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator->isValid('слово')) {
    $messages = $validator->getMessages();
    echo current($messages);

    // "Строка 'слово' слишком короткая. Она должна быть длиной как минимум
    // 8 символов"
}
]]></programlisting>
        </para>

        <para>
            Вы можете устанавливать несколько сообщений сразу, используя
            метод <code>setMessages()</code>. Его аргумент является массивом,
            содержащим пары ключ/значение.

            <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);

$validator->setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT =>
        'Строка \'%value%\' слишком короткая',
    Zend_Validate_StringLength::TOO_LONG  =>
        'Строка \'%value%\' слишком длинная'
));
]]></programlisting>

        </para>

        <para>
            Если ваше приложение требует большей гибкости, ...
            то вы можете использовать доступ к свойствам под теми же именами,
            что и метки сообщения, поддерживаемые данным классом валидации.
            Свойство <code>value</code> всегда доступно в валидаторах, это
            значение, которое вы передали в качестве аргумента метода
            <code>isValid()</code>. Другие свойства могут поддерживаться не
            всеми классами валидации.

            <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);

if (!validator->isValid('слово')) {
    echo 'Слово не прошедшее проверку: '
        . $validator->value
        . '; его длина не находится в диапазоне между '
        . $validator->min
        . ' и '
        . $validator->max
        . " символами\n";
}
]]></programlisting>
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.static">

        <title>Использование статического метода is()</title>

        <para>
            Если неудобно каждый раз загружать требуемый класс валидации и
            создавать его экземпляр, то можно использовать статический метод
            <code>Zend_Validate::is()</code> в качестве
            альтернативного способа вызова.
            Первый аргумент этого метода является входным значением,
            которое вы передавали бы методу <code>isValid()</code>.
            Второй аргумент является строкой, которая соответствует базовому
            имени класса валидации относительно пространства имен
            <code>Zend_Validate</code>. Метод <code>is()</code> автоматически
            загружает класс, создает его экземпляр и применяет метод
            <code>isValid()</code> к входным данным.

            <programlisting language="php"><![CDATA[
if (Zend_Validate::is($email, 'EmailAddress')) {
    // Да, похоже, email валиден
}
]]></programlisting>

        </para>

        <para>
            Вы можете также передавать массив аргументов конструктора,
            если они нужны для данного класса валидации.

            <programlisting language="php"><![CDATA[
if (Zend_Validate::is($value, 'Between', array(1, 12))) {
    // Да, $value имеет значение в диапазоне между 1 и 12
}
]]></programlisting>

        </para>

        <para>
            Метод <code>is()</code> возвращает значение булевого типа,
            как и метод <code>isValid()</code>.
            При использовании статического метода <code>is()</code>
            сообщения ошибки валидации не доступны.
        </para>

        <para>
            Вариант со статическим методом может быть удобным при единичном
            вызове валидатора, но если вам нужно применить валидацию
            к нескольким входным значениям, то более эффективным будет
            использование варианта с инстанцированием.
        </para>

        <para>
            Кроме того, класс <classname>Zend_Filter_Input</classname>
            позволяет инстанцировать и запускать более одного класса фильтра и
            валидации для обработки набора входных данных. Читайте
            <xref linkend="zend.filter.input" />.
        </para>

    </sect2>


    <sect2 id="zend.validate.introduction.translation">

        <title>Перевод сообщений</title>

        <para>
            Классы валидации предоставляют метод <code>setTranslator()</code>,
            с помощью которого вы можете устанавливать экземпляр класса
            <classname>Zend_Translate</classname>, который будет переводить
            сообщения в случае ошибки валидации.
            Метод <code>getTranslator()</code> возвращает установленный
            экземпляр переводчика.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);
$translate = new Zend_Translate(
    'array',
    array(Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''),
    'en'
);

$validator->setTranslator($translate);
]]></programlisting>

        <para>
            С помощью статического метода <code>setDefaultTranslator()</code>
            вы можете установить экземпляр
            <classname>Zend_Translate</classname>, который будет использоваться
            во всех классах валидации, и извлекать его с помощью
            <code>getDefaultTranslator()</code>.
            Это избавляет от установки вручную переводчика для всех классов
            валидации и упрощает ваш код.
        </para>

        <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    'array',
    array(Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''),
    'en'
);
Zend_Validate::setDefaultTranslator($translate);
]]></programlisting>

        <note>
            <para>
                Если вы установили глобальную для всего приложения локаль
                через <classname>Zend_Registry</classname>, то эта локаль
                будет использоваться по умолчанию в переводчике.
            </para>
        </note>

        <para>
            Иногда бывает необходимым отключить переводчика в валидаторе.
            Для этого используйте метод <code>setDisableTranslator()</code>,
            который принимает булево значение. Для получения установленного
            значения используйте <code>translatorIsDisabled()</code>.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);
if (!$validator->isTranslatorDisabled()) {
    $validator->setDisableTranslator();
}
]]></programlisting>

        <para>
            Вы можете также использовать переводчика вместо установки
            собственных сообщений через метод <code>setMessage()</code>. Но при
            этом имейте в виду, что переводчик обрабатывает и сообщения, которые
            вы установили самостоятельно.
        </para>

    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->