documentation/manual/pl/module_specs/Zend_Service_Akismet.xml

   1 <sect1 id="zend.service.akismet">
   2     <title>Zend_Service_Akismet</title>
   3
   4     <sect2 id="zend.service.akismet.introduction">
   5         <title>Wprowadzenie</title>
   6
   7         <para>
   8             Komponent <code>Zend_Service_Akismet</code> jest klientem dla <ulink
   9                 url="http://akismet.com/development/api/">API serwisu Akismet</ulink>.
  10             Serwis Akismet jest używany do określenia czy nadesłane dane są
  11             potencjalnym spamem; udostępnia on także metody do nadsyłania danych,
  12             które uznamy za spam, oraz danych, które niesłusznie zostały uznane
  13             za spam (czyli ham). Pierwotnie serwis Akismet służył do kategoryzowania
  14             i identyfikowania spamu dla aplikacji Wordpress, ale obecnie może być
  15             użyty do dowolnych danych.
  16         </para>
  17
  18         <para>
  19             Do użycia serwisu Akismet wymagane jest posiadanie klucza API. Możesz
  20             go otrzymać rejestrując konto w serwisie
  21             <ulink url="http://wordpress.com/">WordPress.com</ulink>. Nie musisz
  22             aktywować bloga; samo założenie konta umożliwi ci otrzymanie klucza
  23             API.
  24         </para>
  25
  26         <para>
  27             Dodatkowo Akismet wymaga aby wszystkie żądania zawierały adres URL
  28             do zasobu, dla którego dane są filtrowane, i z tego względu, że
  29             Akismet pochodzi z WordPress, ten zasób nazywany jest adresem bloga
  30             (blog url). Ta wartość powinna być przekazana jako drugi argument do
  31             konstruktora, ale może być zresetowana w dowolnej chwili za pomocą
  32             metody dostępowej <code>setBlogUrl()</code> lub nadpisana przez
  33             określenie klucza 'blog' w różnych wywołaniach metod.
  34         </para>
  35     </sect2>
  36
  37     <sect2 id="zend.service.akismet.verifykey">
  38         <title>Weryfikowanie klucza API</title>
  39
  40         <para>
  41             Metoda <code>Zend_Service_Akismet::verifyKey($key)</code> jest
  42             używana do weryfikowania poprawności klucza API Akismet.
  43             W większości przypadków nie musisz tego sprawdzać, ale jeśli chcesz
  44             przeprowadzić test dla pewności lub sprawdzić czy otrzymany klucz
  45             jest aktywny, możesz to zrobić za pomocą tej metody.
  46         </para>
  47
  48         <programlisting role="php"><![CDATA[
  49 // Tworzymy instancję podając klucz API
  50 // i adres URL używanej aplikacji
  51 $akismet = new Zend_Service_Akismet($apiKey,
  52                                     'http://framework.zend.com/wiki/');
  53 if ($akismet->verifyKey($apiKey) {
  54     echo "Key is valid.\n";
  55 } else {
  56     echo "Key is not valid\n";
  57 }
  58 ]]>
  59         </programlisting>
  60
  61         <para>
  62             Jeśli metoda <code>verifyKey()</code> jest wywołana bez żadnych
  63             argumentów, to używany jest klucz API, który był podany do
  64             konstruktora.
  65         </para>
  66
  67         <para>
  68             Metoda <code>verifyKey()</code> implementuje metodę REST
  69             <code>verify-key</code> serwisu Akismet.
  70         </para>
  71     </sect2>
  72
  73     <sect2 id="zend.service.akismet.isspam">
  74         <title>Sprawdzanie czy dane są spamem</title>
  75
  76         <para>
  77             Metoda <code>Zend_Service_Akismet::isSpam($data)</code> jest używana
  78             do sprawdzenia, czy przekazane dane są uznane przez Akismet jako
  79             spam. Metoda przyjmuje tablicę asocjacyjną jako jedyny argument.
  80             Tablica ta wymaga zdefiniowania poniższych kluczy:
  81         </para>
  82
  83         <itemizedlist>
  84             <listitem>
  85                 <para>
  86                     <code>user_ip</code>, adres IP użytkownika wysyłającego
  87                     dane (nie twój adres IP, tylko użytkownika twojego serwisu)
  88                 </para>
  89             </listitem>
  90
  91             <listitem>
  92                 <para>
  93                     <code>user_agent</code>, nazwa klienta HTTP (przeglądarka
  94                     oraz wersja) użytkownika wysyłającego dane.
  95                 </para>
  96             </listitem>
  97         </itemizedlist>
  98
  99         <para>
 100             Poniższe klucze są także rozpoznawane przez API:
 101         </para>
 102
 103         <itemizedlist>
 104             <listitem>
 105                 <para>
 106                     <code>blog</code>, pełny adres URL do zasobu lub aplikacji.
 107                     Jeśli nie jest określony, zostanie użyty adres URL, który
 108                     był podany do konstruktora.
 109                 </para>
 110             </listitem>
 111
 112             <listitem>
 113                 <para>
 114                     <code>referrer</code>, zawartość nagłówka HTTP_REFERER w
 115                     trakcie wysyłania danych. (Zwróć uwagę na pisownię; nie jest
 116                     ona taka sama jak nazwa nagłówka.)
 117                 </para>
 118             </listitem>
 119
 120             <listitem>
 121                 <para>
 122                     <code>permalink</code>, bezpośredni odnośnik do wpisu, dla
 123                     którego dane są przesyłane.
 124                 </para>
 125             </listitem>
 126
 127             <listitem>
 128                 <para>
 129                     <code>comment_type</code>, typ przesyłanych danych.
 130                     Możliwe wartości określone w API to 'comment', 'trackback',
 131                     'pingback', oraz pusty łańcuch znaków (''), ale wartość
 132                     może być dowolna.
 133                 </para>
 134             </listitem>
 135
 136             <listitem>
 137                 <para>
 138                     <code>comment_author</code>, nazwa osoby dodającej dane.
 139                 </para>
 140             </listitem>
 141
 142             <listitem>
 143                 <para>
 144                     <code>comment_author_email</code>, adres email osoby
 145                     dodającej dane.
 146                 </para>
 147             </listitem>
 148
 149             <listitem>
 150                 <para>
 151                     <code>comment_author_url</code>, adres URL lub strona
 152                     domowa osoby dodającej dane.
 153                 </para>
 154             </listitem>
 155
 156             <listitem>
 157                 <para>
 158                     <code>comment_content</code>, aktualnie wysłana zawartość
 159                     komentarza.
 160                 </para>
 161             </listitem>
 162         </itemizedlist>
 163
 164         <para>
 165             Możesz także przesłać dowolne inne zmienne opisujące środowisko,
 166             ktore według ciebie mogą być pomocne w zweryfikowaniu danych pod
 167             kątem spamu. Serwis Akismet sugeruje, aby była to cała zawartość
 168             tablicy $_SERVER.
 169         </para>
 170
 171         <para>
 172             Metoda <code>isSpam()</code> zwróci wartość logiczną true lub false,
 173             a w przypadku gdy klucz API jest nieprawidłowy, wyrzuci wyjątek.
 174         </para>
 175
 176         <example id="zend.service.akismet.isspam.example-1">
 177             <title>Użycie metody isSpam()</title>
 178
 179             <programlisting role="php"><![CDATA[
 180 $data = array(
 181     'user_ip'              => '111.222.111.222',
 182     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT' .
 183                               '5.2; en-GB; rv:1.8.1) Gecko/20061010' .
 184                               'Firefox/2.0',
 185     'comment_type'         => 'contact',
 186     'comment_author'       => 'John Doe',
 187     'comment_author_email' => 'nospam@myhaus.net',
 188     'comment_content'      => "I'm not a spammer, honest!"
 189 );
 190 if ($akismet->isSpam($data)) {
 191     echo "Sorry, but we think you're a spammer.";
 192 } else {
 193     echo "Welcome to our site!";
 194 }
 195 ]]>
 196             </programlisting>
 197         </example>
 198
 199         <para>
 200             Metoda <code>isSpam()</code> implementuje metodę <code>comment-check</code>
 201             API serwisu Akismet.
 202         </para>
 203     </sect2>
 204
 205     <sect2 id="zend.service.akismet.submitspam">
 206         <title>Wysyłanie informacji o spamie</title>
 207
 208         <para>
 209             Czasem dane, które są spamem mogą przejść przez filtr. Jeśli
 210             będziesz przeglądał przychodzące dane i znajdziesz dane, które
 211             według ciebie powinny być uznane za spam, możesz wysłać je do
 212             Akismet aby pomóc ulepszyć filtr.
 213         </para>
 214
 215         <para>
 216             Metoda <code>Zend_Service_Akismet::submitSpam()</code> przyjmuje
 217             taką samą tablicę danych jak metoda <code>isSpam()</code>, ale nie
 218             zwraca wartości. Jeśli klucz API jest nieprawidłowy, zostanie
 219             wyrzucony wyjątek.
 220         </para>
 221
 222         <example id="zend.service.akismet.submitspam.example-1">
 223             <title>Użycie metody submitSpam()</title>
 224
 225             <programlisting role="php"><![CDATA[
 226 $data = array(
 227     'user_ip'              => '111.222.111.222',
 228     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
 229                               'en-GB; rv:1.8.1) Gecko/20061010' .
 230                               'Firefox/2.0',
 231     'comment_type'         => 'contact',
 232     'comment_author'       => 'John Doe',
 233     'comment_author_email' => 'nospam@myhaus.net',
 234     'comment_content'      => "I'm not a spammer, honest!"
 235 );
 236 $akismet->submitSpam($data));
 237 ]]>
 238             </programlisting>
 239         </example>
 240
 241         <para>
 242             Metoda <code>submitSpam()</code> implementuje metodę <code>submit-spam</code>
 243             API serwisu Akismet.
 244         </para>
 245     </sect2>
 246
 247     <sect2 id="zend.service.akismet.submitham">
 248         <title>Wysyłanie informacji o fałszywym spamie (ham)</title>
 249
 250         <para>
 251             Czasem dane zostaną przez Akismet błędnie uznane za spam. Z tego
 252             względu, powinieneś zapisywać dane uznane przez Akismet za spam i
 253             regularnie je przeglądać. Jeśli znajdziesz takie przypadki, możesz
 254             wysłać takie dane do Akismet jako "ham" czyli poprawne dane błędnie
 255             uznane  za spam (ham jest dobry, spam nie jest).
 256         </para>
 257
 258         <para>
 259             Metoda <code>Zend_Service_Akismet::submitHam()</code> przyjmuje
 260             taką samą tablicę danych jak metody <code>isSpam()</code> oraz
 261             <code>submitSpam()</code> i tak samo jak metoda
 262             <code>submitSpam()</code> nie zwraca wartości. Jeśli klucz API jest
 263             nieprawidłowy, zostanie wyrzucony wyjątek.
 264         </para>
 265
 266         <example id="zend.service.akismet.submitham.example-1">
 267             <title>Użycie metody submitHam()</title>
 268
 269             <programlisting role="php"><![CDATA[
 270 $data = array(
 271     'user_ip'              => '111.222.111.222',
 272     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
 273                               'en-GB; rv:1.8.1) Gecko/20061010' .
 274                               'Firefox/2.0',
 275     'comment_type'         => 'contact',
 276     'comment_author'       => 'John Doe',
 277     'comment_author_email' => 'nospam@myhaus.net',
 278     'comment_content'      => "I'm not a spammer, honest!"
 279 );
 280 $akismet->submitHam($data));
 281 ]]>
 282             </programlisting>
 283         </example>
 284
 285         <para>
 286             Metoda <code>submitHam()</code> implementuje metodę <code>submit-ham</code>
 287             API serwisu Akismet.
 288         </para>
 289     </sect2>
 290
 291     <sect2 id="zend.service.akismet.accessors">
 292         <title>Specyficzne metody dostępowe</title>
 293
 294         <para>
 295             O ile API serwisu Akismet określa jedynie cztery metody,
 296             komponent <code>Zend_Service_Akismet</code> posiada kilka
 297             dodatkowych metod dostępowych, które mogą być użyte do modyfikowania
 298             wewnętrznych właściwości.
 299         </para>
 300
 301         <itemizedlist>
 302             <listitem>
 303                 <para>
 304                     Metody <code>getBlogUrl()</code> oraz <code>setBlogUrl()</code>
 305                     pozwalają ci na odebranie oraz modyfikację adresu URL bloga
 306                     używanego w żądaniach.
 307                 </para>
 308             </listitem>
 309
 310             <listitem>
 311                 <para>
 312                     Metody <code>getApiKey()</code> oraz <code>setApiKey()</code>
 313                     pozwalają ci na odebranie oraz modyfikację klucza API
 314                     używanego w żądaniach.
 315                 </para>
 316             </listitem>
 317
 318             <listitem>
 319                 <para>
 320                     Metody <code>getCharset()</code> oraz <code>setCharset()</code>
 321                     pozwalają ci na odebranie oraz modyfikację zestawu znaków
 322                     używanego w żądaniach.
 323                 </para>
 324             </listitem>
 325
 326             <listitem>
 327                 <para>
 328                     Metody <code>getPort()</code> oraz <code>setPort()</code>
 329                     pozwalają ci na odebranie oraz modyfikację portu TCP
 330                     używanego w żądaniach.
 331                 </para>
 332             </listitem>
 333
 334             <listitem>
 335                 <para>
 336                     Metody <code>getUserAgent()</code> oraz
 337                     <code>setUserAgent()</code> pozwalają ci na pobranie oraz
 338                     modyfikowanie informacji o kliencie HTTP używanym do
 339                     przeprowadzenia żądania.
 340                     Nota: nie jest to ta sama wartość co user_agent, która jest
 341                     używana w danych wysyłanych do serwisu, ale raczej wartość,
 342                     która będzie wysłana w nagłówku HTTP User-Agent podczas
 343                     przeprowadzania żądania do serwisu.
 344                 </para>
 345
 346                 <para>
 347                     Wartość użyta do ustawienia nazwy klienta HTTP powinna być
 348                     w formacie <code>nazwa klienta/wersja | Akismet/wersja</code>.
 349                     Domyślna wartość to <code>Zend Framework/ZF-VERSION | Akismet/1.11</code>,
 350                     gdzie <code>ZF-VERSION</code> jest numerem obecnej wersji ZF
 351                     przechowywanym w stałej <code>Zend_Framework::VERSION</code>.
 352                 </para>
 353             </listitem>
 354         </itemizedlist>
 355     </sect2>
 356 </sect1>