## Class TCaptcha

Description

TCaptcha class.

TCaptcha displays a CAPTCHA (a token displayed as an image) that can be used to determine if the input is entered by a real user instead of some program.

Unlike other CAPTCHA scripts, TCaptcha does not need session or cookie.

The token (a string consisting of alphanumeric characters) displayed is automatically generated and can be configured in several ways. To specify the length of characters in the token, set MinTokenLength and MaxTokenLength. To use case-insensitive comparison and generate upper-case-only token, set CaseSensitive to false. Advanced users can try to set TokenAlphabet, which specifies what characters can appear in tokens.

The validation of the token is related with two properties: TestLimit and TokenExpiry. The former specifies how many times a token can be tested with on the server side, and the latter says when a generated token will expire.

To specify the appearance of the generated token image, set TokenImageTheme to be an integer between 0 and 63. And to adjust the generated image size, set TokenFontSize (you may also set TWebControl::setWidth, but the scaled image may not look good.) By setting ChangingTokenBackground to true, the image background of the token will be variating even though the token is the same during postbacks.

Upon postback, user input can be validated by calling validate(). The TCaptchaValidator control can also be used to do validation, which provides client-side validation besides the server-side validation. By default, the token will remain the same during multiple postbacks. A new one can be generated by calling regenerateToken() manually.

The following template shows a typical use of TCaptcha control:

     <com:TCaptcha ID="Captcha" />
     <com:TTextBox ID="Input" />
     <com:TCaptchaValidator CaptchaControl="Captcha"
                            ControlToValidate="Input"
                            ErrorMessage="You are challenged!" />

- since: 3.1.1
- version: $Id: TCaptcha.php 2541 2008-10-21 15:05:13Z qiang.xue $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TCaptcha.php (line 60)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TImage
                   |
                   --TCaptcha

Class Constant Summary
MAX_TOKEN_LENGTH = 40
MIN_TOKEN_LENGTH = 2
Method Summary
boolean checkRequirements ()
string generatePrivateKeyFile ()
string generateRandomKey ()
string generateToken (string $publicKey, string $privateKey, integer $alphabet, boolean $tokenLength, mixed $caseSensitive)
string getCaptchaScriptFile ()
boolean getCaseSensitive ()
boolean getChangingTokenBackground ()
void getFontFile ()
boolean getIsTokenExpired ()
integer getMaxTokenLength ()
integer getMinTokenLength ()
string getPrivateKey ()
string getPublicKey ()
integer getTestLimit ()
string getToken ()
string getTokenAlphabet ()
integer getTokenExpiry ()
integer getTokenFontSize ()
string getTokenImageOptions ()
integer getTokenImageTheme ()
integer getTokenLength ()
string hash2string (string $hex, [string $alphabet = ''])
void onPreRender (mixed $param)
void regenerateToken ()
void setCaseSensitive (boolean $value)
void setChangingTokenBackground (boolean $value)
void setMaxTokenLength (integer $value)
void setMinTokenLength (integer $value)
void setPublicKey (string $value)
void setTestLimit (integer $value)
void setTokenAlphabet (string $value)
void setTokenExpiry (integer $value)
void setTokenFontSize (integer $value)
void setTokenImageTheme (integer $value)
boolean validate (string $input)
Methods
checkRequirements (line 486)

Checks the requirements needed for generating CAPTCHA images.

TCaptach requires GD2 with TrueType font support and PNG image support.

- return: whether the requirements are satisfied.
- static:
- access: public

boolean checkRequirements ()
generatePrivateKeyFile (line 417)

Generates a file with a randomly generated private key.

- return: the path of the file keeping the private key
- access: protected

string generatePrivateKeyFile ()
generateRandomKey (line 437)

- return: a randomly generated key
- access: protected

string generateRandomKey ()
generateToken (line 450)

Generates the token.

- return: the token generated.
- access: protected

string generateToken (string $publicKey, string $privateKey, integer $alphabet, boolean $tokenLength, mixed $caseSensitive)

- string $publicKey: public key
- string $privateKey: private key
- integer $alphabet: the length of the token
- boolean $tokenLength: whether the token is case sensitive

getCaptchaScriptFile (line 403)

- return: the file path of the PHP script generating the token image
- access: protected

string getCaptchaScriptFile ()
getCaseSensitive (line 163)

- return: whether the token should be treated as case-sensitive. Defaults to true.
- access: public

boolean getCaseSensitive ()
getChangingTokenBackground (line 213)

- return: whether the background of the token image should be variated during postbacks. Defaults to false.
- access: public

boolean getChangingTokenBackground ()
getFontFile (line 408)

- access: protected

void getFontFile ()
getIsTokenExpired (line 245)

- return: whether the currently generated token has expired.
- access: public

boolean getIsTokenExpired ()
getMaxTokenLength (line 143)

- return: the maximum length of the token. Defaults to 6.
- access: public

integer getMaxTokenLength ()
getMinTokenLength (line 123)

