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:

  1. <com:TCaptcha ID="Captcha" />
  2. <com:TTextBox ID="Input" />
  3. <com:TCaptchaValidator CaptchaControl="Captcha"
  4. ControlToValidate="Input"
  5. ErrorMessage="You are challenged!" />

  • since: 3.1.1
  • version: $Id: TCaptcha.php 2265 2007-09-29 14:33:13Z 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
Method Summary
boolean checkRequirements ()
string generateRandomKey ()
string generateToken (string $publicKey, string $privateKey, integer $alphabet, boolean $tokenLength, mixed $caseSensitive)
boolean getCaseSensitive ()
void getFontFile ()
boolean getIsTokenExpired ()
integer getMaxTokenLength ()
integer getMinTokenLength ()
string getPrivateKey ()
string getPublicKey ()
integer getTestLimit ()
string getToken ()
string getTokenAlphabet ()
integer getTokenExpiry ()
integer getTokenFontSize ()
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

Documentation generated on Mon, 21 Apr 2008 11:32:39 -0400 by phpDocumentor 1.3.0RC4