documentation/manual/ru/module_specs/Zend_Validate.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.validate.introduction">
   4
   5     <title>Введение</title>
   6
   7     <para>
   8         Компонента <classname>Zend_Validate</classname> предоставляет набор наиболее часто
   9         используемых валидаторов. Она также предоставляет простой механизм
  10         формирования цепочки валидаторов, посредством которого к одним и
  11         тем же данным может быть применено несколько валидаторов в порядке,
  12         заданном пользователем.
  13     </para>
  14
  15     <sect2 id="zend.validate.introduction.definition">
  16
  17         <title>Что такое валидатор?</title>
  18
  19         <para>
  20             Валидатор проверяет входные данные на предмет соответствия
  21             требованиям и возвращает результат булевого типа. Если входные
  22             данные не соответствуют требованиям, то валидатор может
  23             предоставить информацию о том, какому требованию (требованиям)
  24             не соответствуют входные данные.
  25         </para>
  26
  27         <para>
  28             Например, веб-приложение может требовать, чтобы имя пользователя
  29             было длиной от 6 до 12 символов и содержало только
  30             алфавитно-цифровые символы. Для того, чтобы проверить,
  31             соответствует ли имя пользователя этим требованиям, можно
  32             использовать валидатор. Если выбранное имя пользователя не
  33             соответствует одному из требований (или обоим требованиям),
  34             то будет также полезно знать, каким именно требованиям не
  35             соответствует имя пользователя.
  36         </para>
  37
  38     </sect2>
  39
  40     <sect2 id="zend.validate.introduction.using">
  41
  42         <title>Базовое использование валидаторов</title>
  43
  44         <para>
  45             Такое определение валидации дает основу для
  46             <classname>Zend_Validate_Interface</classname>, который определяет два
  47             метода - <code>isValid()</code> и <code>getMessages()</code>.
  48             Метод <code>isValid()</code> выполняет валидацию переданного
  49             значения, возвращая <constant>TRUE</constant> тогда и только тогда, когда
  50             значение прошло проверку по критериям валидации.
  51         </para>
  52
  53         <para>
  54             Если <code>isValid()</code> возвращает <constant>FALSE</constant>, то
  55             <code>getMessages()</code> возвращает массив
  56             сообщений, поясняющих, по каким причинам валидация не была
  57             пройдена.
  58             Ключи массива являются короткими строками, идентифицирующими
  59             причины, по которым не была пройдена валидация. Значения массива
  60             являются строками сообщений, понятных человеку.
  61             Ключи и значения зависят от класса валидатора - каждый класс
  62             валидатора определяет собственный набор сообщений об ошибке и
  63             уникальных ключей-идентификаторов.
  64             Каждый класс также определяет константы, соответствующие
  65             идентификаторам причин, по которым валидация не была пройдена.
  66         </para>
  67
  68         <note>
  69             <para>
  70                 Метод <code>getMessages()</code> возвращает сообщения ошибок
  71                 валидации только для последнего вызова <code>isValid()</code>.
  72                 Любой вызов метода <code>isValid()</code> стирает все сообщения
  73                 и ошибки с его прошлого вызова, т.к. вероятно,
  74                 что отдельные вызовы <code>isValid()</code> производятся для
  75                 различных входных значений.
  76             </para>
  77         </note>
  78
  79         <para>
  80             Следующий пример демонстрирует проверку адреса e-mail:
  81
  82             <programlisting language="php"><![CDATA[
  83 $validator = new Zend_Validate_EmailAddress();
  84
  85 if ($validator->isValid($email)) {
  86     // email прошел валидацию
  87 } else {
  88     // email не прошел валидацию; вывод причин этого
  89     foreach ($validator->getMessages() as $messageId => $message) {
  90         echo "Validation failure '$messageId': $message\n";
  91     }
  92 }
  93 ]]></programlisting>
  94
  95         </para>
  96
  97     </sect2>
  98
  99     <sect2 id="zend.validate.introduction.messages">
 100
 101         <title>Установка собственных сообщений от ошибках</title>
 102
 103         <para>
 104             Классы валидации предоставляют метод <code>setMessage()</code>,
 105             с помощью которого вы можете устанавливать формат сообщения,
 106             возвращаемого методом <code>getMessages()</code> в случае,
 107             если валидация не была пройдена.
 108             Первый аргумент этого метода является строкой, содержащей текст
 109             сообщения об ошибке.
 110             Вы можете включать в нее маркеры, которые будут замещаться данными,
 111             относящимися к валидатору.
 112             Маркер <code>%value%</code> поддерживается всеми валидаторами, он
 113             заменяется значением, который вы передали методу
 114             <code>isValid()</code>. Другие маркеры могут поддерживаться не во
 115             всех валидаторах. Например, <code>%max%</code>
 116             является маркером, поддерживаемым валидатором
 117             <classname>Zend_Validate_LessThan</classname>.
 118             Метод <code>getMessageVariables()</code> возвращает массив маркеров,
 119             поддерживаемых валидатором.
 120         </para>
 121
 122         <para>
 123             Второй необязательный аргумент является строкой, которую нужно
 124             установить в качестве идентификатора шаблона сообщения,
 125             это может быть полезным в том случае, когда класс валидации
 126             предусматривает несколько причин, по которым валидация может быть не
 127             пройдена.
 128             Если вы опустите второй аргумент, то <code>setMessage()</code>
 129             предполагает, что переданное вами сообщение должно
 130             использоваться в качестве первого шаблона сообщения, объявленного
 131             в классе валидации.
 132             Многие классы валидации имеют только один шаблон
 133             сообщения об ошибке, поэтому в большинстве случаев нет необходимости
 134             указывать, какой именно шаблон требуется изменить.
 135         </para>
 136
 137         <para>
 138             <programlisting language="php"><![CDATA[
 139 $validator = new Zend_Validate_StringLength(8);
 140
 141 $validator->setMessage(
 142     'Строка \'%value%\' слишком короткая. Она должна быть длиной как минимум ' .
 143     '%min% символов',
 144     Zend_Validate_StringLength::TOO_SHORT);
 145
 146 if (!$validator->isValid('слово')) {
 147     $messages = $validator->getMessages();
 148     echo current($messages);
 149
 150     // "Строка 'слово' слишком короткая. Она должна быть длиной как минимум
 151     // 8 символов"
 152 }
 153 ]]></programlisting>
 154         </para>
 155
 156         <para>
 157             Вы можете устанавливать несколько сообщений сразу, используя
 158             метод <code>setMessages()</code>. Его аргумент является массивом,
 159             содержащим пары ключ/значение.
 160
 161             <programlisting language="php"><![CDATA[
 162 $validator = new Zend_Validate_StringLength(8, 12);
 163
 164 $validator->setMessages( array(
 165     Zend_Validate_StringLength::TOO_SHORT =>
 166         'Строка \'%value%\' слишком короткая',
 167     Zend_Validate_StringLength::TOO_LONG  =>
 168         'Строка \'%value%\' слишком длинная'
 169 ));
 170 ]]></programlisting>
 171
 172         </para>
 173
 174         <para>
 175             Если ваше приложение требует большей гибкости, ...
 176             то вы можете использовать доступ к свойствам под теми же именами,
 177             что и метки сообщения, поддерживаемые данным классом валидации.
 178             Свойство <code>value</code> всегда доступно в валидаторах, это
 179             значение, которое вы передали в качестве аргумента метода
 180             <code>isValid()</code>. Другие свойства могут поддерживаться не
 181             всеми классами валидации.
 182
 183             <programlisting language="php"><![CDATA[
 184 $validator = new Zend_Validate_StringLength(8, 12);
 185
 186 if (!validator->isValid('слово')) {
 187     echo 'Слово не прошедшее проверку: '
 188         . $validator->value
 189         . '; его длина не находится в диапазоне между '
 190         . $validator->min
 191         . ' и '
 192         . $validator->max
 193         . " символами\n";
 194 }
 195 ]]></programlisting>
 196         </para>
 197
 198     </sect2>
 199
 200     <sect2 id="zend.validate.introduction.static">
 201
 202         <title>Использование статического метода is()</title>
 203
 204         <para>
 205             Если неудобно каждый раз загружать требуемый класс валидации и
 206             создавать его экземпляр, то можно использовать статический метод
 207             <code>Zend_Validate::is()</code> в качестве
 208             альтернативного способа вызова.
 209             Первый аргумент этого метода является входным значением,
 210             которое вы передавали бы методу <code>isValid()</code>.
 211             Второй аргумент является строкой, которая соответствует базовому
 212             имени класса валидации относительно пространства имен
 213             <code>Zend_Validate</code>. Метод <code>is()</code> автоматически
 214             загружает класс, создает его экземпляр и применяет метод
 215             <code>isValid()</code> к входным данным.
 216
 217             <programlisting language="php"><![CDATA[
 218 if (Zend_Validate::is($email, 'EmailAddress')) {
 219     // Да, похоже, email валиден
 220 }
 221 ]]></programlisting>
 222
 223         </para>
 224
 225         <para>
 226             Вы можете также передавать массив аргументов конструктора,
 227             если они нужны для данного класса валидации.
 228
 229             <programlisting language="php"><![CDATA[
 230 if (Zend_Validate::is($value, 'Between', array(1, 12))) {
 231     // Да, $value имеет значение в диапазоне между 1 и 12
 232 }
 233 ]]></programlisting>
 234
 235         </para>
 236
 237         <para>
 238             Метод <code>is()</code> возвращает значение булевого типа,
 239             как и метод <code>isValid()</code>.
 240             При использовании статического метода <code>is()</code>
 241             сообщения ошибки валидации не доступны.
 242         </para>
 243
 244         <para>
 245             Вариант со статическим методом может быть удобным при единичном
 246             вызове валидатора, но если вам нужно применить валидацию
 247             к нескольким входным значениям, то более эффективным будет
 248             использование варианта с инстанцированием.
 249         </para>
 250
 251         <para>
 252             Кроме того, класс <classname>Zend_Filter_Input</classname>
 253             позволяет инстанцировать и запускать более одного класса фильтра и
 254             валидации для обработки набора входных данных. Читайте
 255             <xref linkend="zend.filter.input" />.
 256         </para>
 257
 258     </sect2>
 259
 260
 261     <sect2 id="zend.validate.introduction.translation">
 262
 263         <title>Перевод сообщений</title>
 264
 265         <para>
 266             Классы валидации предоставляют метод <code>setTranslator()</code>,
 267             с помощью которого вы можете устанавливать экземпляр класса
 268             <classname>Zend_Translate</classname>, который будет переводить
 269             сообщения в случае ошибки валидации.
 270             Метод <code>getTranslator()</code> возвращает установленный
 271             экземпляр переводчика.
 272         </para>
 273
 274         <programlisting language="php"><![CDATA[
 275 $validator = new Zend_Validate_StringLength(8, 12);
 276 $translate = new Zend_Translate(
 277     'array',
 278     array(Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''),
 279     'en'
 280 );
 281
 282 $validator->setTranslator($translate);
 283 ]]></programlisting>
 284
 285         <para>
 286             С помощью статического метода <code>setDefaultTranslator()</code>
 287             вы можете установить экземпляр
 288             <classname>Zend_Translate</classname>, который будет использоваться
 289             во всех классах валидации, и извлекать его с помощью
 290             <code>getDefaultTranslator()</code>.
 291             Это избавляет от установки вручную переводчика для всех классов
 292             валидации и упрощает ваш код.
 293         </para>
 294
 295         <programlisting language="php"><![CDATA[
 296 $translate = new Zend_Translate(
 297     'array',
 298     array(Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''),
 299     'en'
 300 );
 301 Zend_Validate::setDefaultTranslator($translate);
 302 ]]></programlisting>
 303
 304         <note>
 305             <para>
 306                 Если вы установили глобальную для всего приложения локаль
 307                 через <classname>Zend_Registry</classname>, то эта локаль
 308                 будет использоваться по умолчанию в переводчике.
 309             </para>
 310         </note>
 311
 312         <para>
 313             Иногда бывает необходимым отключить переводчика в валидаторе.
 314             Для этого используйте метод <code>setDisableTranslator()</code>,
 315             который принимает булево значение. Для получения установленного
 316             значения используйте <code>translatorIsDisabled()</code>.
 317         </para>
 318
 319         <programlisting language="php"><![CDATA[
 320 $validator = new Zend_Validate_StringLength(8, 12);
 321 if (!$validator->isTranslatorDisabled()) {
 322     $validator->setDisableTranslator();
 323 }
 324 ]]></programlisting>
 325
 326         <para>
 327             Вы можете также использовать переводчика вместо установки
 328             собственных сообщений через метод <code>setMessage()</code>. Но при
 329             этом имейте в виду, что переводчик обрабатывает и сообщения, которые
 330             вы установили самостоятельно.
 331         </para>
 332
 333     </sect2>
 334 </sect1>
 335 <!--
 336 vim:se ts=4 sw=4 et:
 337 -->