- return: the minimum length of the token. Defaults to 4.
- access: public

integer getMinTokenLength ()
getPrivateKey (line 305)

- return: the private key used for generating the token. This is randomly generated and kept in a file for persistency.
- access: public

string getPrivateKey ()
getPublicKey (line 256)

- return: the public key used for generating the token. A random one will be generated and returned if this is not set.
- access: public

string getPublicKey ()
getTestLimit (line 229)

- return: how many times a generated token can be tested. Defaults to 5.
- access: public

integer getTestLimit ()
getToken (line 277)

- return: the token that will be displayed
- access: public

string getToken ()
getTokenAlphabet (line 179)

- return: the characters that may appear in the token. Defaults to '234578adefhijmnrtABDEFGHJLMNRT'.
- access: public

string getTokenAlphabet ()
getTokenExpiry (line 197)

- return: the number of seconds that a generated token will remain valid. Defaults to 600 seconds (10 minutes).
- access: public

integer getTokenExpiry ()
getTokenFontSize (line 100)

- return: the font size used for displaying the token in an image. Defaults to 30.
- access: public

integer getTokenFontSize ()
getTokenImageOptions (line 379)

- return: the options to be passed to the token image generator
- access: protected

string getTokenImageOptions ()
getTokenImageTheme (line 70)

- return: the theme of the token image. Defaults to 0.
- access: public

integer getTokenImageTheme ()
getTokenLength (line 285)

- return: the length of the token to be generated.
- access: protected

integer getTokenLength ()
hash2string (line 462)

Converts a hash string into a string with characters consisting of alphanumeric characters.

- return: the converted string
- access: protected

string hash2string (string $hex, [string $alphabet = ''])

- string $hex: the hexadecimal representation of the hash string
- string $alphabet: the alphabet used to represent the converted string. If empty, it means '234578adefhijmnrtwyABDEFGHIJLMNQRTWY', which excludes those confusing characters.

onPreRender (line 359)

Configures the image URL that shows the token.

- access: public

void onPreRender (mixed $param)

- mixed $param: event parameter

Redefinition of:

TControl::onPreRender()
  This method is invoked when the control enters 'OnPreRender' stage.

regenerateToken (line 346)

Regenerates the token to be displayed.

By default, a token, once generated, will remain the same during the following page postbacks. Calling this method will generate a new token.

- access: public

void regenerateToken ()
setCaseSensitive (line 171)

- access: public

void setCaseSensitive (boolean $value)

- boolean $value: whether the token should be treated as case-sensitive. If false, only upper-case letters will appear in the token.

setChangingTokenBackground (line 221)

- access: public

void setChangingTokenBackground (boolean $value)

- boolean $value: whether the background of the token image should be variated during postbacks.

setMaxTokenLength (line 151)

- access: public

void setMaxTokenLength (integer $value)

- integer $value: the maximum length of the token. It must be between 2 and 40.

setMinTokenLength (line 131)

- access: public

void setMinTokenLength (integer $value)

- integer $value: the minimum length of the token. It must be between 2 and 40.

setPublicKey (line 269)

- access: public

void setPublicKey (string $value)

- string $value: the public key used for generating the token. A random one will be generated if this is not set.

setTestLimit (line 237)

- access: public

void setTestLimit (integer $value)

- integer $value: how many times a generated token can be tested. For unlimited tests, set it to 0.

setTokenAlphabet (line 187)

- access: public

void setTokenAlphabet (string $value)

- string $value: the characters that may appear in the token. At least 2 characters must be specified.

setTokenExpiry (line 205)

- access: public

void setTokenExpiry (integer $value)

- integer $value: the number of seconds that a generated token will remain valid. A value smaller than 1 means the token will not expire.

setTokenFontSize (line 111)

Sets the font size used for displaying the token in an image.

This property affects the generated token image size. The image width is proportional to this font size.

- access: public

void setTokenFontSize (integer $value)

- integer $value: the font size used for displaying the token in an image. It must be an integer between 20 and 100.

setTokenImageTheme (line 88)

Sets the theme of the token image.

You may test each theme to find out the one you like the most. Below is the explanation of the theme value: It is treated as a 5-bit integer. Each bit toggles a specific feature of the image. Bit 0 (the least significant): whether the image is opaque (1) or transparent (0). Bit 1: whether we should add white noise to the image (1) or not (0). Bit 2: whether we should add a grid to the image (1) or not (0). Bit 3: whether we should add some scribbles to the image (1) or not (0). Bit 4: whether the image background should be morphed (1) or not (0). Bit 5: whether the token text should cast a shadow (1) or not (0).

- access: public

void setTokenImageTheme (integer $value)

- integer $value: the theme of the token image. It must be an integer between 0 and 63.

validate (line 325)

Validates a user input with the token.

- return: if the user input is not the same as the token.
- access: public

boolean validate (string $input)

- string $input: user input

#### Inherited Methods

Inherited From TImage

