From 1b4b678cce49218c9e9c2bc512c7e875702fbdf5 Mon Sep 17 00:00:00 2001 From: Gary Hockin Date: Fri, 30 Oct 2015 12:20:07 +0000 Subject: [PATCH] Added base documentation --- doc/book/zend.captcha.adapters.md | 109 +++++++++++++++++++++++++++++ doc/book/zend.captcha.intro.md | 14 ++++ doc/book/zend.captcha.operation.md | 60 ++++++++++++++++ doc/bookdown.json | 9 +++ 4 files changed, 192 insertions(+) create mode 100644 doc/book/zend.captcha.adapters.md create mode 100644 doc/book/zend.captcha.intro.md create mode 100644 doc/book/zend.captcha.operation.md create mode 100644 doc/bookdown.json diff --git a/doc/book/zend.captcha.adapters.md b/doc/book/zend.captcha.adapters.md new file mode 100644 index 0000000..f57cd2a --- /dev/null +++ b/doc/book/zend.captcha.adapters.md @@ -0,0 +1,109 @@ +# CAPTCHA Adapters + +The following adapters are shipped with Zend Framework by default. + +## Zend\\Captcha\\AbstractWord + +`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. `Zend\Captcha\AbstractWord` 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\`"). + +In addition to the methods required by the `Zend\Captcha\AdapterInterface` interface, +`Zend\Captcha\AbstractWord` exposes the following methods: + +- `setWordLen($length)` and `getWordLen()` allow you to specify the length of the generated "word" +in characters, and to retrieve the current value. +- `setTimeout($ttl)` and `getTimeout()` allow you to specify the time-to-live of the session token, +and to retrieve the current value. `$ttl` should be specified in seconds. +- `setUseNumbers($numbers)` and `getUseNumbers()` allow you to specify if numbers will be considered +as possible characters for the random work or only letters would be used. +- `setSessionClass($class)` and `getSessionClass()` allow you to specify an alternate +`Zend\Session\Container` implementation to use to persist the *CAPTCHA* token and to retrieve the +current value. +- `getId()` allows you to retrieve the current token identifier. +- `getWord()` allows you to retrieve the generated word to use with the *CAPTCHA*. It will generate +the word for you if none has been generated yet. +- `setSession(Zend\Session\Container $session)` allows you to specify a session object to use for +persisting the *CAPTCHA* token. `getSession()` allows you to retrieve the current session object. + +All word *CAPTCHA*s allow you to pass an array of options or `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. + +> ## Note +`Zend\Captcha\AbstractWord` is an abstract class and may not be instantiated directly. + +## Zend\\Captcha\\Dumb + +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`. + +## Zend\\Captcha\\Figlet + +The `Zend\Captcha\Figlet` adapter utilizes \[Zend\\Text\\Figlet\](zend.text.figlet) to present a +figlet to the user. + +Options passed to the constructor will also be passed to the +\[Zend\\Text\\Figlet\](zend.text.figlet) object. See the \[Zend\\Text\\Figlet\](zend.text.figlet) +documentation for details on what configuration options are available. + +## Zend\\Captcha\\Image + +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](http://php.net/gd) 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: + +- `setExpiration($expiration)` and `getExpiration()` allow you to specify a maximum lifetime the +*CAPTCHA* image may reside on the filesystem. This is typically a longer than the session lifetime. +Garbage collection is run periodically each time the *CAPTCHA* object is invoked, deleting all +images that have expired. Expiration values should be specified in seconds. +- `setGcFreq($gcFreq)` and `getGcFreg()` allow you to specify how frequently garbage collection +should run. Garbage collection will run every `1/$gcFreq` calls. The default is 100. +- `setFont($font)` and `getFont()` allow you to specify the font you will use. `$font` should be a +fully qualified path to the font file. This value is required; the *CAPTCHA* will throw an exception +during generation if the font file has not been specified. +- `setFontSize($fsize)` and `getFontSize()` allow you to specify the font size in pixels for +generating the *CAPTCHA*. The default is 24px. +- `setHeight($height)` and `getHeight()` allow you to specify the height in pixels of the generated +*CAPTCHA* image. The default is 50px. +- `setWidth($width)` and `getWidth()` allow you to specify the width in pixels of the generated +*CAPTCHA* image. The default is 200px. +- `setImgDir($imgDir)` and `getImgDir()` allow you to specify the directory for storing *CAPTCHA* +images. The default is "`./images/captcha/`", relative to the bootstrap script. +- `setImgUrl($imgUrl)` and `getImgUrl()` allow you to specify the relative path to a *CAPTCHA* image +to use for *HTML* markup. The default is "`/images/captcha/`". +- `setSuffix($suffix)` and `getSuffix()` allow you to specify the filename suffix for the *CAPTCHA* +image. The default is "`.png`". Note: changing this value will not change the type of the generated +image. +- `setDotNoiseLevel($level)` and `getDotNoiseLevel()`, along with `setLineNoiseLevel($level)` and +`getLineNoiseLevel()`, allow you to control how much "noise" in the form of random dots and lines +the image would contain. Each unit of `$level` produces one random dot or line. The default is 100 +dots and 5 lines. The noise is added twice - before and after the image distortion transformation. + +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. + +## Zend\\Captcha\\ReCaptcha + +The `Zend\Captcha\ReCaptcha` adapter uses +\[Zend\\Service\\ReCaptcha\\ReCaptcha\](zendservice.recaptcha) to generate and validate *CAPTCHA*s. +It exposes the following methods: + +- `setPrivKey($key)` and `getPrivKey()` allow you to specify the private key to use for the +ReCaptcha service. This must be specified during construction, although it may be overridden at any +point. +- `setPubKey($key)` and `getPubKey()` allow you to specify the public key to use with the ReCaptcha +service. This must be specified during construction, although it may be overridden at any point. +- `setService(ZendService\ReCaptcha\ReCaptcha $service)` and `getService()` allow you to set and get +the ReCaptcha service object. + diff --git a/doc/book/zend.captcha.intro.md b/doc/book/zend.captcha.intro.md new file mode 100644 index 0000000..58807dd --- /dev/null +++ b/doc/book/zend.captcha.intro.md @@ -0,0 +1,14 @@ +# Introduction to Zend\\Captcha + +[CAPTCHA](http://en.wikipedia.org/wiki/Captcha) stands for "Completely Automated Public Turing test +to tell Computers and Humans Apart"; it is used as a challenge-response to ensure that the +individual submitting information is a human and not an automated process. Typically, a captcha is +used with form submissions where authenticated users are not necessary, but you want to prevent spam +submissions. + +## Overview + +Captchas can take a variety of forms, including asking logic questions, presenting skewed fonts, and +presenting multiple images and asking how they relate. The `Zend\Captcha` component aims to provide +a variety of back ends that may be utilized either standalone or in conjunction with the +\[Zend\\Form component\](zend.form.intro). diff --git a/doc/book/zend.captcha.operation.md b/doc/book/zend.captcha.operation.md new file mode 100644 index 0000000..3a364a9 --- /dev/null +++ b/doc/book/zend.captcha.operation.md @@ -0,0 +1,60 @@ +# Captcha Operation + +## The AdapterInterface + +All *CAPTCHA* adapters implement `Zend\Captcha\AdapterInterface`, which looks like the following: + +``` sourceCode +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 methods are `generate()` and `render()`. `generate()` 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. `render()` is used to render the information that represents the *CAPTCHA*, +be it an image, a figlet, a logic problem, or some other *CAPTCHA*. + +## Basic Usage + +A simple use case might look like the following: + +``` sourceCode +// Originating request: +$captcha = new Zend\Captcha\Figlet(array( + 'name' => 'foo', + 'wordLen' => 6, + 'timeout' => 300, +)); + +$id = $captcha->generate(); + +//this will output a Figlet string +echo $captcha->getFiglet()->render($captcha->getWord()); + + +// On a subsequent request: +// Assume a captcha setup as before, with corresponding form fields, the value of $_POST['foo'] +// would be key/value array: id => captcha ID, input => captcha value +if ($captcha->isValid($_POST['foo'], $_POST)) { + // Validated! +} +``` + +> ## Note +Under most circumstances, you probably prefer the use of `Zend\Captcha` functionality combined with +the power of the `Zend\Form` component. For an example on how to use `Zend\Form\Element\Captcha`, +have a look at the \[Zend\\Form Quick Start\](zend.form.quick-start). diff --git a/doc/bookdown.json b/doc/bookdown.json new file mode 100644 index 0000000..25528eb --- /dev/null +++ b/doc/bookdown.json @@ -0,0 +1,9 @@ +{ + "title": "Zend\\Captcha", + "target": "html/", + "content": [ + "book/zend.captcha.intro.md", + "book/zend.captcha.operation.md", + "book/zend.captcha.adapters.md" + ] +} \ No newline at end of file