finished TCaptcha.

1 files changed, 77 insertions, 4 deletions

diff --git a/framework/Web/UI/WebControls/TCaptcha.php b/framework/Web/UI/WebControls/TCaptcha.php
index 17e9ad34..bff04236 100644
--- a/framework/Web/UI/WebControls/TCaptcha.php
+++ b/framework/Web/UI/WebControls/TCaptcha.php
@@ -18,11 +18,18 @@ Prado::using('System.Web.UI.WebControls.TImage');
  * 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 {@link setMinTokenLength MinTokenLength} and {@link setMaxTokenLength MaxTokenLength}.

  * To use case-insensitive comparison and generate upper-case-only token, set {@link setCaseSensitive CaseSensitive}

- * to false.

+ * to false. More advanced users can try to set {@link setTokenAlphabet TokenAlphabet}, which

+ * specifies what characters can appear in tokens.

+ *

+ * To specify the appearance of the generated token image, set {@link setTokenImageTheme TokenImageTheme}

+ * to be an integer between 0 and 31. And to adjust the generated image size, set {@link setTokenFontSize TokenFontSize}

+ * (you may also set {@link TWebControl::setWidth Width}, but the scaled image may not look good.)

  *

  * Upon postback, user input can be validated by calling {@link validate()}.

  * The {@link TCaptchaValidator} control can also be used to do validation, which provides

@@ -30,6 +37,15 @@ Prado::using('System.Web.UI.WebControls.TImage');
  * remain the same during multiple postbacks. A new one can be generated by calling

  * {@link regenerateToken()} manually.

  *

+ * The following template shows a typical use of TCaptcha control:

+ * <code>

+ * <com:TCaptcha ID="Captcha" />

+ * <com:TTextBox ID="Input" />

+ * <com:TCaptchaValidator CaptchaControl="Captcha"

+ *                        ControlToValidate="Input"

+ *                        ErrorMessage="You are challenged!" />

+ * </code>

+ *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Id$

  * @package System.Web.UI.WebControls

@@ -41,6 +57,9 @@ class TCaptcha extends TImage
 	const MAX_TOKEN_LENGTH=40;

 	private $_privateKey;

 

+	/**

+	 * Checks the requirements needed for using TCaptcha.

+	 */

 	public function onInit($param)

 	{

 		parent::onInit($param);

@@ -48,6 +67,58 @@ class TCaptcha extends TImage
 	}

 

 	/**

+	 * @return integer the theme of the token image. Defaults to 0.

+	 */

+	public function getTokenImageTheme()

+	{

+		return $this->getViewState('TokenImageTheme',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).

+	 * @param integer the theme of the token image. It must be an integer between 0 and 31.

+	 */

+	public function setTokenImageTheme($value)

+	{

+		$value=TPropertyValue::ensureInteger($value);

+		if($value>=0 && $value<=31)

+			$this->setViewState('TokenImageTheme',$value,0);

+		else

+			throw new TConfigurationException('captcha_tokenimagetheme_invalid',0,31);

+	}

+

+	/**

+	 * @return integer the font size used for displaying the token in an image. Defaults to 30.

+	 */

+	public function getTokenFontSize()

+	{

+		return $this->getViewState('TokenFontSize',30);

+	}

+

+	/**

+	 * 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.

+	 * @param integer the font size used for displaying the token in an image. It must be an integer between 20 and 100.

+	 */

+	public function setTokenFontSize($value)

+	{

+		$value=TPropertyValue::ensureInteger($value);

+		if($value>=20 && $value<=100)

+			$this->setViewState('TokenFontSize',$value,30);

+		else

+			throw new TConfigurationException('captcha_tokenfontsize_invalid',20,100);

+	}

+

+	/**

 	 * @return integer the minimum length of the token. Defaults to 5.

 	 */

 	public function getMinTokenLength()

@@ -104,11 +175,11 @@ class TCaptcha extends TImage
 	}

 

 	/**

-	 * @return string the characters that may appear in the token. Defaults to '234578adefhijmnrtABDEFGHJLMNQRT'.

+	 * @return string the characters that may appear in the token. Defaults to '234578adefhijmnrtABDEFGHJLMNRT'.

 	 */

 	public function getTokenAlphabet()

 	{

-		return $this->getViewState('TokenAlphabet','234578adefhijmnrtABDEFGHJLMNQRT');

+		return $this->getViewState('TokenAlphabet','234578adefhijmnrtABDEFGHJLMNRT');

 	}

 

 	/**

@@ -118,7 +189,7 @@ class TCaptcha extends TImage
 	{

 		if(strlen($value)<2)

 			throw new TConfigurationException('captcha_tokenalphabet_invalid');

-		$this->setViewState('TokenAlphabet',$value,'234578adefhijmnrtABDEFGHJLMNQRT');

+		$this->setViewState('TokenAlphabet',$value,'234578adefhijmnrtABDEFGHJLMNRT');

 	}

 

 	/**

@@ -241,6 +312,8 @@ class TCaptcha extends TImage
 		$options['tokenLength']=strlen($token);

 		$options['caseSensitive']=$this->getCaseSensitive();

 		$options['alphabet']=$this->getTokenAlphabet();

+		$options['fontSize']=$this->getTokenFontSize();

+		$options['theme']=$this->getTokenImageTheme();

 		$str=serialize($options);

 		return base64_encode(md5($privateKey.$str).$str);

 	}