PRADO Component Framework for PHP 5
  • Home
  • About
  • Testimonials
  • Demos
  • Download
  • Documentation
  • Forum
  • Development
  • Tutorials
  • Class Docs
  • API Manual
  • Wiki

Packages

  • None
  • System
    • Caching
    • Collections
    • Data
      • ActiveRecord
        • Relations
        • Scaffold
          • InputBuilder
      • Commom
        • Sqlite
      • Common
        • Mssql
        • Mysql
        • Oracle
        • Pgsql
        • Sqlite
      • DataGateway
      • SqlMap
        • Configuration
        • Statements
    • Exceptions
    • I18N
    • IO
    • Security
    • Util
    • Web
      • Javascripts
      • Services
      • UI
        • ActiveControls
        • WebControls
    • Xml
  • Wsat
    • pages
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated
  • Todo

Class TCaptcha

TCaptcha class.

Notice: while this class is easy to use and implement, it does not provide full security. In fact, it's easy to bypass the checks reusing old, already-validated tokens (reply attack). A better alternative is provided by TReCaptcha.

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 setMinTokenLength MinTokenLength and setMaxTokenLength MaxTokenLength. To use case-insensitive comparison and generate upper-case-only token, set setCaseSensitive CaseSensitive to false. Advanced users can try to set setTokenAlphabet TokenAlphabet, which specifies what characters can appear in tokens.

The validation of the token is related with two properties: setTestLimit TestLimit and setTokenExpiry 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 setTokenImageTheme TokenImageTheme to be an integer between 0 and 63. And to adjust the generated image size, set setTokenFontSize TokenFontSize (you may also set TWebControl::setWidth Width, but the scaled image may not look good.) By setting setChangingTokenBackground 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 TCaptcha::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 TCaptcha::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!" />
TComponent
Extended by TApplicationComponent
Extended by TControl implements IRenderable, IBindable
Extended by TWebControl implements IStyleable
Extended by TImage implements IDataRenderer
Extended by TCaptcha
Package: System\Web\UI\WebControls
Copyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.1.1
Located at Web/UI/WebControls/TCaptcha.php
Methods summary
public integer
# getTokenImageTheme( )

Returns

integer
the theme of the token image. Defaults to 0.
public
# setTokenImageTheme( integer $value )

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).

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).

Parameters

$value
integer
the theme of the token image. It must be an integer between 0 and 63.
public integer
# getTokenFontSize( )

Returns

integer
the font size used for displaying the token in an image. Defaults to 30.
public
# setTokenFontSize( integer $value )

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.

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.

Parameters

$value
integer
the font size used for displaying the token in an image. It must be an integer between 20 and 100.
public integer
# getMinTokenLength( )

Returns

integer
the minimum length of the token. Defaults to 4.
public
# setMinTokenLength( integer $value )

Parameters

$value
integer
the minimum length of the token. It must be between 2 and 40.
public integer
# getMaxTokenLength( )

Returns

integer
the maximum length of the token. Defaults to 6.
public
# setMaxTokenLength( integer $value )

Parameters

$value
integer
the maximum length of the token. It must be between 2 and 40.
public boolean
# getCaseSensitive( )

Returns

boolean
whether the token should be treated as case-sensitive. Defaults to true.
public
# setCaseSensitive( boolean $value )

Parameters

$value
boolean
whether the token should be treated as case-sensitive. If false, only upper-case letters will appear in the token.
public string
# getTokenAlphabet( )

Returns

string
the characters that may appear in the token. Defaults to '234578adefhijmnrtABDEFGHJLMNRT'.
public
# setTokenAlphabet( string $value )

Parameters

$value
string
the characters that may appear in the token. At least 2 characters must be specified.
public integer
# getTokenExpiry( )

Returns

integer
the number of seconds that a generated token will remain valid. Defaults to 600 seconds (10 minutes).
public
# setTokenExpiry( integer $value )

Parameters

$value
integer
the number of seconds that a generated token will remain valid. A value smaller than 1 means the token will not expire.
public boolean
# getChangingTokenBackground( )

