Added documentation.

1 files changed, 63 insertions, 4 deletions

diff --git a/framework/Web/UI/TPageStatePersister.php b/framework/Web/UI/TPageStatePersister.php
index 9c9954de..d312ed84 100644
--- a/framework/Web/UI/TPageStatePersister.php
+++ b/framework/Web/UI/TPageStatePersister.php
@@ -1,12 +1,44 @@
 <?php

+/**

+ * TPageStatePersister class file

+ *

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

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 2005 PradoSoft

+ * @license http://www.pradosoft.com/license/

+ * @version $Revision: $  $Date: $

+ * @package System.Web.UI

+ */

 

+/**

+ * TPageStatePersister class

+ *

+ * TPageStatePersister implements a page state persistent method based on

+ * form hidden fields. It is the default way of storing page state.

+ * Should you need to access this module, you may get it via

+ * {@link TPageService::getPageStatePersister}.

+ *

+ * TPageStatePersister uses a private key to generate a private unique hash

+ * code to prevent the page state from being tampered.

+ * By default, the private key is a randomly generated string.

+ * You may specify it explicitly by setting the {@link setPrivateKey PrivateKey} property.

+ * This may be useful if your application is running on a server farm.

+ *

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

+ * @version $Revision: $  $Date: $

+ * @package System.Web.UI

+ * @since 3.0

+ */

 class TPageStatePersister extends TModule implements IStatePersister

 {

+	/**

+	 * @var string private key

+	 */

 	private $_privateKey=null;

 

 	/**

-	 * Initializes the service.

-	 * This method is required by IModule interface.

+	 * Registers the module with the page service.

+	 * This method is required by IModule interface and is invoked when the module is initialized.

 	 * @param TXmlElement module configuration

 	 */

 	public function init($config)

@@ -14,6 +46,10 @@ class TPageStatePersister extends TModule implements IStatePersister
 		$this->getService()->setPageStatePersister($this);

 	}

 

+	/**

+	 * Saves state in hidden fields.

+	 * @param mixed state to be stored

+	 */

 	public function save($state)

 	{

 		$data=Prado::serialize($state);

@@ -25,6 +61,11 @@ class TPageStatePersister extends TModule implements IStatePersister
 		$this->getService()->getRequestedPage()->getClientScript()->registerHiddenField(TPage::FIELD_PAGESTATE,base64_encode($data));

 	}

 

+	/**

+	 * Loads page state from hidden fields.

+	 * @return mixed the restored state

+	 * @throws THttpException if page state is corrupted

+	 */

 	public function load()

 	{

 		$str=base64_decode($this->getApplication()->getRequest()->getItems()->itemAt(TPage::FIELD_PAGESTATE));

@@ -41,9 +82,14 @@ class TPageStatePersister extends TModule implements IStatePersister
 			if($hmac===$this->computeHMAC($state,$this->getPrivateKey()))

 				return Prado::unserialize($state);

 		}

-		throw new TInvalidDataValueException('pagestatepersister_viewstate_corrupted.');

+		throw new THttpException(400,'pagestatepersister_pagestate_corrupted');

 	}

 

+	/**

+	 * Generates a random private key used for hashing the state.

+	 * You may override this method to provide your own way of private key generation.

+	 * @return string  the rondomly generated private key

+	 */

 	protected function generatePrivateKey()

 	{

 		$v1=rand();

@@ -52,6 +98,9 @@ class TPageStatePersister extends TModule implements IStatePersister
 		return md5("$v1$v2$v3");

 	}

 

+	/**

+	 * @return string private key used for hashing the state.

+	 */

 	public function getPrivateKey()

 	{

 		if(empty($this->_privateKey))

@@ -65,13 +114,23 @@ class TPageStatePersister extends TModule implements IStatePersister
 		return $this->_privateKey;

 	}

 

+	/**

+	 * @param string private key used for hashing the state.

+	 * @throws TInvalidDataValueException if the length of the private key is shorter than 8.

+	 */

 	public function setPrivateKey($value)

 	{

 		if(strlen($value)<8)

-			throw new TConfigurationException('pagestatepersister_privatekey_invalid');

+			throw new TInvalidDataValueException('pagestatepersister_privatekey_invalid');

 		$this->_privateKey=$value;

 	}

 

+	/**

+	 * Computes a hashing code based on the input data and the private key.

+	 * @param string input data

+	 * @param string the private key

+	 * @return string the hashing code

+	 */

 	private function computeHMAC($data,$key)

 	{

 		if (strlen($key) > 64)