MINOR: HTTPRequest and HTTPResponse now return $this on all setters

MINOR: also added some docs

control/HTTPRequest.php

@@ -121,38 +121,68 @@ class SS_HTTPRequest implements ArrayAccess {
 		$this->postVars = (array)$postVars;
 		$this->body = $body;
 	}
-	
+
+	/**
+	 * @return bool
+	 */
 	public function isGET() {
 		return $this->httpMethod == 'GET';
 	}
-	
+
+	/**
+	 * @return bool
+	 */
 	public function isPOST() {
 		return $this->httpMethod == 'POST';
 	}
-	
+
+	/**
+	 * @return bool
+	 */
 	public function isPUT() {
 		return $this->httpMethod == 'PUT';
 	}
 
+	/**
+	 * @return bool
+	 */
 	public function isDELETE() {
 		return $this->httpMethod == 'DELETE';
-	}	
+	}
 
+	/**
+	 * @return bool
+	 */
 	public function isHEAD() {
 		return $this->httpMethod == 'HEAD';
-	}	
+	}
-	
+
+	/**
+	 * @param string $body
+	 * @return SS_HTTPRequest $this
+	 */
 	public function setBody($body) {
 		$this->body = $body;
+		return $this;
 	}
-	
+
+	/**
+	 * @return null|string
+	 */
 	public function getBody() {
 		return $this->body;
 	}
-	
+
+	/**
+	 * @return array
+	 */
 	public function getVars() {
 		return $this->getVars;
 	}
+
+	/**
+	 * @return array
+	 */
 	public function postVars() {
 		return $this->postVars;
 	}
