From: Brion Vibber <brion@users.mediawiki.org>
Date: Sat, 4 Sep 2004 00:12:08 +0000 (+0000)
Subject: Add some documentation comments
X-Git-Tag: 1.5.0alpha1~2119
X-Git-Url: http://git.cyclocoop.org/%7B%24www_url%7Dadmin/password.php?a=commitdiff_plain;h=0e082d44544b2512812397aaaff65adb12d94be0;p=lhc%2Fweb%2Fwiklou.git

Add some documentation comments
---

diff --git a/includes/WebRequest.php b/includes/WebRequest.php
index 04cc51d0f5..de7c13ac2b 100644
--- a/includes/WebRequest.php
+++ b/includes/WebRequest.php
@@ -23,8 +23,15 @@
 # http://www.gnu.org/copyleft/gpl.html
 
 /**
- * Hypothetically, we could use a WebRequest object to fake a
- * self-contained request (FauxRequest).
+ * The WebRequest class encapsulates getting at data passed in the
+ * URL or via a POSTed form, handling remove of "magic quotes" slashes,
+ * stripping illegal input characters and normalizing Unicode sequences.
+ *
+ * Usually this is used via a global singleton, $wgRequest. You should
+ * not create a second WebRequest object; make a FauxRequest object if
+ * you want to pass arbitrary data to some function in place of the web
+ * input.
+ *
  * @package MediaWiki
  */
 class WebRequest {
@@ -44,6 +51,11 @@ class WebRequest {
 		}
 	}
 
