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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.captcha.operation">
   4     <title>Captcha Operation</title>
   5
   6     <para>
   7         All <acronym>CAPTCHA</acronym> adapter implement
   8         <classname>Zend_Captcha_Adapter</classname>, which looks like the following:
   9     </para>
  10
  11     <programlisting language="php"><![CDATA[
  12 interface Zend_Captcha_Adapter extends Zend_Validate_Interface
  13 {
  14     public function generate();
  15
  16     public function render(Zend_View $view, $element = null);
  17
  18     public function setName($name);
  19
  20     public function getName();
  21
  22     public function getDecorator();
  23
  24     // Additionally, to satisfy Zend_Validate_Interface:
  25     public function isValid($value);
  26
  27     public function getMessages();
  28
  29     public function getErrors();
  30 }
  31 ]]></programlisting>
  32
  33     <para>
  34         The name setter and getter are used to specify and retrieve the
  35         <acronym>CAPTCHA</acronym> identifier. <methodname>getDecorator()</methodname> can be used
  36         to specify a <classname>Zend_Form</classname> decorator either by name or returning an
  37         actual decorator object. The most interesting methods are
  38         <methodname>generate()</methodname> and <methodname>render()</methodname>.
  39         <methodname>generate()</methodname> is used to create the <acronym>CAPTCHA</acronym>
  40         token. This process typically will store the token in the session so that you may compare
  41         against it in subsequent requests. <methodname>render()</methodname> is used to render the
  42         information that represents the <acronym>CAPTCHA</acronym>, be it an image, a figlet, a
  43         logic problem, or some other <acronym>CAPTCHA</acronym>.
  44     </para>
  45
  46     <para>
  47         A typical use case might look like the following:
  48     </para>
  49
  50     <programlisting language="php"><![CDATA[
  51 // Creating a Zend_View instance
  52 $view = new Zend_View();
  53
  54 // Originating request:
  55 $captcha = new Zend_Captcha_Figlet(array(
  56     'name' => 'foo',
  57     'wordLen' => 6,
  58     'timeout' => 300,
  59 ));
  60
  61 $id = $captcha->generate();
  62 echo "<form method=\"post\" action=\"\">";
  63 echo $captcha->render($view);
  64 echo "</form>";
  65
  66 // On subsequent request:
  67 // Assume captcha setup as before, the value of $_POST['foo']
  68 // would be key/value array: id => captcha ID, input => captcha value
  69 if ($captcha->isValid($_POST['foo'], $_POST)) {
  70     // Validated!
  71 }
  72 ]]></programlisting>
  73 </sect1>
  74 <!--
  75 vim:se ts=4 sw=4 et:
  76 -->