Returns

boolean
whether the background of the token image should be variated during postbacks. Defaults to false.
public
# setChangingTokenBackground( boolean $value )

Parameters

$value
boolean
whether the background of the token image should be variated during postbacks.
public integer
# getTestLimit( )

Returns

integer
how many times a generated token can be tested. Defaults to 5.
public
# setTestLimit( integer $value )

Parameters

$value
integer
how many times a generated token can be tested. For unlimited tests, set it to 0.
public boolean
# getIsTokenExpired( )

Returns

boolean
whether the currently generated token has expired.
public string
# getPublicKey( )

Returns

string
the public key used for generating the token. A random one will be generated and returned if this is not set.
public
# setPublicKey( string $value )

Parameters

$value
string
the public key used for generating the token. A random one will be generated if this is not set.
public string
# getToken( )

Returns

string
the token that will be displayed
protected integer
# getTokenLength( )

Returns

integer
the length of the token to be generated.
public string
# getPrivateKey( )

Returns

string
the private key used for generating the token. This is randomly generated and kept in a file for persistency.
public boolean
# validate( string $input )

Validates a user input with the token.

Validates a user input with the token.

Parameters

$input
string
user input

Returns

boolean
if the user input is not the same as the token.
public
# regenerateToken( )

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.

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.

public
# onPreRender( mixed $param )

Configures the image URL that shows the token.

Configures the image URL that shows the token.

Parameters

$param
mixed
event parameter

Overrides

TWebControl::onPreRender()
protected string
# getTokenImageOptions( )

Returns

string
the options to be passed to the token image generator
protected string
# getCaptchaScriptFile( )

Returns

string
the file path of the PHP script generating the token image
protected
# getFontFile( )
protected string
# generatePrivateKeyFile( )

Generates a file with a randomly generated private key.

Generates a file with a randomly generated private key.

Returns

string
the path of the file keeping the private key
protected string
# generateRandomKey( )

Returns

string
a randomly generated key
protected string
# generateToken( string $publicKey, string $privateKey, integer $alphabet, boolean $tokenLength, mixed $caseSensitive )

Generates the token.

Generates the token.

Parameters

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

Returns

string
the token generated.
protected string
# hash2string( string $hex, string $alphabet = '' )

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

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

Parameters

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

Returns

string
the converted string
public static boolean
# checkRequirements( )

Checks the requirements needed for generating CAPTCHA images. TCaptach requires GD2 with TrueType font support and PNG image support.

Checks the requirements needed for generating CAPTCHA images. TCaptach requires GD2 with TrueType font support and PNG image support.

Returns