+	/**
+	 * Recursively strips slashes from the given array;
+	 * used for undoing the evil that is magic_quotes_gpc.
+	 * @private
+	 */
 	function &fix_magic_quotes( &$arr ) {
 		foreach( $arr as $key => $val ) {
 			if( is_array( $val ) ) {
@@ -55,6 +67,13 @@ class WebRequest {
 		return $arr;
 	}
 	
+	/**
+	 * If magic_quotes_gpc option is on, run the global arrays
+	 * through fix_magic_quotes to strip out the stupid dlashes.
+	 * WARNING: This should only be done once! Running a second
+	 * time could damage the values.
+	 * @private
+	 */
 	function checkMagicQuotes() {
 		if ( get_magic_quotes_gpc() ) {
 			$this->fix_magic_quotes( $_COOKIE );
@@ -66,6 +85,10 @@ class WebRequest {
 		}
 	}
 	
+	/**
+	 * Recursively normalizes UTF-8 strings in the given array.
+	 * @private
+	 */
 	function normalizeUnicode( &$arr ) {
 		foreach( $arr as $key => $val ) {
 			if( is_array( $val ) ) {
@@ -76,6 +99,10 @@ class WebRequest {
 		}
 	}
 	
+	/**
+	 * Fetch a value from the given array or return $default if it's not set.
+	 * @private
+	 */
 	function getGPCVal( &$arr, $name, $default ) {
 		if( isset( $arr[$name] ) ) {
 			return $arr[$name];
@@ -84,6 +111,12 @@ class WebRequest {
 		}
 	}
 	
+	/**
+	 * Fetch a value from the given array or return $default if it's not set.
+	 * \r is stripped from the text, and with some language modules there is
+	 * an input transliteration applied.
+	 * @private
+	 */
 	function getGPCText( &$arr, $name, $default ) {
 		# Text fields may be in an alternate encoding which we should check.
 		# Also, strip CRLF line endings down to LF to achieve consistency.
@@ -95,18 +128,37 @@ class WebRequest {
 		}
 	}
 	
+	/**
+	 * Fetch a value from the input or return $default if it's not set.
+	 * Value may be of any type -- even an array -- and is not altered.
+	 */
 	function getVal( $name, $default = NULL ) {
 		return $this->getGPCVal( $_REQUEST, $name, $default );
 	}
 	
+	/**
+	 * Fetch an integer value from the input or return $default if not set.
+	 * Guaranteed to return an integer; non-integer input will typically
+	 * return 0.
+	 */
 	function getInt( $name, $default = 0 ) {
 		return IntVal( $this->getVal( $name, $default ) );
 	}
 	
+	/**
+	 * Fetch a boolean value from the input or return $default if not set.
+	 * Guaranteed to return true or false, with normal PHP semantics for
+	 * boolean interpretation of strings.
+	 */
 	function getBool( $name, $default = false ) {
 		return $this->getVal( $name, $default ) ? true : false;
 	}
 	
+	/**
+	 * Return true if the named value is set in the input, whatever that
+	 * value is (even "0"). Return false if the named value is not set.
+	 * Example use is checking for the presence of check boxes in forms.
+	 */
 	function getCheck( $name ) {
 		# Checkboxes and buttons are only present when clicked
 		# Presence connotes truth, abscense false
@@ -114,10 +166,21 @@ class WebRequest {
 		return isset( $val );
 	}
 	
+	/**
+	 * Fetch a text string from the given array or return $default if it's not
+	 * set. \r is stripped from the text, and with some language modules there 
+	 * is an input transliteration applied. This should generally be used for
+	 * form <textarea> and <input> fields.
+	 */
 	function getText( $name, $default = '' ) {
 		return $this->getGPCText( $_REQUEST, $name, $default );
 	}
 	
+	/**
+	 * Extracts the given named values into an array.
+	 * If no arguments are given, returns all input values.
+	 * No transformation is performed on the values.
+	 */
 	function getValues() {	
 		$names = func_get_args();
 		if ( count( $names ) == 0 ) {
@@ -134,18 +197,35 @@ class WebRequest {
 		return $retVal;
 	}
 
+	/**
+	 * Returns true if the present request was reached by a POST operation,
+	 * false otherwise (GET, HEAD, or command-line).
+	 *
+	 * Note that values retrieved by the object may come from the
+	 * GET URL etc even on a POST request.
+	 */
 	function wasPosted() {
 		return $_SERVER['REQUEST_METHOD'] == 'POST';
 	}
 	
+	/**
+	 * Returns true if there is a session cookie set.
+	 * This does not necessarily mean that the user is logged in!
+	 */
 	function checkSessionCookie() {
 		return isset( $_COOKIE[ini_get('session.name')] );
 	}
 	
+	/**
+	 * Return the path portion of the request URI.
+	 */
 	function getRequestURL() {
 		return $_SERVER['REQUEST_URI'];
 	}
 	
+	/**
+	 * Return the request URI with the canonical service and hostname.
+	 */
 	function getFullRequestURL() {
 		global $wgServer;
 		return $wgServer . $this->getRequestURL();
@@ -168,6 +248,9 @@ class WebRequest {
 		return $wgTitle->getLocalURL( $basequery );
 	}
 	
+	/**
+	 * HTML-safe version of appendQuery().
+	 */
 	function escapeAppendQuery( $query ) {
 		return htmlspecialchars( $this->appendQuery( $query ) );
 	}
@@ -190,7 +273,8 @@ class WebRequest {
 	}
 	
 	/**
-	 * Get information on uploaded files
+	 * Return the path to the temporary file where PHP has stored the upload.
+	 * Returns NULL if no such thing.
 	 */
 	function getFileTempname( $key ) {
 		if( !isset( $_FILES[$key] ) ) {
@@ -199,6 +283,9 @@ class WebRequest {
 		return $_FILES[$key]['tmp_name'];
 	}
 	
+	/**
+	 * Return the size of the upload, or 0.
+	 */
 	function getFileSize( $key ) {
 		if( !isset( $_FILES[$key] ) ) {
 			return 0;
@@ -206,6 +293,14 @@ class WebRequest {
 		return $_FILES[$key]['size'];
 	}
 	
+	/**
+	 * Return the original filename of the uploaded file, as reported by
+	 * the submitting user agent. HTML-style character entities are
+	 * interpreted and normalized to Unicode normalization form C, in part
+	 * to deal with weird input from Safari with non-ASCII filenames.
+	 *
+	 * Other than this the name is not verified for being a safe filename.
+	 */
 	function getFileName( $key ) {
 		if( !isset( $_FILES[$key] ) ) {
 			return NULL;
@@ -229,6 +324,7 @@ class WebRequest {
 }
 
 /**
+ * WebRequest clone which takes values from a provided array.
  *
  * @package MediaWiki
  */