MINOR Documentation for HTTPRequest and RequestHandlingData

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@63655 467b73ca-7a2a-4603-9d3b-597d59a354a9
This commit is contained in:
Ingo Schommer 2008-10-05 22:16:07 +00:00
parent 52ae575630
commit 1bb708377d
2 changed files with 76 additions and 12 deletions

View File

@ -10,13 +10,19 @@
*
* @todo Accept X_HTTP_METHOD_OVERRIDE http header and $_REQUEST['_method'] to override request types (useful for webclients
* not supporting PUT and DELETE)
*
* @package sapphire
* @subpackage control
*/
class HTTPRequest extends Object implements ArrayAccess {
/**
* The non-extension parts of the URL, separated by "/"
* The non-extension parts of the URL, separated by "/".
* All elements of the URL are loaded in here,
* and subsequently popped out of the array by {@link shift()}.
*/
protected $dirParts;
/**
* The URL extension
*/
@ -27,8 +33,14 @@ class HTTPRequest extends Object implements ArrayAccess {
*/
protected $httpMethod;
/**
* @var array $getVars Contains alls HTTP GET parameters passed into this request.
*/
protected $getVars = array();
/**
* @var array $postVars Contains alls HTTP POST parameters passed into this request.
*/
protected $postVars = array();
/**
@ -46,8 +58,22 @@ class HTTPRequest extends Object implements ArrayAccess {
*/
protected $body;
/**
* @var array $allParams Contains an assiciative array of all
* arguments matched in all calls to {@link RequestHandlingData->handleRequest()}.
* Its a "historical record" thats specific to the current call of
* {@link handleRequest()}, and only complete once the last call is made.
*/
protected $allParams = array();
/**
* @var array $latestParams Contains an associative array of all
* arguments matched in the current call from {@link RequestHandlingData->handleRequest()},
* as denoted with a "$"-prefix in the $url_handler definitions.
* Contains different states throughout its lifespan, so just useful
* while processed in {@link RequestHandlingData} and to get the last
* processes arguments.
*/
protected $latestParams = array();
protected $unshiftedButParsedParts = 0;
@ -86,6 +112,14 @@ class HTTPRequest extends Object implements ArrayAccess {
function postVars() {
return $this->postVars;
}
/**
* Returns all combined HTTP GET and POST parameters
* passed into this request. If a parameter with the same
* name exists in both arrays, the POST value is returned.
*
* @return array
*/
function requestVars() {
return array_merge($this->getVars, $this->postVars);
}
@ -93,14 +127,24 @@ class HTTPRequest extends Object implements ArrayAccess {
function getVar($name) {
if(isset($this->getVars[$name])) return $this->getVars[$name];
}
function postVar($name) {
if(isset($this->postVars[$name])) return $this->postVars[$name];
}
function requestVar($name) {
if(isset($this->postVars[$name])) return $this->postVars[$name];
if(isset($this->getVars[$name])) return $this->getVars[$name];
}
/**
* Returns a possible file extension found in parsing the URL
* as denoted by a "."-character near the end of the URL.
* Doesn't necessarily have to belong to an existing file,
* for example used for {@link RestfulServer} content-type-switching.
*
* @return string
*/
function getExtension() {
return $this->extension;
}
@ -285,15 +329,16 @@ class HTTPRequest extends Object implements ArrayAccess {
} else if(!isset($this->dirParts[$i]) || $this->dirParts[$i] != $part) {
return false;
}
}
if($shiftOnSuccess) {
$this->shift($shiftCount);
// We keep track of pattern parts that we looked at but didn't shift off.
// This lets us say that we have *parsed* the whole URL even when we haven't *shifted* it all
$this->unshiftedButParsedParts = sizeof($patternParts) - $shiftCount;
}
$this->latestParams = $arguments;
// Load the arguments that actually have a value into $this->allParams
@ -318,6 +363,14 @@ class HTTPRequest extends Object implements ArrayAccess {
else
return null;
}
/**
* Finds a named URL parameter (denoted by "$"-prefix in $url_handlers)
* from the full URL.
*
* @param string $name
* @return string Value of the URL parameter (if found)
*/
function param($name) {
if(isset($this->allParams[$name]))
return $this->allParams[$name];
@ -325,6 +378,13 @@ class HTTPRequest extends Object implements ArrayAccess {
return null;
}
/**
* Returns the unparsed part of the original URL
* separated by commas. This is used by {@link RequestHandlingData->handleRequest()}
* to determine if further URL processing is necessary.
*
* @return string Partial URL
*/
function remaining() {
return implode("/", $this->dirParts);
}

View File

@ -5,20 +5,23 @@
*
* Any RequestHandlingData object can be made responsible for handling its own segment of the URL namespace.
* The {@link Director} begins the URL parsing process; it will parse the beginning of the URL to identify which
* controller is being used. It will then call handleRequest on that Controller, passing it the parameters that it
* parsed from the URL, and the HTTPRequest that contains the remainder of the URL to be parsed.
* controller is being used. It will then call {@link handleRequest()} on that Controller, passing it the parameters that it
* parsed from the URL, and the {@link HTTPRequest} that contains the remainder of the URL to be parsed.
*
* You can use ?debug_request=1 to view information about the different components and rule matches for a specific URL.
*
* In Sapphire, URL parsing is distributed throughout the object graph. For example, suppose that we have a search form
* that contains a {@link TreeMultiSelectField}, Groups. We want to use ajax to load segments of this tree as they are needed
* that contains a {@link TreeMultiSelectField} named "Groups". We want to use ajax to load segments of this tree as they are needed
* rather than downloading the tree right at the beginning. We could use this URL to get the tree segment that appears underneath
* Group #36:
*
* admin/crm/SearchForm/fields/Groups/treesegment/36
*
* Group #36: "admin/crm/SearchForm/field/Groups/treesegment/36"
* - Director will determine that admin/crm is controlled by a new ModelAdmin object, and pass control to that.
* Matching Director Rule: "admin/crm" => "ModelAdmin" (defined in mysite/_config.php)
* - ModelAdmin will determine that SearchForm is controlled by a Form object returned by $this->SearchForm(), and pass control to that.
* - Form will determine that fields/Groups is controlled by the Groups field, a TreeMultiselectField, and pass control to that.
* Matching $url_handlers: "$Action" => "$Action" (defined in RequestHandlingData class)
* - Form will determine that field/Groups is controlled by the Groups field, a TreeMultiselectField, and pass control to that.
* Matching $url_handlers: 'field/$FieldName!' => 'handleField' (defined in Form class)
* - TreeMultiselectField will determine that treesegment/36 is handled by its treesegment() method. This method will return an HTML fragment that is output to the screen.
* Matching $url_handlers: "$Action/$ID" => "handleItem" (defined in TreeMultiSelectField class)
*
* {@link RequestHandlingData::handleRequest()} is where this behaviour is implemented.
*/
@ -68,6 +71,7 @@ class RequestHandlingData extends ViewableData {
* @param $params The parameters taken from the parsed URL of the parent url handler
* @param $request The {@link HTTPRequest} object that is reponsible for distributing URL parsing
* @uses HTTPRequest
* @uses HTTPRequest->match()
* @return HTTPResponse|RequestHandlingData|string|array
*/
function handleRequest($request) {