documentation/manual/en/module_specs/Zend_Captcha-Adapters.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.captcha.adapters">
   4     <title>CAPTCHA Adapters</title>
   5
   6     <para>
   7         The following adapters are shipped with Zend Framework by default.
   8     </para>
   9
  10     <sect2 id="zend.captcha.adapters.word">
  11         <title>Zend_Captcha_Word</title>
  12
  13         <para>
  14             <classname>Zend_Captcha_Word</classname> is an abstract adapter that serves as the base
  15             class for most other <acronym>CAPTCHA</acronym> adapters. It provides mutators for
  16             specifying word length, session <acronym>TTL</acronym>, the session namespace object
  17             to use, and the session namespace class to use for persistence if
  18             you do not wish to use <classname>Zend_Session_Namespace</classname>.
  19             <classname>Zend_Captcha_Word</classname> encapsulates validation logic.
  20         </para>
  21
  22         <para>
  23             By default, the word length is 8 characters, the session timeout is
  24             5 minutes, and <classname>Zend_Session_Namespace</classname> is used for persistence
  25             (using the namespace "<classname>Zend_Form_Captcha_&lt;captcha ID&gt;</classname>").
  26         </para>
  27
  28         <para>
  29             In addition to the methods required by the
  30             <classname>Zend_Captcha_Adapter</classname> interface,
  31             <classname>Zend_Captcha_Word</classname> exposes the following methods:
  32         </para>
  33
  34         <itemizedlist>
  35             <listitem>
  36                 <para>
  37                     <methodname>setWordLen($length)</methodname> and
  38                     <methodname>getWordLen()</methodname> allow you to specify the length of the
  39                     generated "word" in characters, and to retrieve the current value.
  40                 </para>
  41             </listitem>
  42
  43             <listitem>
  44                 <para>
  45                     <methodname>setTimeout($ttl)</methodname> and
  46                     <methodname>getTimeout()</methodname> allow you to specify the time-to-live of
  47                     the session token, and to retrieve the current value. <varname>$ttl</varname>
  48                     should be specified in seconds.
  49                 </para>
  50             </listitem>
  51
  52             <listitem>
  53                 <para>
  54                     <methodname>setUseNumbers($numbers)</methodname> and
  55                     <methodname>getUseNumbers()</methodname> allow you to specify if numbers will be
  56                     considered as possible characters for the random work or only letters would be
  57                     used.
  58                 </para>
  59             </listitem>
  60
  61             <listitem>
  62                 <para>
  63                     <methodname>setSessionClass($class)</methodname> and
  64                     <methodname>getSessionClass()</methodname> allow you to specify an
  65                     alternate <classname>Zend_Session_Namespace</classname> implementation to
  66                     use to persist the <acronym>CAPTCHA</acronym> token and to retrieve the
  67                     current value.
  68                 </para>
  69             </listitem>
  70
  71             <listitem>
  72                 <para>
  73                     <methodname>getId()</methodname> allows you to retrieve the current token
  74                     identifier.
  75                 </para>
  76             </listitem>
  77
  78             <listitem>
  79                 <para>
  80                     <methodname>getWord()</methodname> allows you to retrieve the generated
  81                     word to use with the <acronym>CAPTCHA</acronym>. It will generate the word for
  82                     you if none has been generated yet.
  83                 </para>
  84             </listitem>
  85
  86             <listitem>
  87                 <para>
  88                     <methodname>setSession(Zend_Session_Namespace $session)</methodname> allows
  89                     you to specify a session object to use for persisting the
  90                     <acronym>CAPTCHA</acronym> token. <methodname>getSession()</methodname> allows
  91                     you to retrieve the current session object.
  92                 </para>
  93             </listitem>
  94         </itemizedlist>
  95
  96         <para>
  97             All word <acronym>CAPTCHA</acronym>s allow you to pass an array of options to the
  98             constructor, or, alternately, pass them to
  99             <methodname>setOptions()</methodname>. You can also pass a
 100             <classname>Zend_Config</classname> object to <methodname>setConfig()</methodname>. By
 101             default, the <emphasis>wordLen</emphasis>, <emphasis>timeout</emphasis>, and
 102             <emphasis>sessionClass</emphasis> keys may all be used. Each concrete
 103             implementation may define additional keys or utilize the options in
 104             other ways.
 105         </para>
 106
 107         <note>
 108             <para>
 109                 <classname>Zend_Captcha_Word</classname> is an abstract class and may not be
 110                 instantiated directly.
 111             </para>
 112         </note>
 113     </sect2>
 114
 115     <sect2 id="zend.captcha.adapters.dumb">
 116         <title>Zend_Captcha_Dumb</title>
 117
 118         <para>
 119             The <classname>Zend_Captch_Dumb</classname> adapter is mostly self-descriptive. It
 120             provides a random string that must be typed in reverse to validate. As such, it's
 121             not a good <acronym>CAPTCHA</acronym> solution and should only be used for
 122             testing. It extends <classname>Zend_Captcha_Word</classname>.
 123         </para>
 124     </sect2>
 125
 126     <sect2 id="zend.captcha.adapters.figlet">
 127         <title>Zend_Captcha_Figlet</title>
 128
 129         <para>
 130             The <classname>Zend_Captcha_Figlet</classname> adapter utilizes <link
 131                 linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link> to present
 132             a figlet to the user.
 133         </para>
 134
 135         <para>
 136             Options passed to the constructor will also be passed to the <link
 137                 linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link> object.
 138             See the <link linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link>
 139             documentation for details on what configuration options are available.
 140         </para>
 141     </sect2>
 142
 143     <sect2 id="zend.captcha.adapters.image">
 144         <title>Zend_Captcha_Image</title>
 145
 146         <para>
 147             The <classname>Zend_Captcha_Image</classname> adapter takes the generated word and
 148             renders it as an image, performing various skewing permutations to make it
 149             difficult to automatically decipher. It
 150             requires the <ulink url="http://php.net/gd">GD extension</ulink>
 151             compiled with TrueType or Freetype support. Currently, the
 152             <classname>Zend_Captcha_Image</classname> adapter can only generate
 153             <acronym>PNG</acronym> images.
 154         </para>
 155
 156         <para>
 157             <classname>Zend_Captcha_Image</classname> extends
 158             <classname>Zend_Captcha_Word</classname>, and additionally exposes the
 159             following methods:
 160         </para>
 161
 162         <itemizedlist>
 163             <listitem>
 164                 <para>
 165                     <methodname>setExpiration($expiration)</methodname> and
 166                     <methodname>getExpiration()</methodname> allow you to specify a maximum
 167                     lifetime the <acronym>CAPTCHA</acronym> image may reside on the filesystem.
 168                     This is typically a longer than the session lifetime. Garbage
 169                     collection is run periodically each time the <acronym>CAPTCHA</acronym> object
 170                     is invoked, deleting all images that have expired.
 171                     Expiration values should be specified in seconds.
 172                 </para>
 173             </listitem>
 174
 175             <listitem>
 176                 <para>
 177                     <methodname>setGcFreq($gcFreq)</methodname> and
 178                     <methodname>getGcFreg()</methodname> allow you to specify how frequently garbage
 179                     collection should run. Garbage collection will run every
 180                     <command>1/$gcFreq</command> calls. The default is 100.
 181                 </para>
 182             </listitem>
 183
 184             <listitem>
 185                 <para>
 186                     <methodname>setFont($font)</methodname> and <methodname>getFont()</methodname>
 187                     allow you to specify the font you will use. <varname>$font</varname>
 188                     should be a fully qualified path to the font file.
 189                     This value is required; the <acronym>CAPTCHA</acronym> will throw an
 190                     exception during generation if the font file has not been specified.
 191                 </para>
 192             </listitem>
 193
 194             <listitem>
 195                 <para>
 196                     <methodname>setFontSize($fsize)</methodname> and
 197                     <methodname>getFontSize()</methodname> allow you to specify the font size in
 198                     pixels for generating the <acronym>CAPTCHA</acronym>. The default is 24px.
 199                 </para>
 200             </listitem>
 201
 202             <listitem>
 203                 <para>
 204                     <methodname>setHeight($height)</methodname> and
 205                     <methodname>getHeight()</methodname> allow you to specify the height in pixels
 206                     of the generated <acronym>CAPTCHA</acronym> image. The default is 50px.
 207                 </para>
 208             </listitem>
 209
 210             <listitem>
 211                 <para>
 212                     <methodname>setWidth($width)</methodname> and
 213                     <methodname>getWidth()</methodname> allow you to specify the width in pixels of
 214                     the generated <acronym>CAPTCHA</acronym> image. The default is 200px.
 215                 </para>
 216             </listitem>
 217
 218             <listitem>
 219                 <para>
 220                     <methodname>setImgDir($imgDir)</methodname> and
 221                     <methodname>getImgDir()</methodname> allow you to specify the directory for
 222                     storing <acronym>CAPTCHA</acronym> images. The default is
 223                     "<filename>./images/captcha/</filename>", relative to the bootstrap script.
 224                 </para>
 225             </listitem>
 226
 227             <listitem>
 228                 <para>
 229                     <methodname>setImgUrl($imgUrl)</methodname> and
 230                     <methodname>getImgUrl()</methodname> allow you to specify the relative path to
 231                     a <acronym>CAPTCHA</acronym> image to use for <acronym>HTML</acronym> markup.
 232                     The default is "<filename>/images/captcha/</filename>".
 233                 </para>
 234             </listitem>
 235
 236             <listitem>
 237                 <para>
 238                     <methodname>setSuffix($suffix)</methodname> and
 239                     <methodname>getSuffix()</methodname> allow you to specify the filename suffix
 240                     for the <acronym>CAPTCHA</acronym> image. The default is
 241                     "<filename>.png</filename>". Note: changing this value will not change the type
 242                     of the generated image.
 243                 </para>
 244             </listitem>
 245
 246             <listitem>
 247                 <para>
 248                     <methodname>setDotNoiseLevel($level)</methodname> and
 249                     <methodname>getDotNoiseLevel()</methodname>, along with
 250                     <methodname>setLineNoiseLevel($level)</methodname> and
 251                     <methodname>getLineNoiseLevel()</methodname>,
 252                     allow you to control how much "noise" in the form of random dots and lines the
 253                     image would contain. Each unit of <varname>$level</varname> produces one random
 254                     dot or line. The default is 100 dots and 5 lines. The noise is added twice -
 255                     before and after the image distortion transformation.
 256                 </para>
 257             </listitem>
 258         </itemizedlist>
 259
 260         <para>
 261             All of the above options may be passed to the
 262             constructor by simply removing the 'set' method prefix and casting
 263             the initial letter to lowercase: "suffix", "height", "imgUrl", etc.
 264         </para>
 265     </sect2>
 266
 267     <sect2 id="zend.captcha.adapters.recaptcha">
 268         <title>Zend_Captcha_ReCaptcha</title>
 269
 270         <para>
 271             The <classname>Zend_Captcha_ReCaptcha</classname> adapter uses <link
 272                 linkend="zend.service.recaptcha">Zend_Service_ReCaptcha</link>
 273             to generate and validate <acronym>CAPTCHA</acronym>s. It exposes the following
 274             methods:
 275         </para>
 276
 277         <itemizedlist>
 278             <listitem>
 279                 <para>
 280                     <methodname>setPrivKey($key)</methodname> and
 281                     <methodname>getPrivKey()</methodname> allow you to specify the private key to
 282                     use for the ReCaptcha service. This must be specified during construction,
 283                     although it may be overridden at any point.
 284                 </para>
 285             </listitem>
 286
 287             <listitem>
 288                 <para>
 289                     <methodname>setPubKey($key)</methodname> and
 290                     <methodname>getPubKey()</methodname> allow you to specify the public key to use
 291                     with the ReCaptcha service. This must be specified during construction, although
 292                     it may be overridden at any point.
 293                 </para>
 294             </listitem>
 295
 296             <listitem>
 297                 <para>
 298                     <methodname>setService(Zend_Service_ReCaptcha $service)</methodname> and
 299                     <methodname>getService()</methodname> allow you to set and get
 300                     the ReCaptcha service object.
 301                 </para>
 302             </listitem>
 303         </itemizedlist>
 304     </sect2>
 305 </sect1>
 306 <!--
 307 vim:se ts=4 sw=4 et:
 308 -->