> TImage::addAttributesToRender()
> TImage::getAlternateText()
> TImage::getData()
> TImage::getDescriptionUrl()
> TImage::getImageAlign()
> TImage::getImageUrl()
> TImage::getTagName()
> TImage::renderContents()
> TImage::setAlternateText()
> TImage::setData()
> TImage::setDescriptionUrl()
> TImage::setImageAlign()
> TImage::setImageUrl()

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::clearStyle()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> TWebControl::getDisplay()
> TWebControl::getFont()
> TWebControl::getForeColor()
> TWebControl::getHasStyle()
> TWebControl::getHeight()
> TWebControl::getStyle()
> TWebControl::getTabIndex()
> TWebControl::getTagName()
> TWebControl::getToolTip()
> TWebControl::getWidth()
> TWebControl::render()
> TWebControl::renderBeginTag()
> TWebControl::renderContents()
> TWebControl::renderEndTag()
> TWebControl::setAccessKey()
> TWebControl::setBackColor()
> TWebControl::setBorderColor()
> TWebControl::setBorderStyle()
> TWebControl::setBorderWidth()
> TWebControl::setCssClass()
> TWebControl::setDisplay()
> TWebControl::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::addToPostDataLoader()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::convertUniqueIdToClientId()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::dataBind()
> TControl::dataBindChildren()
> TControl::dataBindProperties()
> TControl::ensureChildControls()
> TControl::findControl()
> TControl::findControlsByID()
> TControl::findControlsByType()
> TControl::focus()
> TControl::getAdapter()
> TControl::getAllowChildControls()
> TControl::getAttribute()
> TControl::getAttributes()
> TControl::getChildControlsCreated()
> TControl::getClientID()
> TControl::getControls()
> TControl::getControlStage()
> TControl::getControlState()
> TControl::getCustomData()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasChildInitialized()
> TControl::getHasControls()
> TControl::getHasInitialized()
> TControl::getHasLoaded()
> TControl::getHasLoadedPostData()
> TControl::getHasPreRendered()
> TControl::getID()
> TControl::getNamingContainer()
> TControl::getPage()
> TControl::getParent()
> TControl::getRegisteredObject()
> TControl::getSkinID()
> TControl::getSourceTemplateControl()
> TControl::getTemplateControl()
> TControl::getUniqueID()
> TControl::getViewState()
> TControl::getVisible()
> TControl::hasAttribute()
> TControl::initRecursive()
> TControl::isDescendentOf()
> TControl::isObjectRegistered()
> TControl::loadRecursive()
> TControl::loadState()
> TControl::loadStateRecursive()
> TControl::onDataBinding()
> TControl::onInit()
> TControl::onLoad()
> TControl::onPreRender()
> TControl::onUnload()
> TControl::preRenderRecursive()
> TControl::raiseBubbleEvent()
> TControl::registerObject()
> TControl::removeAttribute()
> TControl::removedControl()
> TControl::render()
> TControl::renderChildren()
> TControl::renderControl()
> TControl::saveState()
> TControl::saveStateRecursive()
> TControl::setAdapter()
> TControl::setAttribute()
> TControl::setChildControlsCreated()
> TControl::setControlStage()
> TControl::setControlState()
> TControl::setCustomData()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::trackViewState()
> TControl::traverseChildControls()
> TControl::unbindProperty()
> TControl::unloadRecursive()
> TControl::unregisterObject()
> TControl::__get()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
MAX_TOKEN_LENGTH = 40 (line 63)
MIN_TOKEN_LENGTH = 2 (line 62)

#### Inherited Constants

Inherited from TControl

> TControl::AUTOMATIC_ID_PREFIX
> TControl::CLIENT_ID_SEPARATOR
> TControl::CS_CHILD_INITIALIZED
> TControl::CS_CONSTRUCTED
> TControl::CS_INITIALIZED
> TControl::CS_LOADED
> TControl::CS_PRERENDERED
> TControl::CS_STATE_LOADED
> TControl::ID_FORMAT
> TControl::ID_SEPARATOR
> TControl::IS_CHILD_CREATED
> TControl::IS_CREATING_CHILD
> TControl::IS_DISABLE_THEMING
> TControl::IS_DISABLE_VIEWSTATE
> TControl::IS_ID_SET
> TControl::IS_SKIN_APPLIED
> TControl::IS_STYLESHEET_APPLIED
> TControl::RF_ADAPTER
> TControl::RF_AUTO_BINDINGS
> TControl::RF_CHILD_STATE
> TControl::RF_CONTROLS
> TControl::RF_CONTROLSTATE
> TControl::RF_DATA_BINDINGS
> TControl::RF_EVENTS
> TControl::RF_NAMED_CONTROLS
> TControl::RF_NAMED_CONTROLS_ID
> TControl::RF_NAMED_OBJECTS
> TControl::RF_SKIN_ID

Documentation generated on Sun, 11 Jan 2009 20:19:31 -0500 by phpDocumentor 1.3.0RC4