<commit_before><sect1 id="zend.captcha.operation">
    <title>Captcha Operation</title>

    <para>
        All concrete CAPTCHA objects implement
        <code>Zend_Captcha_Adapter</code>, which looks like the following:
    </para>

    <programlisting role="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 mutator and accessor are used to specify and retrieve the
        captcha identifier. <code>getDecorator()</code> can be used to specify a
        Zend_Form decorator either by name or returning an actual decorator
        object. The true keys to usage, however, lie in <code>generate()</code>
        and <code>render()</code>. <code>generate()</code> is used to create the
        captcha token. This process typically will store the token in the
        session so that you may compare against it in subsequent requests.
        <code>render()</code> is used to render the information that represents
        the captcha -- be it in image, a figlet, a logic problem, etc.
    </para>

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

        <programlisting role="php"><![CDATA[
// Originating request:
$captcha = new Zend_Captcha_Figlet(array(
    'name' => 'foo',
    'wordLen' => 6,
    'timeout' => 300,
));
$id = $captcha->generate();
echo $captcha->render();

// On subsequent request:
// Assume captcha setup as before, and $value is the submitted value:
if ($captcha->isValid($value)) {
    // Validated!
}
]]></programlisting>
</sect1>
<!--
vim:se ts=4 sw=4 et:
--><commit_msg>ZF-3995: Fix documentation of captcha usage<commit_after><sect1 id="zend.captcha.operation">
    <title>Captcha Operation</title>

    <para>
        All concrete CAPTCHA objects implement
        <code>Zend_Captcha_Adapter</code>, which looks like the following:
    </para>

    <programlisting role="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 mutator and accessor are used to specify and retrieve the
        captcha identifier. <code>getDecorator()</code> can be used to specify a
        Zend_Form decorator either by name or returning an actual decorator
        object. The true keys to usage, however, lie in <code>generate()</code>
        and <code>render()</code>. <code>generate()</code> is used to create the
        captcha token. This process typically will store the token in the
        session so that you may compare against it in subsequent requests.
        <code>render()</code> is used to render the information that represents
        the captcha -- be it in image, a figlet, a logic problem, etc.
    </para>

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

        <programlisting role="php"><![CDATA[
// Originating request:
$captcha = new Zend_Captcha_Figlet(array(
    'name' => 'foo',
    'wordLen' => 6,
    'timeout' => 300,
));
$id = $captcha->generate();
echo $captcha->render();

// On subsequent request:
// Assume captcha setup as before, and $value is the submitted value:
if ($captcha->isValid($_POST['foo'], $_POST)) {
    // Validated!
}
]]></programlisting>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
{'fraction_non_alphanumeric': 0.11568187484417851, 'fraction_numerical': 0.004986287708800797, 'mean_word_length': 3.3232758620689653, 'pattern_counts': {'":': 0, '<': 61, '<?xml version=': 0, '>': 73, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5562638', 'n_tokens_mistral': 1177, 'n_tokens_neox': 1104, 'n_words': 406}