/6_crm/sapphire/core/control/RequestHandler.php
PHP | 225 lines | 115 code | 22 blank | 88 comment | 39 complexity | fdaf7a024f83bfd643a4f4f8ac4043e8 MD5 | raw file
- <?php
- /**
- * This class is the base class of any Sapphire object that can be used to handle HTTP requests.
- *
- * Any RequestHandler 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 {@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} 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/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.
- * Matching $url_handlers: "$Action" => "$Action" (defined in RequestHandler 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 RequestHandler::handleRequest()} is where this behaviour is implemented.
- */
- class RequestHandler extends ViewableData {
- protected $request = null;
-
- /**
- * The default URL handling rules. This specifies that the next component of the URL corresponds to a method to
- * be called on this RequestHandlingData object.
- *
- * The keys of this array are parse rules. See {@link HTTPRequest::match()} for a description of the rules available.
- *
- * The values of the array are the method to be called if the rule matches. If this value starts with a '$', then the
- * named parameter of the parsed URL wil be used to determine the method name.
- */
- static $url_handlers = array(
- '$Action' => '$Action',
- );
-
- /**
- * Define a list of action handling methods that are allowed to be called directly by URLs.
- * The variable should be an array of action names. This sample shows the different values that it can contain:
- *
- * <code>
- * array(
- * 'someaction', // someaction can be accessed by anyone, any time
- * 'otheraction' => true, // So can otheraction
- * 'restrictedaction' => 'ADMIN', // restrictedaction can only be people with ADMIN privilege
- * 'complexaction' '->canComplexAction' // complexaction can only be accessed if $this->canComplexAction() returns true
- * );
- * </code>
- */
- static $allowed_actions = null;
- /**
- * Handles URL requests.
- *
- * - ViewableData::handleRequest() iterates through each rule in {@link self::$url_handlers}.
- * - If the rule matches, the named method will be called.
- * - If there is still more URL to be processed, then handleRequest() is called on the object that that method returns.
- *
- * Once all of the URL has been processed, the final result is returned. However, if the final result is an array, this
- * array is interpreted as being additional template data to customise the 2nd to last result with, rather than an object
- * in its own right. This is most frequently used when a Controller's action will return an array of data with which to
- * customise the controller.
- *
- * @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|RequestHandler|string|array
- */
- function handleRequest($request) {
- $this->request = $request;
-
- // $handlerClass is used to step up the class hierarchy to implement url_handlers inheritance
- $handlerClass = ($this->class) ? $this->class : get_class($this);
- // We stop after RequestHandler; in other words, at ViewableData
- while($handlerClass && $handlerClass != 'ViewableData') {
- // Todo: ajshort's stat rewriting could be useful here.
- $urlHandlers = eval("return $handlerClass::\$url_handlers;");
-
- if($urlHandlers) foreach($urlHandlers as $rule => $action) {
- if(isset($_REQUEST['debug_request'])) Debug::message("Testing '$rule' with '" . $request->remaining() . "' on $this->class");
- if($params = $request->match($rule, true)) {
- // FIXME: This unnecessary coupling was added to fix a bug in Image_Uploader.
- if($this instanceof Controller) $this->urlParams = $request->allParams();
-
- if(isset($_REQUEST['debug_request'])) {
- Debug::message("Rule '$rule' matched to action '$action' on $this->class. Latest request params: " . var_export($request->latestParams(), true));
- }
-
- // Actions can reference URL parameters, eg, '$Action/$ID/$OtherID' => '$Action',
- if($action[0] == '$') $action = $params[substr($action,1)];
-
- if($this->checkAccessAction($action)) {
- if(!$action) {
- if(isset($_REQUEST['debug_request'])) Debug::message("Action not set; using default action method name 'index'");
- $action = "index";
- } else if(!is_string($action)) {
- user_error("Non-string method name: " . var_export($action, true), E_USER_ERROR);
- }
- $result = $this->$action($request);
- } else {
- return $this->httpError(403, "Action '$action' isn't allowed on class $this->class");
- }
-
- if($result instanceof HTTPResponse && $result->isError()) {
- if(isset($_REQUEST['debug_request'])) Debug::message("Rule resulted in HTTP error; breaking");
- return $result;
- }
-
- // If we return a RequestHandler, call handleRequest() on that, even if there is no more URL to parse.
- // It might have its own handler. However, we only do this if we haven't just parsed an empty rule ourselves,
- // to prevent infinite loops
- if(!$request->isEmptyPattern($rule) && is_object($result) && $result instanceof RequestHandler) {
- $returnValue = $result->handleRequest($request);
- // Array results can be used to handle
- if(is_array($returnValue)) $returnValue = $this->customise($returnValue);
-
- return $returnValue;
-
- // If we return some other data, and all the URL is parsed, then return that
- } else if($request->allParsed()) {
- return $result;
-
- // But if we have more content on the URL and we don't know what to do with it, return an error.
- } else {
- return $this->httpError(400, "I can't handle sub-URLs of a $this->class object.");
- }
-
- return $this;
- }
- }
-
- $handlerClass = get_parent_class($handlerClass);
- }
-
- // If nothing matches, return this object
- return $this;
- }
- /**
- * Check that the given action is allowed to be called from a URL.
- * It will interrogate {@link self::$allowed_actions} to determine this.
- */
- function checkAccessAction($action) {
- // Collate self::$allowed_actions from this class and all parent classes
- $access = null;
- $className = ($this->class) ? $this->class : get_class($this);
- while($className && $className != 'RequestHandler') {
- // Merge any non-null parts onto $access.
- $accessPart = eval("return $className::\$allowed_actions;");
- if($accessPart != null) $access = array_merge((array)$access, $accessPart);
-
- // Build an array of parts for checking if part[0] == part[1], which means that this class doesn't directly define it.
- $accessParts[] = $accessPart;
-
- $className = get_parent_class($className);
- }
-
- // Add $allowed_actions from extensions
- if($this->extension_instances) {
- foreach($this->extension_instances as $inst) {
- $accessPart = $inst->stat('allowed_actions');
- if($accessPart !== null) $access = array_merge((array)$access, $accessPart);
- }
- }
- if($action == 'index') return true;
-
- // Make checkAccessAction case-insensitive
- $action = strtolower($action);
- if($access) {
- foreach($access as $k => $v) $newAccess[strtolower($k)] = strtolower($v);
- $access = $newAccess;
-
- if(isset($access[$action])) {
- $test = $access[$action];
- if($test === true) return true;
- if(substr($test,0,2) == '->') {
- $funcName = substr($test,2);
- return $this->$funcName();
- }
- if(Permission::check($test)) return true;
- } else if((($key = array_search($action, $access)) !== false) && is_numeric($key)) {
- return true;
- }
- }
- if($access === null || (isset($accessParts[1]) && $accessParts[0] === $accessParts[1])) {
- // If no allowed_actions are provided, then we should only let through actions that aren't handled by magic methods
- // we test this by calling the unmagic method_exists and comparing it to the magic $this->hasMethod(). This will
- // still let through actions that are handled by templates.
- return method_exists($this, $action) || !$this->hasMethod($action);
- }
- return false;
- }
- /**
- * Throw an HTTP error instead of performing the normal processing
- * @todo This doesn't work properly right now. :-(
- */
- function httpError($errorCode, $errorMessage = null) {
- $r = new HTTPResponse();
- $r->setBody($errorMessage);
- $r->setStatuscode($errorCode);
- return $r;
- }
-
- /**
- * Returns the HTTPRequest object that this controller is using.
- *
- * @return HTTPRequest
- */
- function getRequest() {
- return $this->request;
- }
- }