boolean
whether the requirements are satisfied.
Methods inherited from TImage
addAttributesToRender(), getAlternateText(), getData(), getDescriptionUrl(), getImageAlign(), getImageUrl(), getTagName(), renderContents(), setAlternateText(), setData(), setDescriptionUrl(), setImageAlign(), setImageUrl()
Methods inherited from TWebControl
clearStyle(), copyBaseAttributes(), createStyle(), getAccessKey(), getBackColor(), getBorderColor(), getBorderStyle(), getBorderWidth(), getCssClass(), getDecorator(), getDisplay(), getEnsureId(), getFont(), getForeColor(), getHasStyle(), getHeight(), getStyle(), getTabIndex(), getToolTip(), getWidth(), render(), renderBeginTag(), renderEndTag(), setAccessKey(), setBackColor(), setBorderColor(), setBorderStyle(), setBorderWidth(), setCssClass(), setDisplay(), setEnsureId(), setForeColor(), setHeight(), setStyle(), setTabIndex(), setToolTip(), setWidth()
Methods inherited from TControl
__construct(), __get(), addParsedObject(), addToPostDataLoader(), addedControl(), applyStyleSheetSkin(), autoBindProperty(), autoDataBindProperties(), bindProperty(), broadcastEvent(), bubbleEvent(), clearChildState(), clearControlState(), clearNamingContainer(), clearViewState(), convertUniqueIdToClientId(), createChildControls(), createControlCollection(), dataBind(), dataBindChildren(), dataBindProperties(), ensureChildControls(), findControl(), findControlsByID(), findControlsByType(), focus(), getAdapter(), getAllowChildControls(), getAttribute(), getAttributes(), getChildControlsCreated(), getClientID(), getControlStage(), getControlState(), getControls(), getCustomData(), getEnableTheming(), getEnableViewState(), getEnabled(), getHasAdapter(), getHasAttributes(), getHasChildInitialized(), getHasControls(), getHasInitialized(), getHasLoaded(), getHasLoadedPostData(), getHasPreRendered(), getID(), getIsSkinApplied(), getNamingContainer(), getPage(), getParent(), getRegisteredObject(), getSkinID(), getSourceTemplateControl(), getTemplateControl(), getUniqueID(), getViewState(), getVisible(), hasAttribute(), initRecursive(), isDescendentOf(), isObjectRegistered(), loadRecursive(), loadState(), loadStateRecursive(), onDataBinding(), onInit(), onLoad(), onUnload(), preRenderRecursive(), raiseBubbleEvent(), registerObject(), removeAttribute(), removedControl(), renderChildren(), renderControl(), saveState(), saveStateRecursive(), setAdapter(), setAttribute(), setChildControlsCreated(), setControlStage(), setControlState(), setCustomData(), setEnableTheming(), setEnableViewState(), setEnabled(), setID(), setPage(), setSkinID(), setTemplateControl(), setViewState(), setVisible(), trackViewState(), traverseChildControls(), unbindProperty(), unloadRecursive(), unregisterObject()
Methods inherited from TApplicationComponent
getApplication(), getRequest(), getResponse(), getService(), getSession(), getUser(), publishAsset(), publishFilePath()
Methods inherited from TComponent
__call(), __destruct(), __isset(), __set(), __sleep(), __unset(), __wakeup(), asa(), attachBehavior(), attachBehaviors(), attachClassBehavior(), attachEventHandler(), canGetProperty(), canSetProperty(), clearBehaviors(), createdOnTemplate(), detachBehavior(), detachBehaviors(), detachClassBehavior(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), evaluateStatements(), fxAttachClassBehavior(), fxDetachClassBehavior(), getAutoGlobalListen(), getBehaviorsEnabled(), getClassHierarchy(), getEventHandlers(), getListeningToGlobalEvents(), getSubProperty(), hasEvent(), hasEventHandler(), hasProperty(), isa(), listen(), raiseEvent(), setSubProperty(), unlisten()
Constants summary
integer MIN_TOKEN_LENGTH 2
#
integer MAX_TOKEN_LENGTH 40
#
Constants inherited from TControl
AUTOMATIC_ID_PREFIX, CLIENT_ID_SEPARATOR, CS_CHILD_INITIALIZED, CS_CONSTRUCTED, CS_INITIALIZED, CS_LOADED, CS_PRERENDERED, CS_STATE_LOADED, ID_FORMAT, ID_SEPARATOR, IS_CHILD_CREATED, IS_CREATING_CHILD, IS_DISABLE_THEMING, IS_DISABLE_VIEWSTATE, IS_ID_SET, IS_SKIN_APPLIED, IS_STYLESHEET_APPLIED, RF_ADAPTER, RF_AUTO_BINDINGS, RF_CHILD_STATE, RF_CONTROLS, RF_CONTROLSTATE, RF_DATA_BINDINGS, RF_EVENTS, RF_NAMED_CONTROLS, RF_NAMED_CONTROLS_ID, RF_NAMED_OBJECTS, RF_SKIN_ID
Constants inherited from TComponent
GLOBAL_RAISE_EVENT_LISTENER
Properties inherited from TWebControl
$_decorator
Terms of Service | Contact Us
PRADO v3.2.4 API Manual API documentation generated by ApiGen 2.8.0
Copyright © 2006-2014 by the PRADO Group.
Powered by PRADO