@@ -167,15 +197,27 @@ class SS_HTTPRequest implements ArrayAccess {
 	public function requestVars() {
 		return ArrayLib::array_merge_recursive($this->getVars, $this->postVars);
 	}
-	
+
+	/**
+	 * @param string $name
+	 * @return mixed
+	 */
 	public function getVar($name) {
 		if(isset($this->getVars[$name])) return $this->getVars[$name];
 	}
-	
+
+	/**
+	 * @param string $name
+	 * @return mixed
+	 */
 	public function postVar($name) {
 		if(isset($this->postVars[$name])) return $this->postVars[$name];
 	}
-	
+
+	/**
+	 * @param string $name
+	 * @return mixed
+	 */
 	public function requestVar($name) {
 		if(isset($this->postVars[$name])) return $this->postVars[$name];
 		if(isset($this->getVars[$name])) return $this->getVars[$name];
@@ -227,6 +269,7 @@ class SS_HTTPRequest implements ArrayAccess {
 	 * Remove an existing HTTP header
 	 *
 	 * @param string $header
+	 * @return mixed
 	 */
 	public function getHeader($header) {
 		return (isset($this->headers[$header])) ? $this->headers[$header] : null;			
@@ -237,16 +280,17 @@ class SS_HTTPRequest implements ArrayAccess {
 	 * e.g. "Content-Type".
 	 *
 	 * @param string $header
+	 * @return SS_HTTPRequest $this
 	 */
 	public function removeHeader($header) {
 		if(isset($this->headers[$header])) unset($this->headers[$header]);
+		return $this;
 	}
 	
 	/**
 	 * Returns the URL used to generate the page
 	 *
 	 * @param bool $includeGetVars whether or not to include the get parameters\
-	 * 
 	 * @return string
 	 */
 	public function getURL($includeGetVars = false) {
@@ -318,6 +362,12 @@ class SS_HTTPRequest implements ArrayAccess {
 	
 	/**
 	 * Construct an SS_HTTPResponse that will deliver a file to the client
+	 *
+	 * @static
+	 * @param $fileData
+	 * @param $fileName
+	 * @param null $mimeType
+	 * @return SS_HTTPResponse
 	 */
 	public static function send_file($fileData, $fileName, $mimeType = null) {
 		if(!$mimeType) {
@@ -350,6 +400,10 @@ class SS_HTTPRequest implements ArrayAccess {
 	 * 
 	 * The pattern can optionally start with an HTTP method and a space.  For example, "POST $Controller/$Action".
 	 * This is used to define a rule that only matches on a specific HTTP method.
+	 *
+	 * @param $pattern
+	 * @param bool $shiftOnSuccess
+	 * @return array|bool
 	 */
 	public function match($pattern, $shiftOnSuccess = false) {
 		// Check if a specific method is required
@@ -431,7 +485,10 @@ class SS_HTTPRequest implements ArrayAccess {
 		if($arguments === array()) $arguments['_matched'] = true;
 		return $arguments;
 	}
-	
+
+	/**
+	 * @return array
+	 */
 	public function allParams() {
 		return $this->allParams;
 	}
@@ -457,26 +514,43 @@ class SS_HTTPRequest implements ArrayAccess {
 
 		return $value;
 	}
-	
+
+	/**
+	 * @return array
+	 */
 	public function latestParams() {
 		return $this->latestParams;
 	}
-	
+
+	/**
+	 * @param string $name
+	 * @return string|null
+	 */
 	public function latestParam($name) {
 		if(isset($this->latestParams[$name])) return $this->latestParams[$name];
 		else return null;
 	}
-	
+
+	/**
+	 * @return array
+	 */
 	public function routeParams() {
 		return $this->routeParams;
 	}
-	
+
+	/**
+	 * @param $params
+	 * @return SS_HTTPRequest $this
+	 */
 	public function setRouteParams($params) {
 		$this->routeParams = $params;
+		return $this;
 	}
-	
+
-	public function params()
+	/**
-	{
+	 * @return array
+	 */
+	public function params() {
 		return array_merge($this->allParams, $this->routeParams);
 	}
 	
@@ -507,6 +581,9 @@ class SS_HTTPRequest implements ArrayAccess {
 	/**
 	 * Returns true if this is a URL that will match without shifting off any of the URL.
 	 * This is used by the request handler to prevent infinite parsing loops.
+	 *
+	 * @param $pattern
+	 * @return bool
 	 */
 	public function isEmptyPattern($pattern) {
 		if(preg_match('/^([A-Za-z]+) +(.*)$/', $pattern, $matches)) {
@@ -521,7 +598,6 @@ class SS_HTTPRequest implements ArrayAccess {
 	 * If you specify shifting more than 1 item off, then the items will be returned as an array
 	 *
 	 * @param int $count Shift Count
-	 *
 	 * @return String|Array
 	 */
 	public function shift($count = 1) {
@@ -543,6 +619,8 @@ class SS_HTTPRequest implements ArrayAccess {
 	/**
 	 * Returns true if the URL has been completely parsed.
 	 * This will respect parsed but unshifted directory parts.
+	 *
+	 * @return bool
 	 */
 	public function allParsed() {
 		return sizeof($this->dirParts) <= $this->unshiftedButParsedParts;

control/HTTPResponse.php

@@ -108,6 +108,7 @@ class SS_HTTPResponse {
 	 *  No newlines are allowed in the description.
 	 *  If omitted, will default to the standard HTTP description
 	 *  for the given $code value (see {@link $status_codes}).
+	 * @return SS_HTTPRequest $this
 	 */
 	public function setStatusCode($code, $description = null) {
 		if(isset(self::$status_codes[$code])) $this->statusCode = $code;
@@ -115,16 +116,19 @@ class SS_HTTPResponse {
 		
 		if($description) $this->statusDescription = $description;
 		else $this->statusDescription = self::$status_codes[$code];
+		return $this;
 	}
 	
 	/**
 	 * The text to be given alongside the status code ("reason phrase").
 	 * Caution: Will be overwritten by {@link setStatusCode()}.
 	 * 
-	 * @param String $description 
+	 * @param String $description
+	 * @return SS_HTTPRequest $this
 	 */
 	public function setStatusDescription($description) {
 		$this->statusDescription = $description;
+		return $this;
 	}
 	
 	/**
@@ -143,18 +147,28 @@ class SS_HTTPResponse {
 	
 	/**
 	 * Returns true if this HTTP response is in error
+	 *
+	 * @return bool
 	 */
 	public function isError() {
 		return $this->statusCode && ($this->statusCode < 200 || $this->statusCode > 399);
 	}
-	
+
+	/**
+	 * @param string $body
+	 * @return SS_HTTPRequest $this
+	 */
 	public function setBody($body) {
 		$this->body = $body;
 		
 		// Set content-length in bytes. Use mbstring to avoid problems with mb_internal_encoding() and mbstring.func_overload
 		$this->headers['Content-Length'] = mb_strlen($this->body,'8bit');
+		return $this;
 	}
-	
+
+	/**
+	 * @return null|string
+	 */
 	public function getBody() {
 		return $this->body;
 	}
@@ -163,24 +177,24 @@ class SS_HTTPResponse {
 	 * Add a HTTP header to the response, replacing any header of the same name.
 	 * 
 	 * @param string $header Example: "Content-Type"
-	 * @param string $value Example: "text/xml" 
+	 * @param string $value Example: "text/xml"
+	 * @return SS_HTTPRequest $this
 	 */
 	public function addHeader($header, $value) {
 		$this->headers[$header] = $value;
+		return $this;
 	}
 	
 	/**
 	 * Return the HTTP header of the given name.
 	 * 
 	 * @param string $header
-	 * @returns string
+	 * @returns null|string
 	 */
 	public function getHeader($header) {
-		if(isset($this->headers[$header])) {
+		if(isset($this->headers[$header]))
-			return $this->headers[$header];			
+			return $this->headers[$header];
-		} else {
+		return null;
-			return null;
-		}
 	}
 	
 	/**
@@ -194,16 +208,24 @@ class SS_HTTPResponse {
 	 * Remove an existing HTTP header by its name,
 	 * e.g. "Content-Type".
 	 *
-	 * @param unknown_type $header
+	 * @param string $header
+	 * @return SS_HTTPRequest $this
 	 */
 	public function removeHeader($header) {
 		if(isset($this->headers[$header])) unset($this->headers[$header]);
+		return $this;
 	}
-	
+
+	/**
+	 * @param string $dest
+	 * @param int $code
+	 * @return SS_HTTPRequest $this
+	 */
 	public function redirect($dest, $code=302) {
 		if(!in_array($code, self::$redirect_codes)) $code = 302;
 		$this->setStatusCode($code);
 		$this->headers['Location'] = $dest;
+		return $this;
 	}
 
 	/**
@@ -244,6 +266,8 @@ class SS_HTTPResponse {
 	/**
 	 * Returns true if this response is "finished", that is, no more script execution should be done.
 	 * Specifically, returns true if a redirect has already been requested
+	 *
+	 * @return bool
 	 */
 	public function isFinished() {
 		return in_array($this->statusCode, array(301, 302, 401, 403));