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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.captcha.operation">
    <title>Captcha Operation</title>

    <para>
        All <acronym>CAPTCHA</acronym> adapter implement
        <classname>Zend_Captcha_Adapter</classname>, which looks like the following:
    </para>

    <programlisting language="php"><![CDATA[
interface Zend_Captcha_Adapter extends Zend_Validate_Interface
{
    public function generate();

    public function render(Zend_View $view, $element = null);

    public function setName($name);

    public function getName();

    public function getDecorator();

    // Additionally, to satisfy Zend_Validate_Interface:
    public function isValid($value);

    public function getMessages();

    public function getErrors();
}
]]></programlisting>

    <para>
        The name setter and getter are used to specify and retrieve the
        <acronym>CAPTCHA</acronym> identifier. <methodname>getDecorator()</methodname> can be used
        to specify a <classname>Zend_Form</classname> decorator either by name or returning an
        actual decorator object. The most interesting methods are
        <methodname>generate()</methodname> and <methodname>render()</methodname>.
        <methodname>generate()</methodname> is used to create the <acronym>CAPTCHA</acronym>
        token. This process typically will store the token in the session so that you may compare
        against it in subsequent requests. <methodname>render()</methodname> is used to render the
        information that represents the <acronym>CAPTCHA</acronym>, be it an image, a figlet, a
        logic problem, or some other <acronym>CAPTCHA</acronym>.
    </para>

    <para>
        A typical use case might look like the following:
    </para>

    <programlisting language="php"><![CDATA[
// Creating a Zend_View instance
$view = new Zend_View();

// Originating request:
$captcha = new Zend_Captcha_Figlet(array(
    'name' => 'foo',
    'wordLen' => 6,
    'timeout' => 300,
));

$id = $captcha->generate();
echo "<form method=\"post\" action=\"\">";
echo $captcha->render($view);
echo "</form>";

// On subsequent request:
// Assume captcha setup as before, the value of $_POST['foo']
// would be key/value array: id => captcha ID, input => captcha value
if ($captcha->isValid($_POST['foo'], $_POST)) {
    // Validated!
}
]]></programlisting>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->