documentation/manual/en/module_specs/Zend_Service_Akismet.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.akismet">
   4     <title>Zend_Service_Akismet</title>
   5
   6     <sect2 id="zend.service.akismet.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Akismet</classname> provides a client for the <ulink
  11                 url="http://akismet.com/development/api/">Akismet <acronym>API</acronym></ulink>.
  12             The Akismet service is used to determine if incoming data is
  13             potentially spam. It also exposes methods for submitting data as
  14             known spam or as false positives (ham). It was originally intended to help
  15             categorize and identify spam for Wordpress, but it can be used for any
  16             type of data.
  17         </para>
  18
  19         <para>
  20             Akismet requires an <acronym>API</acronym> key for usage. You can get one by signing
  21             up for a <ulink url="http://wordpress.com/">WordPress.com</ulink>
  22             account. You do not need to activate a blog. Simply acquiring the
  23             account will provide you with the <acronym>API</acronym> key.
  24         </para>
  25
  26         <para>
  27             Akismet requires that all requests contain a <acronym>URL</acronym> to
  28             the resource for which data is being filtered. Because of
  29             Akismet's origins in WordPress, this resource is called the blog
  30             <acronym>URL</acronym>. This value should be passed as the second argument to the
  31             constructor, but may be reset at any time using the
  32             <methodname>setBlogUrl()</methodname> method, or overridden by specifying a
  33             'blog' key in the various method calls.
  34         </para>
  35     </sect2>
  36
  37     <sect2 id="zend.service.akismet.verifykey">
  38         <title>Verify an API key</title>
  39
  40         <para>
  41             <methodname>Zend_Service_Akismet::verifyKey($key)</methodname> is used to
  42             verify that an Akismet <acronym>API</acronym> key is valid. In most cases, you
  43             will not need to check, but if you need a sanity check, or
  44             to determine if a newly acquired key is active, you may do
  45             so with this method.
  46         </para>
  47
  48         <programlisting language="php"><![CDATA[
  49 // Instantiate with the API key and a URL to the application or
  50 // resource being used
  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 ]]></programlisting>
  59
  60         <para>
  61             If called with no arguments, <methodname>verifyKey()</methodname> uses
  62             the <acronym>API</acronym> key provided to the constructor.
  63         </para>
  64
  65         <para>
  66             <methodname>verifyKey()</methodname> implements Akismet's
  67             <code>verify-key</code> REST method.
  68         </para>
  69     </sect2>
  70
  71     <sect2 id="zend.service.akismet.isspam">
  72         <title>Check for spam</title>
  73
  74         <para>
  75             <methodname>Zend_Service_Akismet::isSpam($data)</methodname> is used to
  76             determine if the data provided is considered spam by
  77             Akismet. It accepts an associative array as the sole
  78             argument. That array requires the following keys be set:
  79         </para>
  80
  81         <itemizedlist>
  82             <listitem>
  83                 <para>
  84                     <code>user_ip</code>, the IP address of the user
  85                     submitting the data (not your IP address, but that
  86                     of a user on your site).
  87                 </para>
  88             </listitem>
  89
  90             <listitem>
  91                 <para>
  92                     <code>user_agent</code>, the reported UserAgent
  93                     string (browser and version) of the user submitting
  94                     the data.
  95                 </para>
  96             </listitem>
  97         </itemizedlist>
  98
  99         <para>
 100             The following keys are also recognized specifically by the
 101             <acronym>API</acronym>:
 102         </para>
 103
 104         <itemizedlist>
 105             <listitem>
 106                 <para>
 107                     <code>blog</code>, the fully qualified <acronym>URL</acronym> to the
 108                     resource or application. If not specified, the <acronym>URL</acronym>
 109                     provided to the constructor will be used.
 110                 </para>
 111             </listitem>
 112
 113             <listitem>
 114                 <para>
 115                     <code>referrer</code>, the content of the
 116                     HTTP_REFERER header at the time of submission. (Note
 117                     spelling; it does not follow the header name.)
 118                 </para>
 119             </listitem>
 120
 121             <listitem>
 122                 <para>
 123                     <code>permalink</code>, the permalink location, if
 124                     any, of the entry the data was submitted to.
 125                 </para>
 126             </listitem>
 127
 128             <listitem>
 129                 <para>
 130                     <code>comment_type</code>, the type of data
 131                     provided. Values specified in the <acronym>API</acronym>
 132                     include 'comment', 'trackback', 'pingback', and an
 133                     empty string (''), but it may be any value.
 134                 </para>
 135             </listitem>
 136
 137             <listitem>
 138                 <para>
 139                     <code>comment_author</code>, the name of the person
 140                     submitting the data.
 141                 </para>
 142             </listitem>
 143
 144             <listitem>
 145                 <para>
 146                     <code>comment_author_email</code>, the email of the
 147                     person submitting the data.
 148                 </para>
 149             </listitem>
 150
 151             <listitem>
 152                 <para>
 153                     <code>comment_author_url</code>, the <acronym>URL</acronym> or home page of the
 154                     person submitting the data.
 155                 </para>
 156             </listitem>
 157
 158             <listitem>
 159                 <para>
 160                     <code>comment_content</code>, the actual data content
 161                     submitted.
 162                 </para>
 163             </listitem>
 164         </itemizedlist>
 165
 166         <para>
 167             You may also submit any other environmental variables you
 168             feel might be a factor in determining if data is spam.
 169             Akismet suggests the contents of the entire $_SERVER array.
 170         </para>
 171
 172         <para>
 173             The <methodname>isSpam()</methodname> method will return either
 174             <constant>TRUE</constant> or <constant>FALSE</constant>, or throw an exception if the
 175             <acronym>API</acronym> key is invalid.
 176         </para>
 177
 178         <example id="zend.service.akismet.isspam.example-1">
 179             <title>isSpam() Usage</title>
 180
 181             <programlisting language="php"><![CDATA[
 182 $data = array(
 183     'user_ip'              => '111.222.111.222',
 184     'user_agent'           => 'Mozilla/5.0 ' . (Windows; U; Windows NT ' .
 185                               '5.2; en-GB; rv:1.8.1) Gecko/20061010 ' .
 186                               'Firefox/2.0',
 187     'comment_type'         => 'contact',
 188     'comment_author'       => 'John Doe',
 189     'comment_author_email' => 'nospam@myhaus.net',
 190     'comment_content'      => "I'm not a spammer, honest!"
 191 );
 192 if ($akismet->isSpam($data)) {
 193     echo "Sorry, but we think you're a spammer.";
 194 } else {
 195     echo "Welcome to our site!";
 196 }
 197 ]]></programlisting>
 198         </example>
 199
 200         <para>
 201             <methodname>isSpam()</methodname> implements the <code>comment-check</code>
 202             Akismet <acronym>API</acronym> method.
 203         </para>
 204     </sect2>
 205
 206     <sect2 id="zend.service.akismet.submitspam">
 207         <title>Submitting known spam</title>
 208
 209         <para>
 210             Spam data will occasionally get through the filter. If you discover spam that you feel
 211             should have been caught, you can submit it to Akismet to help improve their filter.
 212         </para>
 213
 214         <para>
 215             <methodname>Zend_Service_Akismet::submitSpam()</methodname> takes the same data
 216             array as passed to <methodname>isSpam()</methodname>, but does not return a
 217             value. An exception will be raised if the <acronym>API</acronym> key used is invalid.
 218         </para>
 219
 220         <example id="zend.service.akismet.submitspam.example-1">
 221             <title>submitSpam() Usage</title>
 222
 223             <programlisting language="php"><![CDATA[
 224 $data = array(
 225     'user_ip'              => '111.222.111.222',
 226     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
 227                               'en-GB; rv:1.8.1) Gecko/20061010 Firefox/2.0',
 228     'comment_type'         => 'contact',
 229     'comment_author'       => 'John Doe',
 230     'comment_author_email' => 'nospam@myhaus.net',
 231     'comment_content'      => "I'm not a spammer, honest!"
 232 );
 233 $akismet->submitSpam($data));
 234 ]]></programlisting>
 235         </example>
 236
 237         <para>
 238             <methodname>submitSpam()</methodname> implements the <code>submit-spam</code>
 239             Akismet <acronym>API</acronym> method.
 240         </para>
 241     </sect2>
 242
 243     <sect2 id="zend.service.akismet.submitham">
 244         <title>Submitting false positives (ham)</title>
 245
 246         <para>
 247             Data will occasionally be trapped erroneously as spam by Akismet. For this reason,
 248             you should probably keep a log of all data trapped as spam by Akismet and review it
 249             periodically. If you find such occurrences, you can submit the data to Akismet as
 250             "ham", or a false positive (ham is good, spam is not).
 251         </para>
 252
 253         <para>
 254             <methodname>Zend_Service_Akismet::submitHam()</methodname> takes the same data
 255             array as passed to <methodname>isSpam()</methodname> or
 256             <methodname>submitSpam()</methodname>, and, like <methodname>submitSpam()</methodname>,
 257             does not return a value. An exception will be raised if the <acronym>API</acronym> key
 258             used is invalid.
 259         </para>
 260
 261         <example id="zend.service.akismet.submitham.example-1">
 262             <title>submitHam() Usage</title>
 263
 264             <programlisting language="php"><![CDATA[
 265 $data = array(
 266     'user_ip'              => '111.222.111.222',
 267     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
 268                               'en-GB; rv:1.8.1) Gecko/20061010 Firefox/2.0',
 269     'comment_type'         => 'contact',
 270     'comment_author'       => 'John Doe',
 271     'comment_author_email' => 'nospam@myhaus.net',
 272     'comment_content'      => "I'm not a spammer, honest!"
 273 );
 274 $akismet->submitHam($data));
 275 ]]></programlisting>
 276         </example>
 277
 278         <para>
 279             <methodname>submitHam()</methodname> implements the <code>submit-ham</code>
 280             Akismet <acronym>API</acronym> method.
 281         </para>
 282     </sect2>
 283
 284     <sect2 id="zend.service.akismet.accessors">
 285         <title>Zend-specific Methods</title>
 286
 287         <para>
 288             While the Akismet <acronym>API</acronym> only specifies four methods,
 289             <classname>Zend_Service_Akismet</classname> has several additional methods
 290             that may be used for retrieving and modifying internal properties.
 291         </para>
 292
 293         <itemizedlist>
 294             <listitem>
 295                 <para>
 296                     <methodname>getBlogUrl()</methodname> and <methodname>setBlogUrl()</methodname>
 297                     allow you to retrieve and modify the blog <acronym>URL</acronym> used in
 298                     requests.
 299                 </para>
 300             </listitem>
 301
 302             <listitem>
 303                 <para>
 304                     <methodname>getApiKey()</methodname> and <methodname>setApiKey()</methodname>
 305                     allow you to retrieve and modify the <acronym>API</acronym> key used in
 306                     requests.
 307                 </para>
 308             </listitem>
 309
 310             <listitem>
 311                 <para>
 312                     <methodname>getCharset()</methodname> and <methodname>setCharset()</methodname>
 313                     allow you to retrieve and modify the character set used to make the request.
 314                 </para>
 315             </listitem>
 316
 317             <listitem>
 318                 <para>
 319                     <methodname>getPort()</methodname> and <methodname>setPort()</methodname>
 320                     allow you to retrieve and modify the <acronym>TCP</acronym> port used to make
 321                     the request.
 322                 </para>
 323             </listitem>
 324
 325             <listitem>
 326                 <para>
 327                     <methodname>getUserAgent()</methodname> and
 328                     <methodname>setUserAgent()</methodname> allow you to retrieve and modify the
 329                     <acronym>HTTP</acronym> user agent used to make the request. Note: this is not
 330                     the user_agent used in data submitted to the service, but rather the value
 331                     provided in the <acronym>HTTP</acronym> User-Agent header when making a request
 332                     to the service.
 333                 </para>
 334
 335                 <para>
 336                     The value used to set the user agent should be of the form
 337                     <code>some user agent/version | Akismet/version</code>. The default is
 338                     <code>Zend Framework/ZF-VERSION | Akismet/1.11</code>, where
 339                     <code>ZF-VERSION</code> is the current Zend Framework version as stored in the
 340                     <constant>Zend_Framework::VERSION</constant> constant.
 341                 </para>
 342             </listitem>
 343         </itemizedlist>
 344     </sect2>
 345 </sect1>
 346 <!--
 347 vim:se ts=4 sw=4 et:
 348 -->