/**
* Dispatches a URI for internal processing.
* Usually called by a front controller.
* @method dispatch
* @static
* @param {mixed} [$uri=null] You can pass a custom URI to dispatch. Otherwise, Qbix will attempt
* to route the requested URL, if any.
* @param {array} [$check=array('accessible')] Pass array() to skip checking whether the URI can be obtained
* as a result of routing some URL.
* @return {boolean}
* @throws {Q_Exception_MethodNotSupported}
* @throws {Q_Exception_Recursion}
* @throws {Q_Exception_DispatcherErrors}
* @throws {Q_Exception_DispatcherForward}
*/
static function dispatch($uri = null, $check = array('accessible'))
{
self::$startedDispatch = true;
self::$servedResponse = false;
if (!is_array($check)) {
$check = array('accessible');
}
if (isset($uri)) {
if (in_array('accessible', $check)) {
if (!Q_Uri::url($uri)) {
// We shouldn't dispatch to this URI
$uri = Q_Uri::from(array());
}
}
self::$uri = Q_Uri::from($uri);
} else {
$request_uri = Q_Request::uri();
self::$uri = clone $request_uri;
}
// if file or dir is requested, try to serve it
$served = false;
$skip = Q_Config::get('Q', 'dispatcherSkipFilename', false);
$filename = $skip ? false : Q_Request::filename();
if ($filename) {
if (is_dir($filename)) {
/**
* @event Q/dir
* @param {string} filename
* @param {string} routed_uri
* @return {boolean}
*/
$served = Q::event("Q/dir", compact('filename', 'routed_uri'));
$dir_was_served = true;
} else {
/**
* @event Q/file
* @param {string} filename
* @param {string} routed_uri
* @return {boolean}
*/
$served = Q::event("Q/file", compact('filename', 'routed_uri'));
$dir_was_served = false;
}
}
// if response was served, then return
if ($served) {
self::result($dir_was_served ? "Dir served" : "File served");
return true;
}
// This loop is for forwarding
$max_forwards = Q_Config::get('Q', 'maxForwards', 10);
for ($try = 0; $try < $max_forwards; ++$try) {
// Make an array from the routed URI
self::$routed = array();
if (self::$uri instanceof Q_Uri) {
self::$routed = self::$uri->toArray();
}
// If no module was found, then respond with noModule and return
if (!isset(self::$uri->module)) {
/**
* Occurs when no module was found during routing.
* The parameters are the routed array
* @event Q/noModule
*/
Q::event("Q/noModule", self::$routed);
// should echo things
self::result("No module");
return false;
}
$module = self::$uri->module;
try {
// Implement restricting of modules we are allowed to access
$routed_modules = Q_Config::get('Q', 'routedModules', null);
if (isset($routed_modules)) {
if (!in_array($module, $routed_modules)) {
/**
* Occurs when no defined action was found during routing.
* The parameters are the routed array
* @event Q/notFound
* @param {array} $routed
*/
Q::event('Q/notFound', self::$routed);
// should echo things
self::result("Unknown module");
return false;
}
} else {
if (!Q::realPath("handlers/{$module}")) {
Q::event('Q/notFound', self::$routed);
// should echo things
self::result("Unknown module");
return false;
}
}
// Implement notFound if action was not found
if (empty(self::$uri->action)) {
Q::event('Q/notFound', self::$routed);
// should echo things
self::result("Unknown action");
return false;
}
// Fire a pure event, for aggregation etc
if (!isset(self::$skip['Q/prepare'])) {
/**
* Gives the app a chance to prepare for handling a request
* The parameters are the routed array
* @event Q/prepare
* @param {array} $routed
*/
Q::event('Q/prepare', self::$routed, true);
}
// Perform validation
if (!isset(self::$skip['Q/validate'])) {
/**
* Gives the app a chance to validate the request and call
* Q_Response::addError() zero or more times.
* The parameters are the routed array
* @event Q/validate
* @param {array} $routed
*/
Q::event('Q/validate', self::$routed);
if (!isset(self::$skip['Q/errors'])) {
// Check if any errors accumulated
if (Q_Response::getErrors()) {
// There were validation errors -- render a response
self::result('Validation errors');
self::errors(null, $module, null);
return false;
}
}
}
// Time to instantiate some app objects from the request
if (!isset(self::$skip['Q/objects'])) {
/**
* Gives the app a chance to fetch objects needed for handling
* the request.
* @event Q/objects
* @param {array} $routed
*/
Q::event('Q/objects', self::$routed, true);
}
// We might want to reroute the request
if (!isset(self::$skip['Q/reroute'])) {
/**
* Gives the app a chance to reroute the request
* @event Q/reroute
* @param {array} $routed
* @return {boolean} whether to stop the dispatch
*/
$stop_dispatch = Q::event('Q/reroute', self::$routed, true);
if ($stop_dispatch) {
self::result("Stopped dispatch");
return false;
}
}
// Make some changes to server state, possibly
$method = Q_Request::method();
if ($method != 'GET') {
$methods = Q_Config::get('Q', 'methods', array('POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD'));
if (!in_array($method, $methods)) {
throw new Q_Exception_MethodNotSupported(compact('method'));
}
$method_event = 'Q/' . strtolower($method);
if (!isset(self::$skip['Q/method']) and !isset(self::$skip[$method_event])) {
if (!Q::canHandle($method_event)) {
throw new Q_Exception_MethodNotSupported(compact('method'));
}
Q::event($method_event);
}
}
// You can calculate some analytics here, and store them somewhere
if (!isset(self::$skip['Q/analytics'])) {
/**
* Gives the app a chance to gather analytics from the request.
* @event Q/analytics
* @param {array} $routed
*/
Q::event('Q/analytics', self::$routed, true);
}
if (!isset(self::$skip['Q/errors'])) {
// Check if any errors accumulated
if (Q_Response::getErrors()) {
// There were processing errors -- render a response
self::result('Processing errors');
self::errors(null, $module, null);
return false;
}
}
// When handling all further events, you should probably
// refrain from changing server state, and only do reading.
// That is because GET in HTTP is not supposed to have side effects
// for which the client is responsible.
self::response();
return true;
} catch (Q_Exception_DispatcherForward $e) {
if (!empty($ob)) {
$ob->getClean();
}
self::handleForwardException($e);
} catch (Q_Exception_DispatcherErrors $e) {
if (!empty($ob)) {
$partialResponse = $ob->getClean();
} else {
$partialResponse = null;
}
self::errors(null, $module, $partialResponse);
self::result("Rendered errors");
return true;
} catch (Exception $exception) {
if (!empty($ob)) {
$partialResponse = $ob->getClean();
} else {
$partialResponse = null;
}
$message = $exception->getMessage();
$file = $exception->getFile();
$line = $exception->getLine();
if (is_callable(array($exception, 'getTraceAsStringEx'))) {
$trace_string = $exception->getTraceAsStringEx();
} else {
$trace_string = $exception->getTraceAsString();
}
$colored = Q_Exception::coloredString($message, $file, $line, $trace_string);
self::result("Exception occurred:\n\n{$colored}");
try {
self::errors($exception, $module, $partialResponse);
} catch (Exception $e) {
if (!empty($forwarding_to_error_action)) {
// Looks like there were errors in the error action
// So show the default one with the original exception
throw $exception;
}
if (get_class($e) === 'Q_Exception_DispatcherForward') {
$forwarding_to_error_action = true;
self::handleForwardException($e);
continue;
} else {
throw $e;
}
}
return false;
}
}
// If we are here, we have done forwarding too much
throw new Q_Exception_Recursion(array('function_name' => 'Dispatcher::forward()'));
}
