documentation/manual/pl/module_specs/Zend_Validate.xml

   1 <sect1 id="zend.validate.introduction">
   2
   3     <title>Wprowadzenie</title>
   4
   5     <para>
   6         Komponent Zend_Validate zapewnia zestaw najczęściej potrzebnych
   7         weryfikatorów. Zapewnia też prosty mechanizm łańcuchowego wywoływania
   8         weryfikatorów, dzięki ktoremu wiele filtrów może być dodanych do jednej
   9         danej w kolejności zdefiniowanej przez programistę.
  10     </para>
  11
  12     <sect2 id="zend.validate.introduction.definition">
  13
  14         <title>Czym jest weryfikator?</title>
  15
  16         <para>
  17             Weryfikator bada dane wejściowe w oparciu o pewne wymagania i tworzy
  18             wynik w postaci wartości logicznej - wartość ta mówi czy dane
  19             wejściowe spełniają te wymagania. Jeśli dane wejściowe nie spełniają
  20             wymagań, weryfikator może dodatkowo przekazać informacje o tym, które
  21             z wymagań nie zostały spełnione.
  22         </para>
  23
  24         <para>
  25             Na przykład, aplikacja web może wymagać, aby długość nazwy użytkownika
  26             mieściła się pomiędzy sześcioma a dwunastoma znakami, a znaki te były
  27             jedynie z grupy znaków alfanumerycznych. Weryfikator może być użyty do
  28             sprawdzenia czy nazwa użytkownika spełnia te wymagania. Jeśli wybrana
  29             nazwa użytkownika nie spełni jednego lub obu tych wymagań, użytecznie
  30             by było wiedzieć, które z wymagań nie zostało spełnione.
  31         </para>
  32
  33     </sect2>
  34
  35     <sect2 id="zend.validate.introduction.using">
  36
  37         <title>Podstawowe użycie weryfikatorów</title>
  38
  39         <para>
  40             Mająć ustaloną w ten sposób definicję weryfikacji, możemy zapewnić
  41             podstawę dla interfejsu <code>Zend_Validate_Interface</code>, który
  42             wymaga zaimplementowania przez klasę weryfikatora dwóch metod,
  43             <code>isValid()</code> oraz <code>getMessages()</code>. Metoda
  44             <code>isValid()</code> przeprowadza weryfikację podanej wartości,
  45             zwracając <code>true</code> wtedy i tylko wtedy, gdy wartość
  46             spełnia kryteria weryfikacji.
  47         </para>
  48
  49         <para>
  50             Jeśli metoda <code>isValid()</code> zwróci <code>false</code>, za
  51             pomocą metody <code>getMessages()</code> można pobrać tablicę
  52             wiadomości wyjaśniających powody niepowodzenia weryfikacji.
  53             Klucze elementów tablicy są krótkimi łańcuchami znaków, które
  54             identyfikują powody nieudanej weryfikacji, a wartości elementów
  55             odpowiadają pełnym treściom komunikatów. Klucze i wartości są
  56             zależne od klasy; każda klasa weryfikatora definiuje własny zestaw
  57             komunikatów o nieudanej weryfikacji, a także klucze identyfikujące je.
  58             Każda klasa posiada także definicje stałych <code>const</code>, które
  59             odpowiadają identyfikatorom komunikatów o nieudanej weryfikacji.
  60         </para>
  61
  62         <note>
  63             <para>
  64                 Metoda <code>getMessages()</code>
  65                 zwracaja informacje o nieudanej weryfikacji tylko dla ostatniego
  66                 wywołania metody <code>isValid()</code>. Każde wywołanie metody
  67                 <code>isValid()</code> czyści wszystkie komunikaty i błędy,
  68                 które wystąpiły podczas poprzedniego wywołania metody
  69                 <code>isValid()</code>, ponieważ najczęściej jest tak, że każde
  70                 wywołanie metody <code>isValid()</code> występuje dla innej
  71                 wartości danych przychodzących.
  72             </para>
  73         </note>
  74
  75         <para>
  76             Poniższy przykład pokazuje weryfikację adresu e-mail:
  77
  78             <programlisting role="php"><![CDATA[
  79 $validator = new Zend_Validate_EmailAddress();
  80
  81 if ($validator->isValid($email)) {
  82     // adres email jest prawidłowy
  83 } else {
  84     // adres email jest nieprawidłowy; wyświetlamy komunikat
  85     foreach ($validator->getMessages() as $messageId => $message) {
  86         echo "Weryfikacja nieudana '$messageId': $message\n";
  87     }
  88 }
  89 ]]>
  90             </programlisting>
  91
  92         </para>
  93
  94     </sect2>
  95
  96     <sect2 id="zend.validate.introduction.messages">
  97
  98         <title>Własne komunikaty</title>
  99
 100         <para>
 101             Klasy weryfikatorów zapewniają metodę <code>setMessage()</code> za
 102             pomocą które możesz określić format komunikatu zwracanego przez
 103             metodę <code>getMessages()</code> w przypadku nieudanej weryfikacji.
 104             Pierwszy argument tej metody jest łańcuchem znaków zawierającym
 105             treść komunikatu błędu. W tym łańcuchu znaków możesz użyć
 106             identyfikatorów, które zostaną zastąpione odpowiednimi danymi
 107             pochodzącymi z weryfikatora. Identyfikator <code>%value%</code> jest
 108             obsługiwany przez wszystkie weryfikatory; będzie on zastąpiony
 109             wartością, która została przekazana do metody <code>isValid()</code>.
 110             Inne identyfikatory mogą być obsługiwane indywidualnie w każdej
 111             klasie weryfikatora. Na przykład identyfikator <code>%max%</code> jest
 112             obsługiwany przez klasę <code>Zend_Validate_LessThan</code>.
 113             Metoda <code>getMessageVariables()</code> zwraca tablicę
 114             identyfikatorów obsługiwanych przez weryfikator.
 115         </para>
 116
 117         <para>
 118             Drugi opcjonalny argument jest łańcuchem znaków, który identyfikuje
 119             szablon komunikatu który chcesz ustawić, co jest przydatne gdy
 120             klasa definiuje więcej niż jeden komunikatów o błędach.
 121             Jeśli pominiesz drugi argument, metoda <code>setMessage()</code>
 122             założy, że komunikat, który określisz powinien być użyty dla
 123             pierwszego szablonu komunikatu zadeklarowanego w klasie weryfikatora.
 124             Wiele klas weryfikatorów posiada tylko jeden szablon komunikatu błędu,
 125             więc nie ma potrzeby dokładnego określania szablonu komunikatu, który
 126             chcesz nadpisać.
 127         </para>
 128
 129         <para>
 130             <programlisting role="php"><![CDATA[
 131 $validator = new Zend_Validate_StringLength(8);
 132
 133 $validator->setMessage(
 134     'Łańcuch znaków \'%value%\' jest za krotki; ' .
 135     'musi składać się z przynajmniej %min% znaków',
 136     Zend_Validate_StringLength::TOO_SHORT);
 137
 138 if (!$validator->isValid('word')) {
 139     $messages = $validator->getMessages();
 140     echo current($messages);
 141
 142     // "Łańcuch znaków 'word' jest za krotki;
 143     // musi składać się z przynajmniej 8 znaków"
 144 }
 145 ]]>
 146             </programlisting>
 147         </para>
 148
 149         <para>
 150             Możesz ustawić wiele komunikatów na raz używając metody
 151             <code>setMessages()</code>. Jej argumentem jest tablica zawierająca
 152             pary klucz/komunikat.
 153
 154             <programlisting role="php"><![CDATA[
 155 $validator = new Zend_Validate_StringLength(8, 12);
 156
 157 $validator->setMessages( array(
 158     Zend_Validate_StringLength::TOO_SHORT =>
 159         'Łańcuch znaków \'%value%\' jest za krótki',
 160     Zend_Validate_StringLength::TOO_LONG  =>
 161         'Łańcuch znaków \'%value%\' jest za długi'
 162 ));
 163 ]]>
 164             </programlisting>
 165
 166         </para>
 167
 168         <para>
 169             Jeśli twoja aplikacja wymaga większej elastyczności w związku z
 170             raportowaniem nieudanej weryfikacji, możesz uzyskać dostęp do
 171             właściwości używając tych samych nazw, co identyfikatory komunikatów
 172             używane przez daną klasę weryfikatora. Właściwość <code>value</code>
 173             jest zawsze dostępna w weryfikatorze; jest to wartość, która została
 174             podana jako argument metody <code>isValid()</code>. Inne właściwości
 175             mogą być obsługiwane indywidualnie w każdej klasie weryfikatora.
 176
 177             <programlisting role="php"><![CDATA[
 178 $validator = new Zend_Validate_StringLength(8, 12);
 179
 180 if (!validator->isValid('word')) {
 181     echo 'Słowo niepoprawne: '
 182         . $validator->value
 183         . '; długość nie jest pomiędzy '
 184         . $validator->min
 185         . ' i '
 186         . $validator->max
 187         . "\n";
 188 }
 189 ]]>
 190             </programlisting>
 191         </para>
 192
 193     </sect2>
 194
 195     <sect2 id="zend.validate.introduction.static">
 196
 197         <title>Użycie statycznej metody <code>is()</code></title>
 198
 199         <para>
 200             Jeśli niewygodne jest ładowanie danej klasy weryfikatora i tworzenie
 201             instancji weryfikatora, możesz użyć statycznej metody
 202             <code>Zend_Validate::is()</code> jako alternatywnego sposobu
 203             wywołania. Pierwszym argumentem tej metody są dane wejściowe, które
 204             chcesz przekazać do metody <code>isValid()</code>. Drugi argument
 205             jest łańcuchem znaków, który odpowiada, bazowej nazwie klasy
 206             weryfikatora, relatywnie do przestrzeni nazw <code>Zend_Validate</code>.
 207             Metoda <code>is()</code> automatycznie ładuje klasę, tworzy instancję
 208             i wywołuje metodę <code>isValid()</code> na danych wejściowych.
 209
 210             <programlisting role="php"><![CDATA[
 211 if (Zend_Validate::is($email, 'EmailAddress')) {
 212     // Tak, adres email jest poprawny
 213 }
 214 ]]>
 215             </programlisting>
 216
 217         </para>
 218
 219         <para>
 220             Możesz także przekazać tablicę argumentów konstruktora, jeśli są
 221             one potrzebne w klasie weryfikatora.
 222
 223             <programlisting role="php"><![CDATA[
 224 if (Zend_Validate::is($value, 'Between', array(1, 12))) {
 225     // Tak, wartość $value jest pomiędzy 1 i 12
 226 }
 227 ]]>
 228             </programlisting>
 229
 230         </para>
 231
 232         <para>
 233             Metoda <code>is()</code> zwraca wartość logiczną, taką samą jak
 234             metoda <code>isValid()</code>. Gdy używana jest metoda statyczna
 235             <code>is()</code>, komunikaty o nieudanej weryfikacji są niedostępne.
 236         </para>
 237
 238         <para>
 239             Użycie statyczne może być wygodne dla jednorazowego wywołania
 240             weryfikatora, ale jeśli musisz wywołać weryfikator dla większej ilości
 241             danych, bardziej efektywne jest wykorzystanie rozwiązania
 242             niestatycznego, czyli utworzenie instancji obiektu weryfikatora
 243             i wywołanie metody <code>isValid()</code>.
 244         </para>
 245
 246         <para>
 247             Dodatkowo klasa <code>Zend_Filter_Input</code> pozwala na utworzenie
 248             instancji i wywołanie większej ilości klas filtrów i weryfikatorów w
 249             celu przetworzenia zestawu danych wejściowych. Zobacz
 250             <xref linkend="zend.filter.input" />.
 251         </para>
 252
 253     </sect2>
 254
 255 </sect1>