|
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
-
TApplicationComponent
-
TControl
implements
IRenderable,
IBindable
-
TWebControl
implements
IStyleable
-
TImage
implements
IDataRenderer
-
TCaptcha
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
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
|
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
|
|
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.
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 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
|
|