CAPTCHA Adapters

zend-captcha defines an abstraction for CAPTCHA implementations via Zend\Captcha\AdapterInterface, and provides several implementations.

The AdapterInterface

All CAPTCHA adapters implement Zend\Captcha\AdapterInterface:

namespace Zend\Captcha;

use Zend\Validator\ValidatorInterface;

interface AdapterInterface extends ValidatorInterface
    public function generate();

    public function setName($name);

    public function getName();

    // Get helper name used for rendering this CAPTCHA type
    public function getHelperName();

The name setter and getter are used to specify and retrieve the CAPTCHA identifier.

The most interesting method is generate(), which 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.

Most implementations also define a render() method (or delegate to one) in order to produce a CAPTCHA representation, be it an image, a figlet, a logic problem, or some other CAPTCHA.


Zend\Captcha\AbstractWord is an abstract adapter that serves as the base class for most other CAPTCHA adapters. It provides mutators for specifying word length, session TTL and the session container object to use; it also encapsulates validation logic.

By default, the word length is 8 characters, the session timeout is 5 minutes, and Zend\Session\Container is used for persistence (using the namespace "Zend\Form\Captcha\<captcha ID>").

In addition to the methods required by the Zend\Captcha\AdapterInterface interface, Zend\Captcha\AbstractWord exposes the following methods:

All word CAPTCHAs allow you to pass an array of options or a Traversable object to the constructor, or, alternately, pass them to setOptions(). By default, the wordLen, timeout, and sessionClass keys may all be used. Each concrete implementation may define additional keys or utilize the options in other ways.

AbstractWord is marked abstract

Zend\Captcha\AbstractWord is an abstract class and may not be instantiated directly.


The Zend\Captcha\Dumb adapter is mostly self-descriptive. It provides a random string that must be typed in reverse to validate. As such, it's not a good CAPTCHA solution and should only be used for testing. It extends Zend\Captcha\AbstractWord.


The Zend\Captcha\Figlet adapter utilizes Zend\Text\Figlet to present a figlet to the user.

Options passed to the constructor will also be passed to the Zend\Text\Figlet object. See the Zend\Text\Figlet documentation for details on what configuration options are available.


The Zend\Captcha\Image adapter takes the generated word and renders it as an image, performing various skewing permutations to make it difficult to automatically decipher. It requires the GD extension, compiled with TrueType or Freetype support. Currently, the Zend\Captcha\Image adapter can only generate PNG images.

Zend\Captcha\Image extends Zend\Captcha\AbstractWord, and additionally exposes the following methods:

All of the above options may be passed to the constructor by simply removing the 'set' method prefix and casting the initial letter to lowercase: "suffix", "height", "imgUrl", etc.


The Zend\Captcha\ReCaptcha adapter uses Zend\Service\ReCaptcha\ReCaptcha to generate and validate CAPTCHAs. It exposes the following methods:

When constructing Zend\Captcha\ReCaptcha, you can use the same set of keys to the $options array as supported by Zend\Service\ReCaptcha\ReCaptcha.

Updating from v2 to v3 of this adapter

As this adapter takes the same option keys as Zend\Service\ReCaptcha\ReCaptcha which supports Recaptcha API v2, this component no longer supports the ssl, xhtml and lang keys in the $options array that is passed to the constructor.

The options keys pubKey and privKey and the getters and setters for these keys are supported in this version, but are deprecated.